feat(desktop): add reusable screenshot workflow for agent UI verification

Agents working on desktop UI changes had no automated way to capture and
share visual results. Extends screenshot.mjs with --messages injection so
agents can populate the channel timeline before capturing, adds
scripts/post-screenshots.sh for hosting PNGs via a shared orphan branch
on GitHub, wires up a just desktop-screenshot target that handles build
and server lifecycle automatically, and updates AGENTS.md with the full
workflow.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>

Author: wpfleger96

AGENTS.md

@@ -230,18 +230,58 @@ E2E mock bridge. A standalone screenshot helper at
 tests use (`addInitScript` + `window.__SPROUT_E2E__`) into a CLI tool.
 
 ```bash
-just desktop-build   # build the frontend first
-cd desktop
-node tests/helpers/screenshot.mjs --name home
-node tests/helpers/screenshot.mjs --name channel --route /channels/general
-node tests/helpers/screenshot.mjs --name search --click open-search
-node tests/helpers/screenshot.mjs --name settings --click open-settings
+just desktop-screenshot --name home
+just desktop-screenshot --name channel --route /channels/general
+just desktop-screenshot --name search --click open-search
+just desktop-screenshot --name settings --click open-settings
 ```
 
 Options: `--name` (filename), `--route` (client route), `--click` (data-testid
 or CSS selector), `--wait` (ms, default 2000), `--viewport` (WxH, default
-1280x720), `--outdir` (default `test-results/screenshots`). Screenshots are
-saved as PNGs and the path is printed to stdout.
+1280x720), `--outdir` (default `test-results/screenshots`),
+`--messages` (JSON file path). Screenshots are saved as PNGs and the path is
+printed to stdout. The `just desktop-screenshot` target handles building the
+frontend and starting the preview server automatically.
+
+#### Injecting messages
+
+Use `--messages` to inject content into the channel timeline before screenshotting.
+The JSON file contains an array of messages to inject:
+
+```bash
+cat > /tmp/msgs.json << 'EOF'
+[
+  { "channelName": "general", "content": "```typescript\nconst x: number = 42;\n```" },
+  { "channelName": "general", "content": "plain text message" }
+]
+EOF
+just desktop-screenshot --name code-blocks --messages /tmp/msgs.json
+```
+
+Each message requires `channelName` and `content`; optional fields are `pubkey`
+and `kind`. When `--messages` is provided, the script navigates to the channel
+from the first message (ignoring `--route`), waits for the live subscription,
+injects all messages, then captures. Available mock channels: `general`,
+`random`, `design`, `sales`, `engineering`, `agents`, `watercooler`,
+`announcements`, `alice-tyler`, `bob-tyler`.
+
+#### Posting screenshots to a PR
+
+`scripts/post-screenshots.sh` hosts PNGs on a shared `agent-screenshots` orphan
+branch and posts them as a PR comment:
+
+```bash
+# Take screenshots, then post them
+just desktop-screenshot --name feature-demo --messages /tmp/msgs.json --outdir test-results/screenshots
+./scripts/post-screenshots.sh 803 test-results/screenshots
+
+# Or provide a custom comment body (images are appended)
+./scripts/post-screenshots.sh 803 test-results/screenshots body.md
+```
+
+The orphan branch accumulates images across PRs, namespaced as `pr-<N>/`. Re-runs
+for the same PR overwrite previous images. Delete the branch when no longer
+needed: `git push origin --delete agent-screenshots`.
 
 The Playwright MCP browser (`@playwright/mcp`) is also configured but cannot
 drive the desktop app directly because it evaluates JS after page load — too

desktop/tests/helpers/screenshot.mjs

@@ -16,9 +16,10 @@
 //   --wait <ms>          Milliseconds to wait before capture (default: 2000)
 //   --viewport <WxH>     Viewport dimensions (default: 1280x720)
 //   --outdir <path>      Output directory (default: test-results/screenshots)
+//   --messages <path>    JSON file with messages to inject before capture
 
 import { parseArgs } from "node:util";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { chromium } from "@playwright/test";
 
@@ -30,6 +31,7 @@ const { values: args } = parseArgs({
     wait: { type: "string", default: "2000" },
     viewport: { type: "string", default: "1280x720" },
     outdir: { type: "string", default: "test-results/screenshots" },
+    messages: { type: "string" },
   },
   strict: true,
 });
@@ -110,9 +112,67 @@ await page.addInitScript(() => {
   window.__SPROUT_E2E_APP_BADGE_COUNT__ = 0;
 });
 
-const url = args.route === "/" ? BASE_URL : `${BASE_URL}/#${args.route}`;
-await page.goto(url);
-await page.waitForTimeout(waitMs);
+if (args.messages) {
+  let messages;
+  try {
+    messages = JSON.parse(readFileSync(resolve(args.messages), "utf8"));
+  } catch (err) {
+    console.error(`Failed to read messages file: ${err.message}`);
+    await browser.close();
+    process.exit(1);
+  }
+
+  if (
+    !Array.isArray(messages) ||
+    messages.length === 0 ||
+    messages.some(
+      (m) => typeof m.channelName !== "string" || typeof m.content !== "string",
+    )
+  ) {
+    console.error(
+      "messages file must be a non-empty array of { channelName: string, content: string, pubkey?: string, kind?: number }",
+    );
+    await browser.close();
+    process.exit(1);
+  }
+
+  const channelName = messages[0].channelName;
+
+  await page.goto(BASE_URL);
+  await page.waitForSelector(`[data-testid="channel-${channelName}"]`, {
+    timeout: 10000,
+  });
+  await page.click(`[data-testid="channel-${channelName}"]`);
+
+  await page.waitForFunction(
+    (name) =>
+      window.__SPROUT_E2E_HAS_MOCK_LIVE_SUBSCRIPTION__?.({
+        channelName: name,
+      }) ?? false,
+    channelName,
+    { timeout: 10000 },
+  );
+
+  for (const msg of messages) {
+    await page.evaluate(
+      (m) => {
+        window.__SPROUT_E2E_EMIT_MOCK_MESSAGE__?.(m);
+      },
+      {
+        channelName: msg.channelName,
+        content: msg.content,
+        pubkey: msg.pubkey ?? DEFAULT_MOCK_PUBKEY,
+        kind: msg.kind,
+      },
+    );
+  }
+
+  await page.waitForTimeout(waitMs);
+} else {
+  const url = args.route === "/" ? BASE_URL : `${BASE_URL}/#${args.route}`;
+  await page.goto(url);
+  await page.waitForTimeout(waitMs);
+}
 
 if (args.click) {
   const selector = args.click.startsWith("[")

justfile

@@ -198,6 +198,19 @@ desktop-e2e-smoke:
 desktop-e2e-integration: _ensure-migrations
     cd {{desktop_dir}} && pnpm test:e2e:integration
 
+# Take desktop screenshots using the mock bridge
+desktop-screenshot *ARGS:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    cd {{desktop_dir}}
+    [[ -d dist ]] || { cd ..; just desktop-build; cd {{desktop_dir}}; }
+    if ! curl -sf http://127.0.0.1:4173/ >/dev/null 2>&1; then
+        python3 -m http.server 4173 -d dist >/dev/null 2>&1 &
+        trap "kill $! 2>/dev/null || true" EXIT
+        for i in $(seq 1 20); do curl -sf http://127.0.0.1:4173/ >/dev/null && break; sleep 0.5; done
+    fi
+    node tests/helpers/screenshot.mjs {{ARGS}}
+
 # Mesh-compute e2e: the CI-safe layers (relay mesh signaling invariants + Playwright UI)
 mesh-e2e:
     cargo test -p sprout-relay mesh_signaling

scripts/post-screenshots.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <pr-number> <png-dir> [comment-body-file]" >&2
+  exit 1
+fi
+
+PR="$1"
+PNG_DIR="$2"
+BODY_FILE="${3:-}"
+
+BRANCH="agent-screenshots"
+REPO="block/sprout"
+RAW_BASE="https://raw.githubusercontent.com/${REPO}/refs/heads/${BRANCH}"
+
+mapfile -t PNGS < <(find "$PNG_DIR" -maxdepth 1 -name "*.png" -type f | sort)
+if [[ ${#PNGS[@]} -eq 0 ]]; then
+  echo "error: no PNGs found in $PNG_DIR" >&2
+  exit 1
+fi
+
+EXISTING_ENTRIES=""
+if git fetch origin "refs/heads/${BRANCH}:refs/remotes/origin/${BRANCH}" 2>/dev/null; then
+  EXISTING_ENTRIES=$(git ls-tree "origin/${BRANCH}" | grep -v "	pr-${PR}/" || true)
+fi
+
+NEW_ENTRIES=""
+IMAGE_URLS=()
+for PNG in "${PNGS[@]}"; do
+  FILENAME=$(basename "$PNG")
+  BLOB=$(git hash-object -w "$PNG")
+  TREE_PATH="pr-${PR}/${FILENAME}"
+  NEW_ENTRIES+="100644 blob ${BLOB}	${TREE_PATH}"$'\n'
+  IMAGE_URLS+=("${RAW_BASE}/${TREE_PATH}")
+done
+
+COMBINED=$(printf '%s\n' "$EXISTING_ENTRIES" "$NEW_ENTRIES" | grep -v '^$')
+TREE=$(echo "$COMBINED" | git mktree)
+
+COMMIT=$(git commit-tree "$TREE" -m "screenshots: PR #${PR}")
+git push --force origin "${COMMIT}:refs/heads/${BRANCH}"
+
+if [[ -n "$BODY_FILE" ]]; then
+  COMMENT_BODY=$(cat "$BODY_FILE")
+  COMMENT_BODY+=$'\n\n'
+  for URL in "${IMAGE_URLS[@]}"; do
+    FILENAME=$(basename "$URL")
+    NAME="${FILENAME%.png}"
+    COMMENT_BODY+="![${NAME}](${URL})"$'\n\n'
+  done
+else
+  COMMENT_BODY="## Screenshots"$'\n\n'
+  for URL in "${IMAGE_URLS[@]}"; do
+    FILENAME=$(basename "$URL")
+    NAME="${FILENAME%.png}"
+    COMMENT_BODY+="![${NAME}](${URL})"$'\n\n'
+  done
+fi
+
+gh pr comment "$PR" --repo "$REPO" --body "$COMMENT_BODY"
+echo "Posted ${#PNGS[@]} screenshot(s) to PR #${PR}"