Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1960e5a886 | ||
|
|
e3afc2a00c | ||
|
|
a60ae5c6d8 | ||
|
|
d26e65db47 | ||
|
|
47f37988a5 | ||
|
|
1a5a95af63 | ||
|
|
fc5b465513 | ||
|
|
09b9f34e33 | ||
|
|
d61d9b9fc5 | ||
|
|
e8a03a362e | ||
|
|
bdd2d8349c | ||
|
|
4d0eddd811 | ||
|
|
02f470dde4 | ||
|
|
a0f192b1d7 | ||
|
|
d9137f1647 |
No files matched your search
@@ -139,12 +139,43 @@ A failure at any stage is recorded in `state.failure`, a partial report is writt
|
||||
| Source change \ evidence | Differs | Same | Not comparable |
|
||||
| --- | --- | --- | --- |
|
||||
| Route added / removed | Added / Removed | Added / Removed | Added / Removed |
|
||||
| Screen source changed (`screen`) | Modified | Needs review | Needs review |
|
||||
| Screen source changed (`screen`) | Modified | Unchanged (not counted as a change) | Needs review |
|
||||
| Only app-wide inputs changed (`app-wide`) | Modified | Unchanged (one line in the PR comment) | Needs review |
|
||||
| No source change (`none`) | Screen variant (listed apart from Changes) | Unchanged | Unchanged |
|
||||
|
||||
A screen whose source changed but whose screenshots were not compared (it is outside the capture scope) has no
|
||||
verdict: the PR comment does not list it, the agent API reports `not-compared`, and the Viewer marks it Not compared.
|
||||
Earlier versions listed it as Source-affected. A planned capture that failed is counted as unavailable and named under
|
||||
Validation.
|
||||
|
||||
"Differs" means the screenshots differ or the accessibility tree does. A Modified screen whose screenshots match is
|
||||
**Accessibility only**: what screen readers and voice control read changed (a label, a role, an element added to the tree)
|
||||
but nothing shows in the capture. It is still a change: the PR comment counts it apart ("3 visual changes · 12
|
||||
accessibility only") under 🟦 Accessibility only, the Viewer marks it blue and Compare steps through it, and the agent API
|
||||
reports `status: "accessibility-only"` with `sourceStatus: "modified"`. The report contract is unchanged (its review
|
||||
status stays `modified`), so earlier reports read the same way. The accessibility tree can include content outside the
|
||||
screenshot, such as rows scrolled below the fold or elements under a sheet, so an accessibility-only change is not always
|
||||
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,14 +4,132 @@ 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.
|
||||
|
||||
## Try it on your app
|
||||
<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>
|
||||
|
||||
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:
|
||||
<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>
|
||||
|
||||
- An iOS app, an Android app, or both. Explore is in v0; Android capture is newer than iOS.
|
||||
- Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer).
|
||||
- An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` for Android. Its EAS environment cannot have secret-visibility variables.
|
||||
- EAS Simulator access (in preview, [join the waitlist](https://expo.dev/services/simulators)).
|
||||
- Node.js 24.12 or newer, and admin access to the GitHub repository.
|
||||
|
||||
</details>
|
||||
|
||||
## Quick start
|
||||
|
||||
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
|
||||
@@ -25,40 +143,6 @@ need to log in to something first, tell me the command.
|
||||
|
||||
For apps behind a sign-in, see [Sign-in and other app state](#sign-in-and-other-app-state).
|
||||
|
||||
### Review a change before you push it
|
||||
|
||||
Once Explore is [set up](#set-up-ci-reviews-on-every-pr) (`.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.
|
||||
```
|
||||
|
||||
<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.
|
||||
- Every run is kept for 30 days (up to 2 GB in all): `npx @expo/explore reports` lists your local reviews, explorations and uploaded reports with their commits, and opens or hosts one without capturing again. `reports add <report.zip>` keeps a report you downloaded, such as a PR's `explore-review` artifact.
|
||||
|
||||
<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>
|
||||
|
||||
<details>
|
||||
<summary><strong>Run it yourself</strong></summary>
|
||||
|
||||
@@ -104,15 +188,19 @@ npx @expo/explore explore:session <session-id> --env-file path/.env.eas-simulato
|
||||
<details>
|
||||
<summary><strong>What a run without source shows</strong></summary>
|
||||
|
||||
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs [CI](#set-up-ci-reviews-on-every-pr).
|
||||
One card per screen the run reached, laid out by how many taps it took, with the tapped control on each edge. There is no before and after; that needs [CI](#set-up-ci).
|
||||
|
||||

|
||||
|
||||
</details>
|
||||
|
||||
## Set up CI: reviews on every PR
|
||||
## Set up CI
|
||||
|
||||
Paste this into Claude Code or Codex from your app's repository:
|
||||
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.
|
||||
|
||||
### Review on every PR
|
||||
|
||||
Each pull request gets a comment linking its report: the screens it added, removed or changed, before and after, on each platform you capture. Paste this into Claude Code or Codex from your app's repository:
|
||||
|
||||
```text
|
||||
Set up this app for Expo Explore CI reviews. Follow
|
||||
@@ -124,45 +212,45 @@ what to merge and how to start the first review.
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><strong>Requirements</strong></summary>
|
||||
<summary id="hosted-previews"><strong>Hosted previews</strong></summary>
|
||||
|
||||
- An iOS app, an Android app, or both. Explore is in v0; Android capture is newer than iOS.
|
||||
- Expo SDK 57 or newer, with Expo Router (57 or newer) or React Navigation (6 or newer).
|
||||
- An EAS build profile per platform: `ios.simulator: true` for iOS, `android.buildType: apk` for Android. Its EAS environment cannot have secret-visibility variables.
|
||||
- EAS Simulator access (in preview, [join the waitlist](https://expo.dev/services/simulators)).
|
||||
- Node.js 24.12 or newer, and admin access to the GitHub repository.
|
||||
By default reviewers download the report from GitHub. With hosted previews, the comment's **Explore report** link opens it in one click, even in private repositories.
|
||||
|
||||
```yaml
|
||||
report:
|
||||
preview:
|
||||
hosting: eas # default: off
|
||||
expiresAfter: 30d # default 30d, max 365d, or never
|
||||
# project: acme-explore # default <repository name>-explore, created on first run
|
||||
```
|
||||
|
||||
- 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 --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).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>After setup: your first review</strong></summary>
|
||||
<summary><strong>Manual setup</strong></summary>
|
||||
|
||||
1. Set the repository secrets that `expo-explore doctor` lists, such as `EXPO_TOKEN`.
|
||||
2. Merge the setup to the default branch and run **Expo Explore baseline** from GitHub Actions.
|
||||
3. Open a PR. **Expo Explore review** runs and posts a comment with the report.
|
||||
The prompt above walks through these steps with you. To do them yourself:
|
||||
|
||||
```sh
|
||||
expo-explore doctor # check every step; exits 1 until ready
|
||||
expo-explore doctor --capture # capture the committed app on EAS once, before the first PR
|
||||
expo-explore capture:review # or see a whole review of your branch on this machine first
|
||||
```
|
||||
1. Run `npx @expo/explore setup` in your app's directory (in a monorepo, add `--project apps/mobile`). It writes `.expo-explore/config.yaml` and the workflows.
|
||||
2. Run `npx @expo/explore doctor` and fix each problem it reports, until it exits 0. `doctor --capture` captures the committed app on EAS once, to check every screen before your first PR.
|
||||
3. Set the repository secrets `doctor` lists:
|
||||
- `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` 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).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Set up without a coding agent</strong></summary>
|
||||
|
||||
```sh
|
||||
npx @expo/explore setup # writes .expo-explore/config.yaml and the workflows; in a monorepo: --project apps/mobile
|
||||
npx @expo/explore doctor # fix each problem it reports, then commit
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Choose a capture mode</strong></summary>
|
||||
<summary><strong>Capture modes: deterministic or agent</strong></summary>
|
||||
|
||||
| | **Deterministic** (recommended to start) | **Agent** |
|
||||
| --- | --- | --- |
|
||||
@@ -173,10 +261,7 @@ npx @expo/explore doctor # fix each problem it reports, then commit
|
||||
|
||||
Both modes use the same comparison rules and report. You can change modes later.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Configure agent mode</strong></summary>
|
||||
**To use agent mode:**
|
||||
|
||||
1. Create an [Anthropic](https://platform.claude.com/settings/keys) or [OpenAI](https://platform.openai.com/api-keys) API key.
|
||||
2. Set `mode: agent` and an `agent.model` your account can use.
|
||||
@@ -188,15 +273,7 @@ The model navigates and recovers on each uncaptured revision; see [agent usage](
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Repository settings</strong></summary>
|
||||
|
||||
- `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 `expo-explore setup --workflows` after you add one.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary id="platforms"><strong>Android and several platforms</strong></summary>
|
||||
<summary id="platforms"><strong>iOS, Android, or both</strong></summary>
|
||||
|
||||
`app.platform` names the primary platform, and a `platforms` map adds the other. Each entry can set its own `device`, `bundleId`, and `easProfile`.
|
||||
|
||||
@@ -222,28 +299,36 @@ platforms:
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary id="hosted-previews"><strong>Hosted previews</strong></summary>
|
||||
<summary><strong>Keep your setup current</strong></summary>
|
||||
|
||||
By default reviewers download the report from GitHub. With hosted previews, the comment's **Explore report** link opens it in one click, even in private repositories.
|
||||
|
||||
```yaml
|
||||
report:
|
||||
preview:
|
||||
hosting: eas # default: off
|
||||
expiresAfter: 30d # default 30d, max 365d, or never
|
||||
# project: acme-explore # default <repository name>-explore, created on first run
|
||||
```
|
||||
|
||||
- Run `expo-explore setup --workflows` after enabling it to add the `deploy` job.
|
||||
- A [comparison of two commits](#compare) 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.
|
||||
- `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).
|
||||
- A PR that adds a guarded screen or a dynamic route should also update `config.yaml`.
|
||||
- Renamed identifiers or labels break deterministic setup steps.
|
||||
- To update Explore, run `npx @expo/explore@latest setup --workflows` and commit the new version. It also adds `explore-compare.yml` if you don't have it, and `doctor` warns when it is missing.
|
||||
|
||||
</details>
|
||||
|
||||
### Compare any two commits
|
||||
|
||||
A release, a release candidate, a nightly: any two branches, tags or commits, reviewed like a PR without one, with the report linked from the run's summary. Once CI reviews PRs, paste this into Claude Code or Codex:
|
||||
|
||||
```text
|
||||
Set up Expo Explore to review this app's releases. Follow the "Compare any two commits"
|
||||
section of https://unpkg.com/@expo/explore/skills/explore-setup/SKILL.md: make sure
|
||||
explore-compare.yml is installed, add a workflow that compares each release tag (and
|
||||
release candidate) with the last stable release, then run it once on the latest tag and
|
||||
give me the report link.
|
||||
```
|
||||
|
||||
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 --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.
|
||||
|
||||
<details>
|
||||
<summary id="compare"><strong>Review any two commits: releases, nightlies, any event</strong></summary>
|
||||
<summary id="compare"><strong>The comparison workflow</strong></summary>
|
||||
|
||||
`.github/workflows/explore-compare.yml` reviews a `head` against a `base`, each a branch, tag or commit SHA, with no pull request. It captures, compares and reports exactly like a PR review, and links the report from the run's summary.
|
||||
|
||||
@@ -280,21 +365,12 @@ jobs:
|
||||
- Pick whatever `base` the event calls for: `main` for a release branch, yesterday's tag for a nightly, the last stable tag for a release candidate.
|
||||
- `scope` and `expires-in` are optional and override `exploration.scope` and `report.preview.expiresAfter` for that run. Without them a comparison captures what a PR review would (`scope: changes` captures only screens whose source changed), and the hosted link expires like a PR's.
|
||||
- The run summary links each platform's report (**Open** and **zip**, like a PR comment) and, with hosting, the hosted report.
|
||||
- `setup --workflows` installs it. The caller grants `contents: read` and `actions: read`; `secrets: inherit` passes `EXPO_TOKEN` and any app-test secrets.
|
||||
- `setup --workflows` installs it from 0.19.0; `npx @expo/explore@latest setup --workflows` adds it to an existing setup. The caller grants `contents: read` and `actions: read`; `secrets: inherit` passes `EXPO_TOKEN` and any app-test secrets.
|
||||
- Call it once per workflow run. A called workflow runs inside its caller's run, so a second call in the same run would reuse the first one's artifact names; use separate workflows instead.
|
||||
- When the baseline workflow captured `base` in the last 30 days, that capture is reused and only `head` is captured. The report artifact is kept 30 days; only a hosted link with `expires-in: never` lasts longer.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Keep your setup current</strong></summary>
|
||||
|
||||
- A PR that adds a guarded screen or a dynamic route should also update `config.yaml`.
|
||||
- Renamed identifiers or labels break deterministic setup steps.
|
||||
- To update Explore, run `npx @expo/explore@latest setup --workflows` and commit the new version. It also adds `explore-compare.yml` if you don't have it, and `doctor` warns when it is missing.
|
||||
|
||||
</details>
|
||||
|
||||
## Sign-in and other app state
|
||||
|
||||
Each run starts on a fresh install. Tell Explore how to get past what the app needs: with `--hints` when running without source, or with [setup steps or agent instructions](docs/quickstart-ci.md#when-the-config-needs-setup-steps) in CI.
|
||||
@@ -324,46 +400,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>
|
||||
@@ -382,7 +419,7 @@ The same link answers differently depending on who asks. It already carries the
|
||||
|
||||
- A browser gets the Viewer.
|
||||
- Anything that does not ask for HTML (`curl`, `fetch`, agents' URL tools) gets a Markdown index of the report, also at `/llms.txt`.
|
||||
- The index links to a read-only JSON API under `/api/v1`: `/screens?status=modified,added,removed`, `/screens/<id>`, `/transitions`, and `/raw` for the report file.
|
||||
- The index links to a read-only JSON API under `/api/v1`: `/screens?status=modified,accessibility-only,added,removed`, `/screens/<id>`, `/transitions`, and `/raw` for the report file.
|
||||
- Reports without source also expose `/journeys`, `/gaps`, and `/frontier`.
|
||||
- Multi-platform reports take `?platform=ios|android`. Expired links answer `410`.
|
||||
|
||||
@@ -392,8 +429,6 @@ curl -s "$LINK/api/v1/screens?status=modified" | jq '.items[] | {route, status,
|
||||
|
||||
</details>
|
||||
|
||||
## More
|
||||
|
||||
<details>
|
||||
<summary><strong>How it works</strong></summary>
|
||||
|
||||
@@ -403,7 +438,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), 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).
|
||||
|
||||
|
||||
@@ -164,7 +164,7 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
|
||||
| Source \ Evidence | Differs | No visible difference | Inconclusive |
|
||||
| --- | --- | --- | --- |
|
||||
| Added / removed route | Added / Removed | Added / Removed | Added / Removed |
|
||||
| Screen source changed | Modified | Needs review | Needs review |
|
||||
| Screen source changed | Modified | Unchanged (not counted as a change) | Needs review |
|
||||
| Only app-wide inputs changed | Modified | Unchanged (the PR comment names the app-wide change once) | Needs review |
|
||||
| Source unchanged | Screen variant | Unchanged | Unchanged |
|
||||
|
||||
@@ -172,13 +172,20 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
|
||||
| --- | --- |
|
||||
| Added / Removed | Route presence differs between source inventories |
|
||||
| Modified | The screen's source changed and comparable evidence differs |
|
||||
| Needs review | The screen's source changed but no visible difference was captured, or its evidence is inconclusive; still a review target |
|
||||
| Accessibility only | Modified, but the screenshots match: only the accessibility tree (what screen readers and voice control read) differs. Counted as a change and listed apart from the visual ones |
|
||||
| Needs review | The screen's source changed and the comparison could not tell whether it looks different; a review target |
|
||||
| Screen variant | No source change reaches the screen, but its captures differ in runtime UI state (balances, timestamps, loaded content). Listed apart from changes |
|
||||
| Source-affected | Source impact without a comparison |
|
||||
| Unchanged | No visible difference and no screen-specific source change |
|
||||
| Not compared | No comparison was performed |
|
||||
| Unchanged | No visible difference, whether or not the screen's source changed. Explore reports visual changes; reports before 0.19.1 called a source change with no visible difference Needs review |
|
||||
| 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.
|
||||
A runtime difference is not proof that the code change caused it. Deterministic mode uses template notes and evidence facts. Agent mode adds AI explanations from the captured evidence and source changes through a separate CLI session; those explanations cannot override fixed verdicts. Structural flows describe possible source navigation; semantic business grouping remains deferred.
|
||||
|
||||
## Artifacts and cache
|
||||
|
||||
|
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,12 +1,12 @@
|
||||
{
|
||||
"name": "@expo/explore",
|
||||
"version": "0.19.0",
|
||||
"version": "0.19.5",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "@expo/explore",
|
||||
"version": "0.19.0",
|
||||
"version": "0.19.5",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@expo/repack-app": "0.10.1",
|
||||
@@ -14,6 +14,7 @@
|
||||
"@zip.js/zip.js": "2.16.0",
|
||||
"agent-device": "0.21.15",
|
||||
"ajv": "^8.17.1",
|
||||
"eas-cli": "25.0.0",
|
||||
"pngjs": "7.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
"yaml": "^2.9.0",
|
||||
@@ -48,7 +49,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 +1601,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 +1643,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 +1901,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 +2593,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 +2638,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 +4557,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",
|
||||
@@ -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.0",
|
||||
"version": "0.19.5",
|
||||
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
@@ -73,7 +73,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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -152,24 +152,34 @@ 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.
|
||||
- Captures are cached in `~/.cache/expo-explore`, so a second review of the same base does not capture it again (`--no-cache` skips the cache). Ctrl+C stops the EAS Simulator sessions the review started.
|
||||
- It builds on EAS and runs simulator sessions, like a CI review: expect several minutes and EAS usage per run.
|
||||
|
||||
## Compare any two commits
|
||||
|
||||
`explore-compare.yml` (installed by `setup --workflows` from 0.19.0; run `npx @expo/explore@latest setup --workflows` to add it to an existing setup) reviews a `head` against a `base`, each a branch, tag or commit SHA, with no pull request. It captures, compares and reports like a PR review and links the report from the run's summary. Its inputs are `base`, `head`, and the optional `scope` (`changes` or `all`) and `expires-in` (such as `30d`, or `never`).
|
||||
|
||||
- **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 --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.
|
||||
|
||||
## Learn from observed failures
|
||||
|
||||
When revising an existing setup, read the previous run's diagnostics, navigation trace and screenshots together. Separate an app prerequisite or defect from a controller failure and a provider or configuration failure. A successful tool response alone does not prove recovery: check the field value, destination, or visible content. For agent mode, inspect `agent-usage.jsonl` before proposing another paid run; missing accounting is unknown, not zero, and dollar fields are estimates. Respect exhausted credit and requests to stop paid calls.
|
||||
|
||||
@@ -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. Under it, **Review a change before you push it**: one sentence and a prompt that runs `capture:review` locally (the explore-setup skill's "Review a change on this machine" section) on a set-up app.
|
||||
3. **Set up CI: reviews on every PR**: one sentence and the setup prompt.
|
||||
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, several platforms, 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. Keep the collapsibles' `id` attributes that other docs link to (`#hosted-previews`, `#platforms`, `#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;
|
||||
|
||||
@@ -610,7 +610,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", "agent-device", "--package-version", AGENT_DEVICE_VERSION, "--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; }
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -446,7 +446,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", "agent-device", "--package-version", AGENT_DEVICE_VERSION, "--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);
|
||||
|
||||
@@ -100,7 +100,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_]+|EAS_SIMULATOR_[A-Z_]+|EXPO_TOKEN|agentDeviceRemoteSession(?:Token|Url)|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,
|
||||
@@ -361,11 +361,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
|
||||
|
||||
@@ -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,10 +32,10 @@ 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;
|
||||
@@ -89,7 +89,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 +271,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 +349,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 +364,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 +376,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);
|
||||
|
||||
|
||||
@@ -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;
|
||||
@@ -81,7 +84,7 @@ const flagKinds: Record<string, Record<string, "value" | "boolean">> = {
|
||||
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" },
|
||||
base:"value", head:"value", project:"value", committed:"boolean", uncommitted:"boolean", "include-untracked":"boolean", upload:"boolean", "no-open":"boolean", "no-cache":"boolean", port:"value" },
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -221,11 +221,12 @@ export async function captureBaseline(): Promise<void> {
|
||||
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 } : {}),
|
||||
// --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"), cache: !has("no-cache"), configPath: flag("config"), progress: stderrProgress() });
|
||||
if (has("output")) {
|
||||
for (const report of result.reports) {
|
||||
|
||||
@@ -17,11 +17,14 @@ const GET_STARTED = `Get started (run these in the Expo app's directory):
|
||||
(--offline skips EAS and GitHub; --check-model sends one small request with the local provider key)
|
||||
doctor --capture [--project DIRECTORY] [--output DIRECTORY] [--platform ios|android] [--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]
|
||||
capture [--base REF] [--head REF | --committed] [--platform ios|android] [--scope all|changes]
|
||||
[--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)
|
||||
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]
|
||||
|
||||
@@ -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>"];
|
||||
|
||||
@@ -88,8 +88,8 @@ export function visibleRuns(state: PickerState): SavedRun[] {
|
||||
|
||||
function counts(run: SavedRun, paint: Paint): string {
|
||||
if (run.explored) return `${paint.text(String(run.explored.screens))} ${paint.dim("screens")} ${paint.dim(`${run.explored.unexplored} unexplored`)}`;
|
||||
const parts = ([["modified", paint.amber, "modified"], ["added", paint.green, "added"], ["removed", paint.red, "removed"], ["needs-review", paint.yellow, "need review"],
|
||||
["source-affected", paint.yellow, "source-affected"]] as const)
|
||||
const parts = ([["modified", paint.amber, "modified"], ["accessibility-only", paint.blue, "accessibility only"], ["added", paint.green, "added"], ["removed", paint.red, "removed"],
|
||||
["needs-review", paint.yellow, "need review"]] as const)
|
||||
.filter(([group]) => run.changes?.[group]).map(([group, colour, label]) => `${colour(String(run.changes![group]))} ${paint.dim(label)}`);
|
||||
return parts.length ? parts.join(" ") : paint.dim("no visible changes");
|
||||
}
|
||||
@@ -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)]!;
|
||||
|
||||
@@ -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" });
|
||||
|
||||
@@ -172,8 +172,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. */
|
||||
|
||||
@@ -8,12 +8,13 @@ const REVIEW_STATUSES = new Set(["added", "modified", "removed", "unchanged", "n
|
||||
const SOURCE_SCOPES = new Set(["screen", "app-wide", "none"]);
|
||||
/** Verdicts each source scope allows: only a source change makes a screen a review target. */
|
||||
const SCOPE_VERDICTS: Record<string, readonly string[]> = {
|
||||
screen: ["modified", "needs-review"],
|
||||
screen: ["modified", "needs-review", "unchanged"],
|
||||
"app-wide": ["modified", "needs-review", "unchanged"],
|
||||
none: ["unchanged", "variant"],
|
||||
};
|
||||
const VISUAL_VERDICTS = new Set(["unchanged", "modified", "needs-review"]);
|
||||
const MAX_REVIEW_DESCRIPTION = 160;
|
||||
const LEGACY_NO_VISIBLE_DIFFERENCE = "Source changed; no visible difference was captured.";
|
||||
|
||||
/** Source analysis belongs to capture planning; delivered reports contain runtime review evidence. */
|
||||
/** Capture shrinks the app icon to at most this many pixels on a side. */
|
||||
@@ -31,6 +32,14 @@ function hasVerifiedPair(surface: Surface): boolean {
|
||||
&& surface[`${side}Outcome`]?.landing === "verified");
|
||||
}
|
||||
|
||||
/**
|
||||
* A modified screen whose verified screenshots match: only what assistive technology reads (its accessibility tree)
|
||||
* changed. Screen readers and voice control see it, so it is a change to review, listed apart from the visual ones.
|
||||
*/
|
||||
export function isAccessibilityOnlyChange(surface: Surface): boolean {
|
||||
return surface.review?.status === "modified" && surface.visual?.verdict === "unchanged" && hasVerifiedPair(surface);
|
||||
}
|
||||
|
||||
function assertReviewFields(surface: Surface, enforceComparisonEvidence: boolean): void {
|
||||
const assertVerifiedPair = () => {
|
||||
if (enforceComparisonEvidence && !hasVerifiedPair(surface)) {
|
||||
@@ -66,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");
|
||||
}
|
||||
@@ -207,6 +226,12 @@ export function normalizePublicReviewForReading(review: PublicReview, onGap?: (g
|
||||
surface = { ...surface, review: { ...surface.review, status: "variant",
|
||||
description: description.length > MAX_REVIEW_DESCRIPTION ? `${description.slice(0, MAX_REVIEW_DESCRIPTION - 1)}…` : description } };
|
||||
}
|
||||
// Reports before 0.19.1 called a screen whose source changed but whose captures matched "needs review". It has no
|
||||
// visible change, so it reads as unchanged and is not counted as a change.
|
||||
if (surface.review?.status === "needs-review" && surface.review.description === LEGACY_NO_VISIBLE_DIFFERENCE) {
|
||||
changed = true;
|
||||
surface = { ...surface, review: { ...surface.review, status: "unchanged", description: "No visible change" } };
|
||||
}
|
||||
const comparisonVerdict = surface.review && surface.review.status !== "added" && surface.review.status !== "removed";
|
||||
if (!((!hasVerifiedPair(surface) && (comparisonVerdict || surface.visual)) || surface.visual?.reason === "diff-failed")) return surface;
|
||||
changed = true;
|
||||
|
||||
@@ -98,7 +98,8 @@ function reviewSurfaceItem(context: AgentContext, surface: Json): Json {
|
||||
const visual = rec(surface.visual), review = rec(surface.review);
|
||||
const id = str(surface.id) ?? "";
|
||||
return defined({
|
||||
id, route: str(route.route), kind: str(route.kind), routeFile: str(route.routeFile), status: str(surface.status), colorScheme: str(surface.colorScheme),
|
||||
id, route: str(route.route), kind: str(route.kind), routeFile: str(route.routeFile), status: verdictOf(surface),
|
||||
sourceStatus: verdictOf(surface) === str(surface.status) ? undefined : str(surface.status), colorScheme: str(surface.colorScheme),
|
||||
review: surface.review === undefined ? undefined : defined({ status: str(review.status), description: str(review.description), facts: arr(review.facts).map(fact => str(rec(fact).bullet)).filter(Boolean) }),
|
||||
visual: surface.visual === undefined ? undefined : defined({ verdict: str(visual.verdict), reason: str(visual.reason), mismatchPercentage: num(visual.mismatchPercentage), threshold: num(visual.threshold) }),
|
||||
note: str(rec(surface.note).text),
|
||||
@@ -120,10 +121,57 @@ function reviewSurfaceDetail(context: AgentContext, review: Json, surface: Json)
|
||||
}
|
||||
const edgeItem = (edge: Json): Json => defined({ from: str(edge.from), to: str(edge.to), kind: str(edge.kind), sourceFile: str(edge.sourceFile), provenance: str(edge.provenance) });
|
||||
|
||||
/**
|
||||
* A screen's status as the Viewer and the PR comment show it: the review's verdict where there is one, so `modified`
|
||||
* means a visible change. A screen whose source changed but whose captures match is unchanged, including in reports
|
||||
* from before 0.19.1, which called it "needs review". A modified screen whose screenshots match changed only in what
|
||||
* assistive technology reads: `accessibility-only`. A screen whose capture failed is `unavailable`, and one whose
|
||||
* source changed but that has no verdict was not compared: `not-compared`.
|
||||
*/
|
||||
/** Both sides captured at their verified destination route, as a verdict requires (isAccessibilityOnlyChange in the contract). */
|
||||
function verifiedPair(surface: Json): boolean {
|
||||
return (["base", "head"] as const).every(side => str(rec(surface[side]).kind) === "screen" && Boolean(surface[`${side}Image`])
|
||||
&& str(rec(surface[`${side}Outcome`]).status) === "captured" && str(rec(surface[`${side}Outcome`]).landing) === "verified");
|
||||
}
|
||||
|
||||
/** The side's planned capture ended without a screenshot, or captured another screen than the route (the Viewer's Unavailable). */
|
||||
function captureUnavailable(surface: Json, side: "base" | "head"): boolean {
|
||||
const outcome = surface[`${side}Outcome`];
|
||||
if (str(rec(surface[side]).kind) !== "screen" || outcome === undefined) return false;
|
||||
const image = Boolean(surface[`${side}Image`]);
|
||||
if (!image) return str(rec(outcome).status) !== "captured";
|
||||
return str(rec(outcome).status) === "captured" && str(rec(outcome).landing) !== "verified" && rec(outcome).observed !== undefined;
|
||||
}
|
||||
|
||||
function verdictOf(surface: Json): string | undefined {
|
||||
// A capture that failed is unavailable, as the Viewer says, whatever the source or an older verdict claims.
|
||||
if (str(surface.status) !== "removed" && captureUnavailable(surface, "head")) return "unavailable";
|
||||
if (["modified", "unchanged"].includes(str(surface.status) ?? "") && captureUnavailable(surface, "base")) return "unavailable";
|
||||
const review = rec(surface.review);
|
||||
const status = str(review.status);
|
||||
if (status === "needs-review" && str(review.description) === "Source changed; no visible difference was captured.") return "unchanged";
|
||||
if (status === "modified" && str(rec(surface.visual).verdict) === "unchanged" && verifiedPair(surface)) return "accessibility-only";
|
||||
// A source change nobody compared is not a change Explore saw.
|
||||
if (status === undefined && str(surface.status) === "modified") return "not-compared";
|
||||
return status ?? str(surface.status);
|
||||
}
|
||||
|
||||
const STATUS_ORDER = ["modified", "accessibility-only", "added", "removed", "needs-review", "unavailable", "not-compared", "unchanged", "variant"];
|
||||
const STATUS_WORDS: Record<string, string> = { "accessibility-only": "accessibility only (screenshots match, the accessibility tree does not)",
|
||||
"needs-review": "need review", "not-compared": "not compared", variant: "screen variants" };
|
||||
|
||||
/** "3 modified, 1 added, 1 removed, 30 unchanged": every status counted, so the parts add up to the total. */
|
||||
function screenCounts(screens: Json): string {
|
||||
const statuses = Object.keys(screens).filter(status => status !== "total")
|
||||
.sort((left, right) => (STATUS_ORDER.indexOf(left) + 1 || 99) - (STATUS_ORDER.indexOf(right) + 1 || 99));
|
||||
const parts = statuses.flatMap(status => (num(screens[status]) ? [`${num(screens[status])} ${STATUS_WORDS[status] ?? status}`] : []));
|
||||
return parts.length ? parts.join(", ") : "none";
|
||||
}
|
||||
|
||||
function reviewSummary(context: AgentContext, review: Json): Json {
|
||||
const surfaces = arr(review.surfaces).map(rec);
|
||||
const counts: Record<string, number> = {};
|
||||
for (const surface of surfaces) { const status = str(surface.status) ?? "unknown"; counts[status] = (counts[status] ?? 0) + 1; }
|
||||
for (const surface of surfaces) { const status = verdictOf(surface) ?? "unknown"; counts[status] = (counts[status] ?? 0) + 1; }
|
||||
const pr = rec(review.pullRequest), runtime = rec(review.runtime);
|
||||
return defined({
|
||||
kind: "pr-review", api: AGENT_API_VERSION, contract: str(review.contract),
|
||||
@@ -132,7 +180,7 @@ function reviewSummary(context: AgentContext, review: Json): Json {
|
||||
createdAt: str(review.createdAt), mode: str(review.mode), platforms: context.platforms, expiresAt: context.expiresAt,
|
||||
screens: { total: surfaces.length, ...counts },
|
||||
links: {
|
||||
screens: withPlatform(context, apiUrl(context, "/screens")), changed: withPlatform(context, apiUrl(context, "/screens?status=modified,added,removed")),
|
||||
screens: withPlatform(context, apiUrl(context, "/screens")), changed: withPlatform(context, apiUrl(context, "/screens?status=modified,accessibility-only,added,removed")),
|
||||
transitions: withPlatform(context, apiUrl(context, "/transitions")), raw: withPlatform(context, apiUrl(context, "/raw")),
|
||||
viewer: viewerUrl(context), viewerChanges: viewerUrl(context, { focus: "modified", inspect: "diff" }), markdown: `${context.pageUrl}/llms.txt`,
|
||||
},
|
||||
@@ -216,10 +264,10 @@ export function agentIndexMarkdown(context: AgentContext, loaded: LoadedReport):
|
||||
// A comparison of two commits, or a local review on someone's machine, has no pull request: its title names both refs.
|
||||
const compared = pr.origin === "compare" || pr.origin === "local";
|
||||
lines.push(`# Expo Explore report: ${escapeMd(app.name ?? pr.repository)} ${compared ? escapeMd(pr.title) : `PR #${escapeMd(pr.number)}`}${app.platform ? ` (${escapeMd(app.platform)})` : ""}`, "",
|
||||
`> Visual review of ${compared ? `${escapeMd(pr.repository)} ${escapeMd(pr.title)}` : `pull request ${escapeMd(pr.repository)}#${escapeMd(pr.number)}`} by Expo Explore. ${screens.total} screens captured: ${screens.modified ?? 0} modified, ${screens.added ?? 0} added, ${screens.removed ?? 0} removed, ${screens.unchanged ?? 0} unchanged.${context.expiresAt ? ` This link stops serving the report after ${context.expiresAt}.` : ""}`, "",
|
||||
`> Visual review of ${compared ? `${escapeMd(pr.repository)} ${escapeMd(pr.title)}` : `pull request ${escapeMd(pr.repository)}#${escapeMd(pr.number)}`} by Expo Explore. ${screens.total} screens: ${screenCounts(screens)}.${context.expiresAt ? ` This link stops serving the report after ${context.expiresAt}.` : ""}`, "",
|
||||
"This URL is the human Viewer. The same report is available as read-only JSON (no credentials beyond this URL):", "",
|
||||
`- [Summary](${links.summary ?? withPlatform(context, apiUrl(context))}): kind, counts by status, app and PR identity, links`,
|
||||
`- [Changed screens](${links.changed}): the modified, added and removed screens with the review description, visual verdict and mismatch percentage; \`status=\` filters, \`limit=\`/\`cursor=\` page`,
|
||||
`- [Changed screens](${links.changed}): the modified, accessibility-only (screenshots match, the accessibility tree does not), added and removed screens with the review description, visual verdict and mismatch percentage; \`status=\` filters, \`limit=\`/\`cursor=\` page`,
|
||||
`- [All screens](${links.screens}): every captured screen; \`${links.screens}/{id}\` (the \`id\` field of a screen) adds source files and navigation in and out`,
|
||||
`- [Transitions](${links.transitions}): navigation edges between screens (\`?from=\`/\`?to=\` take a screen id or route)`,
|
||||
`- Screenshots: each screen's \`headImage\`/\`baseImage\` URL returns the PNG`,
|
||||
@@ -339,7 +387,7 @@ export async function agentApiReply(context: AgentContext, loaded: LoadedReport,
|
||||
const surfaces = arr(loaded.json.surfaces).map(rec);
|
||||
if (id !== undefined) { const surface = surfaces.find(s => s.id === id); return surface ? json(reviewSurfaceDetail(context, loaded.json, surface)) : notFound(); }
|
||||
const statuses = params.get("status")?.split(",").filter(Boolean);
|
||||
const items = surfaces.filter(s => !statuses || statuses.includes(str(s.status) ?? "")).map(s => reviewSurfaceItem(context, s));
|
||||
const items = surfaces.filter(s => !statuses || statuses.includes(verdictOf(s) ?? "")).map(s => reviewSurfaceItem(context, s));
|
||||
const paged = page(items, params);
|
||||
if (!paged) return json({ error: "bad_request", message: `limit must be 1-${MAX_LIMIT} and cursor a non-negative integer` }, 400);
|
||||
return wantsMarkdown ? markdown(screensMarkdown(loaded, paged.items, paged.total)) : json(paged);
|
||||
|
||||
@@ -5,7 +5,7 @@ import { assertPublicReview, projectPublicReviewForReport } from "../contracts/r
|
||||
import { createHash } from "node:crypto";
|
||||
import type { ArtifactReport } from "../contracts/artifact-report.js";
|
||||
import { compareTitleMarkdown, projectReviewPresentation, type CompareReviewPresentation } from "../contracts/review.js";
|
||||
import { renderPublicComment, platformSectionMerge, type PublicCommentState } from "./pr-comment-body.js";
|
||||
import { renderPublicComment, platformSectionMerge, reviewChangeCount, type PublicCommentState } from "./pr-comment-body.js";
|
||||
import type { ExplorePlatform } from "../config/explore-config.js";
|
||||
import { upsertStickyComment } from "./pr-comment.js";
|
||||
import { previewLinks, viewerLinks } from "./viewer-links.js";
|
||||
@@ -214,7 +214,7 @@ async function publishCompareSummary(input: CiReportInput, options: { artifactUr
|
||||
runAttempt: review.runAttempt, configPath: input.commentState.configPath, artifactUrl: options.artifactUrl,
|
||||
...(options.platform ? { platform: options.platform } : {}) });
|
||||
const changes = input.commentState.review ?? review;
|
||||
const count = changes.surfaces.filter(surface => surface.review ? surface.review.status !== "unchanged" && surface.review.status !== "variant" : surface.status !== "unchanged").length;
|
||||
const count = reviewChangeCount({ review: changes }) ?? 0;
|
||||
const platform = (options.platform ?? review.runtime.platform) === "android" ? "Android" : "iOS";
|
||||
if (environment.GITHUB_STEP_SUMMARY) {
|
||||
await appendFile(environment.GITHUB_STEP_SUMMARY, `- ${platform} report of ${compareTitleMarkdown(comparison)}: [Open](${links.viewer!.open}) · [zip](${links.download!}) · ${count} ${count === 1 ? "change" : "changes"}\n`);
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
import type { PublicReview } from "../contracts/capture.js";
|
||||
import type { SimulatorRuntimeMetadata } from "../capture/run.js";
|
||||
import { CI_COMMENT_MARKER } from "./pr-comment.js";
|
||||
import { CHANGE_GROUPS, foldRecord, historyLine, readCommentRecords, recordLine, recordSummary, type ChangeGroup, type CommentPlatform, type CommentRecords, type HistoryEntry, type PlatformRecord } from "./pr-comment-record.js";
|
||||
import { sourceImpactSentences } from "../contracts/source-change.js";
|
||||
import { CHANGE_GROUPS, changeCountText, foldRecord, strongerGroup, historyLine, readCommentRecords, recordLine, recordSummary, type ChangeGroup, type CommentPlatform, type CommentRecords, type HistoryEntry, type PlatformRecord } from "./pr-comment-record.js";
|
||||
import { isAccessibilityOnlyChange } from "../contracts/review-validation.js";
|
||||
import type { PublicCaptureHealth, PublicEvidenceSummary } from "../review/evidence-assessment.js";
|
||||
import type { ReviewPresentation } from "../contracts/review.js";
|
||||
import type { ViewerLinks } from "./viewer-links.js";
|
||||
@@ -60,8 +60,8 @@ const GROUP_LABEL: Record<ReviewGroup, string> = {
|
||||
added: "🟩 Added",
|
||||
modified: "🟧 Modified",
|
||||
removed: "🟥 Removed",
|
||||
"accessibility-only": "🟦 Accessibility only",
|
||||
"needs-review": "🟨 Needs review",
|
||||
"source-affected": "🟨 Source-affected",
|
||||
};
|
||||
|
||||
/** The body is HTML, so no blank lines are needed and the block keeps its natural spacing. */
|
||||
@@ -121,16 +121,32 @@ function plural(count: number, noun: string): string {
|
||||
|
||||
type Surface = PublicReview["surfaces"][number];
|
||||
|
||||
/** Evidence-based group when the run produced verdicts; otherwise the source-based status. */
|
||||
function groupOf(surface: Surface, evidenceBased: boolean): ReviewGroup | "unchanged" | "variant" {
|
||||
/**
|
||||
* The group a surface is listed under, from the run's verdicts. A screen without one (its source changed but no
|
||||
* screenshots were compared) is not listed: Explore reports what the captures show. A capture that failed is counted as
|
||||
* unavailable in the result and named under Validation instead.
|
||||
*/
|
||||
function groupOf(surface: Surface, evidenceBased: boolean): ReviewGroup | "unlisted" {
|
||||
if (surface.status === "added" || surface.status === "removed") return surface.status;
|
||||
const verified = (["base", "head"] as const).every(side => surface[`${side}Image`]
|
||||
&& surface[`${side}Outcome`]?.status === "captured" && surface[`${side}Outcome`]?.landing === "verified");
|
||||
if (evidenceBased && verified && surface.review && surface.visual?.reason !== "diff-failed") return surface.review.status;
|
||||
switch (surface.status) {
|
||||
case "modified": return "source-affected";
|
||||
case "unchanged": return "unchanged";
|
||||
if (evidenceBased && verified && surface.review && surface.visual?.reason !== "diff-failed") {
|
||||
const status = surface.review.status;
|
||||
if (status === "unchanged" || status === "variant") return "unlisted";
|
||||
return isAccessibilityOnlyChange(surface) ? "accessibility-only" : status;
|
||||
}
|
||||
return "unlisted";
|
||||
}
|
||||
|
||||
/**
|
||||
* A screen whose source changed and whose captures were both verified, but that has no verdict: the comparison did
|
||||
* not run or failed. Not a change, but not a screen that looks the same either, so the result says how many.
|
||||
*/
|
||||
function notComparedChange(surface: Surface): boolean {
|
||||
if (surface.status !== "modified" || (surface.head ?? surface.base)?.kind === "redirect") return false;
|
||||
const verified = (["base", "head"] as const).every(side => surface[`${side}Image`]
|
||||
&& surface[`${side}Outcome`]?.status === "captured" && surface[`${side}Outcome`]?.landing === "verified");
|
||||
return verified && (!surface.review || surface.visual?.reason === "diff-failed");
|
||||
}
|
||||
|
||||
function routeOf(surface: Surface): string {
|
||||
@@ -143,9 +159,6 @@ function descriptionOf(surface: Surface, group: ReviewGroup): string {
|
||||
if (group === "added") return `Added ${route} screen`;
|
||||
if (group === "removed") return `Removed ${route} screen`;
|
||||
// A group's own label already says added or removed; the route makes the line readable alone.
|
||||
if (group === "source-affected") {
|
||||
return sourceImpactSentences(surface.sourceImpact) ?? "Source-affected; not compared";
|
||||
}
|
||||
if (surface.review) return plainText(surface.review.description, MAX_DESCRIPTION_LENGTH);
|
||||
return "No visible change";
|
||||
}
|
||||
@@ -270,10 +283,12 @@ export function platformRecordOf(state: PublicCommentState, platform?: CommentPl
|
||||
for (const surface of state.review.surfaces) {
|
||||
if ((surface.head ?? surface.base)?.kind === "redirect") continue;
|
||||
const group = groupOf(surface, evidenceBased);
|
||||
if (group === "unchanged" || group === "variant") continue;
|
||||
if (group === "unlisted") continue;
|
||||
const scheme = schemeOf(surface.id);
|
||||
record.changes.push({ id: surface.id, route: routeOf(surface), group, description: descriptionOf(surface, group), ...(scheme ? { scheme } : {}) });
|
||||
}
|
||||
const notCompared = state.review.surfaces.filter(notComparedChange).length;
|
||||
if (notCompared) record.notCompared = notCompared;
|
||||
record.context = contextLines(state.review).filter(line => line.length);
|
||||
const diagnostics = [...(state.evidence?.diagnostics ?? [])];
|
||||
for (const surface of state.review.surfaces) {
|
||||
@@ -318,12 +333,12 @@ function resultCell(record: PlatformRecord): string {
|
||||
}
|
||||
case "failed": return `🟥 failed · ${inlineText(record.failure?.step ?? "capture", 48)}`;
|
||||
case "ready": {
|
||||
const changes = record.changes?.length ?? 0;
|
||||
const unavailable = record.health ? record.health.base.unavailable + record.health.head.unavailable : 0;
|
||||
const unverified = record.health ? record.health.base.unverified + record.health.head.unverified : 0;
|
||||
const failed = (record.validation?.visual?.failed ?? 0) + (record.validation?.accessibility?.failed ?? 0);
|
||||
const icon = unavailable || unverified || failed ? "🟨" : "🟩";
|
||||
return [`${icon} ${plural(changes, "change")}`, unavailable ? `${unavailable} unavailable` : undefined, unverified ? `${unverified} unattributed` : undefined,
|
||||
const notCompared = record.notCompared ?? 0;
|
||||
const icon = unavailable || unverified || failed || notCompared ? "🟨" : "🟩";
|
||||
return [`${icon} ${changeCountText(record.changes?.map(change => change.group) ?? [])}`, notCompared ? `${notCompared} not compared` : undefined, unavailable ? `${unavailable} unavailable` : undefined, unverified ? `${unverified} unattributed` : undefined,
|
||||
failed ? `${failed} comparison${failed === 1 ? "" : "s"} failed` : undefined, duration(record.startedAt, record.updatedAt)].filter(Boolean).join(" · ");
|
||||
}
|
||||
}
|
||||
@@ -363,6 +378,8 @@ function changeRows(records: PlatformRecord[]): Map<ReviewGroup, ChangeRow[]> {
|
||||
for (const change of record.changes ?? []) {
|
||||
const href = record.links.report ? surfaceLink(record.links.report, change.id) : undefined;
|
||||
const row = rows.get(change.id) ?? { id: change.id, route: change.route, group: change.group, description: change.description, perPlatform: {}, ...(change.scheme ? { scheme: change.scheme } : {}) };
|
||||
// A screen accessibility-only on one platform and visibly changed on another is listed as the visible change.
|
||||
if (strongerGroup(row.group, change.group) !== row.group) Object.assign(row, { group: change.group, description: change.description });
|
||||
row.perPlatform[record.platform] = { group: change.group, ...(href ? { href } : {}) };
|
||||
rows.set(change.id, row);
|
||||
}
|
||||
@@ -390,12 +407,14 @@ function changesSection(records: PlatformRecord[], platforms: CommentPlatform[],
|
||||
const lines: string[] = [];
|
||||
const total = [...groups.values()].reduce((sum, rows) => sum + rows.length, 0);
|
||||
lines.push(`**Changes** · ${plural(total, "screen")}${platforms.length > 1 && ready.length > 1 ? " · a screen is listed once, with a link per platform" : ""}`, "");
|
||||
if (total === 0) lines.push("No screen changed on the reviewed platforms.", "");
|
||||
// With screens left uncompared, nothing changed only among the ones compared.
|
||||
if (total === 0) lines.push(ready.some(record => record.notCompared) ? "No compared screen changed on the reviewed platforms." : "No screen changed on the reviewed platforms.", "");
|
||||
for (const group of GROUP_ORDER) {
|
||||
const rows = groups.get(group) ?? [];
|
||||
if (!rows.length) continue;
|
||||
const shown = rows.slice(0, rowCap);
|
||||
const content = ["", ...shown.map(row => renderChangeRow(row, platforms))];
|
||||
const content = ["", ...(group === "accessibility-only" ? ["Before and After look the same. What screen readers and voice control read changed.", ""] : []),
|
||||
...shown.map(row => renderChangeRow(row, platforms))];
|
||||
if (rows.length > shown.length) {
|
||||
const report = ready.find(record => record.links.report)?.links.report;
|
||||
content.push(`- ${rows.length - shown.length} more${report ? ` — ${link("Explore report", report)}` : ""}`);
|
||||
@@ -606,19 +625,28 @@ export function reviewChanges(review: PublicReview): Map<string, ChangeGroup> {
|
||||
for (const surface of review.surfaces) {
|
||||
if ((surface.head ?? surface.base)?.kind === "redirect") continue;
|
||||
const group = groupOf(surface, evidenceBased);
|
||||
if (group !== "unchanged" && group !== "variant") changes.set(surface.id, group);
|
||||
if (group !== "unlisted") changes.set(surface.id, group);
|
||||
}
|
||||
return changes;
|
||||
}
|
||||
|
||||
/** Surfaces the review calls changed (reviewer verdicts first, raw status otherwise); undefined before the review exists. */
|
||||
/** How many screens the comment lists as changed; undefined before the review exists. */
|
||||
export function reviewChangeCount(state: Pick<PublicCommentState, "review">): number | undefined {
|
||||
return state.review?.surfaces.filter(surface => surface.review ? surface.review.status !== "unchanged" && surface.review.status !== "variant"
|
||||
: surface.status !== "unchanged").length;
|
||||
return state.review ? reviewChanges(state.review).size : undefined;
|
||||
}
|
||||
|
||||
export { recordSummary, readCommentRecords };
|
||||
|
||||
/** A surface's status in the local text summary, named as the comment groups it. */
|
||||
function localStatus(surface: Surface): string {
|
||||
if (isAccessibilityOnlyChange(surface)) return "accessibility only";
|
||||
if (surface.review) return surface.review.status;
|
||||
if (surface.status === "added" || surface.status === "removed") return surface.status;
|
||||
const failed = (["base", "head"] as const).some(side => surface[side]?.kind === "screen" && !surface[`${side}Image`]
|
||||
&& surface[`${side}Outcome`] && surface[`${side}Outcome`]?.status !== "captured");
|
||||
return failed ? "unavailable" : "not compared";
|
||||
}
|
||||
|
||||
function renderLocalText(state: PublicCommentState): string {
|
||||
const pr = state.pullRequest as Extract<ReviewPresentation, { origin: "local" }>;
|
||||
const counts = state.capture;
|
||||
@@ -630,6 +658,6 @@ function renderLocalText(state: PublicCommentState): string {
|
||||
...(counts && counts.planned.base + counts.planned.head === 0 ? ["No captures selected; visual comparison was not required.", ""] : []),
|
||||
...(state.review?.surfaces.filter(s => (s.status === "added" || s.status === "removed"
|
||||
|| s.baseOutcome || s.headOutcome || s.review) && s.review?.status !== "unchanged" && s.review?.status !== "variant").map(s =>
|
||||
`- ${inlineText((s.head ?? s.base)?.route ?? s.id, 160)}: ${s.review?.status ?? (s.status === "added" || s.status === "removed" ? s.status : "not compared")}${s.note ? ` — ${inlineText(s.note.text, 500)}` : ""}`) ?? []),
|
||||
`- ${inlineText((s.head ?? s.base)?.route ?? s.id, 160)}: ${localStatus(s)}${s.note ? ` — ${inlineText(s.note.text, 500)}` : ""}`) ?? []),
|
||||
"", ...(state.review ? contextLines(state.review) : []), "Report: artifacts/report.zip", "Details: README.md, agent-mode-cost.md, issues.md", ""].join("\n");
|
||||
}
|
||||
@@ -13,8 +13,32 @@ import { deflateRawSync, inflateRawSync } from "node:zlib";
|
||||
*/
|
||||
export type CommentPlatform = "ios" | "android";
|
||||
export type RecordPhase = "pending" | "capturing" | "ready" | "failed";
|
||||
export type ChangeGroup = "added" | "modified" | "removed" | "needs-review" | "source-affected";
|
||||
export const CHANGE_GROUPS: ChangeGroup[] = ["added", "removed", "modified", "needs-review", "source-affected"];
|
||||
/**
|
||||
* `accessibility-only`: modified, but the screenshots match; only what assistive technology reads changed. A screen
|
||||
* whose source changed but that was not compared is no group: Explore reports what the captures show, not what the code
|
||||
* might do.
|
||||
*/
|
||||
export type ChangeGroup = "added" | "modified" | "removed" | "accessibility-only" | "needs-review";
|
||||
export const CHANGE_GROUPS: ChangeGroup[] = ["added", "removed", "modified", "accessibility-only", "needs-review"];
|
||||
|
||||
/**
|
||||
* "12 changes", or "3 visual changes · 12 accessibility only" when some changed only for assistive technology: those
|
||||
* are changes too (screen readers and voice control see them), but not ones a screenshot shows.
|
||||
*/
|
||||
/**
|
||||
* The group of a screen that changed on several platforms. Accessibility only says the screenshots match, so it
|
||||
* yields to any other group; otherwise the first platform's group stands, as it always has.
|
||||
*/
|
||||
export function strongerGroup(first: ChangeGroup, other: ChangeGroup): ChangeGroup {
|
||||
return first === "accessibility-only" ? other : first;
|
||||
}
|
||||
|
||||
export function changeCountText(groups: readonly ChangeGroup[]): string {
|
||||
const accessibility = groups.filter(group => group === "accessibility-only").length;
|
||||
const visual = groups.length - accessibility;
|
||||
if (!accessibility) return `${visual} change${visual === 1 ? "" : "s"}`;
|
||||
return [visual ? `${visual} visual change${visual === 1 ? "" : "s"}` : undefined, `${accessibility} accessibility only`].filter(Boolean).join(" · ");
|
||||
}
|
||||
|
||||
export type SideHealth = { planned: number; captured: number; verified: number; unverified: number; unavailable: number };
|
||||
|
||||
@@ -41,6 +65,8 @@ export type PlatformRecord = {
|
||||
};
|
||||
/** The review's changed surfaces, one per surface; `scheme` for a secondary appearance (`<route>@<scheme>`). */
|
||||
changes?: { id: string; route: string; group: ChangeGroup; description: string; scheme?: string }[];
|
||||
/** Screens whose source changed and whose captures were verified, but that got no verdict: the comparison did not run or failed. */
|
||||
notCompared?: number;
|
||||
/** Differences stated once rather than per screen (variants, app-wide source changes). */
|
||||
context?: string[];
|
||||
diagnostics?: { side?: "base" | "head"; route: string; code: string; message: string; nextAction: string }[];
|
||||
@@ -166,6 +192,7 @@ export function parsePlatformRecord(value: unknown): PlatformRecord | undefined
|
||||
&& isString(entry.message) && isString(entry.nextAction)
|
||||
? [{ ...(isSide(entry.side) ? { side: entry.side } : {}), route: entry.route, code: entry.code, message: entry.message, nextAction: entry.nextAction }] : []).slice(0, 20);
|
||||
}
|
||||
if (isCount(value.notCompared) && value.notCompared > 0) record.notCompared = value.notCompared;
|
||||
if (isCount(value.diagnosticCount)) record.diagnosticCount = value.diagnosticCount;
|
||||
if (isRecord(value.failure) && isString(value.failure.step, 200) && isString(value.failure.message)) record.failure = { step: value.failure.step, message: value.failure.message };
|
||||
if (value.superseded === true) record.superseded = true;
|
||||
@@ -207,13 +234,12 @@ export function readCommentRecords(body: string | undefined): CommentRecords {
|
||||
|
||||
/** A short result for a run that is no longer current: "🟩 34 changes", "🟨 12 changes · 4 unavailable", "🟥 failed · capture". */
|
||||
export function recordSummary(record: PlatformRecord): string {
|
||||
const changes = record.changes?.length;
|
||||
switch (record.phase) {
|
||||
case "failed": return `🟥 failed · ${record.failure?.step ?? "capture"}`;
|
||||
case "ready": {
|
||||
const unavailable = record.health ? record.health.base.unavailable + record.health.head.unavailable : 0;
|
||||
const icon = unavailable > 0 || (record.validation?.visual?.failed ?? 0) > 0 ? "🟨" : "🟩";
|
||||
return `${icon} ${changes ?? 0} change${changes === 1 ? "" : "s"}${unavailable > 0 ? ` · ${unavailable} unavailable` : ""}`;
|
||||
const icon = unavailable > 0 || (record.validation?.visual?.failed ?? 0) > 0 || record.notCompared ? "🟨" : "🟩";
|
||||
return `${icon} ${changeCountText(record.changes?.map(change => change.group) ?? [])}${unavailable > 0 ? ` · ${unavailable} unavailable` : ""}${record.notCompared ? ` · ${record.notCompared} not compared` : ""}`;
|
||||
}
|
||||
default: return "⏳ did not finish";
|
||||
}
|
||||
|
||||
@@ -10,6 +10,7 @@ import { readZipDirectory, readZipEntry } from "./zip-reader.js";
|
||||
import { reviewChangeCount, reviewDevice } from "./pr-comment-body.js";
|
||||
import type { ExplorePlatform } from "../config/explore-config.js";
|
||||
import type { ArtifactReport } from "../contracts/artifact-report.js";
|
||||
import { normalizePublicReviewForReading } from "../contracts/review-validation.js";
|
||||
import { EXPLORATION_REPORT_KIND, type ExplorationReport } from "../contracts/standalone-report.js";
|
||||
import { compareTitleMarkdown, type CompareReviewPresentation } from "../contracts/review.js";
|
||||
import { CiError, toCiError } from "../shared/ci-errors.js";
|
||||
@@ -203,7 +204,7 @@ export async function readReportZip(zip: Uint8Array): Promise<ReportZipSummary>
|
||||
if (!sha(pr.head?.sha) || !sha(pr.base?.sha) || !text(pr.head?.ref) || !text(pr.base?.ref) || !text(pr.repository) || !text(pr.title) || !text(review.runId)) {
|
||||
throw new Error("review.json does not name its repository, title and commits as a report does");
|
||||
}
|
||||
const changes = reviewChangeCount({ review });
|
||||
const changes = reviewChangeCount({ review: normalizePublicReviewForReading(review) });
|
||||
const device = reviewDevice({ runtime: { deviceModel: review.runtime?.device?.model ?? "", osVersion: review.runtime?.device?.osVersion ?? "",
|
||||
...(review.runtime?.colorSchemes ? { colorSchemes: review.runtime.colorSchemes } : {}) } });
|
||||
return { kind: "review", platform, repository: pr.repository, runId: review.runId, base: pr.base.sha, head: pr.head.sha,
|
||||
|
||||
@@ -6,8 +6,9 @@ import type { ArtifactReport } from "../contracts/artifact-report.js";
|
||||
import { EXPLORATION_REPORT_KIND, type ExplorationReport } from "../contracts/standalone-report.js";
|
||||
import { exploreCacheRoot } from "../shared/cache-root.js";
|
||||
import { MAX_METADATA_BYTES } from "./agent-api.js";
|
||||
import { normalizePublicReviewForReading } from "../contracts/review-validation.js";
|
||||
import { reviewChanges, reviewDevice } from "./pr-comment-body.js";
|
||||
import type { ChangeGroup } from "./pr-comment-record.js";
|
||||
import { strongerGroup, type ChangeGroup } from "./pr-comment-record.js";
|
||||
import { readZipDirectory, readZipEntry } from "./zip-reader.js";
|
||||
|
||||
/**
|
||||
@@ -99,9 +100,12 @@ export async function describeReports(reports: SavedReport[], extra: { subjects?
|
||||
const review = reviews[0];
|
||||
const pr = review?.pullRequest;
|
||||
if (!review || !pr) throw new Error("Not an Explore review report");
|
||||
// One surface changed on two platforms is one change, under the first platform's group, as the PR comment lists it.
|
||||
// One surface changed on two platforms is one change, under the group the PR comment lists it in (strongerGroup).
|
||||
const merged = new Map<string, ChangeGroup>();
|
||||
for (const each of reviews) if (each) for (const [id, group] of reviewChanges(each)) if (!merged.has(id)) merged.set(id, group);
|
||||
for (const each of reviews) if (each) for (const [id, group] of reviewChanges(normalizePublicReviewForReading(each))) {
|
||||
const first = merged.get(id);
|
||||
merged.set(id, first ? strongerGroup(first, group) : group);
|
||||
}
|
||||
const changes: Partial<Record<ChangeGroup, number>> = {};
|
||||
for (const group of merged.values()) changes[group] = (changes[group] ?? 0) + 1;
|
||||
const devices = [...new Set(reviews.map(each => each ? reviewDevice({ runtime: { deviceModel: each.runtime?.device?.model ?? "", osVersion: each.runtime?.device?.osVersion ?? "",
|
||||
|
||||
@@ -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 });
|
||||
@@ -277,11 +301,11 @@ function localEvidencePath(side: PublicEvidenceSide, relativePath: string): stri
|
||||
|
||||
/**
|
||||
* The verdict combines the source scope with the evidence. Only a source change makes a surface a
|
||||
* review target: a changed screen is Modified when evidence differs and Needs review when nothing
|
||||
* visible differs. A source-unchanged screen is never a review target: a difference there is the
|
||||
* same screen captured in another runtime state (a screen variant), not a change. When only
|
||||
* app-wide inputs changed, a screen without a visible difference stays Unchanged; the PR comment
|
||||
* names the app-wide change once.
|
||||
* review target: a changed screen is Modified when its evidence differs, Needs review when the
|
||||
* comparison could not tell, and Unchanged when both captures show the same thing. Explore reports
|
||||
* visual changes, so a source change nobody can see is not one. A source-unchanged screen is never a
|
||||
* review target: a difference there is the same screen captured in another runtime state (a screen
|
||||
* variant), not a change. The PR comment names an app-wide change once.
|
||||
*/
|
||||
export function decideReview(scope: SurfaceSourceScope, visual: PublicVisualVerdict, summary?: WhatChangedSummary): PublicSurfaceReview {
|
||||
const facts = summary?.facts.map((fact) => ({ category: fact.category, templateId: fact.templateId, bullet: truncate(fact.bullet) })) ?? [];
|
||||
@@ -303,8 +327,7 @@ export function decideReview(scope: SurfaceSourceScope, visual: PublicVisualVerd
|
||||
if (inconclusive) {
|
||||
return { status: "needs-review", description: truncate(visual.verdict === "needs-review" ? visualReasonText(visual) : issue ?? "Needs review") };
|
||||
}
|
||||
if (scope === "app-wide") return { status: "unchanged", description: "No visible change" };
|
||||
return { status: "needs-review", description: "Source changed; no visible difference was captured." };
|
||||
return { status: "unchanged", description: "No visible change" };
|
||||
}
|
||||
|
||||
function captureDiagnostic(surface: PlanSurface, side: "base" | "head", evidence: PublicEvidenceSide, surfaceId: string = surface.id): PublicEvidenceDiagnostic | undefined {
|
||||
@@ -464,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);
|
||||
}
|
||||
@@ -1005,7 +1005,7 @@ test("a docs-only report with zero images and no EAS build opens Screens without
|
||||
assert.deepEqual(errors, []);
|
||||
});
|
||||
|
||||
test("unverified capture diagnostics stay separate from verified Needs review and source impact filters", async t => {
|
||||
test("unverified capture diagnostics stay separate from verified Needs review, and source changes nobody compared are not changes", async t => {
|
||||
const report = reportFixture();
|
||||
const home = report.review.surfaces[0];
|
||||
const uncertain = structuredClone(home);
|
||||
@@ -1029,12 +1029,13 @@ test("unverified capture diagnostics stay separate from verified Needs review an
|
||||
await expect(page.locator(".app-shell")).toBeVisible();
|
||||
await page.getByRole("button", { name: "Screens", exact: true }).click();
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-needs-review")).toHaveCount(1);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(2);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(1);
|
||||
// The unverified /home and the never-captured /candidate changed in source only: not compared, like /untouched.
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(0);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(3);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-modified")).toHaveCount(0);
|
||||
const menu = await openChangesMenu(page);
|
||||
const chips = menu.getByRole("group", { name: "Filter changes" }).getByRole("button");
|
||||
await expect(chips).toHaveText(["Modified 0", "No visible change 1", "Source-affected 2"]);
|
||||
await expect(chips).toHaveText(["Modified 0", "No visible change 1"]);
|
||||
assert.deepEqual(errors, []);
|
||||
});
|
||||
|
||||
@@ -1068,8 +1069,8 @@ test("an existing report with operational verdicts opens as diagnostics without
|
||||
const { page, errors } = await harness(t, await archive(report), { app: true });
|
||||
await expect(page.locator(".app-shell")).toBeVisible();
|
||||
await page.getByRole("button", { name: "Screens", exact: true }).click();
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(1);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(1);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-source-affected")).toHaveCount(0);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-not-compared")).toHaveCount(2);
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-unavailable")).toHaveCount(1, "an added route whose capture failed has nothing to show");
|
||||
await expect(page.locator(".screens-page .diff-frame.diff-removed")).toHaveCount(1);
|
||||
await expect(page.locator(".diff-frame.diff-needs-review, .diff-frame.diff-modified, .diff-frame.diff-unchanged, .diff-frame.diff-added")).toHaveCount(0);
|
||||
|
||||
@@ -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);
|
||||
|
||||
}
|
||||
|
||||
@@ -103,7 +103,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
const pullRequestPath = join(root, 'pull-request.json'); await writeFile(pullRequestPath, JSON.stringify(pr));
|
||||
const environment = { PATH: process.env.PATH, HOME: root, RUNNER_TEMP: root, EXPO_TOKEN: 'test-expo-secret', GITHUB_TOKEN: 'test-github-secret',
|
||||
GITHUB_RUN_ID: '1234', GITHUB_RUN_ATTEMPT: '1', GITHUB_REPOSITORY: pr.repository, TOOLS_COMMIT: 'c'.repeat(40), EXPLORE_VIEWER_ORIGIN: 'https://viewer.example' };
|
||||
const requests = []; const comments = []; const sessions = new Map(); let currentSession; let currentPath = '/'; let sessionCounter = 0; let repackedSha; let openFailed = false; let currentScheme = 'light';
|
||||
const requests = []; const comments = []; const sessions = new Map(); let currentSession; const idleDevice = { path: '/', scheme: 'light' }; let sessionCounter = 0; let repackedSha; let openFailed = false;
|
||||
const identity = () => ({ session: 'expo-explore-runtime', appBundleId: config.app.bundleId,
|
||||
device: { id: 'device-1', name: config.device.name, platform, target: 'mobile', osVersion: '26.0', locale: 'en-US', orientation: 'portrait', colorScheme: 'light' },
|
||||
identifiers: { session: 'expo-explore-runtime', appBundleId: config.app.bundleId, deviceId: 'device-1', deviceName: config.device.name } });
|
||||
@@ -140,8 +140,8 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
return json({ jobs: [{ key: 'repack', status: 'SUCCESS', outputs: { build_id: `repacked-${repackedSha}`, platform } }] });
|
||||
}
|
||||
if (command === 'simulator:start') {
|
||||
const id = `session-${++sessionCounter}`; currentSession = id; currentPath = '/'; openFailed = false;
|
||||
const session = { id, name: value(request, '--name'), build: value(request, '--build-id') }; sessions.set(id, session);
|
||||
const id = `session-${++sessionCounter}`; currentSession = id; openFailed = false;
|
||||
const session = { id, name: value(request, '--name'), build: value(request, '--build-id'), path: '/', scheme: 'light' }; sessions.set(id, session);
|
||||
writeFileSync(join(request.cwd, '.env.eas-simulator'), `${HEADER}EAS_SIMULATOR_SESSION_ID='${id}'\nAGENT_DEVICE_DAEMON_BASE_URL='https://controller.example/${id}'\nAGENT_DEVICE_DAEMON_AUTH_TOKEN='controller-private-token'\n`);
|
||||
return { stdout: 'ready', stderr: '' };
|
||||
}
|
||||
@@ -155,6 +155,9 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
return { stdout: '', stderr: '' };
|
||||
}
|
||||
if (basename(request.command) === 'agent-device') {
|
||||
// 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;
|
||||
if (command === '--version') return { stdout: AGENT_DEVICE_VERSION, stderr: '' };
|
||||
if (command === 'open') {
|
||||
if (request.args[2]?.startsWith('sample://')) {
|
||||
@@ -162,7 +165,7 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
openFailed = true;
|
||||
return json({ success: false, error: { code: 'COMMAND_FAILED', message: 'The app is not ready for this link yet.' } });
|
||||
}
|
||||
currentPath = '/' + request.args[2].slice('sample://'.length);
|
||||
device.path = '/' + request.args[2].slice('sample://'.length);
|
||||
}
|
||||
return ok(identity());
|
||||
}
|
||||
@@ -170,17 +173,17 @@ const Navigation=createStaticNavigation(Root); export default function App(){ret
|
||||
if (command === 'wait') return ok({});
|
||||
if (command === 'alert' && request.args[1] === 'get') return json({ success: false, error: { code: 'COMMAND_FAILED', message: 'alert not found' } });
|
||||
if (command === 'snapshot') {
|
||||
const dynamic = currentPath.startsWith('/item/');
|
||||
const dynamic = device.path.startsWith('/item/');
|
||||
const destination = provider === 'expo-router'
|
||||
? { provider, pathname: currentPath, segments: dynamic ? ['item', '[id]'] : currentPath.split('/').filter(Boolean), parameters: dynamic ? { id: currentPath.slice('/item/'.length) } : {} }
|
||||
: { provider, segments: [currentPath.slice(1).replace(/^./, first => first.toUpperCase())], parameters: {} };
|
||||
? { provider, pathname: device.path, segments: dynamic ? ['item', '[id]'] : device.path.split('/').filter(Boolean), parameters: dynamic ? { id: device.path.slice('/item/'.length) } : {} }
|
||||
: { provider, segments: [device.path.slice(1).replace(/^./, first => first.toUpperCase())], parameters: {} };
|
||||
return ok({ truncated: false, nodes: [
|
||||
{ index: 0, type: 'StaticText', label: currentPath, identifier: 'screen-title', enabled: true, visible: true, rect: { x: 0, y: 0, width: 16, height: 24 } },
|
||||
...(currentPath === observerFailurePath ? [] : [{ index: 1, type: 'StaticText', label: JSON.stringify(destination), identifier: CAPTURE_OBSERVER_IDENTIFIER, enabled: true, visible: true }]),
|
||||
{ index: 0, type: 'StaticText', label: device.path, identifier: 'screen-title', enabled: true, visible: true, rect: { x: 0, y: 0, width: 16, height: 24 } },
|
||||
...(device.path === observerFailurePath ? [] : [{ index: 1, type: 'StaticText', label: JSON.stringify(destination), identifier: CAPTURE_OBSERVER_IDENTIFIER, enabled: true, visible: true }]),
|
||||
] });
|
||||
}
|
||||
if (command === 'settings') { if (request.args[1] === 'appearance') currentScheme = request.args[2]; return ok({ setting: request.args[1], value: request.args[2] }); }
|
||||
if (command === 'screenshot') { const color = createHash('sha256').update(`${currentPath}:${currentScheme}:${currentPath === '/home' ? sessions.get(currentSession).build : 'unchanged-source'}`).digest(); const data = Buffer.alloc(16 * 24 * 4); for (let i = 0; i < data.length; i += 4) { data[i] = color[0]; data[i + 1] = color[1]; data[i + 2] = color[2]; data[i + 3] = 255; } writeFileSync(request.args[1], PNG.sync.write({ width: 16, height: 24, data })); return ok({ path: request.args[1] }); }
|
||||
if (command === 'settings') { if (request.args[1] === 'appearance') device.scheme = request.args[2]; return ok({ setting: request.args[1], value: request.args[2] }); }
|
||||
if (command === 'screenshot') { const color = createHash('sha256').update(`${device.path}:${device.scheme}:${device.path === '/home' ? device.build : 'unchanged-source'}`).digest(); const data = Buffer.alloc(16 * 24 * 4); for (let i = 0; i < data.length; i += 4) { data[i] = color[0]; data[i + 1] = color[1]; data[i + 2] = color[2]; data[i + 3] = 255; } writeFileSync(request.args[1], PNG.sync.write({ width: 16, height: 24, data })); return ok({ path: request.args[1] }); }
|
||||
}
|
||||
throw new Error(`Unexpected mocked command: ${request.command} ${request.args.join(' ')}`);
|
||||
};
|
||||
|
||||
@@ -2,16 +2,44 @@ import assert from "node:assert/strict";
|
||||
import test from "node:test";
|
||||
|
||||
const { tsImport } = await import("tsx/esm/api");
|
||||
const { isVisibleChange } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
|
||||
const { isCapturedChange } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
|
||||
|
||||
test("only a change the captures show counts for Compare and Screens' Changed filter", () => {
|
||||
assert.equal(isVisibleChange({ status: "added" }), true);
|
||||
assert.equal(isVisibleChange({ status: "removed" }), true);
|
||||
assert.equal(isVisibleChange({ status: "modified" }), true);
|
||||
// The source changed but the captures look the same.
|
||||
assert.equal(isVisibleChange({ status: "modified", notVisible: true }), false);
|
||||
assert.equal(isVisibleChange({ status: "needs-review" }), false);
|
||||
assert.equal(isVisibleChange({ status: "source-affected" }), false);
|
||||
assert.equal(isVisibleChange({ status: "unchanged" }), false);
|
||||
assert.equal(isVisibleChange(undefined), false);
|
||||
assert.equal(isCapturedChange({ status: "added" }), true);
|
||||
assert.equal(isCapturedChange({ status: "removed" }), true);
|
||||
assert.equal(isCapturedChange({ status: "modified" }), true);
|
||||
// The screenshots match but the accessibility tree changed: screen readers see it, so it is reviewed.
|
||||
assert.equal(isCapturedChange({ status: "modified", accessibilityOnly: true }), true);
|
||||
// The source changed but the captures show nothing different.
|
||||
assert.equal(isCapturedChange({ status: "needs-review" }), false);
|
||||
assert.equal(isCapturedChange({ status: "source-affected" }), false);
|
||||
assert.equal(isCapturedChange({ status: "unchanged" }), false);
|
||||
assert.equal(isCapturedChange(undefined), false);
|
||||
});
|
||||
|
||||
const { splitForAssistiveTechnology } = await tsImport("../../viewer/src/utils/presented-changes.ts", import.meta.url);
|
||||
|
||||
test("What changed lists what assistive technology reads under its own heading", () => {
|
||||
const change = (id, category) => ({ id, copy: id, fact: { id, category, templateId: `${category}.x`, priority: 0, evidenceRefs: [] } });
|
||||
const changes = [change("Added button “Play”.", "element"), change("Changed accessibility label.", "accessibility")];
|
||||
const ids = ({ visible, assistive }) => [visible.map(entry => entry.id), assistive.map(entry => entry.id)];
|
||||
// Pixels differ: an added element may be visible, a label is not.
|
||||
assert.deepEqual(ids(splitForAssistiveTechnology(changes, { status: "modified" })), [["Added button “Play”."], ["Changed accessibility label."]]);
|
||||
// The screenshots match: nothing on the screen looks different, so every finding is for assistive technology.
|
||||
assert.deepEqual(ids(splitForAssistiveTechnology(changes, { status: "modified", accessibilityOnly: true })), [[], ["Added button “Play”.", "Changed accessibility label."]]);
|
||||
// A reviewer note is not a finding about the accessibility tree.
|
||||
assert.deepEqual(ids(splitForAssistiveTechnology([{ id: "review-note", copy: "Note" }], { status: "modified", accessibilityOnly: true })), [["review-note"], []]);
|
||||
});
|
||||
|
||||
const { focusCounts, focusStatusOf } = await tsImport("../../viewer/src/utils/changed-screens.ts", import.meta.url);
|
||||
|
||||
test("the Changes filter counts Accessibility only apart from Modified", () => {
|
||||
const screens = new Map([
|
||||
["a", { status: "modified" }], ["b", { status: "modified", accessibilityOnly: true }], ["c", { status: "modified", accessibilityOnly: true }],
|
||||
["d", { status: "added" }], ["e", { status: "not-compared" }], ["f", { status: "unchanged" }],
|
||||
]);
|
||||
assert.deepEqual(focusCounts({ screens }), { added: 1, modified: 1, "accessibility-only": 2, removed: 0, "needs-review": 0, "source-affected": 0 });
|
||||
assert.equal(focusStatusOf({ status: "modified", accessibilityOnly: true }), "accessibility-only");
|
||||
assert.equal(focusStatusOf({ status: "modified" }), "modified");
|
||||
assert.equal(focusStatusOf(undefined), undefined);
|
||||
});
|
||||
@@ -150,7 +150,8 @@ async function fixture(t, settings = {}) {
|
||||
app: { id: settings.wrongProject ? 'foreign-project' : PROJECT_ID, slug: 'example', ownerAccount: { name: 'acme' } },
|
||||
remoteConfig: { 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' });
|
||||
@@ -356,6 +357,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);
|
||||
|
||||
@@ -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" });
|
||||
|
||||
@@ -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 { 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');
|
||||
|
||||
@@ -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: {
|
||||
@@ -196,14 +196,15 @@ test('an OS version the simulator did not report is omitted, not shown as unknow
|
||||
assert.doesNotMatch(body, /unknown/i);
|
||||
});
|
||||
|
||||
test('without evidence the comment falls back to source statuses and says comparisons did not run', () => {
|
||||
test('without evidence the comment lists only added and removed screens and says comparisons did not run', () => {
|
||||
const plain = review([surface('care-guide', 'added'), surface('sweet-bee', 'removed'), surface('settings', 'modified'), surface('cats', 'unchanged')]);
|
||||
const body = renderPublicComment(reviewOnlyState(plain));
|
||||
assert.match(body, /<summary>🟨 Source-affected \(1\)<\/summary>/);
|
||||
assert.match(body, /\n- `\/settings` — Source\\-affected; not compared · \[iOS\]/);
|
||||
// A source change nobody compared is not a change the captures show.
|
||||
assert.deepEqual(summaries(body).slice(0, 2), ['🟩 Added (1)', '🟥 Removed (1)']);
|
||||
assert.doesNotMatch(body, /Source-affected|screen=settings/);
|
||||
assert.equal(checkRow(body, 'Visual comparison'), '| Visual comparison | 🟨 not run |');
|
||||
assert.equal(checkRow(body, 'Accessibility comparison'), '| Accessibility comparison | 🟨 not run |');
|
||||
assert.match(platformRow(body, 'iOS'), /^\| iOS \| Example 1\\\.4\\\.0 \\\(27\\\) \| 🟩 3 changes · 0s \|/);
|
||||
assert.match(platformRow(body, 'iOS'), /^\| iOS \| Example 1\\\.4\\\.0 \\\(27\\\) \| 🟨 2 changes · 1 not compared · 0s \|/, 'the uncompared /settings is counted, not hidden');
|
||||
assert.doesNotMatch(body, /Needs review|Unchanged|screen=cats/);
|
||||
});
|
||||
|
||||
@@ -261,8 +262,10 @@ test('capture problems are listed as diagnostics inside the validation block wit
|
||||
flagged.surfaces[2].headOutcome.landing = 'unverified';
|
||||
flagged.surfaces[2].review = { status: 'needs-review', description: 'old destination failure' };
|
||||
const body = renderPublicComment(state({ review: flagged, capture: { planned: { base: 3, head: 3 }, done: { base: 1, head: 2 }, baseFromCache: false } }));
|
||||
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', '🟨 Source-affected (1)', 'Validation · iOS 🟨 3/6 captured']);
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟨 3 changes · 3 unavailable · 1 unattributed · 6m 12s \|/);
|
||||
// /settings could not be compared, so it is no change: its failures are named under Validation.
|
||||
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', 'Validation · iOS 🟨 3/6 captured']);
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟨 2 changes · 3 unavailable · 1 unattributed · 6m 12s \|/);
|
||||
assert.match(body, /\n- Base · \/settings · /);
|
||||
assert.match(body, /\*\*iOS\*\* · base 1\/3 verified · 2 unavailable · head 1\/3 verified · 1 unattributed · 1 unavailable/);
|
||||
assert.match(body, /\n- Base · \/cats\/sweet\\-bee · BASE\\_SESSION\\_FAILED: base simulator disconnected; token=\\\[redacted\\\] Next action: Restart the base simulator session and rerun capture\\\./);
|
||||
assert.match(body, /\n- Head · \/cats\/care\\-guide · HEAD\\_SESSION\\_FAILED/);
|
||||
@@ -284,7 +287,7 @@ test('zero eligible pairs are visibly skipped instead of successful comparisons'
|
||||
assert.equal(checkRow(body, 'Route verification'), '| Route verification | 🟨 0/6 verified · 6 unattributed |');
|
||||
assert.equal(checkRow(body, 'Visual comparison'), '| Visual comparison | 🟨 0 compared · threshold 0.1 · 2 skipped |');
|
||||
assert.equal(checkRow(body, 'Accessibility comparison'), '| Accessibility comparison | 🟨 0 compared · 0 descriptions |');
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟨 4 changes · 6 unattributed · 6m 12s \|/);
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟨 2 changes · 6 unattributed · 6m 12s \|/, 'the uncompared modified screens are not changes');
|
||||
});
|
||||
|
||||
test('the review-only comment counts failed outcomes in planned coverage and lists the reason', () => {
|
||||
@@ -450,3 +453,64 @@ test('a report whose hosted preview is still deploying says so instead of linkin
|
||||
assert.equal(record.links.report, undefined, 'the record carries no report link while deploying');
|
||||
assert.equal(parsePlatformRecord(record).links.deploying, true, 'the deploying flag survives the comment round trip');
|
||||
});
|
||||
|
||||
test('a screen whose screenshots match but whose accessibility tree changed is listed as accessibility only, apart from the visual changes', () => {
|
||||
const accessibilityOnly = (id) => surface(id, 'modified', { extra: {
|
||||
review: { status: 'modified', description: 'Added button “Edit tempo”.', facts: [
|
||||
{ category: 'element', templateId: 'element.added', bullet: 'Added button “Edit tempo”.' },
|
||||
{ category: 'accessibility', templateId: 'accessibility.label-changed', bullet: 'Changed accessibility label from “lane-row-title-3” to “Clap”.' },
|
||||
] },
|
||||
visual: { verdict: 'unchanged', reason: 'matched', mismatchPercentage: 0, threshold: 0.1, tool: '[email protected]' },
|
||||
sourceChange: sourceChange('Labelled the lane rows.'),
|
||||
} });
|
||||
const withAccessibility = review([...evidenceReview().surfaces, accessibilityOnly('device-picker'), accessibilityOnly('enable-midi')]);
|
||||
const body = renderPublicComment(state({ review: withAccessibility, artifactOnly: true }));
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟩 3 visual changes · 2 accessibility only · 6m 12s \|/);
|
||||
assert.deepEqual(summaries(body), ['🟩 Added (1)', '🟥 Removed (1)', '🟧 Modified (1)', '🟦 Accessibility only (2)', 'Validation · iOS 🟩 10/10 captured']);
|
||||
assert.match(body, /\n\*\*Changes\*\* · 5 screens\n/);
|
||||
assert.match(body, /<summary>🟦 Accessibility only \(2\)<\/summary>\n\nBefore and After look the same\. What screen readers and voice control read changed\.\n\n- `\/device-picker` — Added button “Edit tempo”\\\. · \[iOS\]/);
|
||||
const record = parsePlatformRecord(JSON.parse(JSON.stringify(platformRecordOf(state({ review: withAccessibility, artifactOnly: true })))));
|
||||
assert.deepEqual(record.changes.filter(change => change.group === 'accessibility-only').map(change => change.id), ['device-picker', 'enable-midi'],
|
||||
'the group survives the comment round trip');
|
||||
// A comment with no accessibility-only screen keeps its plain count.
|
||||
assert.match(platformRow(renderPublicComment(state({ artifactOnly: true })), 'iOS'), /\| 🟩 3 changes · 6m 12s \|/);
|
||||
});
|
||||
|
||||
test('a comment whose only changes are for assistive technology counts just those', () => {
|
||||
const only = review([surface('device-picker', 'modified', { extra: {
|
||||
review: { status: 'modified', description: 'Changed “Play” from a text to a button.', facts: [{ category: 'accessibility', templateId: 'accessibility.role-changed', bullet: 'Changed “Play” from a text to a button.' }] },
|
||||
visual: { verdict: 'unchanged', reason: 'matched', mismatchPercentage: 0, threshold: 0.1, tool: '[email protected]' },
|
||||
sourceChange: sourceChange('Made Play a button.'),
|
||||
} })]);
|
||||
assert.match(platformRow(renderPublicComment(state({ review: only, artifactOnly: true })), 'iOS'), /\| 🟩 1 accessibility only · 6m 12s \|/);
|
||||
});
|
||||
|
||||
test('a screen accessibility-only on iOS and visibly modified on Android is listed as Modified, whichever platform comes first', async () => {
|
||||
const { platformSectionMerge } = await import('../../dist/report/pr-comment-body.js');
|
||||
const settings = (verdict) => {
|
||||
const changed = evidenceReview();
|
||||
changed.surfaces[2].visual = { ...changed.surfaces[2].visual, verdict, mismatchPercentage: verdict === 'modified' ? 3.2 : 0 };
|
||||
return changed;
|
||||
};
|
||||
const androidState = overrides => state({ artifactOnly: true, build: { ...state().build, platform: 'android' },
|
||||
runtime: { ...state().runtime, platform: 'android', deviceModel: 'EasAndroidDevice01', osVersion: '15.0' }, ...overrides });
|
||||
const ios = renderPublicComment(state({ review: settings('unchanged'), artifactOnly: true }));
|
||||
assert.ok(summaries(ios).includes('🟦 Accessibility only (1)'), 'iOS alone: the screenshots match');
|
||||
const both = platformSectionMerge(androidState({ review: settings('modified') }), 'android').merge(ios);
|
||||
assert.deepEqual(summaries(both).slice(0, 3), ['🟩 Added (1)', '🟥 Removed (1)', '🟧 Modified (1)']);
|
||||
assert.doesNotMatch(both, /Accessibility only \(|Before and After look the same/);
|
||||
assert.match(both, /\n- `\/settings` — [^\n]+ · \[iOS \(accessibility only\)\]\(<[^>]+>\) · \[Android\]\(<[^>]+>\)\n/);
|
||||
});
|
||||
|
||||
test('screens whose comparison did not run are counted as not compared, never as a green "no change"', () => {
|
||||
const uncompared = review([surface('settings', 'modified'), surface('tempo', 'modified')]);
|
||||
const body = renderPublicComment(state({ review: uncompared, artifactOnly: true }));
|
||||
assert.match(platformRow(body, 'iOS'), /\| 🟨 0 changes · 2 not compared · 6m 12s \|/);
|
||||
assert.match(body, /\nNo compared screen changed on the reviewed platforms\.\n/);
|
||||
// A screen that was never captured (outside the capture scope) stays out of the count.
|
||||
const outOfScope = surface('channel', 'modified');
|
||||
for (const key of ['baseImage', 'headImage', 'baseOutcome', 'headOutcome']) delete outOfScope[key];
|
||||
const quiet = renderPublicComment(state({ review: review([outOfScope]), artifactOnly: true, evidence: undefined, capture: { planned: { base: 0, head: 0 }, done: { base: 0, head: 0 }, baseFromCache: false } }));
|
||||
assert.match(platformRow(quiet, 'iOS'), /\| 🟩 0 changes · 6m 12s \|/);
|
||||
assert.match(quiet, /\nNo screen changed on the reviewed platforms\.\n/);
|
||||
});
|
||||
@@ -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",
|
||||
};
|
||||
@@ -210,10 +210,9 @@ test("the verdict table: source scope decides whether a screen is a review targe
|
||||
const head = await side(root, "head", manifests.head);
|
||||
const assess = (overrides, mismatches = {}) => assessPublicEvidence({ plan: plan("all", overrides), base, head,
|
||||
profile: "explore:bundle", agentDeviceCommand: "/nonexistent/agent-device", measure: measurer(mismatches) });
|
||||
// Screen-specific source change, identical evidence: still a review target.
|
||||
// Screen-specific source change, identical evidence: not a visible change, so Unchanged and not counted.
|
||||
let result = await assess({});
|
||||
assert.equal(result.surfaces.pixels.review.status, "needs-review");
|
||||
assert.equal(result.surfaces.pixels.review.description, "Source changed; no visible difference was captured.");
|
||||
assert.deepEqual(result.surfaces.pixels.review, { status: "unchanged", description: "No visible change" });
|
||||
assert.equal(result.surfaces.changed.review.status, "modified", "an accessibility fact is a visible difference");
|
||||
// Only app-wide inputs changed: no visible difference is Unchanged; a difference is Modified.
|
||||
result = await assess({ pixels: { status: "modified", reasons: ["App configuration changed: package.json"] },
|
||||
|
||||
@@ -172,7 +172,7 @@ test("reader never shows malformed original verdicts, capture outcomes, or prove
|
||||
});
|
||||
|
||||
test("a source scope allows only its verdicts, and legacy source-unchanged differences read as variants", () => {
|
||||
const allowed = { screen: ["modified", "needs-review"], "app-wide": ["modified", "needs-review", "unchanged"], none: ["unchanged", "variant"] };
|
||||
const allowed = { screen: ["modified", "needs-review", "unchanged"], "app-wide": ["modified", "needs-review", "unchanged"], none: ["unchanged", "variant"] };
|
||||
for (const [scope, statuses] of Object.entries(allowed)) {
|
||||
for (const status of ["modified", "needs-review", "unchanged", "variant"]) {
|
||||
const input = review();
|
||||
@@ -194,6 +194,13 @@ test("a source scope allows only its verdicts, and legacy source-unchanged diffe
|
||||
const read = normalizePublicReviewForReading(legacy);
|
||||
assert.deepEqual(read.surfaces[0].review, { status: "variant", description: "Runtime state differs: Removed text “84”." });
|
||||
assert.deepEqual(read.surfaces[1].review, legacy.surfaces[1].review, "a legacy source-changed verdict has no scope to re-judge");
|
||||
// A report from before 0.19.1 called a source change with matching captures "needs review": it reads as unchanged.
|
||||
const older = review();
|
||||
older.surfaces[0].review = { status: "needs-review", description: "Source changed; no visible difference was captured." };
|
||||
older.surfaces[1].review = { status: "needs-review", description: "Visual comparison was inconclusive" };
|
||||
const reread = normalizePublicReviewForReading(older);
|
||||
assert.deepEqual(reread.surfaces[0].review, { status: "unchanged", description: "No visible change" });
|
||||
assert.equal(reread.surfaces[1].review.status, "needs-review", "an inconclusive comparison still needs a look");
|
||||
});
|
||||
|
||||
test("launch evidence carries verified splash and settled frames, an mp4 with provenance, and a splash verdict only when both sides observed one", () => {
|
||||
@@ -246,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);
|
||||
}
|
||||
});
|
||||
@@ -211,7 +211,7 @@ test("public inventory preserves source classification while unverified images s
|
||||
const workspace = publicReviewToWorkspace(review);
|
||||
const { baseline, current } = workspaceSides(workspace);
|
||||
assert.deepEqual(workspace.comparison.entries.map(({ id, status }) => ({ id, status })), [
|
||||
{ id: "games-free", status: "source-affected" }, { id: "games-pro", status: "not-compared" },
|
||||
{ id: "games-free", status: "not-compared" }, { id: "games-pro", status: "not-compared" },
|
||||
{ id: "care-guide", status: "added" }, { id: "sweet-bee", status: "removed" },
|
||||
{ id: "scan-mood", status: "not-compared" }, { id: "scan-breed", status: "not-compared" },
|
||||
{ id: "home", status: "not-compared" }, { id: "camera-alias", status: "not-compared" },
|
||||
@@ -231,9 +231,9 @@ test("public inventory preserves source classification while unverified images s
|
||||
assert.ok(payload.map.screens.every((screen) => !screen.start && !screen.terminal));
|
||||
}
|
||||
const diff = diffFor(review);
|
||||
assert.equal(diff.screens.get("games-free").status, "source-affected", "Equal PNG hashes cannot prove verified destinations");
|
||||
assert.equal(diff.screens.get("games-free").status, "not-compared", "Equal PNG hashes cannot prove verified destinations");
|
||||
assert.equal(diff.screens.get("games-pro").status, "not-compared", "Different PNG hashes cannot prove a route modification");
|
||||
assert.deepEqual(diff.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 1, "not-compared": 5, unavailable: 0, variant: 0 });
|
||||
assert.deepEqual(diff.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 0, "not-compared": 6, unavailable: 0, variant: 0 });
|
||||
assert.equal(workspace.review, undefined, "The adapter must not fabricate semantic review evidence");
|
||||
assert.deepEqual(review, before, "The source publication remains immutable");
|
||||
});
|
||||
@@ -281,7 +281,7 @@ test("existing route-family presentation groups query variants without losing th
|
||||
assert.equal(scan.observationIds.length, 2);
|
||||
assert.deepEqual(scan.variantIds.map((id) => presentation.index.variants.get(id).name), ["mood", "breed"]);
|
||||
const displayed = presentBuildDiff(diff, presentation);
|
||||
assert.deepEqual(displayed.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 1, "not-compared": 3, unavailable: 0, variant: 0 });
|
||||
assert.deepEqual(displayed.counts, { added: 1, modified: 0, removed: 1, unchanged: 0, "needs-review": 0, "source-affected": 0, "not-compared": 4, unavailable: 0, variant: 0 });
|
||||
assert.equal(presentation.map.screens.length, 6);
|
||||
assert.equal(scan.title, "Scan — Instruction");
|
||||
const graph = buildObservedGraph(presentation.map, presentation.index);
|
||||
@@ -455,7 +455,7 @@ test("What changed uses commit-bound Git summaries without changing screenshot i
|
||||
review.surfaces[0].sourceChange = summary;
|
||||
const diff = diffFor(review).screens.get("games-free");
|
||||
assert.equal(diff.changeSummary, summary.summary);
|
||||
assert.equal(diff.status, "source-affected");
|
||||
assert.equal(diff.status, "not-compared");
|
||||
assert.equal(diff.beforeScreenshot, review.surfaces[0].baseImage.url);
|
||||
assert.equal(diff.afterScreenshot, review.surfaces[0].headImage.url);
|
||||
assert.doesNotMatch(diff.changeSummary, /Visual changes have not been classified/);
|
||||
@@ -583,16 +583,16 @@ test("public notes survive viewer projection without changing deterministic verd
|
||||
});
|
||||
|
||||
|
||||
test("source-only impact and untouched uncaptured inventory stay distinct from runtime verdicts", () => {
|
||||
test("a source change without a comparison is not compared, as untouched uncaptured inventory is: it is no change the captures show", () => {
|
||||
const review = fixture("changes");
|
||||
delete review.surfaces[0].baseImage;
|
||||
delete review.surfaces[0].headImage;
|
||||
const diff = diffFor(review);
|
||||
assert.equal(diff.screens.get("games-free").status, "source-affected");
|
||||
assert.equal(diff.screens.get("games-free").status, "not-compared");
|
||||
assert.equal(diff.screens.get("games-pro").status, "not-compared");
|
||||
assert.equal(diff.counts.modified, 0);
|
||||
assert.equal(diff.counts.unchanged, 0);
|
||||
assert.equal(diff.counts["source-affected"], 1);
|
||||
assert.equal(diff.counts["source-affected"], 0);
|
||||
assert.equal(review.surfaces[0].status, "modified", "source classification is retained without inventing a visual verdict");
|
||||
});
|
||||
|
||||
@@ -657,7 +657,7 @@ test("unverified captures on either side remain diagnostics and cannot become ap
|
||||
assert.equal(affected.coverage.observations, 6, "an unverified image is retained as diagnostic evidence");
|
||||
assert.match(affected.map.gaps.find(gap => gap.screenId === surface.id).message, /destination unverified/);
|
||||
const diff = diffFor(review);
|
||||
assert.equal(diff.screens.get(surface.id).status, "source-affected");
|
||||
assert.equal(diff.screens.get(surface.id).status, "not-compared");
|
||||
assert.equal(diff.screens.get(surface.id).noVisibleChange, false);
|
||||
assert.deepEqual(diff.screens.get(surface.id).reviewerChanges, []);
|
||||
assert.equal(diff.counts["needs-review"], 0);
|
||||
@@ -710,7 +710,7 @@ test("direct reads of existing operational verdicts preserve diagnostics without
|
||||
deepFreeze(input);
|
||||
publicReviewToWorkspace(input);
|
||||
const diff = diffFor(input);
|
||||
assert.equal(diff.screens.get(surface.id).status, "source-affected");
|
||||
assert.equal(diff.screens.get(surface.id).status, "not-compared");
|
||||
assert.equal(diff.counts["needs-review"], 0);
|
||||
assert.deepEqual(diff.screens.get(surface.id).reviewerChanges, []);
|
||||
assert.equal(surface.review.status, "needs-review", "the original report is not mutated by reading");
|
||||
|
||||
@@ -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]);
|
||||
});
|
||||
@@ -51,7 +51,7 @@ test('round trip: iOS and Android jobs of one run share a single comment: one ro
|
||||
assert.equal(comment.match(/^### Explore review/gm).length, 1, 'one header');
|
||||
const routeLines = comment.split('\n').filter(line => /^- `\/(added|removed|home)`/.test(line));
|
||||
assert.ok(routeLines.length >= 1, `the comment lists changed routes once:\n${comment}`);
|
||||
assert.equal(routeLines.length, 6, 'each changed screen is listed once');
|
||||
assert.equal(routeLines.length, 6, `each changed screen is listed once:\n${comment}`);
|
||||
for (const line of routeLines) assert.ok(/\[iOS\]\(/.test(line) && /\[Android\]\(/.test(line), `each changed route carries both platforms once: ${line}`);
|
||||
const projection = publicReviewProjection(android.report.review);
|
||||
for (const surface of android.report.review.surfaces) assert.ok(projection.surfaces[surface.id], `the Viewer projects the Android surface ${surface.id}`);
|
||||
|
||||
@@ -15,7 +15,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 +188,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", () => {
|
||||
|
||||
@@ -180,3 +180,29 @@ test('cached captures go after 30 days unused, then the least recently used past
|
||||
assert.deepEqual((await readdir(join(environment.EXPLORE_CACHE_DIR, 'captures', 'ios'))), ['c'.repeat(40)]);
|
||||
assert.ok(newest);
|
||||
});
|
||||
|
||||
test('a screen accessibility-only on one platform and visibly modified on the other counts as modified, whatever the order', async t => {
|
||||
const { readZipDirectory, readZipEntry } = await import('../../dist/report/zip-reader.js');
|
||||
const directory = readZipDirectory(review);
|
||||
const original = JSON.parse(new TextDecoder().decode(await readZipEntry(review, directory.get('review.json'), 50_000_000)));
|
||||
const variant = async (platform, verdict) => {
|
||||
const report = structuredClone(original);
|
||||
report.review.runtime.platform = platform;
|
||||
const surface = report.review.surfaces.find(entry => entry.id === 'expo-cats-add-9b770c554b11');
|
||||
surface.review = { status: 'modified', description: 'Changed accessibility label from “Add” to “Add a cat”.',
|
||||
facts: [{ category: 'accessibility', templateId: 'accessibility.label-changed', bullet: 'Changed accessibility label from “Add” to “Add a cat”.' }] };
|
||||
surface.visual = { ...surface.visual, verdict, mismatchPercentage: verdict === 'modified' ? 2.4 : 0 };
|
||||
const folder = await mkdtemp(join(tmpdir(), 'explore-saved-a11y-'));
|
||||
t.after(() => rm(folder, { recursive: true, force: true }));
|
||||
await writeFile(join(folder, 'review.json'), JSON.stringify(report));
|
||||
return zipReportDirectory(folder);
|
||||
};
|
||||
const ios = { platform: 'ios', zip: await variant('ios', 'unchanged') };
|
||||
const android = { platform: 'android', zip: await variant('android', 'modified') };
|
||||
const alone = (await describeReports([ios])).changes;
|
||||
assert.equal(alone['accessibility-only'], 1, 'on iOS alone the screenshots match');
|
||||
const both = (await describeReports([ios, android])).changes;
|
||||
assert.equal(both['accessibility-only'], undefined);
|
||||
assert.equal(both.modified, alone.modified + 1, 'the Android visual change is what the run counts');
|
||||
assert.deepEqual((await describeReports([android, ios])).changes, both);
|
||||
});
|
||||
@@ -327,3 +327,27 @@ test("keeps source provenance while reducing the viewer to route-level screens",
|
||||
false,
|
||||
);
|
||||
});
|
||||
|
||||
test("a route family is accessibility-only only when every changed member is", () => {
|
||||
const family = (statuses) => {
|
||||
// Screens recorded on one router path are one family.
|
||||
const members = statuses.map((_, index) => screen(`screen-${index}`, `Policy ${index}`, "/policies", [`variant-${index}`]));
|
||||
const sourceMap = mapWith(members);
|
||||
const presentation = presentationModel.presentScreensByPath(sourceMap);
|
||||
const screens = new Map(members.map((member, index) => {
|
||||
const [status, accessibilityOnly] = statuses[index];
|
||||
return [member.id, { status, changeSummary: "", reviewerChanges: [], runtimeEvidenceRefs: [], noVisibleChange: false,
|
||||
...(status !== "added" ? { beforeScreenshot: `before-${index}.png` } : {}), afterScreenshot: `after-${index}.png`,
|
||||
...(accessibilityOnly ? { accessibilityOnly: true } : {}) }];
|
||||
}));
|
||||
const presented = presentationModel.presentBuildDiff({ baselineId: "build-1", map: sourceMap, index: indexMap(sourceMap), screens,
|
||||
counts: { added: 0, modified: 0, removed: 0, unchanged: 0 } }, presentation);
|
||||
assert.equal(presented.screens.size, 1, "the members are one family");
|
||||
return [...presented.screens.values()][0];
|
||||
};
|
||||
assert.equal(family([["modified", true], ["modified", true]]).accessibilityOnly, true);
|
||||
assert.equal(family([["modified", true], ["unchanged", false]]).accessibilityOnly, true);
|
||||
// An added or visibly modified member is a visible change, so the family is not accessibility-only.
|
||||
assert.equal(family([["modified", true], ["added", false]]).accessibilityOnly, undefined);
|
||||
assert.equal(family([["modified", true], ["modified", false]]).accessibilityOnly, undefined);
|
||||
});
|
||||
@@ -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);
|
||||
});
|
||||
@@ -4,7 +4,7 @@ import { webcrypto, createHash } from "node:crypto";
|
||||
import { deflateRawSync } from "node:zlib";
|
||||
import { readFileSync } from "node:fs";
|
||||
import { PREVIEW_CIPHER, previewResponse, type PreviewEnvironment } from "../src/server/preview";
|
||||
import { loadReport, prefersHtml, prefersMarkdown } from "../../src/report/agent-api";
|
||||
import { agentApiReply, agentIndexMarkdown, loadReport, prefersHtml, prefersMarkdown } from "../../src/report/agent-api";
|
||||
import { readZipDirectory } from "../../src/report/zip-reader";
|
||||
|
||||
const subtle = webcrypto.subtle as SubtleCrypto;
|
||||
@@ -105,7 +105,7 @@ test("the token page negotiates: browsers get the shell carrying the agent index
|
||||
const shell = await browser.text();
|
||||
assert.ok(shell.startsWith("<!doctype html>"));
|
||||
assert.match(shell, /<div id="root"><section data-explore-agent-index style="[^"]*clip:rect\(0 0 0 0\)[^"]*"><h1>Expo Explore report: .* PR #\d+/);
|
||||
assert.match(shell, new RegExp(`href="${origin}/p/${token}/api/v1/screens\\?status=modified,added,removed"`));
|
||||
assert.match(shell, new RegExp(`href="${origin}/p/${token}/api/v1/screens\\?status=modified,accessibility-only,added,removed"`));
|
||||
assert.match(shell, /<\/section><\/div><script type="module"/);
|
||||
assert.equal(browser.headers.get("vary"), "Accept");
|
||||
assert.equal(browser.headers.get("link"), `<${origin}/p/${token}/api/v1>; rel="alternate"; type="application/json", <${origin}/p/${token}/llms.txt>; rel="alternate"; type="text/markdown"`);
|
||||
@@ -119,7 +119,7 @@ test("the token page negotiates: browsers get the shell carrying the agent index
|
||||
const body = await response.text();
|
||||
assert.match(body, /^# Expo Explore report: /, String(accept));
|
||||
assert.match(body, /This link stops serving the report after 2030-01-01T00:00:00.000Z/);
|
||||
assert.ok(body.includes(`(${origin}/p/${token}/api/v1/screens?status=modified,added,removed)`), body);
|
||||
assert.ok(body.includes(`(${origin}/p/${token}/api/v1/screens?status=modified,accessibility-only,added,removed)`), body);
|
||||
assert.equal(response.headers.get("content-security-policy"), browser.headers.get("content-security-policy"));
|
||||
}
|
||||
const llms = await site.get("/llms.txt", "text/html");
|
||||
@@ -286,3 +286,51 @@ test("Accept negotiation honours quality values and listing order, and wildcards
|
||||
assert.equal(prefersMarkdown("text/markdown;q=0"), false);
|
||||
assert.equal(prefersMarkdown("*/*"), false);
|
||||
});
|
||||
|
||||
test("screens count and filter by what changed visibly: a source change with matching captures is unchanged, even from an older report", async () => {
|
||||
const surface = (id: string, status: string, review: { status: string; description: string }) =>
|
||||
({ id, status, sourceScope: "screen", head: { route: `/${id}`, kind: "screen" }, base: { route: `/${id}`, kind: "screen" }, review });
|
||||
const report = { kind: "explore.report", review: { contract: "explore.review", pullRequest: { origin: "local", repository: "a/b", title: "HEAD vs main", base: { ref: "main", sha: "a".repeat(40) }, head: { ref: "HEAD", sha: "b".repeat(40) } },
|
||||
runtime: { platform: "ios" }, surfaces: [
|
||||
surface("tempo", "modified", { status: "modified", description: "Added text “Beat pulse”." }),
|
||||
surface("enable-midi", "modified", { status: "needs-review", description: "Source changed; no visible difference was captured." }),
|
||||
surface("lane-editor", "modified", { status: "needs-review", description: "Visual comparison was inconclusive" }),
|
||||
] }, assets: [] };
|
||||
const loaded = (await loadReport(zip({ "review.json": new TextEncoder().encode(JSON.stringify(report)) })))!;
|
||||
const context = { pageUrl: "http://127.0.0.1:1/p/t", platforms: ["ios"], expiresAt: null };
|
||||
const summary = JSON.parse((await agentApiReply(context, loaded, "", new URLSearchParams(), "application/json")).body as string);
|
||||
assert.deepEqual(summary.screens, { total: 3, modified: 1, unchanged: 1, "needs-review": 1 });
|
||||
const modified = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=modified"), "application/json")).body as string);
|
||||
assert.deepEqual(modified.items.map((item: { id: string }) => item.id), ["tempo"]);
|
||||
const all = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams(), "application/json")).body as string);
|
||||
const midi = all.items.find((item: { id: string }) => item.id === "enable-midi");
|
||||
assert.deepEqual([midi.status, midi.sourceStatus], ["unchanged", "modified"], "its source status is still there");
|
||||
});
|
||||
|
||||
test("statuses follow the Viewer: accessibility-only, unavailable for a failed or misattributed capture, not-compared for the rest", async () => {
|
||||
const side = (id: string) => ({ route: `/${id}`, kind: "screen" });
|
||||
const verified = { status: "captured", landing: "verified", attempts: 1 };
|
||||
const surface = (id: string, verdict: string) => ({ id, status: "modified", sourceScope: "screen", head: side(id), base: side(id),
|
||||
headImage: { sha256: "c".repeat(64) }, baseImage: { sha256: "c".repeat(64) }, headOutcome: verified, baseOutcome: verified,
|
||||
review: { status: "modified", description: "Added button “Edit tempo”." }, visual: { verdict, reason: "matched", threshold: 0.1, tool: "agent-device" } });
|
||||
const report = { kind: "explore.report", review: { contract: "explore.review", pullRequest: { origin: "local", repository: "a/b", title: "HEAD vs main", base: { ref: "main", sha: "a".repeat(40) }, head: { ref: "HEAD", sha: "b".repeat(40) } },
|
||||
runtime: { platform: "ios" }, surfaces: [surface("tempo", "modified"), surface("device-picker", "unchanged"),
|
||||
// Its source changed but nothing was compared: not a change Explore saw.
|
||||
{ id: "c-explore", status: "modified", sourceScope: "screen", head: side("c/_explore"), base: side("c/_explore") },
|
||||
// Its head capture failed, and another landed on the wrong screen: both unavailable, as the Viewer says.
|
||||
{ id: "cards", status: "modified", sourceScope: "screen", head: side("cards"), base: side("cards"), baseImage: { sha256: "c".repeat(64) },
|
||||
baseOutcome: verified, headOutcome: { status: "failed", attempts: 1, landing: "unverified" } },
|
||||
{ id: "login", status: "modified", sourceScope: "screen", head: side("login"), base: side("login"), ...{ baseImage: { sha256: "c".repeat(64) }, headImage: { sha256: "c".repeat(64) } },
|
||||
baseOutcome: verified, headOutcome: { status: "captured", attempts: 2, landing: "unverified", observed: { reason: "landing-mismatch", route: "/home", attempts: 2 } } }] }, assets: [] };
|
||||
const loaded = (await loadReport(zip({ "review.json": new TextEncoder().encode(JSON.stringify(report)) })))!;
|
||||
const context = { pageUrl: "http://127.0.0.1:1/p/t", platforms: ["ios"], expiresAt: null };
|
||||
const summary = JSON.parse((await agentApiReply(context, loaded, "", new URLSearchParams(), "application/json")).body as string);
|
||||
assert.deepEqual(summary.screens, { total: 5, modified: 1, "accessibility-only": 1, "not-compared": 1, unavailable: 2 });
|
||||
const unavailable = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=unavailable"), "application/json")).body as string);
|
||||
assert.deepEqual(unavailable.items.map((item: { id: string }) => item.id), ["cards", "login"]);
|
||||
// The index sentence names every status, so its parts add up to the total.
|
||||
assert.match(agentIndexMarkdown(context, loaded), /5 screens: 1 modified, 1 accessibility only \(screenshots match, the accessibility tree does not\), 2 unavailable, 1 not compared\./);
|
||||
assert.match(summary.links.changed, /status=modified,accessibility-only,added,removed/);
|
||||
const only = JSON.parse((await agentApiReply(context, loaded, "/screens", new URLSearchParams("status=accessibility-only"), "application/json")).body as string);
|
||||
assert.deepEqual(only.items.map((item: { id: string; status: string; sourceStatus: string }) => [item.id, item.status, item.sourceStatus]), [["device-picker", "accessibility-only", "modified"]]);
|
||||
});
|
||||
@@ -12,7 +12,7 @@ import { AppLoading } from "./components/shared/app-loading";
|
||||
import { ReportLoadingShell } from "./components/shared/report-loading-shell";
|
||||
import { screenLabel } from "./utils/screen-path";
|
||||
import { AppPill, PLATFORM_NAMES } from "./components/panels/app-pill";
|
||||
import { changedScreens, isVisibleChange, type ChangedScreen } from "./utils/changed-screens";
|
||||
import { changedScreens, focusCounts as countFocusStatuses, isCapturedChange, type ChangedScreen } from "./utils/changed-screens";
|
||||
import { MapView } from "./components/views/semantic-map";
|
||||
import { RightPanel } from "./components/panels/right";
|
||||
import { SearchCommand } from "./components/search-command";
|
||||
@@ -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 = {
|
||||
@@ -1181,16 +1185,10 @@ function ViewerApp() {
|
||||
), [presentedMap, workspace]);
|
||||
// Focus singles out diff states, so it means nothing without a baseline to diff against.
|
||||
const focusFilter = diff ? route.focus : [];
|
||||
const focusCounts = {
|
||||
added: diff?.counts.added ?? 0,
|
||||
modified: diff?.counts.modified ?? 0,
|
||||
removed: diff?.counts.removed ?? 0,
|
||||
"needs-review": diff?.counts["needs-review"] ?? 0,
|
||||
"source-affected": diff?.counts["source-affected"] ?? 0,
|
||||
};
|
||||
const focusCounts = useMemo(() => countFocusStatuses(diff), [diff]);
|
||||
const index = diff?.index ?? screenPresentation?.index;
|
||||
const compareOrder = useMemo(
|
||||
() => (diff && index ? changedScreens(diff, index).filter(entry => isVisibleChange(diff.screens.get(entry.id))) : []),
|
||||
() => (diff && index ? changedScreens(diff, index).filter(entry => isCapturedChange(diff.screens.get(entry.id))) : []),
|
||||
[diff, index],
|
||||
);
|
||||
compareOrderRef.current = compareOrder;
|
||||
|
||||
@@ -1,15 +1,16 @@
|
||||
import { diffLabel, type DiffStatus } from "../../utils/build-diff";
|
||||
import { diffClass, diffLabel, type DiffStatus } from "../../utils/build-diff";
|
||||
|
||||
/**
|
||||
* Colour ring + label chip around a screenshot item on any canvas. It sits outside the
|
||||
* item's box (negative margins) so layout geometry is untouched. Renders as a span so it can
|
||||
* sit inside a button.
|
||||
*/
|
||||
export function DiffFrame(props: { status?: DiffStatus | undefined; notVisible?: boolean | undefined; children: React.ReactNode }) {
|
||||
export function DiffFrame(props: { status?: DiffStatus | undefined; accessibilityOnly?: boolean | undefined; children: React.ReactNode }) {
|
||||
const status = props.status ?? "unchanged";
|
||||
const label = diffLabel({ status, ...(props.notVisible ? { notVisible: true as const } : {}) });
|
||||
const diff = { status, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) };
|
||||
const label = diffLabel(diff);
|
||||
return (
|
||||
<span className={`diff-frame diff-${status}`}>
|
||||
<span className={`diff-frame ${diffClass(diff)}`}>
|
||||
{status !== "unchanged" && (
|
||||
<span className="diff-label" aria-label={`${label} in this build`}>
|
||||
{label}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { CSSProperties, MouseEventHandler, ReactNode } from "react";
|
||||
import { ImageOff, PanelRight } from "lucide-react";
|
||||
import type { DiffStatus } from "../../utils/build-diff";
|
||||
import { diffClass, type DiffStatus } from "../../utils/build-diff";
|
||||
import { ScreenPathText } from "../shared/screen-path-text";
|
||||
import { DEFAULT_SCREENSHOT_SIZE, ScreenshotImage } from "../shared/screenshot-image";
|
||||
import { CanvasActiveFrame } from "./active-frame";
|
||||
@@ -15,8 +15,8 @@ export type ScreenScreenshotCardProps = {
|
||||
/** Shown in place of the image when the run recorded why there is none. */
|
||||
missingReason?: string;
|
||||
diff?: DiffStatus;
|
||||
/** A modified screen whose screenshots match: the label says the change is not visible. */
|
||||
notVisible?: boolean;
|
||||
/** A modified screen whose screenshots match: the label says only what assistive technology reads changed. */
|
||||
accessibilityOnly?: boolean;
|
||||
className?: string;
|
||||
style?: CSSProperties;
|
||||
selected?: boolean;
|
||||
@@ -56,7 +56,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
|
||||
"screen-screenshot-card",
|
||||
props.className,
|
||||
// The status class carries the frame colour to the card, so its handles can share it.
|
||||
props.diff ? `diff-${props.diff}` : undefined,
|
||||
props.diff ? diffClass({ status: props.diff, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) }) : undefined,
|
||||
props.selected ? "selected" : undefined,
|
||||
props.highlighted ? "highlighted" : undefined,
|
||||
].filter(Boolean).join(" ");
|
||||
@@ -92,7 +92,7 @@ export function ScreenScreenshotCard(props: ScreenScreenshotCardProps) {
|
||||
aria-label={props.ariaLabel ?? `Open ${props.plainTitle ? props.title : props.path}`}
|
||||
{...(props.ariaPressed !== undefined ? { "aria-pressed": props.ariaPressed } : {})}
|
||||
onClick={props.onClick}>
|
||||
<DiffFrame status={props.diff} notVisible={props.notVisible}>
|
||||
<DiffFrame status={props.diff} accessibilityOnly={props.accessibilityOnly}>
|
||||
<span className={`screen-node-image${props.screenshot ? " has-screenshot" : " is-missing"}`}>
|
||||
{props.screenshot ? (
|
||||
<ScreenshotImage
|
||||
|
||||
@@ -1,10 +1,14 @@
|
||||
import { useEffect, useRef } from "react";
|
||||
import { useEffect, useId, useRef } from "react";
|
||||
import { ChevronLeft, ChevronRight, List } from "lucide-react";
|
||||
import { ChangesMenu } from "../panels/changes-menu";
|
||||
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";
|
||||
|
||||
/**
|
||||
@@ -15,6 +19,8 @@ import type { ComparePicker } from "./compare-section";
|
||||
*/
|
||||
export function CompareNav(props: {
|
||||
status: DiffStatus;
|
||||
/** Modified only in what assistive technology reads: the mark takes that status's colour and shape. */
|
||||
accessibilityOnly?: boolean | undefined;
|
||||
route: string;
|
||||
title: string;
|
||||
/** Zero-based; below zero when the screen is not in the order. */
|
||||
@@ -39,7 +45,7 @@ export function CompareNav(props: {
|
||||
disabled={!desktop || picker.open}>
|
||||
<button type="button" className="compare-nav-picker" aria-haspopup="true"
|
||||
aria-expanded={picker.open} onClick={() => picker.onOpenChange(!picker.open)}>
|
||||
<StatusGlyph status={props.status} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
|
||||
<StatusGlyph status={props.status} accessibilityOnly={props.accessibilityOnly} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
|
||||
{/* A route that does not fit loses its start, not the end that names the screen. */}
|
||||
<code className="compare-nav-route" title={props.title}><bdi>{props.route}</bdi></code>
|
||||
</button>
|
||||
@@ -87,21 +93,68 @@ export function CompareSteps(props: {
|
||||
|
||||
/**
|
||||
* What changed on a screen, as the phone's sheet and the desktop popover both list it: CI's
|
||||
* findings as bullets, then the notes about the comparison under a hairline.
|
||||
* 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[]; 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>)}
|
||||
</ul>
|
||||
) : null}
|
||||
{assistive.length > 0 ? (
|
||||
<section className="what-changed-assistive" aria-labelledby={assistiveTitle}>
|
||||
<h4 id={assistiveTitle} className="what-changed-assistive-title">
|
||||
<span className="status-glyph-dot diff-accessibility-only" aria-hidden="true" />
|
||||
For assistive technology
|
||||
</h4>
|
||||
<p className="what-changed-assistive-context">
|
||||
{props.accessibilityOnly
|
||||
? "Before and After look the same. Only what screen readers and voice control read changed."
|
||||
: "Read by screen readers and voice control, not shown in the screenshot."}
|
||||
</p>
|
||||
<ul className="what-changed-content-list">
|
||||
{assistive.map((fact) => <li key={fact}>{fact}</li>)}
|
||||
</ul>
|
||||
</section>
|
||||
) : null}
|
||||
{props.notes.length > 0 ? (
|
||||
<div className="what-changed-content-notes">
|
||||
{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>
|
||||
);
|
||||
}
|
||||
@@ -113,13 +166,17 @@ export function WhatChangedContent(props: { facts: string[]; notes: string[] })
|
||||
*/
|
||||
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.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) => {
|
||||
@@ -149,8 +206,11 @@ export function WhatChangedPopover(props: {
|
||||
</Tooltip>
|
||||
{open ? (
|
||||
<div className="compare-what-changed-popover" role="dialog" aria-modal="false" aria-label="What changed">
|
||||
<strong className="compare-what-changed-popover-title">What changed</strong>
|
||||
<WhatChangedContent facts={props.facts} notes={props.notes} />
|
||||
{/* A screen that changed only for assistive technology has nothing else to title. */}
|
||||
{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} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
|
||||
@@ -196,6 +196,58 @@
|
||||
}
|
||||
.what-changed-content-list > li::marker { color: var(--tertiary); }
|
||||
.what-changed-content-notes { display: flex; flex-direction: column; gap: 6px; }
|
||||
/* What changed for assistive technology: its own heading, led by Accessibility only's blue square. */
|
||||
.what-changed-assistive { display: flex; flex-direction: column; gap: 6px; }
|
||||
.what-changed-content-list + .what-changed-assistive { padding-top: 12px; border-top: 1px solid var(--panel-line); }
|
||||
.what-changed-assistive-title { display: flex; align-items: center; gap: 8px; margin: 0; color: var(--text); font-size: 13px; font-weight: 600; line-height: 18px; }
|
||||
.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; }
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type CSSProperties, type ReactNode, type RefObject } from "react";
|
||||
import { ImageOff, ScanSearch } from "lucide-react";
|
||||
import type { ChangesMenuData } from "../panels/changes-menu";
|
||||
import { diffLabel, NOT_VISIBLE_HIGHLIGHT, type BuildDiff, type ScreenDiff } from "../../utils/build-diff";
|
||||
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";
|
||||
@@ -13,7 +13,7 @@ import { ToggleGroup } from "../shared/toggle-group";
|
||||
import { Tooltip } from "../shared/tooltip";
|
||||
import { DEFAULT_SCREENSHOT_RATIO, ScreenshotImage, ScreenshotPlaceholder } from "../shared/screenshot-image";
|
||||
import { ChangeOutlines, HomeIndicatorBand, StatusBarBand, SwipeCompare, SWIPE_STEP } from "../panels/visual-diff";
|
||||
import { placeholderFor, presentedChanges } from "../../utils/presented-changes";
|
||||
import { placeholderFor, presentedChanges, splitForAssistiveTechnology } from "../../utils/presented-changes";
|
||||
import { CompareNav, WhatChangedPopover } from "./compare-header";
|
||||
import "./compare-section.css";
|
||||
|
||||
@@ -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,10 +104,25 @@ 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.
|
||||
const facts = useMemo(
|
||||
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"),
|
||||
[screenDiff],
|
||||
// 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"
|
||||
&& !(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]);
|
||||
|
||||
const phone = usePhoneLayout();
|
||||
const [desktopMode, setDesktopMode] = useState<CompareMode>(() => storedMode(MODE_STORAGE_KEY, "split"));
|
||||
@@ -239,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,
|
||||
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,
|
||||
@@ -318,8 +336,9 @@ export function CompareSection(props: CompareSectionProps) {
|
||||
</>
|
||||
) : null;
|
||||
|
||||
const factCopies = facts.map((fact) => fact.copy);
|
||||
const notes = compareNotes(screenDiff, factCopies.length, statusBarIgnored, homeIndicatorIgnored);
|
||||
const factCopies = compare.split.visible.map((fact) => fact.copy);
|
||||
const assistive = compare.split.assistive.map((fact) => fact.copy);
|
||||
const notes = compareNotes(screenDiff, facts.length, statusBarIgnored, homeIndicatorIgnored);
|
||||
|
||||
return (
|
||||
<section ref={sectionRef} className="compare-section" aria-label={`Compare ${route}`}
|
||||
@@ -328,7 +347,7 @@ export function CompareSection(props: CompareSectionProps) {
|
||||
how to look at it, and what to look for. The bottom toolbar stays the same on every section. */}
|
||||
<header className="compare-top">
|
||||
<div className="compare-bar">
|
||||
<CompareNav variant="desktop" status={screenDiff.status} statusLabel={diffLabel(screenDiff)} route={route} title={title}
|
||||
<CompareNav variant="desktop" status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} statusLabel={diffLabel(screenDiff)} route={route} title={title}
|
||||
position={compare.position} count={props.order.length} picker={props.picker}
|
||||
onPrevious={compare.previous ? () => props.onSelectScreen(compare.previous!.id) : undefined}
|
||||
onNext={compare.next ? () => props.onSelectScreen(compare.next!.id) : undefined} />
|
||||
@@ -345,13 +364,14 @@ export function CompareSection(props: CompareSectionProps) {
|
||||
/>
|
||||
</div>
|
||||
<span className="toolbar-divider" aria-hidden="true" />
|
||||
<Tooltip label={screenDiff.notVisible ? NOT_VISIBLE_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom">
|
||||
<Tooltip label={screenDiff.accessibilityOnly ? ACCESSIBILITY_ONLY_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom">
|
||||
<button type="button" className="toolbar-button compare-outlines" aria-label="Highlight changes"
|
||||
aria-pressed={outlines} disabled={areas.length === 0} onClick={toggleOutlines}>
|
||||
<ScanSearch aria-hidden="true" />
|
||||
</button>
|
||||
</Tooltip>
|
||||
<WhatChangedPopover facts={factCopies} notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
|
||||
<WhatChangedPopover facts={factCopies} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
|
||||
</div>
|
||||
</header>
|
||||
|
||||
@@ -486,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,
|
||||
@@ -44,11 +44,16 @@ function ReviewModes(props: {
|
||||
*/
|
||||
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 empty = !props.onOpenChange || (props.facts.length === 0 && props.notes.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 (
|
||||
<section className="what-changed-accordion">
|
||||
@@ -60,7 +65,7 @@ function WhatChangedAccordion(props: {
|
||||
onClick={() => props.onOpenChange?.(!props.open)}>
|
||||
<span className="what-changed-toggle-title">
|
||||
What changed
|
||||
{props.facts.length > 0 ? <span className="what-changed-toggle-count">{props.facts.length}</span> : null}
|
||||
{count > 0 ? <span className="what-changed-toggle-count">{count}</span> : null}
|
||||
</span>
|
||||
<ChevronDown aria-hidden="true" />
|
||||
</button>
|
||||
@@ -68,7 +73,8 @@ function WhatChangedAccordion(props: {
|
||||
</div>
|
||||
{open ? (
|
||||
<div className="what-changed-accordion-content" id="what-changed-accordion-content">
|
||||
<WhatChangedContent facts={props.facts} notes={props.notes} />
|
||||
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
|
||||
accessibilityOnly={props.accessibilityOnly} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
|
||||
</div>
|
||||
) : null}
|
||||
</section>
|
||||
@@ -109,7 +115,8 @@ export function SidebarReview(props: CompareControllerOptions) {
|
||||
</>
|
||||
)
|
||||
: null;
|
||||
const facts = compare.facts.map((fact) => fact.copy);
|
||||
const facts = compare.split.visible.map((fact) => fact.copy);
|
||||
const assistive = compare.split.assistive.map((fact) => fact.copy);
|
||||
const notes = compareNotes(screenDiff, compare.facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
|
||||
|
||||
return (
|
||||
@@ -140,7 +147,9 @@ export function SidebarReview(props: CompareControllerOptions) {
|
||||
/>
|
||||
</div>
|
||||
|
||||
<WhatChangedAccordion facts={facts} notes={notes} open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
|
||||
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes}
|
||||
open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -17,7 +17,7 @@ import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
|
||||
import { changedScreens, compareText } from "../../utils/changed-screens";
|
||||
import "./changes.css";
|
||||
|
||||
const STATUSES: FocusStatus[] = ["added", "modified", "removed", "needs-review", "source-affected"];
|
||||
const STATUSES: FocusStatus[] = ["added", "modified", "accessibility-only", "removed", "needs-review", "source-affected"];
|
||||
|
||||
export type ChangesPanelProps = {
|
||||
diff: BuildDiff;
|
||||
@@ -176,10 +176,10 @@ export function ChangesPanel(props: ChangesPanelProps) {
|
||||
<button
|
||||
type="button"
|
||||
className={`changes-screen-row diff-${screen.status}`}
|
||||
aria-label={`Open ${screen.title}, ${DIFF_LABELS[screen.status]}, ${screen.route}`}
|
||||
aria-label={`Open ${screen.title}, ${FOCUS_LABELS[screen.status]}, ${screen.route}`}
|
||||
aria-current={screen.id === props.selectedScreenId ? "true" : undefined}
|
||||
onClick={() => props.onOpenScreen(screen.id)}>
|
||||
<StatusGlyph status={screen.status} />
|
||||
<StatusGlyph status={screen.status === "accessibility-only" ? "modified" : screen.status} accessibilityOnly={screen.status === "accessibility-only"} />
|
||||
<code className="changes-screen-path" title={screen.title}>{screen.route}</code>
|
||||
</button>
|
||||
</li>
|
||||
|
||||
@@ -23,7 +23,8 @@ import { copyImageToClipboard } from "../../utils/copy-image";
|
||||
import type { NavigationEdge } from "../../../../src/contracts/navigation-graph";
|
||||
import { navigationEdgeKey } from "../../utils/source-navigation";
|
||||
import {
|
||||
DIFF_LABELS,
|
||||
diffClass,
|
||||
diffLabel,
|
||||
type BuildDiff,
|
||||
type ScreenDiff,
|
||||
} from "../../utils/build-diff";
|
||||
@@ -111,7 +112,8 @@ function TransitionRow(props: {
|
||||
const { screen, sources, observed } = props.item;
|
||||
const targetId = screen.id;
|
||||
const screenshot = artifactUrl(screenshotForScreen(screen, props.index));
|
||||
const status = props.diff?.screens.get(targetId)?.status ?? "unchanged";
|
||||
const targetDiff = props.diff?.screens.get(targetId);
|
||||
const status = targetDiff?.status ?? "unchanged";
|
||||
const kinds = [...new Set(sources.length
|
||||
? sources.map(({ edge }) => edge.kind)
|
||||
: observed.map(transition => transition.actionKind))].sort();
|
||||
@@ -141,7 +143,7 @@ function TransitionRow(props: {
|
||||
<span className="transition-copy">
|
||||
<strong className="transition-path">{screenLabel(screen, props.index)}</strong>
|
||||
</span>
|
||||
<span className={`diff-dot diff-${status}`} title={DIFF_LABELS[status]} />
|
||||
<span className={`diff-dot ${diffClass(targetDiff ?? { status })}`} title={diffLabel(targetDiff ?? { status })} />
|
||||
<ChevronRight size={13} aria-hidden="true" />
|
||||
</button>
|
||||
</Tooltip>
|
||||
@@ -347,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 (
|
||||
|
||||
@@ -4,7 +4,7 @@ import { Tooltip } from "../shared/tooltip";
|
||||
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
|
||||
import { InspectorPanel } from "./inspector";
|
||||
import type { ChangedScreen } from "../../utils/changed-screens";
|
||||
import { diffLabel, NOT_VISIBLE_HIGHLIGHT, type BuildDiff } from "../../utils/build-diff";
|
||||
import { diffLabel, ACCESSIBILITY_ONLY_HIGHLIGHT, type BuildDiff } from "../../utils/build-diff";
|
||||
import type { MapIndex, Screen } from "../../utils/model";
|
||||
import type { TransitionDirection } from "../../utils/navigation";
|
||||
import { displayPathForScreen } from "../../utils/screen-path";
|
||||
@@ -93,7 +93,7 @@ export function RightPanel(props: RightPanelProps) {
|
||||
{/* The screen's status as Compare's header and the Changes list mark it: a dot (+ or −
|
||||
for added or removed) in the status colour, named for screen readers. */}
|
||||
{screenDiff ? (
|
||||
<StatusGlyph status={screenDiff.status} label={diffLabel(screenDiff)}
|
||||
<StatusGlyph status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} label={diffLabel(screenDiff)}
|
||||
className="inspector-diff-status" />
|
||||
) : null}
|
||||
{props.index.plainTitles ? (
|
||||
@@ -114,7 +114,7 @@ export function RightPanel(props: RightPanelProps) {
|
||||
both in place, off. */}
|
||||
{props.screen && props.diff && props.onOpenCompare ? (
|
||||
<>
|
||||
<Tooltip label={screenDiff?.notVisible ? NOT_VISIBLE_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom-end">
|
||||
<Tooltip label={screenDiff?.accessibilityOnly ? ACCESSIBILITY_ONLY_HIGHLIGHT : "Highlight changes"} shortcut={formatShortcut(SHORTCUTS.compare.outlines)} placement="bottom-end">
|
||||
<button type="button" className="icon-button inspector-highlight" aria-label="Highlight changes"
|
||||
aria-pressed={outlinable ? outlines : false} disabled={!outlinable}
|
||||
onClick={() => setOutlinesShown(!outlines)}>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -45,8 +45,9 @@ export function PhoneCompare(props: CompareControllerOptions & {
|
||||
{compare.homeIndicatorIgnored ? <HomeIndicatorBand /> : null}
|
||||
</>
|
||||
) : null;
|
||||
const facts = compare.facts.map((fact) => fact.copy);
|
||||
const notes = compareNotes(screenDiff, facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
|
||||
const facts = compare.split.visible.map((fact) => fact.copy);
|
||||
const assistive = compare.split.assistive.map((fact) => fact.copy);
|
||||
const notes = compareNotes(screenDiff, compare.facts.length, compare.statusBarIgnored, compare.homeIndicatorIgnored);
|
||||
const previous = compare.previous ? () => props.onSelectScreen(compare.previous!.id) : undefined;
|
||||
const next = compare.next ? () => props.onSelectScreen(compare.next!.id) : undefined;
|
||||
// A tap near either side of the stage steps through the screens, like the stepper in the header. It runs
|
||||
@@ -67,14 +68,14 @@ export function PhoneCompare(props: CompareControllerOptions & {
|
||||
return (
|
||||
<section className="phone-compare" aria-label={`Compare ${route}`}>
|
||||
<header className="phone-compare-head">
|
||||
<CompareNav variant="phone" status={screenDiff.status} statusLabel={diffLabel(screenDiff)} route={route} title={screen.title}
|
||||
<CompareNav variant="phone" status={screenDiff.status} accessibilityOnly={screenDiff.accessibilityOnly} statusLabel={diffLabel(screenDiff)} route={route} title={screen.title}
|
||||
position={compare.position} count={props.order.length} picker={props.picker} stepsApart />
|
||||
<button type="button" className="phone-icon-button" aria-label="Outlines" aria-pressed={compare.outlines}
|
||||
disabled={areas.length === 0} onClick={compare.toggleOutlines}>
|
||||
<ScanSearch aria-hidden="true" />
|
||||
</button>
|
||||
<button type="button" className="phone-icon-button" aria-label="What changed" aria-haspopup="dialog"
|
||||
disabled={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}
|
||||
@@ -121,7 +122,8 @@ export function PhoneCompare(props: CompareControllerOptions & {
|
||||
</div>
|
||||
|
||||
<PhoneSheet title="What changed" open={compare.factsOpen} onClose={() => compare.setFactsOpen(false)}>
|
||||
<WhatChangedContent facts={facts} notes={notes} />
|
||||
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
|
||||
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} />
|
||||
</PhoneSheet>
|
||||
</section>
|
||||
);
|
||||
|
||||
@@ -1,17 +1,18 @@
|
||||
import { Minus, Plus } from "lucide-react";
|
||||
import type { DiffStatus } from "../../utils/build-diff";
|
||||
import { diffClass, type DiffStatus } from "../../utils/build-diff";
|
||||
|
||||
/**
|
||||
* A screen's diff status as a bare glyph in the status colour: + added, − removed, a dot for the
|
||||
* rest. The Changes list marks its rows with it; a header that names the same screen uses it too.
|
||||
* With a label it is an image of that name; without one it is decoration beside text that says it.
|
||||
* An accessibility-only change is a square in its own colour, so it does not rest on colour alone.
|
||||
*/
|
||||
export function StatusGlyph(props: { status: DiffStatus; label?: string; className?: string }) {
|
||||
export function StatusGlyph(props: { status: DiffStatus; accessibilityOnly?: boolean | undefined; label?: string; className?: string }) {
|
||||
const glyph = props.status === "added" ? <Plus />
|
||||
: props.status === "removed" ? <Minus />
|
||||
: <span className="status-glyph-dot" />;
|
||||
return (
|
||||
<span className={`status-glyph diff-${props.status}${props.className ? ` ${props.className}` : ""}`}
|
||||
<span className={`status-glyph ${diffClass({ status: props.status, ...(props.accessibilityOnly ? { accessibilityOnly: true as const } : {}) })}${props.className ? ` ${props.className}` : ""}`}
|
||||
{...(props.label ? { role: "img", "aria-label": props.label } : { "aria-hidden": true })}>
|
||||
{glyph}
|
||||
</span>
|
||||
|
||||
@@ -136,6 +136,7 @@ button.screens-tree-row:hover { color: var(--text); background: var(--panel-hove
|
||||
cursor: pointer;
|
||||
}
|
||||
.screens-tree-dot[class*="diff-"] { background: var(--diff); }
|
||||
.screens-tree-dot.diff-accessibility-only { border-radius: 2px; }
|
||||
.screens-tree-dot.elsewhere { background: color-mix(in srgb, var(--modified) 50%, transparent); }
|
||||
.screens-tree-legend {
|
||||
display: flex;
|
||||
@@ -183,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. */
|
||||
|
||||
@@ -2,18 +2,20 @@ import { useEffect, useMemo, useRef, useState, type CSSProperties, type Keyboard
|
||||
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 type { BuildDiff, DiffStatus } from "../../utils/build-diff";
|
||||
import { isVisibleChange } from "../../utils/changed-screens";
|
||||
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 { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
|
||||
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
|
||||
import { PhoneSheet } from "../phone/phone-chrome";
|
||||
import "./screens.css";
|
||||
|
||||
/** The statuses a tree dot marks. The Changed filter keeps only the screens that look different (isVisibleChange). */
|
||||
/** The statuses a tree dot marks. The Changed filter keeps only the screens whose captures differ (isCapturedChange). */
|
||||
const CHANGED_STATUSES = new Set<DiffStatus>(["modified", "added", "removed", "needs-review", "source-affected"]);
|
||||
|
||||
type Filter = "changed" | "all";
|
||||
@@ -45,13 +47,13 @@ function statusOf(diff: BuildDiff | undefined, id: string): DiffStatus | undefin
|
||||
}
|
||||
|
||||
function isChanged(diff: BuildDiff | undefined, id: string): boolean {
|
||||
return isVisibleChange(diff?.screens.get(id));
|
||||
return isCapturedChange(diff?.screens.get(id));
|
||||
}
|
||||
|
||||
/** The dot beside a tree row: changed here, changed only in another appearance, or nothing. */
|
||||
function dotClass(diff: BuildDiff | undefined, elsewhere: ReadonlyMap<string, Appearance[]> | undefined, id: string): string | undefined {
|
||||
const status = statusOf(diff, id);
|
||||
if (status && CHANGED_STATUSES.has(status)) return `diff-${status}`;
|
||||
const screen = diff?.screens.get(id);
|
||||
if (screen && CHANGED_STATUSES.has(screen.status)) return diffClass(screen);
|
||||
if (elsewhere?.get(id)?.length) return "elsewhere";
|
||||
return undefined;
|
||||
}
|
||||
@@ -75,6 +77,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, "_")}`;
|
||||
}
|
||||
@@ -109,7 +131,7 @@ function ScreenCell(props: {
|
||||
{...(url ? { screenshot: url } : {})}
|
||||
{...(size ? size : {})}
|
||||
{...(status ? { diff: status } : {})}
|
||||
{...(props.diff?.screens.get(props.screen.id)?.notVisible ? { notVisible: true } : {})}
|
||||
{...(props.diff?.screens.get(props.screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {})}
|
||||
selected={props.selected}
|
||||
ariaPressed={props.selected}
|
||||
loading="lazy"
|
||||
@@ -168,6 +190,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)}>
|
||||
@@ -188,21 +211,22 @@ function TreeRows(props: {
|
||||
});
|
||||
}
|
||||
|
||||
/** Changed and Accessibility only always: a reader learns the kinds even on a report without one. */
|
||||
function Legend(props: { others: Appearance[] }) {
|
||||
return (
|
||||
<div className="screens-tree-legend">
|
||||
<span><span className="screens-tree-dot diff-modified" aria-hidden="true" />Changed</span>
|
||||
<span><span className="screens-tree-dot diff-modified diff-accessibility-only" aria-hidden="true" />Accessibility only</span>
|
||||
{props.others.length ? (
|
||||
<span><span className="screens-tree-dot elsewhere" aria-hidden="true" />Changed in {props.others.join(" and ")} only</span>
|
||||
) : null}
|
||||
<span><span className="screens-tree-dot diff-source-affected" aria-hidden="true" />Source-affected</span>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 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(
|
||||
@@ -221,6 +245,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
|
||||
@@ -320,12 +347,118 @@ 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)}
|
||||
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}
|
||||
@@ -377,28 +510,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 === statusOf(props.diff, 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>
|
||||
|
||||
|
||||
@@ -23,6 +23,7 @@ import type { BuildDiff, DiffStatus } from "../../utils/build-diff";
|
||||
import { CANVAS_MAX_ZOOM } from "../../utils/canvas-zoom";
|
||||
import { usePhoneLayout } from "../../utils/phone-layout";
|
||||
import type { FocusBehavior, FocusRequest, FocusStatus, MapDirection } from "../../utils/navigation";
|
||||
import { focusStatusOf } from "../../utils/changed-screens";
|
||||
import { displayPathForScreen } from "../../utils/screen-path";
|
||||
import { shortcutsLive } from "../../utils/shortcuts";
|
||||
import { mapKeyDirection, mapKeyTarget } from "../../utils/map-keyboard";
|
||||
@@ -58,7 +59,7 @@ type ScreenNodeData = {
|
||||
highlighted: boolean;
|
||||
direction: MapDirection;
|
||||
diff?: DiffStatus;
|
||||
notVisible?: boolean;
|
||||
accessibilityOnly?: boolean;
|
||||
projectionDelayMs?: number;
|
||||
projectionScreenScale?: number;
|
||||
projectionMotion: ProjectionMotionMetadata;
|
||||
@@ -93,7 +94,7 @@ function ScreenNodeCard({ data, selected }: NodeProps<ScreenGraphNode>) {
|
||||
{...(data.screenshot ? { screenshot: data.screenshot } : {})}
|
||||
{...(data.missingReason ? { missingReason: data.missingReason } : {})}
|
||||
{...(data.diff ? { diff: data.diff } : {})}
|
||||
{...(data.notVisible ? { notVisible: true } : {})}
|
||||
{...(data.accessibilityOnly ? { accessibilityOnly: true } : {})}
|
||||
selected={selected}
|
||||
highlighted={data.highlighted}
|
||||
style={{
|
||||
@@ -287,7 +288,8 @@ function projectionElements(
|
||||
const screenshot = structure.screenshots.get(screen.id);
|
||||
const highlighted = false;
|
||||
const status = diff?.screens.get(screen.id)?.status;
|
||||
const muted = focus.length > 0 && !focus.some((state) => state === status);
|
||||
const focusStatus = focusStatusOf(diff?.screens.get(screen.id));
|
||||
const muted = focus.length > 0 && !focus.some((state) => state === focusStatus);
|
||||
const projectionMotion: ProjectionMotionMetadata = {
|
||||
motionKey: `screen:${screen.id}`,
|
||||
role: "screen",
|
||||
@@ -318,7 +320,7 @@ function projectionElements(
|
||||
highlighted,
|
||||
direction: structure.horizontal ? "LR" : "TB",
|
||||
...(status ? { diff: status } : {}),
|
||||
...(diff?.screens.get(screen.id)?.notVisible ? { notVisible: true } : {}),
|
||||
...(diff?.screens.get(screen.id)?.accessibilityOnly ? { accessibilityOnly: true } : {}),
|
||||
projectionMotion,
|
||||
onSelect: onSelectScreen,
|
||||
onHover: onHoverScreen,
|
||||
|
||||
@@ -10,6 +10,7 @@ import type {
|
||||
import {
|
||||
captureNotes,
|
||||
visualDiff,
|
||||
type RegionMove,
|
||||
type ReviewerChangeCategory,
|
||||
type ReviewRuntimeEvidence,
|
||||
type ViewerReviewProjection,
|
||||
@@ -50,7 +51,21 @@ function comparisonStatus(surface: Surface): BuildComparisonEntry["status"] {
|
||||
if (captureUnavailable(surface, "base") || unattributed("base")) return "unavailable";
|
||||
}
|
||||
if (surface.status === "added" || surface.status === "removed") return surface.status;
|
||||
return comparisonReview(surface)?.status ?? (surface.status === "modified" ? "source-affected" : "not-compared");
|
||||
// A source change with no comparison is not a change the captures show: not compared, whatever the source did.
|
||||
return comparisonReview(surface)?.status ?? "not-compared";
|
||||
}
|
||||
|
||||
/**
|
||||
* A region's move in percent of the image, from its pixel shift and the image size its rect implies. iOS
|
||||
* screenshots are one pixel per point; Android's are in the screenshot's own pixels, since the report does not
|
||||
* know the screen's density.
|
||||
*/
|
||||
function regionMove(region: NonNullable<NonNullable<Surface["visual"]>["regions"]>[number], platform: "ios" | "android" | undefined): RegionMove | undefined {
|
||||
const { shift, rect, normalizedRect } = region;
|
||||
if (!shift || !(normalizedRect.width > 0) || !(normalizedRect.height > 0)) return undefined;
|
||||
const imageWidth = (rect.width * 100) / normalizedRect.width;
|
||||
const imageHeight = (rect.height * 100) / normalizedRect.height;
|
||||
return { x: (shift.x * 100) / imageWidth, y: (shift.y * 100) / imageHeight, amount: { x: shift.x, y: shift.y }, unit: platform === "android" ? "px" : "pt" };
|
||||
}
|
||||
|
||||
/** The side's route exists and was planned, but its capture ended without a screenshot. */
|
||||
@@ -571,10 +586,11 @@ export function publicReviewProjection(review: PublicReview): ViewerReviewProjec
|
||||
...(surface.visual?.mismatchPercentage !== undefined ? { mismatchPercentage: surface.visual.mismatchPercentage } : {}),
|
||||
...(surface.visual?.ignoredStatusBarRegions ? { ignoredStatusBarRegions: surface.visual.ignoredStatusBarRegions } : {}),
|
||||
...(surface.visual?.ignoredHomeIndicatorRegions ? { ignoredHomeIndicatorRegions: surface.visual.ignoredHomeIndicatorRegions } : {}),
|
||||
regions: (surface.visual?.regions ?? []).map((region) => ({
|
||||
...region.normalizedRect,
|
||||
share: region.shareOfDiffPercentage,
|
||||
})),
|
||||
...(surface.visual?.allRegionsMoved ? { allRegionsMoved: true } : {}),
|
||||
regions: (surface.visual?.regions ?? []).map((region) => {
|
||||
const move = regionMove(region, review.runtime.platform);
|
||||
return { ...region.normalizedRect, share: region.shareOfDiffPercentage, ...(move ? { move } : {}) };
|
||||
}),
|
||||
})
|
||||
: undefined;
|
||||
// A side that exists in its revision but has no screenshot says why, in the report's words.
|
||||
|
||||
@@ -64,6 +64,11 @@
|
||||
/* Modified is orange in both themes, as in the PR comment (🟧). Yellow means "needs review". */
|
||||
--modified: #ea580c;
|
||||
--modified-soft: #ffefd6;
|
||||
/* Accessibility only is blue, as in the PR comment (🟦), deeper than the accent a screen variant uses. */
|
||||
--accessibility: #2f6feb;
|
||||
--accessibility-soft: #e8f0fe;
|
||||
/* A measurement: slate, quieter than any change colour. */
|
||||
--moved: #5b6b85;
|
||||
--graph-dot: #d9d9e0;
|
||||
--graph-line: #8b8d98;
|
||||
--graph-line-soft: #c5c7ce;
|
||||
@@ -181,6 +186,9 @@
|
||||
--purple-soft: #301c3b;
|
||||
--modified: #ff9a3c;
|
||||
--modified-soft: #331e0b;
|
||||
--accessibility: #8fa8ff;
|
||||
--accessibility-soft: #17224a;
|
||||
--moved: #9fb0cc;
|
||||
--graph-dot: #212225;
|
||||
--graph-line: #696e77;
|
||||
--graph-line-soft: #3f4349;
|
||||
@@ -1665,6 +1673,11 @@ code {
|
||||
/* Modified reads orange everywhere: the Changes list, the canvas chip and border, the Inspector badge. */
|
||||
.diff-modified { --diff: var(--modified); --diff-soft: var(--modified-soft); }
|
||||
.diff-removed { --diff: var(--danger); --diff-soft: var(--danger-soft); }
|
||||
/* Accessibility only: modified for assistive technology, with matching screenshots. It keeps Modified's frame
|
||||
(it carries diff-modified too) in blue, and its marks are squares, so it does not rest on colour alone. */
|
||||
.diff-accessibility-only { --diff: var(--accessibility); --diff-soft: var(--accessibility-soft); }
|
||||
.diff-accessibility-only.diff-dot,
|
||||
.diff-accessibility-only .status-glyph-dot { border-radius: 2px; }
|
||||
.diff-unchanged { --diff: var(--tertiary); --diff-soft: var(--element); }
|
||||
.diff-needs-review { --diff: var(--tertiary); --diff-soft: var(--element); }
|
||||
.diff-source-affected { --diff: var(--purple); --diff-soft: var(--purple-soft); }
|
||||
|
||||
@@ -67,16 +67,28 @@ export type ScreenDiff = {
|
||||
reviewerChanges: ReviewerChangeFact[];
|
||||
runtimeEvidenceRefs: string[];
|
||||
noVisibleChange: boolean;
|
||||
/** Modified in what the review read (the accessibility tree, text), with no pixel difference: nothing to outline. */
|
||||
notVisible?: true;
|
||||
/**
|
||||
* Modified only in what assistive technology reads (the accessibility tree): the screenshots match, so there is
|
||||
* nothing to outline. Screen readers and voice control still see the change, so it is reviewed like any other.
|
||||
*/
|
||||
accessibilityOnly?: true;
|
||||
};
|
||||
|
||||
/** Why Highlight changes is off for a change that is not visible. */
|
||||
export const NOT_VISIBLE_HIGHLIGHT = "Nothing to highlight: the screenshots match";
|
||||
/** Why Highlight changes is off for an accessibility-only change. */
|
||||
export const ACCESSIBILITY_ONLY_HIGHLIGHT = "Nothing to highlight: only what assistive technology reads changed";
|
||||
|
||||
/** A screen's status as the Viewer names it: a modified screen whose screenshots match says the change is not visible. */
|
||||
export function diffLabel(diff: Pick<ScreenDiff, "status" | "notVisible">): string {
|
||||
return diff.notVisible && diff.status === "modified" ? "Changed (not visible)" : DIFF_LABELS[diff.status];
|
||||
/** A screen's status as the Viewer names it: a modified screen whose screenshots match changed for assistive technology only. */
|
||||
export function diffLabel(diff: Pick<ScreenDiff, "status" | "accessibilityOnly">): string {
|
||||
return isAccessibilityOnly(diff) ? "Accessibility only" : DIFF_LABELS[diff.status];
|
||||
}
|
||||
|
||||
export function isAccessibilityOnly(diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): boolean {
|
||||
return diff?.status === "modified" && Boolean(diff.accessibilityOnly);
|
||||
}
|
||||
|
||||
/** The class that colours a screen's status: an accessibility-only change keeps Modified's frame in its own colour. */
|
||||
export function diffClass(diff: Pick<ScreenDiff, "status" | "accessibilityOnly">): string {
|
||||
return isAccessibilityOnly(diff) ? "diff-modified diff-accessibility-only" : `diff-${diff.status}`;
|
||||
}
|
||||
|
||||
export type BuildDiff = {
|
||||
@@ -355,7 +367,7 @@ export function buildDiff(options: {
|
||||
reviewerChanges: reviewSurface?.reviewerChanges ?? [],
|
||||
runtimeEvidenceRefs: reviewSurface?.runtimeEvidenceRefs ?? [],
|
||||
noVisibleChange: screen.status === "unchanged" && (reviewSurface?.noVisibleChange ?? false),
|
||||
...(screen.status === "modified" && reviewSurface?.pixelsUnchanged ? { notVisible: true as const } : {}),
|
||||
...(screen.status === "modified" && reviewSurface?.pixelsUnchanged ? { accessibilityOnly: true as const } : {}),
|
||||
...(before ?? borrowed.before ? { beforeScreenshot: (before ?? borrowed.before)! } : {}),
|
||||
...(after ?? borrowed.after ? { afterScreenshot: (after ?? borrowed.after)! } : {}),
|
||||
...(redirectTo && (borrowed.before || borrowed.after) ? { redirectTo } : {}),
|
||||
|
||||
@@ -1,15 +1,17 @@
|
||||
import type { BuildDiff, DiffStatus, ScreenDiff } from "./build-diff";
|
||||
import { isAccessibilityOnly, type BuildDiff, type DiffStatus, type ScreenDiff } from "./build-diff";
|
||||
import type { MapIndex } from "./model";
|
||||
import { isLaunchScreen } from "./model";
|
||||
import type { FocusStatus } from "./navigation";
|
||||
import { displayPathForScreen } from "./screen-path";
|
||||
|
||||
/** Review order: the visible changes first, then what changed only for assistive technology. */
|
||||
const STATUS_ORDER: Record<FocusStatus, number> = {
|
||||
added: 0,
|
||||
modified: 1,
|
||||
removed: 2,
|
||||
"needs-review": 3,
|
||||
"source-affected": 4,
|
||||
"accessibility-only": 3,
|
||||
"needs-review": 4,
|
||||
"source-affected": 5,
|
||||
};
|
||||
|
||||
export type ChangedScreen = {
|
||||
@@ -19,17 +21,33 @@ export type ChangedScreen = {
|
||||
route: string;
|
||||
};
|
||||
|
||||
export function isChangedStatus(status: DiffStatus): status is FocusStatus {
|
||||
/** The status the Changes filter and focus match a screen on: Accessibility only apart from Modified. */
|
||||
export function focusStatusOf(diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): DiffStatus | "accessibility-only" | undefined {
|
||||
return isAccessibilityOnly(diff) ? "accessibility-only" : diff?.status;
|
||||
}
|
||||
|
||||
/** Each focus status's count: Modified counts only the visible changes, Accessibility only the rest. */
|
||||
export function focusCounts(diff: BuildDiff | undefined): Record<FocusStatus, number> {
|
||||
const counts: Record<FocusStatus, number> = { added: 0, modified: 0, "accessibility-only": 0, removed: 0, "needs-review": 0, "source-affected": 0 };
|
||||
for (const screen of diff?.screens.values() ?? []) {
|
||||
const status = focusStatusOf(screen);
|
||||
if (status && status in counts) counts[status as FocusStatus] += 1;
|
||||
}
|
||||
return counts;
|
||||
}
|
||||
|
||||
export function isChangedStatus(status: DiffStatus): status is Exclude<FocusStatus, "accessibility-only"> {
|
||||
return status !== "unchanged" && status !== "not-compared" && status !== "unavailable" && status !== "variant";
|
||||
}
|
||||
|
||||
/**
|
||||
* A change the captures show: an added or removed screen, or a modified one whose pixels differ. A screen whose
|
||||
* source changed but whose captures look the same ("No visible change", source-affected, or modified with
|
||||
* unchanged pixels) stays in the Changes list, but Compare does not step through it and Screens' Changed hides it.
|
||||
* A change the captures show: an added, removed or modified screen, including one modified only in what assistive
|
||||
* technology reads (its screenshots match, its accessibility tree does not). A screen whose source changed but whose
|
||||
* captures show nothing different ("No visible change") stays in the Changes list, but Compare does
|
||||
* not step through it and Screens' Changed hides it.
|
||||
*/
|
||||
export function isVisibleChange(diff: Pick<ScreenDiff, "status" | "notVisible"> | undefined): boolean {
|
||||
return diff !== undefined && (diff.status === "added" || diff.status === "removed" || (diff.status === "modified" && !diff.notVisible));
|
||||
export function isCapturedChange(diff: Pick<ScreenDiff, "status"> | undefined): boolean {
|
||||
return diff !== undefined && (diff.status === "added" || diff.status === "removed" || diff.status === "modified");
|
||||
}
|
||||
|
||||
export function compareText(left: string, right: string): number {
|
||||
@@ -58,7 +76,7 @@ export function changedScreens(diff: BuildDiff, index: MapIndex): ChangedScreen[
|
||||
if (!isChangedStatus(screenDiff.status)) continue;
|
||||
const screen = index.screens.get(id);
|
||||
if (!screen) continue;
|
||||
result.push({ id, status: screenDiff.status, title: screen.title, route: displayPathForScreen(screen) });
|
||||
result.push({ id, status: isAccessibilityOnly(screenDiff) ? "accessibility-only" : screenDiff.status, title: screen.title, route: displayPathForScreen(screen) });
|
||||
}
|
||||
return result.sort(compareChangedScreens);
|
||||
}
|
||||
@@ -54,7 +54,7 @@ export function handoffPrompt(input: HandoffInput, view?: HandoffView): string {
|
||||
input.pageUrl,
|
||||
"",
|
||||
`Fetch the link first${local ? " (from this machine, with curl if your fetch tool refuses local addresses)" : ""}. It explains the report's JSON API. Go through the changed screens, compare the before and after screenshots${appearances}, and tell me which changes look intended and which look like regressions. For each regression, name the source file to fix.`,
|
||||
...(local ? ["", "The link is served by `expo-explore capture:review` on this machine and stops working when it exits."] : []),
|
||||
...(local ? ["", "The link is served by `expo-explore capture` on this machine and stops working when it exits."] : []),
|
||||
];
|
||||
if (view) {
|
||||
const where = [view.screen, view.view, view.platform, view.appearance].filter(Boolean).join(" · ");
|
||||
|
||||
@@ -4,8 +4,8 @@
|
||||
* or a spinner accelerates. The browser's own key repeat is ignored (its rate is a fixed OS setting),
|
||||
* so the hold is timed here and ends on key up, blur, or the end of the list.
|
||||
*/
|
||||
export const HOLD_INITIAL_DELAY_MS = 400;
|
||||
export const HOLD_FIRST_INTERVAL_MS = 300;
|
||||
export const HOLD_INITIAL_DELAY_MS = 250;
|
||||
export const HOLD_FIRST_INTERVAL_MS = 200;
|
||||
export const HOLD_FLOOR_INTERVAL_MS = 70;
|
||||
const HOLD_DECAY = 0.8;
|
||||
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
import { useSyncExternalStore } from "react";
|
||||
import { optionalStorage } from "./embedded-report";
|
||||
|
||||
const MEASUREMENTS_STORAGE_KEY = "expo-explore:compare-measurements";
|
||||
const listeners = new Set<() => void>();
|
||||
/** The choice made this visit: storage can be denied (a private window), and the switch must still work. */
|
||||
let chosen: boolean | undefined;
|
||||
|
||||
function stored(): boolean {
|
||||
return chosen ?? optionalStorage.getItem(MEASUREMENTS_STORAGE_KEY) !== "false";
|
||||
}
|
||||
|
||||
/** Shows or hides how far each moved area moved, everywhere at once, and remembers the choice where it can. */
|
||||
export function setMeasurementsShown(shown: boolean) {
|
||||
chosen = shown;
|
||||
optionalStorage.setItem(MEASUREMENTS_STORAGE_KEY, String(shown));
|
||||
for (const listener of listeners) listener();
|
||||
}
|
||||
|
||||
/** Whether outlines label how far each moved area moved: on until a reader turns it off in What changed. */
|
||||
export function useMeasurementsShown(): boolean {
|
||||
return useSyncExternalStore(
|
||||
(onChange) => {
|
||||
listeners.add(onChange);
|
||||
return () => listeners.delete(onChange);
|
||||
},
|
||||
stored,
|
||||
() => true,
|
||||
);
|
||||
}
|
||||
@@ -8,7 +8,8 @@ export type ThemePreference = "light" | "dark" | "system";
|
||||
export type MapDirection = "TB" | "LR";
|
||||
/** The explicitly selected amount of Map hierarchy, independent from camera zoom. */
|
||||
/** The diff states the canvas can single out. An empty selection is "All": nothing drops back. */
|
||||
export type FocusStatus = "added" | "modified" | "removed" | "needs-review" | "source-affected";
|
||||
/** `accessibility-only`: a modified screen whose screenshots match, filtered apart from the visible changes. */
|
||||
export type FocusStatus = "added" | "modified" | "accessibility-only" | "removed" | "needs-review" | "source-affected";
|
||||
/** The right panel shows Session and Diff. */
|
||||
export type InspectView = "session" | "diff";
|
||||
/** Which way the inspector's transition list reads: into the screen, or out of it. */
|
||||
@@ -83,7 +84,7 @@ export type FocusRequest = {
|
||||
const CANVASES: CanvasView[] = ["map", "screens", "compare"];
|
||||
const INSPECTS: InspectView[] = ["session", "diff"];
|
||||
const DIRECTIONS: TransitionDirection[] = ["in", "out"];
|
||||
const FOCUSES: FocusStatus[] = ["added", "modified", "removed", "needs-review", "source-affected"];
|
||||
const FOCUSES: FocusStatus[] = ["added", "modified", "accessibility-only", "removed", "needs-review", "source-affected"];
|
||||
|
||||
function isCanvas(value: string | null | undefined): value is CanvasView {
|
||||
return CANVASES.includes(value as CanvasView);
|
||||
@@ -326,6 +327,7 @@ export const CANVAS_DESCRIPTIONS: Record<CanvasView, string> = {
|
||||
export const FOCUS_LABELS: Record<FocusStatus, string> = {
|
||||
added: "Added",
|
||||
modified: "Modified",
|
||||
"accessibility-only": "Accessibility only",
|
||||
removed: "Removed",
|
||||
"needs-review": "No visible change",
|
||||
"source-affected": "Source-affected",
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import type { DiffStatus, ScreenDiff } from "./build-diff";
|
||||
import { isAccessibilityOnly, type DiffStatus, type ScreenDiff } from "./build-diff";
|
||||
import { formatReviewerChange, sortReviewerChanges, type CaptureNotes, type ReviewerChangeFact } from "./review-model";
|
||||
|
||||
/** One line of "What changed": a reviewer note, a CI finding, or the legacy summary. */
|
||||
@@ -25,6 +25,19 @@ export function presentedChanges(diff: ScreenDiff | undefined): PresentedChange[
|
||||
return legacy ? [{ id: "legacy-summary", copy: legacy }] : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* What changed, split by who sees it. On a screen whose screenshots match, every finding is for assistive technology:
|
||||
* nothing on it looks different. Elsewhere only the accessibility findings (labels, roles) are, since an added
|
||||
* element or new text may well be visible.
|
||||
*/
|
||||
export function splitForAssistiveTechnology(changes: PresentedChange[], diff: Pick<ScreenDiff, "status" | "accessibilityOnly"> | undefined): {
|
||||
visible: PresentedChange[];
|
||||
assistive: PresentedChange[];
|
||||
} {
|
||||
const assistive = (change: PresentedChange) => Boolean(change.fact) && (isAccessibilityOnly(diff) || change.fact?.category === "accessibility");
|
||||
return { visible: changes.filter((change) => !assistive(change)), assistive: changes.filter(assistive) };
|
||||
}
|
||||
|
||||
/** What a missing side of a comparison shows instead of a screenshot. */
|
||||
export function placeholderFor(side: "before" | "after", status: DiffStatus, notes?: CaptureNotes): string {
|
||||
if (side === "before" && status === "added") return "Not in baseline";
|
||||
|
||||
@@ -67,6 +67,12 @@ export type ReviewRuntimeEvidenceComparison = {
|
||||
current?: ReviewRuntimeEvidence;
|
||||
};
|
||||
|
||||
/**
|
||||
* How far an area's content moved from Before to After when it is otherwise the same: in percent of the image
|
||||
* (to place the Before outline) and in the screenshot's own units (to label it). Right and down are positive.
|
||||
*/
|
||||
export type RegionMove = { x: number; y: number; amount: { x: number; y: number }; unit: "pt" | "px" };
|
||||
|
||||
/** One area of the screenshot that differs, in percent of the image width and height (0–100). */
|
||||
export type VisualDiffRegion = {
|
||||
x: number;
|
||||
@@ -75,12 +81,16 @@ export type VisualDiffRegion = {
|
||||
height: number;
|
||||
/** This region's share of all differing pixels, in percent. */
|
||||
share: number;
|
||||
/** Set when the area only moved; absent when its content changed. */
|
||||
move?: RegionMove;
|
||||
};
|
||||
|
||||
/** The CI pixel comparison of the before and after screenshots. */
|
||||
export type ReviewVisualDiff = {
|
||||
mismatchPercentage?: number;
|
||||
regions: VisualDiffRegion[];
|
||||
/** Every region CI found only moved, including ones the report leaves out: nothing on the screen changed content. */
|
||||
allRegionsMoved?: true;
|
||||
/** Diff regions inside the status-bar band that CI left out of the verdict. */
|
||||
ignoredStatusBarRegions?: number;
|
||||
/** Diff regions inside the home-indicator band (iOS, bottom) that CI left out of the verdict. */
|
||||
@@ -98,7 +108,7 @@ export type ReviewSurface = {
|
||||
reviewerChanges: ReviewerChangeFact[];
|
||||
runtimeEvidenceRefs: string[];
|
||||
noVisibleChange: boolean;
|
||||
/** CI compared both verified screenshots and found no pixel difference: whatever changed is not visible. */
|
||||
/** CI compared both verified screenshots and found no pixel difference: anything that changed is in the accessibility tree. */
|
||||
pixelsUnchanged?: true;
|
||||
/** Route this surface declares instead of rendering a screen of its own. */
|
||||
redirectTo?: string;
|
||||
@@ -260,7 +270,17 @@ function visualDiffRegion(value: unknown): VisualDiffRegion | undefined {
|
||||
const [x, y, width, height, share] = ["x", "y", "width", "height", "share"].map((key) => percent(candidate?.[key]));
|
||||
if (x === undefined || y === undefined || width === undefined || height === undefined || share === undefined) return undefined;
|
||||
if (width <= 0 || height <= 0 || x + width > 100.01 || y + height > 100.01) return undefined;
|
||||
return { x, y, width, height, share };
|
||||
const move = regionMove(candidate?.move);
|
||||
return { x, y, width, height, share, ...(move ? { move } : {}) };
|
||||
}
|
||||
|
||||
function regionMove(value: unknown): RegionMove | undefined {
|
||||
const candidate = record(value);
|
||||
const amount = record(candidate?.amount);
|
||||
const finite = (entry: unknown): entry is number => typeof entry === "number" && Number.isFinite(entry) && Math.abs(entry) <= 100;
|
||||
if (!candidate || !amount || !finite(candidate.x) || !finite(candidate.y) || !finite(amount.x) || !finite(amount.y)
|
||||
|| (candidate.unit !== "pt" && candidate.unit !== "px")) return undefined;
|
||||
return { x: candidate.x, y: candidate.y, amount: { x: amount.x, y: amount.y }, unit: candidate.unit };
|
||||
}
|
||||
|
||||
export function visualDiff(value: unknown): ReviewVisualDiff | undefined {
|
||||
@@ -276,6 +296,7 @@ export function visualDiff(value: unknown): ReviewVisualDiff | undefined {
|
||||
const ignoredHomeIndicatorRegions = count(candidate.ignoredHomeIndicatorRegions);
|
||||
return {
|
||||
regions,
|
||||
...(candidate.allRegionsMoved === true && regions.length > 0 && regions.every((region) => region.move) ? { allRegionsMoved: true as const } : {}),
|
||||
...(mismatchPercentage !== undefined ? { mismatchPercentage } : {}),
|
||||
...(ignoredStatusBarRegions !== undefined ? { ignoredStatusBarRegions } : {}),
|
||||
...(ignoredHomeIndicatorRegions !== undefined ? { ignoredHomeIndicatorRegions } : {}),
|
||||
|
||||
@@ -218,6 +218,11 @@ function aggregateStatus(statuses: readonly DiffStatus[]): DiffStatus {
|
||||
return "modified";
|
||||
}
|
||||
|
||||
function accessibilityOnlyFamily(diffs: readonly ScreenDiff[]): boolean {
|
||||
const changed = diffs.filter((diff) => diff.status === "added" || diff.status === "removed" || diff.status === "modified");
|
||||
return changed.length > 0 && changed.every((diff) => diff.status === "modified" && diff.accessibilityOnly);
|
||||
}
|
||||
|
||||
function firstDiffWithScreenshot(
|
||||
diffs: readonly ScreenDiff[],
|
||||
side: "beforeScreenshot" | "afterScreenshot",
|
||||
@@ -241,7 +246,7 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
|
||||
reviewerChanges: ScreenDiff["reviewerChanges"];
|
||||
runtimeEvidenceRefs: string[];
|
||||
noVisibleChange: boolean;
|
||||
notVisible?: true;
|
||||
accessibilityOnly?: true;
|
||||
} {
|
||||
const first = diffs[0];
|
||||
if (!first) throw new Error("Cannot present an empty diff family");
|
||||
@@ -251,7 +256,6 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
|
||||
const beforeDiff = firstDiffWithScreenshot(diffs, "beforeScreenshot");
|
||||
const afterDiff = firstDiffWithScreenshot(diffs, "afterScreenshot");
|
||||
const primary = paired ?? afterDiff ?? beforeDiff ?? first;
|
||||
const modified = diffs.filter((diff) => diff.status === "modified");
|
||||
const reviewerChanges = [...new Map(diffs
|
||||
.flatMap((diff) => diff.reviewerChanges ?? [])
|
||||
.map((change) => [change.id, change])).values()];
|
||||
@@ -263,8 +267,8 @@ function familyEvidence(diffs: readonly ScreenDiff[]): {
|
||||
reviewerChanges,
|
||||
runtimeEvidenceRefs,
|
||||
noVisibleChange: diffs.some((diff) => diff.noVisibleChange),
|
||||
// Not visible only when no modified member of the family shows a difference.
|
||||
...(modified.length > 0 && modified.every((diff) => diff.notVisible) ? { notVisible: true as const } : {}),
|
||||
// Accessibility only when every changed member is: an added, removed or visibly modified member is a visible change.
|
||||
...(accessibilityOnlyFamily(diffs) ? { accessibilityOnly: true as const } : {}),
|
||||
...(primary.captureNotes ? { captureNotes: primary.captureNotes } : {}),
|
||||
// A redirect's screenshots belong to the route it declares; the panel must keep saying so.
|
||||
...(primary.redirectTo ? { redirectTo: primary.redirectTo } : {}),
|
||||
|
||||
@@ -228,6 +228,22 @@ export type ScreenTreeIndex = {
|
||||
parents: Map<string, string>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Every screen in the order the tree lists it: depth first, so a subfolder's screens follow its parent folder's own,
|
||||
* where sections list folders in the order they were found. A screen the tree leaves out comes last.
|
||||
*/
|
||||
export function treeScreenOrder(tree: ScreenTree): string[] {
|
||||
const ids: string[] = [];
|
||||
const walk = (nodes: readonly ScreenTreeNode[]) => {
|
||||
for (const node of nodes) {
|
||||
if (node.kind === "screen") ids.push(node.screenId);
|
||||
walk(node.children);
|
||||
}
|
||||
};
|
||||
walk(tree.tree);
|
||||
return [...new Set([...ids, ...tree.sections.flatMap(section => section.screenIds)])];
|
||||
}
|
||||
|
||||
export function treeIndex(tree: readonly ScreenTreeNode[]): ScreenTreeIndex {
|
||||
const index: ScreenTreeIndex = { keys: [], screensUnder: new Map(), ancestors: new Map(), parents: new Map() };
|
||||
const walk = (nodes: readonly ScreenTreeNode[], above: string[]): string[] => nodes.flatMap((node) => {
|
||||
|
||||
@@ -7,6 +7,8 @@ export type Shortcut = {
|
||||
code: string;
|
||||
/** ⌘ on Apple keyboards, Ctrl everywhere else. */
|
||||
mod?: boolean;
|
||||
/** The Control key itself on every keyboard, for chords whose ⌘ form the browser keeps (⌘1–⌘9 switch tabs). */
|
||||
ctrl?: boolean;
|
||||
/** ⌥ on Apple keyboards, Alt everywhere else. */
|
||||
alt?: boolean;
|
||||
shift?: boolean;
|
||||
@@ -17,6 +19,12 @@ export type Shortcut = {
|
||||
const APPLE = typeof navigator !== "undefined"
|
||||
&& /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent);
|
||||
|
||||
/**
|
||||
* Whether Ctrl+1–3 reach the page. On Apple keyboards ⌃ is free (the browser's tab keys are ⌘1–9); elsewhere the
|
||||
* browser keeps Ctrl+1–8 for its tabs, so those keys are neither handled nor printed there.
|
||||
*/
|
||||
export const CANVAS_NUMBER_KEYS = APPLE;
|
||||
|
||||
function mod(code: string, key: string): Shortcut {
|
||||
return { code, key, mod: true };
|
||||
}
|
||||
@@ -25,6 +33,10 @@ function modShift(code: string, key: string): Shortcut {
|
||||
return { code, key, mod: true, shift: true };
|
||||
}
|
||||
|
||||
function ctrl(code: string, key: string): Shortcut {
|
||||
return { code, key, ctrl: true };
|
||||
}
|
||||
|
||||
function shift(code: string, key: string): Shortcut {
|
||||
return { code, key, shift: true };
|
||||
}
|
||||
@@ -68,6 +80,12 @@ export const SHORTCUTS = {
|
||||
screens: plain("KeyS", "S"),
|
||||
compare: plain("KeyC", "C"),
|
||||
},
|
||||
/** The canvases by their place in the toolbar, as tabs are numbered elsewhere. Apple keyboards only (CANVAS_NUMBER_KEYS). */
|
||||
canvasByNumber: {
|
||||
map: ctrl("Digit1", "1"),
|
||||
screens: ctrl("Digit2", "2"),
|
||||
compare: ctrl("Digit3", "3"),
|
||||
},
|
||||
/** Compare only. The arrows walk changed screens; J and K walk the changed areas of one. */
|
||||
compare: {
|
||||
previousScreen: plain("ArrowLeft", "←"),
|
||||
@@ -92,10 +110,10 @@ export const SHORTCUTS = {
|
||||
/** The hint, in the idiom of the keyboard reading it: Apple's ⌥⇧⌘ order, or Ctrl+Alt+Shift. */
|
||||
export function formatShortcut(shortcut: Shortcut, apple = APPLE): string {
|
||||
if (apple) {
|
||||
return `${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${shortcut.mod ? "⌘" : ""}${shortcut.key}`;
|
||||
return `${shortcut.ctrl ? "⌃" : ""}${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${shortcut.mod ? "⌘" : ""}${shortcut.key}`;
|
||||
}
|
||||
const parts: string[] = [];
|
||||
if (shortcut.mod) parts.push("Ctrl");
|
||||
if (shortcut.mod || shortcut.ctrl) parts.push("Ctrl");
|
||||
if (shortcut.alt) parts.push("Alt");
|
||||
if (shortcut.shift) parts.push("Shift");
|
||||
parts.push(shortcut.key);
|
||||
@@ -104,7 +122,9 @@ export function formatShortcut(shortcut: Shortcut, apple = APPLE): string {
|
||||
|
||||
export function matchesShortcut(event: KeyboardEvent, shortcut: Shortcut): boolean {
|
||||
if (event.code !== shortcut.code) return false;
|
||||
if ((event.metaKey || event.ctrlKey) !== Boolean(shortcut.mod)) return false;
|
||||
if (shortcut.ctrl) {
|
||||
if (!event.ctrlKey || event.metaKey) return false;
|
||||
} else if ((event.metaKey || event.ctrlKey) !== Boolean(shortcut.mod)) return false;
|
||||
if (event.shiftKey !== Boolean(shortcut.shift)) return false;
|
||||
return event.altKey === Boolean(shortcut.alt);
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import type { VisualDiffRegion } from "./review-model";
|
||||
import type { RegionMove, VisualDiffRegion } from "./review-model";
|
||||
|
||||
/** A rectangle in percent of the image width and height (0–100). */
|
||||
export type PercentRect = { x: number; y: number; width: number; height: number };
|
||||
@@ -8,18 +8,69 @@ export type VisualChange = PercentRect & {
|
||||
/** This change's share of all differing pixels, in percent. */
|
||||
share: number;
|
||||
regionCount: number;
|
||||
/** Set when every region in it only moved, by the same amount: their average, which places and labels the outline. */
|
||||
move?: RegionMove;
|
||||
/** The least and most its regions moved, in the screenshot's units, which keeps a merged outline to one amount. */
|
||||
moveRange?: { x: [number, number]; y: [number, number] };
|
||||
};
|
||||
|
||||
/**
|
||||
* Areas moved by the same amount when their moves are within this of each other, in the screenshot's units. Parts of
|
||||
* one rigid sheet measure up to a third apart (re-rasterized text), so a third is the same move; rows that drifted by
|
||||
* half a point or more (1, 1.5, 2pt down a list) keep their own outlines.
|
||||
*/
|
||||
const SAME_MOVE = 0.34;
|
||||
/**
|
||||
* The most the regions in one outline may differ, together. Measuring a move from re-rasterized text is good to
|
||||
* about this: a sheet that moved 4.17pt as a whole measures 3.8–4.3pt across its parts (brentvatne/euxy#161).
|
||||
*/
|
||||
const MAX_MOVE_SPREAD = 0.5;
|
||||
|
||||
function sameMove(a: VisualChange, b: VisualChange): boolean {
|
||||
if (!a.move || !b.move) return !a.move && !b.move;
|
||||
const first = rangeOf(a), second = rangeOf(b);
|
||||
const same = (axis: "x" | "y") => {
|
||||
const low = Math.min(first[axis][0], second[axis][0]), high = Math.max(first[axis][1], second[axis][1]);
|
||||
// One direction only: content that moved up and content that moved down did not move together.
|
||||
return Math.abs(a.move!.amount[axis] - b.move!.amount[axis]) <= SAME_MOVE + 1e-6
|
||||
&& high - low <= MAX_MOVE_SPREAD + 1e-6 && (low >= -0.25 || high <= 0.25);
|
||||
};
|
||||
return same("x") && same("y");
|
||||
}
|
||||
|
||||
function overlaps(a: PercentRect, b: PercentRect): boolean {
|
||||
return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
|
||||
}
|
||||
|
||||
/** Two moves as one, weighted by each change's share of the difference. */
|
||||
function mergedMove(a: VisualChange, b: VisualChange): RegionMove | undefined {
|
||||
if (!a.move || !b.move) return undefined;
|
||||
const total = a.share + b.share || 1;
|
||||
const mix = (first: number, second: number) => (first * a.share + second * b.share) / total;
|
||||
return { x: mix(a.move.x, b.move.x), y: mix(a.move.y, b.move.y), unit: a.move.unit,
|
||||
amount: { x: mix(a.move.amount.x, b.move.amount.x), y: mix(a.move.amount.y, b.move.amount.y) } };
|
||||
}
|
||||
|
||||
/** Regions closer than this, in percent of the image height, read as one change. */
|
||||
const VERTICAL_GAP = 1.5;
|
||||
/** Regions closer than this, in percent of the image width, read as one change. */
|
||||
const HORIZONTAL_GAP = 3;
|
||||
|
||||
function near(a: PercentRect, b: PercentRect): boolean {
|
||||
return a.x <= b.x + b.width + HORIZONTAL_GAP
|
||||
&& b.x <= a.x + a.width + HORIZONTAL_GAP
|
||||
&& a.y <= b.y + b.height + VERTICAL_GAP
|
||||
&& b.y <= a.y + a.height + VERTICAL_GAP;
|
||||
/**
|
||||
* Areas that moved by the same amount moved together (a sheet, a card and the rows under it), so they read as one
|
||||
* across a wider gap: the content between them moved too, it just has no edges for CI to see.
|
||||
*/
|
||||
const MOVED_VERTICAL_GAP = 8;
|
||||
const MOVED_HORIZONTAL_GAP = 10;
|
||||
|
||||
function near(a: VisualChange, b: VisualChange): boolean {
|
||||
const moved = Boolean(a.move && b.move);
|
||||
const horizontal = moved ? MOVED_HORIZONTAL_GAP : HORIZONTAL_GAP;
|
||||
const vertical = moved ? MOVED_VERTICAL_GAP : VERTICAL_GAP;
|
||||
return a.x <= b.x + b.width + horizontal
|
||||
&& b.x <= a.x + a.width + horizontal
|
||||
&& a.y <= b.y + b.height + vertical
|
||||
&& b.y <= a.y + a.height + vertical;
|
||||
}
|
||||
|
||||
function union(a: VisualChange, b: VisualChange): VisualChange {
|
||||
@@ -32,9 +83,19 @@ function union(a: VisualChange, b: VisualChange): VisualChange {
|
||||
height: Math.max(a.y + a.height, b.y + b.height) - y,
|
||||
share: a.share + b.share,
|
||||
regionCount: a.regionCount + b.regionCount,
|
||||
...(mergedMove(a, b) ? { move: mergedMove(a, b)!, moveRange: {
|
||||
x: [Math.min(rangeOf(a).x[0], rangeOf(b).x[0]), Math.max(rangeOf(a).x[1], rangeOf(b).x[1])],
|
||||
y: [Math.min(rangeOf(a).y[0], rangeOf(b).y[0]), Math.max(rangeOf(a).y[1], rangeOf(b).y[1])],
|
||||
} } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
/** A change's move range: its own, or its single move's amount. */
|
||||
function rangeOf(change: VisualChange): { x: [number, number]; y: [number, number] } {
|
||||
const amount = change.move?.amount ?? { x: 0, y: 0 };
|
||||
return change.moveRange ?? { x: [amount.x, amount.x], y: [amount.y, amount.y] };
|
||||
}
|
||||
|
||||
/**
|
||||
* CI reports many small regions for one visible change (a card that grew reports its text rows,
|
||||
* its badge and its border). Merge regions that touch or nearly touch until none do, then order
|
||||
@@ -50,9 +111,13 @@ export function groupVisualRegions(regions: readonly VisualDiffRegion[]): Visual
|
||||
merged = false;
|
||||
outer: for (let i = 0; i < changes.length; i += 1) {
|
||||
for (let j = i + 1; j < changes.length; j += 1) {
|
||||
if (!near(changes[i]!, changes[j]!)) continue;
|
||||
// A moved area and a changed one stay apart, as do areas that moved by different amounts.
|
||||
if (!near(changes[i]!, changes[j]!) || !sameMove(changes[i]!, changes[j]!)) continue;
|
||||
const combined = union(changes[i]!, changes[j]!);
|
||||
// Nor does one moved outline grow around a changed area: that content did not move, it changed.
|
||||
if (combined.move && changes.some((change, index) => index !== i && index !== j && !change.move && overlaps(combined, change))) continue;
|
||||
const next = changes.filter((_, index) => index !== i && index !== j);
|
||||
next.push(union(changes[i]!, changes[j]!));
|
||||
next.push(combined);
|
||||
changes = next;
|
||||
merged = true;
|
||||
break outer;
|
||||
@@ -64,6 +129,42 @@ export function groupVisualRegions(regions: readonly VisualDiffRegion[]): Visual
|
||||
return changes.sort((a, b) => a.y - b.y || a.x - b.x);
|
||||
}
|
||||
|
||||
/** "1.3" for 1.33, "4" for 4.04: a move to a tenth, about as fine as measuring it from pixels gets. */
|
||||
function amount(value: number): string {
|
||||
return (Math.round(Math.abs(value) * 10) / 10).toString();
|
||||
}
|
||||
|
||||
/** A change's move as its outline labels it: "↑4.1pt", "↓1.3pt", "→2 ↓1pt". A part under a quarter is left out. */
|
||||
export function formatMove(change: Pick<VisualChange, "move">): string {
|
||||
const move = change.move;
|
||||
if (!move) return "";
|
||||
const { x, y } = move.amount;
|
||||
const horizontal = `${x < 0 ? "←" : "→"}${amount(x)}`, vertical = `${y < 0 ? "↑" : "↓"}${amount(y)}`;
|
||||
const parts = [...(Math.abs(x) >= 0.25 ? [horizontal] : []), ...(Math.abs(y) >= 0.25 ? [vertical] : [])];
|
||||
// Merged diagonal nudges can average under a quarter on both axes; the larger still says which way.
|
||||
return `${parts.length ? parts.join(" ") : Math.abs(y) >= Math.abs(x) ? vertical : horizontal}${move.unit}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* How far the areas of a screen whose every changed area only moved went, a line per direction: "2 areas moved up
|
||||
* 4pt", "3 areas moved down 1–2pt". Undefined when any area's content changed.
|
||||
*/
|
||||
export function layoutShiftSummary(changes: readonly VisualChange[]): string[] | undefined {
|
||||
if (changes.length === 0 || changes.some((change) => !change.move)) return undefined;
|
||||
const groups = new Map<string, number[]>();
|
||||
for (const change of changes) {
|
||||
const { x, y } = change.move!.amount;
|
||||
const vertical = Math.abs(y) >= Math.abs(x);
|
||||
const direction = vertical ? (y < 0 ? "up" : "down") : (x < 0 ? "left" : "right");
|
||||
groups.set(direction, [...(groups.get(direction) ?? []), Math.abs(vertical ? y : x)]);
|
||||
}
|
||||
const unit = changes[0]!.move!.unit;
|
||||
return [...groups].map(([direction, amounts]) => {
|
||||
const low = amount(Math.min(...amounts)), high = amount(Math.max(...amounts));
|
||||
return `${amounts.length === 1 ? "1 area" : `${amounts.length} areas`} moved ${direction} ${low === high ? low : `${low}–${high}`}${unit}.`;
|
||||
});
|
||||
}
|
||||
|
||||
/** Room around a change's outline, in percent of the image width and height, so it frames text. */
|
||||
const OUTLINE_PAD_X = 1.5;
|
||||
const OUTLINE_PAD_Y = 0.7;
|
||||
|
||||