# Browser Video Proof

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-ahmadrosid-nakama-browser-video-proof`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ahmadrosid](https://agentstack.voostack.com/s/ahmadrosid)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ahmadrosid](https://github.com/ahmadrosid)
- **Source:** https://github.com/ahmadrosid/nakama/tree/main/.agents/skills/browser-video-proof
- **Website:** https://ahmadrosid.github.io/nakama

## Install

```sh
agentstack add skill-ahmadrosid-nakama-browser-video-proof
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Browser video proof for PRs

Record a short, playable browser video that proves a UI fix, attach it to the
PR description, and verify the live body. Do not change application code for
the recording unless the user explicitly asks.

Reference run: PR #723 (`/automations` expanded long-run scroll).

## Prerequisites

- `gh` authenticated with push access to the target repo
- Bun + repo deps installed in the worktree (`bun install`)
- Google Chrome (or Chromium) on the host
- `ffmpeg` on PATH (for webm → H.264 MP4)
- Playwright in an isolated dir under `/tmp` (do not add it to the repo):

```bash
mkdir -p /tmp//playwright
cd /tmp//playwright
npm i playwright
npx playwright install ffmpeg
```

## Process

### 1. Isolate with a git worktree

Keep the main checkout clean.

```bash
cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b  .worktrees/ origin/main   # or attach to the fix branch
cd .worktrees/
```

Work only inside that worktree for servers and recording.

### 2. Inspect fixtures and UI first

Before inventing data:

1. Read the page under test (labels, expand controls, scroll containers).
2. Check existing test fixtures / factories for the same feature.
3. Prefer seeding via the public HTTP API. Fall back to a one-off SQLite insert
   in an isolated `NAKAMA_CONFIG_DIR` only when no API can create the needed row
   (e.g. a completed automation run with huge `output`).

### 3. Seed deterministic tall content

For scroll / overflow proofs, the fixture must be taller than the pane.

- Put a unique top marker near the start: `SCROLL_PROOF_MARKER_TOP`
- Put a unique bottom marker at the end: `SCROLL_PROOF_MARKER_BOTTOM`
- Use enough body text that `scrollHeight - clientHeight` is large (thousands of px)

Example shape for run output:

```markdown
# SCROLL_PROOF_MARKER_TOP — long automation run output

## Section 1
...

## Section 80
...

# SCROLL_PROOF_MARKER_BOTTOM — end of tall content
```

Never seed into the operator's real `~/.nakama` data. Always use a fresh
`NAKAMA_CONFIG_DIR` under `/tmp//`.

### 4. Start isolated local servers

Pick free ports. Do not steal the default stack if something already listens
on 4310 / 3000 / 3003.

```bash
RUN=/tmp/
API_PORT=4330
WEB_PORT=3014
mkdir -p "$RUN/nakama-data" "$RUN/logs"

# Keep processes alive after the shell exits (plain nohup ... & dies here)
setsid nohup env NAKAMA_CONFIG_DIR="$RUN/nakama-data" NAKAMA_PORT=$API_PORT \
  bun run apps/server/src/index.ts \
  >"$RUN/logs/server.log" 2>&1 "$RUN/logs/web.log" 2>&1 /` only. Never commit it.

```js
const browser = await chromium.launch({
  channel: "chrome", // if Chrome is installed
  headless: false,
  args: ["--disable-gpu"],
});
const context = await browser.newContext({
  viewport: { width: 1440, height: 900 },
  recordVideo: { dir: rawDir, size: { width: 1440, height: 900 } },
});
```

Rules:

1. Drive the real UI path under test (role/text locators).
2. Make motion visible — mouse wheel or stepped scroll, not a single invisible jump only.
3. Assert scroll moved (`scrollTop` delta) and that the bottom marker becomes reachable.
4. Capture `page.video()?.path()` before `context.close()`.
5. Convert: `ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4`
6. Write `results.json` + before/after screenshots under `artifacts/e2e-/`.

WebM alone is not enough for GitHub playback. Ship H.264 + `yuv420p`.

### 6. Validate the video before claiming anything

```bash
ffprobe -v error -show_entries stream=codec_name,width,height \
  -show_entries format=duration -of json out.mp4
# Extract early / late frames and look at them
ffmpeg -y -ss 00:00:02 -i out.mp4 -vframes 1 frame-early.png
ffmpeg -y -ss 00:00:08 -i out.mp4 -vframes 1 frame-late.png
```

Pass only if:

- codec is `h264`
- duration is long enough to see the interaction
- early frame shows the start state (e.g. top marker / expanded pane)
- late frame shows scroll progress (bottom marker or advanced sections)
- `results.json` reports a real `scrollTop` delta (or equivalent proof metric)

### 7. Upload to GitHub user-attachments

Undocumented but token-auth works for images/video when you have push access:

```bash
TOKEN=$(gh auth token)
REPO_ID=$(gh api repos// --jq .id)
MP4=artifacts/e2e-/.mp4

UPLOAD_JSON=$(curl -sS -X POST \
  "https://uploads.github.com/user-attachments/assets?name=$(basename "$MP4")&repository_id=${REPO_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: video/mp4" \
  -H "Accept: application/vnd.github+json" \
  --data-binary @"${MP4}")

VIDEO_URL=$(printf '%s' "$UPLOAD_JSON" | bun -e 'console.log(JSON.parse(await Bun.stdin.text()).url)')
echo "$VIDEO_URL"  # https://github.com/user-attachments/assets/
```

Save the URL. Confirm a HEAD/GET on the asset returns a video content type.

### 8. Update the PR description

Add a short **Browser proof** section with the steps shown and the bare
`https://github.com/user-attachments/assets/...` URL on its own line (GitHub
embeds the player). Prefer writing the body via a file:

```bash
gh api repos///pulls/ --method PATCH --input body.json
# or: gh pr edit  --body-file /tmp/pr-body.md
```

Follow `.agents/skills/adhd-pr-description/SKILL.md` for the rest of the body.

### 9. Verify the live PR body

```bash
gh api repos///pulls/ --jq .body | rg 'user-attachments/assets/|Browser proof'
```

Do not report success until this check passes.

## Example: automations expanded-run scroll

1. Worktree on the fix branch (or docs-only branch for this skill).
2. Isolated API `4330` + web `3014`, fresh `NAKAMA_CONFIG_DIR`.
3. `POST /v1/auth/setup` → provider → create automation **Long output digester**.
4. Insert/complete one run whose `output` is the long markdown with
   `SCROLL_PROOF_MARKER_TOP` / `SCROLL_PROOF_MARKER_BOTTOM`.
5. Playwright: open `/automations` → select the automation → **Expand run** →
   wheel-scroll the detail pane until the bottom marker is in view.
6. Convert to H.264 MP4, inspect frames, upload, patch PR body, verify.

## Cleanup

1. Kill the isolated API/web listeners on the ports you chose.
2. Leave `/tmp//` and profile `artifacts/e2e-/` as local evidence
   (do not commit videos or recorder scripts).
3. Remove the worktree when the branch is merged or abandoned:
   `git worktree remove .worktrees/`

## Honesty rules

1. Never claim browser proof without watching frames or `ffprobe` + screenshots.
2. Never paste a `user-attachments` URL you did not upload and re-fetch from the live PR body.
3. Never treat a green unit test as a substitute for the video when the ask was visual proof.
4. If scroll did not move, markers are wrong, or the MP4 is empty/corrupt — say it failed. Do not soften.
5. Do not modify application code “to make the video easier” unless the user asked for a product fix.
6. Do not touch the operator’s real Nakama config dir.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ahmadrosid](https://github.com/ahmadrosid)
- **Source:** [ahmadrosid/nakama](https://github.com/ahmadrosid/nakama)
- **License:** MIT
- **Homepage:** https://ahmadrosid.github.io/nakama

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ahmadrosid-nakama-browser-video-proof
- Seller: https://agentstack.voostack.com/s/ahmadrosid
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.