|
| 1 | +--- |
| 2 | +name: desktop-screenshot |
| 3 | +description: > |
| 4 | + Capture desktop app screenshots and post them to GitHub PRs with immutable URLs. |
| 5 | +version: 1 |
| 6 | +--- |
| 7 | + |
| 8 | +# Desktop Screenshot Skill |
| 9 | + |
| 10 | +## CRITICAL: How to Host Screenshots for PRs |
| 11 | + |
| 12 | +**NEVER use `sprout upload`, the relay media endpoint, or any third-party image |
| 13 | +host (imgur, imgbb, etc.) for PR screenshots.** Relay media URLs fail through |
| 14 | +GitHub's camo proxy (`Non-Image content-type returned`). External hosts are |
| 15 | +unreliable and may expose content. |
| 16 | + |
| 17 | +**ALWAYS use `scripts/post-screenshots.sh`** — it hosts PNGs on a per-developer |
| 18 | +git branch with immutable commit-SHA URLs that render correctly on GitHub. |
| 19 | + |
| 20 | +## Step 1 — Capture Screenshots |
| 21 | + |
| 22 | +`just desktop-screenshot` builds the frontend, starts a preview server, and |
| 23 | +runs Playwright with the mock bridge (no relay needed). |
| 24 | + |
| 25 | +```bash |
| 26 | +just desktop-screenshot --name home |
| 27 | +just desktop-screenshot --name channel --route /channels/general |
| 28 | +just desktop-screenshot --name ctx-menu --right-click channel-random --clip 0,200,320,300 |
| 29 | +just desktop-screenshot --name sidebar --active-channel general --messages /tmp/msgs.json --clip 0,0,256,720 |
| 30 | +``` |
| 31 | + |
| 32 | +**Flags:** `--name` (filename, required), `--route` (client route), `--active-channel` |
| 33 | +(channel to view), `--click`/`--right-click`/`--hover` (interact before capture), |
| 34 | +`--clip` (crop as `x,y,w,h`), `--messages` (JSON file), `--wait` (ms, default 2000), |
| 35 | +`--viewport` (WxH, default 1280x720), `--outdir` (default `test-results/screenshots`). |
| 36 | + |
| 37 | +Output: PNG path on stdout. |
| 38 | + |
| 39 | +### Injecting Messages |
| 40 | + |
| 41 | +Write a JSON array to a temp file. `channelName` and `content` are required: |
| 42 | + |
| 43 | +```json |
| 44 | +[ |
| 45 | + {"channelName": "random", "content": "Hey check this out", "kind": 40002}, |
| 46 | + {"channelName": "random", "content": "Another message"} |
| 47 | +] |
| 48 | +``` |
| 49 | + |
| 50 | +Without `--active-channel`, the helper navigates to the message channel (for |
| 51 | +showing content). With `--active-channel`, messages can target other channels |
| 52 | +while the camera stays put (for unread indicators, badges). |
| 53 | + |
| 54 | +### Available Mock Channels |
| 55 | + |
| 56 | +`general`, `random`, `design`, `sales`, `engineering`, `agents`, `watercooler`, |
| 57 | +`announcements`, `alice-tyler`, `bob-tyler`. |
| 58 | + |
| 59 | +`general` has pre-seeded messages (always shows `hasUnread`). Use `engineering` |
| 60 | +for "no unread" visual states. |
| 61 | + |
| 62 | +## Step 2 — Post to a PR |
| 63 | + |
| 64 | +```bash |
| 65 | +./scripts/post-screenshots.sh <PR-number> test-results/screenshots |
| 66 | +./scripts/post-screenshots.sh <PR-number> test-results/screenshots body.md |
| 67 | +``` |
| 68 | + |
| 69 | +The script pushes images to `agent-screenshots/<github-username>` and posts a |
| 70 | +PR comment with `## Screenshots` and all images. Re-runs overwrite that PR's |
| 71 | +images only. |
| 72 | + |
| 73 | +### Body Templates |
| 74 | + |
| 75 | +The optional third argument is a markdown file with `{{filename}}` placeholders |
| 76 | +(without `.png`). Images not referenced by a placeholder are appended at the end. |
| 77 | + |
| 78 | +```markdown |
| 79 | +### Context menu |
| 80 | +Right-click shows "Star channel". |
| 81 | + |
| 82 | +{{01-ctx-menu}} |
| 83 | + |
| 84 | +### Starred section |
| 85 | +`engineering` appears under Starred. |
| 86 | + |
| 87 | +{{02-starred}} |
| 88 | +``` |
| 89 | + |
| 90 | +## Gotchas |
| 91 | + |
| 92 | +1. **Stale server** — `reuseExistingServer: true` means a prior build serves old |
| 93 | + code. Kill port 4173 and rebuild (`cd desktop && pnpm run build`) after code changes. |
| 94 | +2. **Clip for readability** — full 1280x720 screenshots are hard to read for sidebar |
| 95 | + features. Sidebar = 256px wide; context menus ~450px. |
| 96 | +3. **`post-screenshots.sh` requires `gh` auth** — the script uses `gh api` and |
| 97 | + `gh pr comment`. Ensure `gh auth status` succeeds. |
0 commit comments