---
name: review-pr-ui-screenshots
description: Download and review Easydict pull request CI screenshot artifacts from GitHub Actions using gh, then verify whether each screenshot matches its filename and artifact directory. Use when asked to review PR UI screenshots, CI visual artifacts, ui-screenshots artifacts, baseline candidates, visual diffs, or failure snapshots generated by the UI Automation workflow.
---

# Review PR UI Screenshots

## Goal

Fetch the relevant GitHub Actions UI screenshot artifacts for a PR, then review them like local UI artifacts: file and directory names describe the expected UI state, and mismatches should be reported first.

## Resolve PR And Run

Use `gh` from the repository root. Start by confirming authentication:

```powershell
gh auth status
```

If the user gave a PR number, use it. Otherwise resolve the current branch PR:

```powershell
$pr = gh pr view --json number,headRefName,headRefOid,url | ConvertFrom-Json
```

Find the latest matching UI Automation workflow run for the PR head commit:

```powershell
$runs = gh run list `
  --workflow ui-automation.yml `
  --branch $pr.headRefName `
  --event pull_request `
  --limit 20 `
  --json databaseId,status,conclusion,headSha,createdAt,displayTitle,url |
  ConvertFrom-Json

$run = $runs |
  Where-Object { $_.headSha -eq $pr.headRefOid -and $_.status -eq "completed" } |
  Sort-Object createdAt -Descending |
  Select-Object -First 1
```

If no completed run matches, list the latest runs and explain whether the workflow is still running, skipped, failed before artifacts, or expired.

## Download Screenshot Artifacts

Download into a unique, meaningful local directory:

```powershell
$dest = "artifacts/pr-ui-screenshots/pr-$($pr.number)/run-$($run.databaseId)"
New-Item -ItemType Directory -Force -Path $dest | Out-Null

gh run download $run.databaseId --pattern "ui-screenshots-*" --dir $dest
gh run download $run.databaseId --pattern "baseline-candidates-*" --dir $dest
gh run download $run.databaseId --pattern "theme-contrast-regression-screenshots-*" --dir $dest
```

Artifact names should remain visible in the folder tree, for example:

```text
artifacts/pr-ui-screenshots/pr-123/run-456/ui-screenshots-ocr-overlay/
artifacts/pr-ui-screenshots/pr-123/run-456/ui-screenshots-core-settings-darkmode/
artifacts/pr-ui-screenshots/pr-123/run-456/baseline-candidates-pop-button/
```

If `gh run download` reports no matching artifacts, inspect the run status and artifact list:

```powershell
gh run view $run.databaseId --json status,conclusion,url
gh run view $run.databaseId --log-failed
```

## Review Workflow

Use the local screenshot review workflow on the downloaded root. Review priority is:

1. `visual-diffs/` and `*_diff.png`
2. `baseline-candidates-*` artifacts and `baseline-candidates/` directories
3. diagnostic files containing `not_found`, `failed`, `failure`, `missing`, `error`, or `navigation_failed`
4. regular `ui-screenshots-*` artifacts

Inspect individual images, not just generated galleries. The artifact name should help set expectations:

- `ui-screenshots-pop-button`: PopButton settings, selection, popup visibility, and mini-window launch states.
- `ui-screenshots-mini-phonetic-dictionary`: mini window long text, phonetic display, dictionary WebView/fallback states.
- `ui-screenshots-core-settings-darkmode`: main window, translation, settings scrolling, window lifecycle, dark mode states.
- `ui-screenshots-theme-contrast`: theme matrix and light/dark contrast states.
- `ui-screenshots-ocr-overlay`: OCR hotkey, overlay, cancel/dismiss, and silent OCR states.
- `ui-screenshots-long-document`: long document mode controls and translation workflow states.

For each screenshot, compare the visible UI to the filename semantics. Examples:

- `*_before_*` should show pre-action state.
- `*_after_translate` should show translation output or an expected result state.
- `*_overlay_active` should show the capture overlay.
- `*_not_found` or `*_failed` should be treated as diagnostic evidence, not a successful UI state.
- `*_dark_*` and `*_light_*` should match the named palette.

## Report Format

Lead with findings. For each finding include:

- severity: `High`, `Medium`, or `Low`
- artifact and screenshot path
- expected state inferred from artifact/file name
- observed state
- why this matters for PR review
- suggested next check or fix

Then include:

- PR URL, run URL, run id, conclusion, and head SHA
- downloaded artifact root
- reviewed artifact groups
- any artifacts that were missing, expired, or not reviewed

If no mismatches are found, say so explicitly and state the review coverage.