proofreel 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. proofreel-1.0.0/.gitignore +4 -0
  2. proofreel-1.0.0/CHANGELOG.md +18 -0
  3. proofreel-1.0.0/LICENSE +21 -0
  4. proofreel-1.0.0/PKG-INFO +157 -0
  5. proofreel-1.0.0/README.md +142 -0
  6. proofreel-1.0.0/examples/acme-notes/README.md +6 -0
  7. proofreel-1.0.0/pyproject.toml +29 -0
  8. proofreel-1.0.0/src/proofreel/__init__.py +36 -0
  9. proofreel-1.0.0/src/proofreel/ax.py +88 -0
  10. proofreel-1.0.0/src/proofreel/ax.swift +99 -0
  11. proofreel-1.0.0/src/proofreel/cli.py +620 -0
  12. proofreel-1.0.0/src/proofreel/conditions/__init__.py +84 -0
  13. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/Info.plist +18 -0
  14. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/apply.sh +8 -0
  15. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/check.sh +2 -0
  16. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/condition.toml +10 -0
  17. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/headset.c +281 -0
  18. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/host.sh +10 -0
  19. proofreel-1.0.0/src/proofreel/conditions/bluetooth-headset-call-mode/probe.swift +76 -0
  20. proofreel-1.0.0/src/proofreel/conditions/no-microphone/apply.sh +7 -0
  21. proofreel-1.0.0/src/proofreel/conditions/no-microphone/check.sh +10 -0
  22. proofreel-1.0.0/src/proofreel/conditions/no-microphone/condition.toml +7 -0
  23. proofreel-1.0.0/src/proofreel/conditions/offline/apply.sh +21 -0
  24. proofreel-1.0.0/src/proofreel/conditions/offline/check.sh +6 -0
  25. proofreel-1.0.0/src/proofreel/conditions/offline/condition.toml +7 -0
  26. proofreel-1.0.0/src/proofreel/conditions/quarantined-download/apply.sh +18 -0
  27. proofreel-1.0.0/src/proofreel/conditions/quarantined-download/check.sh +10 -0
  28. proofreel-1.0.0/src/proofreel/conditions/quarantined-download/condition.toml +10 -0
  29. proofreel-1.0.0/src/proofreel/conditions/quarantined-download/host.sh +4 -0
  30. proofreel-1.0.0/src/proofreel/conditions/run-from-dmg/apply.sh +17 -0
  31. proofreel-1.0.0/src/proofreel/conditions/run-from-dmg/check.sh +11 -0
  32. proofreel-1.0.0/src/proofreel/conditions/run-from-dmg/condition.toml +10 -0
  33. proofreel-1.0.0/src/proofreel/conditions/run-from-dmg/host.sh +4 -0
  34. proofreel-1.0.0/src/proofreel/conditions/slow-network/apply.sh +2 -0
  35. proofreel-1.0.0/src/proofreel/conditions/slow-network/check.sh +2 -0
  36. proofreel-1.0.0/src/proofreel/conditions/slow-network/condition.toml +21 -0
  37. proofreel-1.0.0/src/proofreel/conditions/slow-network/remove.sh +2 -0
  38. proofreel-1.0.0/src/proofreel/conditions/slow-network/shape.sh +115 -0
  39. proofreel-1.0.0/src/proofreel/crash.py +129 -0
  40. proofreel-1.0.0/src/proofreel/demo.py +156 -0
  41. proofreel-1.0.0/src/proofreel/draw.py +109 -0
  42. proofreel-1.0.0/src/proofreel/flow.py +81 -0
  43. proofreel-1.0.0/src/proofreel/guest.py +162 -0
  44. proofreel-1.0.0/src/proofreel/image.py +130 -0
  45. proofreel-1.0.0/src/proofreel/images/debian-desktop.sh +64 -0
  46. proofreel-1.0.0/src/proofreel/images/debian-seed/meta-data +2 -0
  47. proofreel-1.0.0/src/proofreel/images/debian-seed/user-data +11 -0
  48. proofreel-1.0.0/src/proofreel/keys.swift +67 -0
  49. proofreel-1.0.0/src/proofreel/latency.py +98 -0
  50. proofreel-1.0.0/src/proofreel/machine.js +163 -0
  51. proofreel-1.0.0/src/proofreel/metrics.py +297 -0
  52. proofreel-1.0.0/src/proofreel/motion.py +207 -0
  53. proofreel-1.0.0/src/proofreel/ocr.swift +34 -0
  54. proofreel-1.0.0/src/proofreel/page.css +315 -0
  55. proofreel-1.0.0/src/proofreel/page.js +707 -0
  56. proofreel-1.0.0/src/proofreel/page.py +188 -0
  57. proofreel-1.0.0/src/proofreel/plugins.py +184 -0
  58. proofreel-1.0.0/src/proofreel/probes/__init__.py +267 -0
  59. proofreel-1.0.0/src/proofreel/probes/browser/observe.js +47 -0
  60. proofreel-1.0.0/src/proofreel/probes/browser/probe.toml +53 -0
  61. proofreel-1.0.0/src/proofreel/probes/browser/run.py +180 -0
  62. proofreel-1.0.0/src/proofreel/probes/host-load/probe.toml +29 -0
  63. proofreel-1.0.0/src/proofreel/probes/host-load/run.py +69 -0
  64. proofreel-1.0.0/src/proofreel/probes/network/addon.py +92 -0
  65. proofreel-1.0.0/src/proofreel/probes/network/probe.toml +13 -0
  66. proofreel-1.0.0/src/proofreel/probes/network/run.py +27 -0
  67. proofreel-1.0.0/src/proofreel/probes/network/start.sh +15 -0
  68. proofreel-1.0.0/src/proofreel/probes/network/stop.sh +8 -0
  69. proofreel-1.0.0/src/proofreel/probes/processes/probe.toml +31 -0
  70. proofreel-1.0.0/src/proofreel/probes/processes/procs.py +146 -0
  71. proofreel-1.0.0/src/proofreel/probes/processes/run.sh +6 -0
  72. proofreel-1.0.0/src/proofreel/qemu.py +208 -0
  73. proofreel-1.0.0/src/proofreel/recording.py +261 -0
  74. proofreel-1.0.0/src/proofreel/redact.py +41 -0
  75. proofreel-1.0.0/src/proofreel/render.py +199 -0
  76. proofreel-1.0.0/src/proofreel/screen.py +294 -0
  77. proofreel-1.0.0/src/proofreel/session.py +118 -0
  78. proofreel-1.0.0/src/proofreel/suite.py +91 -0
  79. proofreel-1.0.0/src/proofreel/tart.py +86 -0
  80. proofreel-1.0.0/src/proofreel/tracks.js +107 -0
  81. proofreel-1.0.0/src/proofreel/vm.py +303 -0
  82. proofreel-1.0.0/tests/conftest.py +19 -0
  83. proofreel-1.0.0/tests/fixtures/browser-cdp.jsonl +29 -0
  84. proofreel-1.0.0/tests/fixtures/network/metrics/network.jsonl +6 -0
  85. proofreel-1.0.0/tests/fixtures/network/session.json +1 -0
  86. proofreel-1.0.0/tests/fixtures/v1-runs.json +7 -0
  87. proofreel-1.0.0/tests/fixtures/v1-session/events.jsonl +7 -0
  88. proofreel-1.0.0/tests/fixtures/v1-session/session.json +1 -0
  89. proofreel-1.0.0/tests/js/machine.test.js +107 -0
  90. proofreel-1.0.0/tests/js/tracks.test.js +73 -0
  91. proofreel-1.0.0/tests/test_ax.py +43 -0
  92. proofreel-1.0.0/tests/test_browser_probe.py +133 -0
  93. proofreel-1.0.0/tests/test_checks.py +43 -0
  94. proofreel-1.0.0/tests/test_conditions.py +130 -0
  95. proofreel-1.0.0/tests/test_flow.py +92 -0
  96. proofreel-1.0.0/tests/test_image.py +73 -0
  97. proofreel-1.0.0/tests/test_keys.py +67 -0
  98. proofreel-1.0.0/tests/test_latency.py +90 -0
  99. proofreel-1.0.0/tests/test_metrics.py +169 -0
  100. proofreel-1.0.0/tests/test_network.py +178 -0
  101. proofreel-1.0.0/tests/test_ocr.py +20 -0
  102. proofreel-1.0.0/tests/test_page.py +108 -0
  103. proofreel-1.0.0/tests/test_plugins.py +34 -0
  104. proofreel-1.0.0/tests/test_pointer.py +26 -0
  105. proofreel-1.0.0/tests/test_processes.py +116 -0
  106. proofreel-1.0.0/tests/test_readme_media.py +28 -0
  107. proofreel-1.0.0/tests/test_recording.py +105 -0
  108. proofreel-1.0.0/tests/test_render.py +70 -0
  109. proofreel-1.0.0/tests/test_screen.py +132 -0
  110. proofreel-1.0.0/tests/test_session.py +91 -0
  111. proofreel-1.0.0/tests/test_slow_network.py +183 -0
  112. proofreel-1.0.0/tests/test_suite.py +141 -0
  113. proofreel-1.0.0/tests/test_vm.py +123 -0
@@ -0,0 +1,4 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0
4
+
5
+ The first release. proofreel records a coding agent driving an app in a VM and turns the run into a review video and a review page (a claude.ai artifact).
6
+
7
+ - **Record:** `start`, `stop`, and flows of steps, states, waits, and checks. Click by words, by the macOS accessibility tree, or by coordinates; real modifier keys in macOS guests.
8
+ - **Review page:** the video with the checks on its scrub bar; the user flow as a state machine of every run (Flow), or each state's steps and times (Steps); Tracks for the metrics, closed until you open them or a budget fails; Journeys, Stats, and Network tabs; Ask about this moment; reviews.
9
+ - **VM states:** macOS and Linux through Tart, Windows 11 ARM and Linux through QEMU. Save a state, warm or cold, and start each run from it.
10
+ - **Suites:** many journeys, each from a clean state, on one page.
11
+ - **Conditions:** `slow-network`, `offline`, `no-microphone`, `bluetooth-headset-call-mode`, `quarantined-download`, `run-from-dmg`.
12
+ - **Probes and budgets:** `host-load`, `processes`, `network`, `browser`, and input latency from the frames; `check metric` fails a run on a budget; `stats` prints a summary.
13
+ - **Crash and hang reports** from macOS guests.
14
+ - **`proofreel vm image`** makes the `linux` state from nothing: it downloads Debian (SHA-512 checked), installs Xfce and Chromium, and saves the state.
15
+ - **Claude Code plugin:** `/plugin marketplace add YGao2005/proofreel`, then `/plugin install proofreel@proofreel`.
16
+ - **Docs:** the README is the front page, with a tour video of the review page; the reference is in docs/. `tools/readme_media.py` makes the tour again from a review folder.
17
+ - **`proofreel --version`.**
18
+ - **License:** MIT (was PolyForm Noncommercial 1.0.0).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Yang Gao
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.5
2
+ Name: proofreel
3
+ Version: 1.0.0
4
+ Summary: Record an agent driving a screen as a review video and page: a gliding pointer, click rings, auto zoom, captions, and checks.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: pillow<13,>=10.1
9
+ Requires-Dist: vncdotool==1.2.0
10
+ Provides-Extra: browser
11
+ Requires-Dist: websocket-client; extra == 'browser'
12
+ Provides-Extra: network
13
+ Requires-Dist: mitmproxy>=11; extra == 'network'
14
+ Description-Content-Type: text/markdown
15
+
16
+ # proofreel
17
+
18
+ Video proof that your coding agent's change works. proofreel lets Claude Code drive your app in a clean VM as a user
19
+ would, record it, and publish a review page that a person can check in a minute.
20
+
21
+ **[See a real review page →](https://claude.ai/artifact/PeehtyBLEMVUsxokb5FqbT)** (the Acme Notes example: three
22
+ journeys that pass and one with a failed network budget)
23
+
24
+ [![A tour of the review page: the video plays, the flow lights each state, a click jumps the video, Tracks open, and a failed run shows its failed budget, request, and numbers.](https://raw.githubusercontent.com/YGao2005/proofreel/main/docs/tour.gif)](https://raw.githubusercontent.com/YGao2005/proofreel/main/docs/tour.mp4)
25
+
26
+ ## Install
27
+
28
+ ```bash
29
+ pip install "proofreel[network,browser]" # Python 3.11+, on an Apple Silicon Mac
30
+ proofreel demo # a made-up session, no VM needed: open the index.html it prints
31
+ ```
32
+
33
+ Install the tools for the guests you use:
34
+
35
+ - `brew install ffmpeg`: always. It makes the video.
36
+ - `brew install qemu`: for a Linux or Windows guest (QEMU).
37
+ - `brew install cirruslabs/cli/tart`: for a macOS guest (Tart).
38
+
39
+ The `network` and `browser` extras add the network and browser probes that the Acme Notes budgets use.
40
+
41
+ To let Claude Code drive it, add the plugin in Claude Code:
42
+
43
+ ```text
44
+ /plugin marketplace add YGao2005/proofreel
45
+ /plugin install proofreel@proofreel
46
+ ```
47
+
48
+ ## Quickstart
49
+
50
+ Make the `linux` state once. It downloads Debian (about 0.4 GB), installs Xfce and Chromium, and saves the disk. It takes
51
+ about 4 minutes and needs QEMU. A state that exists is not made again; `proofreel vm drop linux` removes it.
52
+
53
+ ```bash
54
+ proofreel vm image # once: the linux state (Debian, Xfce, Chromium)
55
+ ```
56
+
57
+ Then start a VM from the state, record a session, and publish the review page. The example app is in this repo:
58
+
59
+ ```bash
60
+ git clone https://github.com/YGao2005/proofreel && cd proofreel
61
+ python3 examples/acme-notes/server.py & # a made-up app on port 8791
62
+ proofreel vm up linux # a run VM, cloned from a saved state in seconds
63
+ proofreel start sign-in --title "Sign in" --about "A returning user signs in."
64
+ proofreel step "Open Acme Notes"
65
+ proofreel vm sh 'browse http://10.0.2.2:8791/' # open a page in Chromium on the screen
66
+ proofreel wait-text "Welcome back" 30
67
+ proofreel click-text "Email" # finds the words on the screen, then clicks them
68
+ proofreel type "sam@example.com"
69
+ proofreel key tab
70
+ proofreel click-text "Sign in"
71
+ proofreel wait-text "Your notes" 20
72
+ proofreel check text "Signed in as sam@example.com" # a pass or fail on the page
73
+ proofreel stop # makes session.mp4, index.html, poster.jpg, shots/
74
+ proofreel publish <session> --out review-sign-in # adds the run to a review folder, and prints its files
75
+ proofreel vm down
76
+ ```
77
+
78
+ `stop` prints the session folder to give to `publish`. `proofreel click 512 400` clicks a point; the screen is 1024x768
79
+ unless you build the [firmware](docs/vm-states.md#windows-11-arm-and-linux-qemu) for a larger one.
80
+
81
+ Publishing is in [the review page](docs/review-page.md). To use an existing VNC screen in place of a VM, set
82
+ `PROOFREEL_VNC=127.0.0.1::5900` and `PROOFREEL_PASSWORD=...`.
83
+
84
+ A flow is a text file with one command on each line, so a journey runs again the same way. A suite runs many flows,
85
+ each from a clean start:
86
+
87
+ ```bash
88
+ proofreel run flows/sign-up.flow --set EMAIL=sam@example.com
89
+ proofreel suite flows/ --out review-sign-in --title "Sign in"
90
+ ```
91
+
92
+ ## Checks
93
+
94
+ | Check | Passes when |
95
+ |---|---|
96
+ | `check text <text> [seconds] [--in BOX]` | the words show on the screen in the seconds (default 10) |
97
+ | `check no-text <text> [seconds]` | the words are gone from the screen in the seconds (default 0) |
98
+ | `check cmd "<command>" [seconds]` | a shell command on the host exits 0. It runs again each second until it does or the seconds pass |
99
+ | `check sh "<command>" [seconds]` | the same, but in the run VM over SSH (PowerShell on Windows) |
100
+ | `check running <process>` | a process with this exact name runs in the run VM |
101
+ | `check metric <series> <stat> --below N` (or `--above N`) | a budget on what a probe measured; see [Probes and budgets](docs/probes.md) |
102
+
103
+ `--in`, `click-text`, and the other commands are in [Flows, checks, and commands](docs/flows.md).
104
+
105
+ ## The review page
106
+
107
+ On a wide screen the video, a scrub bar with a mark for each step and check, and a folded Tracks row are on the left.
108
+ The right column shows the state machine of the review folder, drawn from the runs' `state` lines (Flow), or a list of
109
+ the steps of each state with their times (Steps). A click on a state or a step jumps the video to that moment. The page
110
+ fits the window, and only that column scrolls. Journeys, Stats, and Network are tabs below. A failed check marks the
111
+ page *Problem*.
112
+
113
+ Publishing, review folders, and what the page adds on claude.ai are in [the review page](docs/review-page.md).
114
+ Tracks, Stats, and Network show what the [probes](docs/probes.md) measured.
115
+
116
+ ## Example: Acme Notes
117
+
118
+ [`examples/acme-notes`](examples/acme-notes) is a made-up notes app with three flows (sign in, write a note,
119
+ search). Its README says how to run it, and how `BROKEN=1` makes a run fail. The suite:
120
+
121
+ ```bash
122
+ python3 examples/acme-notes/server.py & # skip if it already runs
123
+ proofreel suite examples/acme-notes/flows --out review-acme
124
+ ```
125
+
126
+ The tour above is made from these runs. `tools/readme_media.py review-acme` makes it again.
127
+
128
+ ## Docs
129
+
130
+ | Page | What is in it |
131
+ |---|---|
132
+ | [Flows, checks, and commands](docs/flows.md) | the checks, flows, suites, states, crash reports, another tool that drives the screen, the accessibility tree, modifier keys |
133
+ | [VM states](docs/vm-states.md) | saved states, Tart (macOS and Linux), conditions, QEMU (Windows and Linux), the `linux` browser image |
134
+ | [Probes and budgets](docs/probes.md) | what a probe measures, `check metric`, `stats`, input latency, network requests, the probe contract |
135
+ | [The review page](docs/review-page.md) | what the page shows, publishing, review folders, claude.ai features |
136
+ | [How it works](docs/how-it-works.md) | the video, the screens it can record, the session folder, capture, time, camera, drawing |
137
+
138
+ The skill an agent reads is [`skills/proofreel/SKILL.md`](skills/proofreel/SKILL.md).
139
+
140
+ ## Limits
141
+
142
+ - A run VM is headless and isolated: no window, no host audio (Tart `--no-audio`; QEMU `-audio none` and no
143
+ sound device), no shared clipboard. Nothing it does shows or plays on the host.
144
+ - One run VM and one recording at a time for each `PROOFREEL_VM` name (default `pr-run`). Agents that work at the
145
+ same time each set their own name, such as `PROOFREEL_VM=pr-a`. macOS lets a Mac run at most 2 macOS VMs at once.
146
+ State and run names use letters, digits, `-`, and `_`. The backend names a run VM `<name>.vm`, so it never has the
147
+ name of a state. Commands to one run VM share one SSH connection for each boot.
148
+ - Files go to `PROOFREEL_HOME` (default `~/.proofreel`): states, run records, compiled helpers, and `sessions/`
149
+ (`PROOFREEL_SESSIONS`). The guest password is in each state's file (`states/<name>.json`), and it reaches `ssh` through the environment,
150
+ never a command line. Use a throwaway password in a VM, never a real one.
151
+ - A VNC server sends keys as keysyms. Some apps read hardware key codes. A macOS run VM posts modifiers in the
152
+ guest (see [Modifier keys](docs/flows.md#modifier-keys-macos-guests)); send other keys from in the guest, and log them with
153
+ `proofreel event key ...`.
154
+
155
+ ## License
156
+
157
+ [MIT](LICENSE).
@@ -0,0 +1,142 @@
1
+ # proofreel
2
+
3
+ Video proof that your coding agent's change works. proofreel lets Claude Code drive your app in a clean VM as a user
4
+ would, record it, and publish a review page that a person can check in a minute.
5
+
6
+ **[See a real review page →](https://claude.ai/artifact/PeehtyBLEMVUsxokb5FqbT)** (the Acme Notes example: three
7
+ journeys that pass and one with a failed network budget)
8
+
9
+ [![A tour of the review page: the video plays, the flow lights each state, a click jumps the video, Tracks open, and a failed run shows its failed budget, request, and numbers.](https://raw.githubusercontent.com/YGao2005/proofreel/main/docs/tour.gif)](https://raw.githubusercontent.com/YGao2005/proofreel/main/docs/tour.mp4)
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pip install "proofreel[network,browser]" # Python 3.11+, on an Apple Silicon Mac
15
+ proofreel demo # a made-up session, no VM needed: open the index.html it prints
16
+ ```
17
+
18
+ Install the tools for the guests you use:
19
+
20
+ - `brew install ffmpeg`: always. It makes the video.
21
+ - `brew install qemu`: for a Linux or Windows guest (QEMU).
22
+ - `brew install cirruslabs/cli/tart`: for a macOS guest (Tart).
23
+
24
+ The `network` and `browser` extras add the network and browser probes that the Acme Notes budgets use.
25
+
26
+ To let Claude Code drive it, add the plugin in Claude Code:
27
+
28
+ ```text
29
+ /plugin marketplace add YGao2005/proofreel
30
+ /plugin install proofreel@proofreel
31
+ ```
32
+
33
+ ## Quickstart
34
+
35
+ Make the `linux` state once. It downloads Debian (about 0.4 GB), installs Xfce and Chromium, and saves the disk. It takes
36
+ about 4 minutes and needs QEMU. A state that exists is not made again; `proofreel vm drop linux` removes it.
37
+
38
+ ```bash
39
+ proofreel vm image # once: the linux state (Debian, Xfce, Chromium)
40
+ ```
41
+
42
+ Then start a VM from the state, record a session, and publish the review page. The example app is in this repo:
43
+
44
+ ```bash
45
+ git clone https://github.com/YGao2005/proofreel && cd proofreel
46
+ python3 examples/acme-notes/server.py & # a made-up app on port 8791
47
+ proofreel vm up linux # a run VM, cloned from a saved state in seconds
48
+ proofreel start sign-in --title "Sign in" --about "A returning user signs in."
49
+ proofreel step "Open Acme Notes"
50
+ proofreel vm sh 'browse http://10.0.2.2:8791/' # open a page in Chromium on the screen
51
+ proofreel wait-text "Welcome back" 30
52
+ proofreel click-text "Email" # finds the words on the screen, then clicks them
53
+ proofreel type "sam@example.com"
54
+ proofreel key tab
55
+ proofreel click-text "Sign in"
56
+ proofreel wait-text "Your notes" 20
57
+ proofreel check text "Signed in as sam@example.com" # a pass or fail on the page
58
+ proofreel stop # makes session.mp4, index.html, poster.jpg, shots/
59
+ proofreel publish <session> --out review-sign-in # adds the run to a review folder, and prints its files
60
+ proofreel vm down
61
+ ```
62
+
63
+ `stop` prints the session folder to give to `publish`. `proofreel click 512 400` clicks a point; the screen is 1024x768
64
+ unless you build the [firmware](docs/vm-states.md#windows-11-arm-and-linux-qemu) for a larger one.
65
+
66
+ Publishing is in [the review page](docs/review-page.md). To use an existing VNC screen in place of a VM, set
67
+ `PROOFREEL_VNC=127.0.0.1::5900` and `PROOFREEL_PASSWORD=...`.
68
+
69
+ A flow is a text file with one command on each line, so a journey runs again the same way. A suite runs many flows,
70
+ each from a clean start:
71
+
72
+ ```bash
73
+ proofreel run flows/sign-up.flow --set EMAIL=sam@example.com
74
+ proofreel suite flows/ --out review-sign-in --title "Sign in"
75
+ ```
76
+
77
+ ## Checks
78
+
79
+ | Check | Passes when |
80
+ |---|---|
81
+ | `check text <text> [seconds] [--in BOX]` | the words show on the screen in the seconds (default 10) |
82
+ | `check no-text <text> [seconds]` | the words are gone from the screen in the seconds (default 0) |
83
+ | `check cmd "<command>" [seconds]` | a shell command on the host exits 0. It runs again each second until it does or the seconds pass |
84
+ | `check sh "<command>" [seconds]` | the same, but in the run VM over SSH (PowerShell on Windows) |
85
+ | `check running <process>` | a process with this exact name runs in the run VM |
86
+ | `check metric <series> <stat> --below N` (or `--above N`) | a budget on what a probe measured; see [Probes and budgets](docs/probes.md) |
87
+
88
+ `--in`, `click-text`, and the other commands are in [Flows, checks, and commands](docs/flows.md).
89
+
90
+ ## The review page
91
+
92
+ On a wide screen the video, a scrub bar with a mark for each step and check, and a folded Tracks row are on the left.
93
+ The right column shows the state machine of the review folder, drawn from the runs' `state` lines (Flow), or a list of
94
+ the steps of each state with their times (Steps). A click on a state or a step jumps the video to that moment. The page
95
+ fits the window, and only that column scrolls. Journeys, Stats, and Network are tabs below. A failed check marks the
96
+ page *Problem*.
97
+
98
+ Publishing, review folders, and what the page adds on claude.ai are in [the review page](docs/review-page.md).
99
+ Tracks, Stats, and Network show what the [probes](docs/probes.md) measured.
100
+
101
+ ## Example: Acme Notes
102
+
103
+ [`examples/acme-notes`](examples/acme-notes) is a made-up notes app with three flows (sign in, write a note,
104
+ search). Its README says how to run it, and how `BROKEN=1` makes a run fail. The suite:
105
+
106
+ ```bash
107
+ python3 examples/acme-notes/server.py & # skip if it already runs
108
+ proofreel suite examples/acme-notes/flows --out review-acme
109
+ ```
110
+
111
+ The tour above is made from these runs. `tools/readme_media.py review-acme` makes it again.
112
+
113
+ ## Docs
114
+
115
+ | Page | What is in it |
116
+ |---|---|
117
+ | [Flows, checks, and commands](docs/flows.md) | the checks, flows, suites, states, crash reports, another tool that drives the screen, the accessibility tree, modifier keys |
118
+ | [VM states](docs/vm-states.md) | saved states, Tart (macOS and Linux), conditions, QEMU (Windows and Linux), the `linux` browser image |
119
+ | [Probes and budgets](docs/probes.md) | what a probe measures, `check metric`, `stats`, input latency, network requests, the probe contract |
120
+ | [The review page](docs/review-page.md) | what the page shows, publishing, review folders, claude.ai features |
121
+ | [How it works](docs/how-it-works.md) | the video, the screens it can record, the session folder, capture, time, camera, drawing |
122
+
123
+ The skill an agent reads is [`skills/proofreel/SKILL.md`](skills/proofreel/SKILL.md).
124
+
125
+ ## Limits
126
+
127
+ - A run VM is headless and isolated: no window, no host audio (Tart `--no-audio`; QEMU `-audio none` and no
128
+ sound device), no shared clipboard. Nothing it does shows or plays on the host.
129
+ - One run VM and one recording at a time for each `PROOFREEL_VM` name (default `pr-run`). Agents that work at the
130
+ same time each set their own name, such as `PROOFREEL_VM=pr-a`. macOS lets a Mac run at most 2 macOS VMs at once.
131
+ State and run names use letters, digits, `-`, and `_`. The backend names a run VM `<name>.vm`, so it never has the
132
+ name of a state. Commands to one run VM share one SSH connection for each boot.
133
+ - Files go to `PROOFREEL_HOME` (default `~/.proofreel`): states, run records, compiled helpers, and `sessions/`
134
+ (`PROOFREEL_SESSIONS`). The guest password is in each state's file (`states/<name>.json`), and it reaches `ssh` through the environment,
135
+ never a command line. Use a throwaway password in a VM, never a real one.
136
+ - A VNC server sends keys as keysyms. Some apps read hardware key codes. A macOS run VM posts modifiers in the
137
+ guest (see [Modifier keys](docs/flows.md#modifier-keys-macos-guests)); send other keys from in the guest, and log them with
138
+ `proofreel event key ...`.
139
+
140
+ ## License
141
+
142
+ [MIT](LICENSE).
@@ -0,0 +1,6 @@
1
+ # Acme Notes
2
+
3
+ A made-up notes app to record with proofreel. Run `python3 server.py` (stdlib only, port 8791).
4
+ `SLOW_SEARCH_MS=1500` slows `/api/search`. `BROKEN=1` makes `/api/tags` return 500.
5
+ In the `linux` state the guest reaches it at `http://10.0.2.2:8791`. Use `--set URL=...` to change that.
6
+ Run all three journeys: `proofreel suite examples/acme-notes/flows --out review-acme`.
@@ -0,0 +1,29 @@
1
+ [project]
2
+ name = "proofreel"
3
+ dynamic = ["version"]
4
+ description = "Record an agent driving a screen as a review video and page: a gliding pointer, click rings, auto zoom, captions, and checks."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ dependencies = ["pillow>=10.1,<13", "vncdotool==1.2.0"]
10
+
11
+ [project.optional-dependencies]
12
+ network = ["mitmproxy>=11"]
13
+ browser = ["websocket-client"]
14
+
15
+ [project.scripts]
16
+ proofreel = "proofreel.cli:main"
17
+
18
+ [build-system]
19
+ requires = ["hatchling"]
20
+ build-backend = "hatchling.build"
21
+
22
+ [tool.hatch.version]
23
+ path = "src/proofreel/__init__.py"
24
+
25
+ [tool.hatch.build.targets.sdist]
26
+ include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["src/proofreel"]
@@ -0,0 +1,36 @@
1
+ """Record an agent driving a screen, and turn it into a review video and page."""
2
+
3
+ import hashlib
4
+ import os
5
+ import shutil
6
+ import subprocess
7
+ import tempfile
8
+ from importlib import resources
9
+ from pathlib import Path
10
+
11
+ __version__ = "1.0.0"
12
+
13
+ HOME = Path(os.environ.get("PROOFREEL_HOME", Path.home() / ".proofreel"))
14
+
15
+
16
+ class Problem(Exception):
17
+ """A failure that a person or agent can fix. The message says what happened and how to fix it."""
18
+
19
+
20
+ def swift_tool(source, *flags):
21
+ """A Swift file of this package, compiled once on the host. The name holds a hash of the source and the flags,
22
+ so a change builds it again. The build goes to a temporary file first, so parallel runs never see half a binary."""
23
+ text = resources.files(__name__).joinpath(source).read_bytes()
24
+ digest = hashlib.sha256(text + repr(flags).encode()).hexdigest()[:12]
25
+ binary = HOME / "bin" / f"proofreel-{Path(source).stem}-{digest}"
26
+ if binary.exists():
27
+ return binary
28
+ if not shutil.which("swiftc"):
29
+ raise Problem(f"{source} is built with swiftc, so it needs a macOS host with Xcode or the Command Line Tools.")
30
+ binary.parent.mkdir(parents=True, exist_ok=True)
31
+ with tempfile.TemporaryDirectory(dir=binary.parent) as temp, \
32
+ resources.as_file(resources.files(__name__).joinpath(source)) as path:
33
+ built = Path(temp) / binary.name
34
+ subprocess.run(["swiftc", "-O", *flags, str(path), "-o", str(built)], check=True, capture_output=True)
35
+ built.replace(binary)
36
+ return binary
@@ -0,0 +1,88 @@
1
+ """Read the accessibility (AX) tree of a macOS guest, and find elements by their label.
2
+
3
+ A small helper (ax.swift) runs in the guest over SSH. macOS gives the Accessibility grant to the process that SSH
4
+ starts (/usr/libexec/sshd-keygen-wrapper), so the app under test needs no permission of its own.
5
+ """
6
+
7
+ import json
8
+ import time
9
+
10
+ from . import Problem, guest
11
+
12
+
13
+ def tree(run, app=None):
14
+ """The AX tree of the app's windows (the front app by default), and the main screen size in points. The helper
15
+ is compiled on the host and copied to the guest the first time."""
16
+ result = guest.GUESTS["macos"].helper(run, "ax.swift", *(["--app", app] if app else []))
17
+ if result.returncode:
18
+ raise Problem(f"AX: {result.stderr.strip() or f'the helper failed ({result.returncode})'}")
19
+ return json.loads(result.stdout)
20
+
21
+
22
+ def to_pixels(point, scale):
23
+ return round(point * scale)
24
+
25
+
26
+ def intersect(a, b):
27
+ left, top = max(a[0], b[0]), max(a[1], b[1])
28
+ return left, top, max(0, min(a[0] + a[2], b[0] + b[2]) - left), max(0, min(a[1] + a[3], b[1] + b[3]) - top)
29
+
30
+
31
+ def flatten(node, scale, clip, depth=0):
32
+ """Each element with its depth, center, and box in screen pixels. Visible: its center is in its window and scroll areas."""
33
+ frame = node.get("frame")
34
+ if frame and (depth == 0 or node["role"] == "AXScrollArea"):
35
+ clip = intersect(clip, frame)
36
+ element = {k: v for k, v in node.items() if k != "children"}
37
+ element["depth"] = depth
38
+ element["visible"] = False
39
+ if frame and frame[2] > 0 and frame[3] > 0:
40
+ cx, cy = frame[0] + frame[2] / 2, frame[1] + frame[3] / 2
41
+ element.update(x=to_pixels(cx, scale), y=to_pixels(cy, scale),
42
+ box=[to_pixels(v, scale) for v in frame],
43
+ visible=clip[0] <= cx < clip[0] + clip[2] and clip[1] <= cy < clip[1] + clip[3])
44
+ yield element
45
+ for child in node.get("children", []):
46
+ yield from flatten(child, scale, clip, depth + 1)
47
+
48
+
49
+ def elements(run, screen, app=None):
50
+ data = tree(run, app)
51
+ scale = screen.size()[0] / data["screen"]["w"]
52
+ clip = (0, 0, data["screen"]["w"], data["screen"]["h"])
53
+ return [element for window in data["windows"] for element in flatten(window, scale, clip)]
54
+
55
+
56
+ def names(element):
57
+ return [v for k in ("title", "description", "label", "value", "id") if isinstance(v := element.get(k), str)
58
+ and not (k == "id" and v.startswith("_NS:"))]
59
+
60
+
61
+ def has_role(element, role):
62
+ want = role.lower().removeprefix("ax")
63
+ return any((element.get(k) or "").lower().removeprefix("ax") == want for k in ("role", "subrole"))
64
+
65
+
66
+ def matches(items, label, role=None):
67
+ """Visible elements named the label, then ones whose name contains it. Case is ignored."""
68
+ want = label.strip().lower()
69
+ pool = [e for e in items if e["visible"] and (not role or has_role(e, role))]
70
+ exact = [e for e in pool if any(name.strip().lower() == want for name in names(e))]
71
+ return exact + [e for e in pool if e not in exact and any(want in name.lower() for name in names(e))]
72
+
73
+
74
+ def wait_for(run, screen, label, seconds, present=True, app=None, role=None):
75
+ end = time.time() + seconds
76
+ while True:
77
+ found = matches(elements(run, screen, app), label, role)
78
+ if bool(found) == present or time.time() > end:
79
+ return found
80
+ time.sleep(0.5)
81
+
82
+
83
+ def describe(element, indent=True):
84
+ where = f"{element['x']:5} {element['y']:5}" if element["visible"] else f"{'-':>5} {'-':>5}"
85
+ role = element["role"] + (f"/{element['subrole']}" if element.get("subrole") else "")
86
+ shown = " ".join(json.dumps(name, ensure_ascii=False) for name in dict.fromkeys(names(element)))
87
+ flags = "".join([" disabled" if element.get("enabled") is False else "", " focused" if element.get("focused") else ""])
88
+ return f"{where} {' ' * element['depth'] if indent else ''}{role} {shown}{flags}".rstrip()
@@ -0,0 +1,99 @@
1
+ import AppKit
2
+ import ApplicationServices
3
+
4
+ var appName: String?
5
+ var maxDepth = 60
6
+ var budget = 4000
7
+ var args = CommandLine.arguments.dropFirst().makeIterator()
8
+ while let arg = args.next() {
9
+ switch arg {
10
+ case "--app": appName = args.next()
11
+ case "--front": appName = nil
12
+ case "--depth": maxDepth = Int(args.next() ?? "") ?? maxDepth
13
+ default:
14
+ FileHandle.standardError.write("usage: proofreel-ax [--app <name>|--front] [--depth N]\n".data(using: .utf8)!)
15
+ exit(2)
16
+ }
17
+ }
18
+
19
+ func fail(_ message: String, _ code: Int32) -> Never {
20
+ FileHandle.standardError.write((message + "\n").data(using: .utf8)!)
21
+ exit(code)
22
+ }
23
+
24
+ guard AXIsProcessTrusted() else {
25
+ fail("This process has no Accessibility permission. Grant it to the process that starts it (over SSH: /usr/libexec/sshd-keygen-wrapper).", 3)
26
+ }
27
+
28
+ func attribute(_ element: AXUIElement, _ name: String) -> AnyObject? {
29
+ var value: AnyObject?
30
+ return AXUIElementCopyAttributeValue(element, name as CFString, &value) == .success ? value : nil
31
+ }
32
+
33
+ func text(_ value: AnyObject?, limit: Int = 200) -> String? {
34
+ guard let string = value as? String, !string.isEmpty else { return nil }
35
+ return string.count > limit ? String(string.prefix(limit)) + "…" : string
36
+ }
37
+
38
+ func plain(_ value: AnyObject?) -> Any? {
39
+ if let string = text(value) { return string }
40
+ if let number = value as? NSNumber { return number }
41
+ if let url = value as? URL { return url.absoluteString }
42
+ return nil
43
+ }
44
+
45
+ func frame(_ element: AXUIElement) -> [Double]? {
46
+ var point = CGPoint.zero, size = CGSize.zero
47
+ guard let position = attribute(element, kAXPositionAttribute), let extent = attribute(element, kAXSizeAttribute),
48
+ CFGetTypeID(position) == AXValueGetTypeID(), CFGetTypeID(extent) == AXValueGetTypeID(),
49
+ AXValueGetValue(position as! AXValue, .cgPoint, &point), AXValueGetValue(extent as! AXValue, .cgSize, &size)
50
+ else { return nil }
51
+ return [point.x, point.y, size.width, size.height].map { (Double($0) * 10).rounded() / 10 }
52
+ }
53
+
54
+ func node(_ element: AXUIElement, _ depth: Int) -> [String: Any] {
55
+ budget -= 1
56
+ var out: [String: Any] = ["role": attribute(element, kAXRoleAttribute) as? String ?? "?"]
57
+ out["subrole"] = text(attribute(element, kAXSubroleAttribute))
58
+ out["title"] = text(attribute(element, kAXTitleAttribute))
59
+ out["description"] = text(attribute(element, kAXDescriptionAttribute))
60
+ out["id"] = text(attribute(element, kAXIdentifierAttribute))
61
+ out["value"] = plain(attribute(element, kAXValueAttribute))
62
+ if let titled = attribute(element, kAXTitleUIElementAttribute), CFGetTypeID(titled) == AXUIElementGetTypeID() {
63
+ let label = titled as! AXUIElement
64
+ out["label"] = text(attribute(label, kAXValueAttribute)) ?? text(attribute(label, kAXTitleAttribute))
65
+ }
66
+ out["enabled"] = attribute(element, kAXEnabledAttribute) as? Bool
67
+ out["focused"] = (attribute(element, kAXFocusedAttribute) as? Bool) == true ? true : nil
68
+ out["frame"] = frame(element)
69
+ let children = attribute(element, kAXChildrenAttribute) as? [AXUIElement] ?? []
70
+ if depth < maxDepth && budget > 0 && !children.isEmpty {
71
+ out["children"] = children.prefix(budget).map { node($0, depth + 1) }
72
+ }
73
+ return out
74
+ }
75
+
76
+ func match(_ app: NSRunningApplication, _ name: String) -> Bool {
77
+ let want = name.lowercased()
78
+ return app.localizedName?.lowercased() == want || app.bundleIdentifier?.lowercased() == want
79
+ }
80
+
81
+ let apps = NSWorkspace.shared.runningApplications
82
+ let found = appName.map { name in
83
+ apps.first { match($0, name) } ?? apps.first { $0.localizedName?.lowercased().contains(name.lowercased()) == true }
84
+ } ?? NSWorkspace.shared.frontmostApplication
85
+ guard let pid = found?.processIdentifier else { fail(appName.map { "No running app named \($0)." } ?? "No app is in front.", 4) }
86
+
87
+ let app = AXUIElementCreateApplication(pid)
88
+ AXUIElementSetMessagingTimeout(app, 3)
89
+ let windows = attribute(app, kAXWindowsAttribute) as? [AXUIElement] ?? []
90
+ let display = CGDisplayBounds(CGMainDisplayID())
91
+ let result: [String: Any] = [
92
+ "app": NSRunningApplication(processIdentifier: pid)?.localizedName ?? "",
93
+ "pid": pid,
94
+ "screen": ["w": display.width, "h": display.height],
95
+ "windows": windows.map { node($0, 0) },
96
+ ]
97
+ let data = try JSONSerialization.data(withJSONObject: result, options: [.sortedKeys])
98
+ FileHandle.standardOutput.write(data)
99
+ FileHandle.standardOutput.write("\n".data(using: .utf8)!)