shapewall 0.0.0-stage → 0.2.2

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 (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
package/README.md CHANGED
@@ -1,3 +1,652 @@
1
- # Temporary Holding Version
1
+ # Shapewall
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/shapewall)](https://www.npmjs.com/package/shapewall)
4
+ [![CI](https://github.com/danbaruch/shapewall/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/danbaruch/shapewall/actions/workflows/ci.yml)
5
+ [![License: Apache-2.0 and FSL-1.1](https://img.shields.io/badge/license-Apache--2.0%20%2B%20FSL--1.1-blue)](#license)
6
+
7
+ **Every page of your site on one zoomable wall, with comments pinned to elements that your coding agent can act on.**
8
+
9
+ ![The demo board: every page of a small site, grouped, at desktop and phone width](docs/images/board-overview.png)
10
+
11
+ With your dev server running, in its project folder:
12
+
13
+ ```sh
14
+ npx shapewall doctor --install-browser # once: downloads the Chromium that captures use
15
+ npx shapewall init --base-url http://localhost:3000 # your dev server: finds its pages
16
+ npx shapewall capture # every page, desktop and phone
17
+ npx shapewall serve --open # the board, in your browser
18
+ ```
19
+
20
+ **[Live demo](https://shapewall.com/demo/)** (no install: a board of a fictional product, 26 pages, comments in every state; comments
21
+ you add stay in your browser) · **[Docs](https://shapewall.com/docs)** · [Quickstart details](#quickstart)
22
+
23
+ Shapewall captures each page at desktop and phone width, lays them out on a canvas grouped by section, and lets you pin comments to the
24
+ exact element that needs work. Zoom out to see the whole product at once; zoom in and the screenshot turns into the real, captured
25
+ HTML, with responsive CSS intact and every script stripped. Comments come out as structured JSON, so a coding agent can read the
26
+ feedback, fix the code, and you recapture to check.
27
+
28
+ - **Whole-site view.** Desktop, tablet and phone captures side by side, grouped (Marketing, App, ...), with per-page notes like
29
+ "signed-out state". Add your own viewports, such as a landscape phone.
30
+ - **Screenshots far out, live HTML up close.** Zoomed out you see light thumbnails; zoomed in (or with "Open live") a frame swaps to a
31
+ self-contained HTML snapshot you can select text in. It runs no JavaScript: three independent locks keep it inert.
32
+ - **Comments that stay put.** On live HTML a comment is anchored to the element under your click (a CSS selector plus its text), so after
33
+ the next capture the pin follows the button, not the old pixel. Resolve, reopen, edit, reply in a thread, and **@mention** people or
34
+ `@agent`. Search the comments and narrow them by state (agent working, needs a person, reopened, ...) or by who is mentioned.
35
+ - **Variants.** Put another version of a page (a branch preview, a redesign) right beside the original.
36
+ - **Journeys.** Name the path people take ("Sign up": home, pricing, sign in, dashboard) in the config or by clicking pages on the board,
37
+ then step through it with arrows between the steps. A journey can fork ("link works" or "link expired") and rejoin; pick a branch as
38
+ you step through. **Links** draws the links each capture found between your pages.
39
+ - **Before and after.** Every recapture keeps the previous shot, so a resolved comment shows before and after near its pin, with a link
40
+ to the pull request or commit that fixed it.
41
+ - **Page history.** Every page keeps its earlier captures: open a page's history to see an earlier capture beside the current one,
42
+ with the changed pixels in red and the comments that were made on each.
43
+ - **Pages from your sitemap.** `shapewall sitemap https://www.example.com/sitemap.xml` fills the page list from a sitemap (or a sitemap
44
+ index), grouped by path, without repeats.
45
+ - **Compare environments.** Capture staging and production, then see each page in both with the changed pixels in red, and filter to the
46
+ pages that changed.
47
+ - **Installs as an app.** The board is a PWA: add it to a phone's home screen and it opens full screen.
48
+ - **Made for the agent loop.** `shapewall comments --json` hands any coding agent the page, viewport, selector, element text, position and
49
+ screenshot path for each open comment. `shapewall watch` dispatches new comments to your agent by itself, and `shapewall mcp` gives it
50
+ tools. It fixes, recaptures, replies on the comment; the pins tell you if it worked.
51
+ - **Works on a phone.** 44 px touch targets, a bottom sheet for comments, and Back closes the topmost panel instead of leaving the board.
52
+ - **Small and local.** Node 22, Playwright, Express, React Flow. Data is plain JSON files in `.shapewall/`. No account, no cloud.
53
+ - **A team server when you want one.** `shapewall hosted` adds passkey accounts, workspaces with roles, share links and live presence
54
+ on a server you run. [Multiplayer (beta)](#multiplayer-on-your-own-server).
55
+ - **Switch local projects.** Serve each project on its own port; the site dropdown lists them together while keeping every project's
56
+ agent and files separate. [Several local projects](docs/deployment.md#several-local-projects).
57
+
58
+ | Live HTML with an element-anchored comment | On a phone |
59
+ | ---------------------------------------------------------------- | ------------------------------------------------------ |
60
+ | ![Live HTML with a pinned comment](docs/images/live-comment.png) | ![The board on a phone](docs/images/phone-comment.png) |
61
+
62
+ ![The Sign up journey: numbered steps and arrows between them, every other page faded](docs/images/journeys.png)
63
+
64
+ ## Quickstart
65
+
66
+ ### Requirements
67
+
68
+ - Runs on Linux, macOS and Windows with Node.js **22.13 or newer**. Linux is the primary tested platform.
69
+ - Chromium for captures: `shapewall doctor --install-browser` downloads Playwright's build, or use a Chrome you already have.
70
+ On a bare Linux server, a container or WSL, Chromium also needs system libraries: run
71
+ `sudo npx playwright install-deps chromium` once.
72
+
73
+ ### Install
74
+
75
+ In the project you want to review, with its dev server running:
76
+
77
+ ```sh
78
+ npm install --save-dev shapewall
79
+ npx shapewall doctor --install-browser # downloads the Chromium that captures use
80
+ npx shapewall init --base-url http://localhost:3000
81
+ npx shapewall capture
82
+ npx shapewall serve --open
83
+ ```
84
+
85
+ `--base-url` is your running dev server, staging or production. `init` finds its pages: `<base URL>/sitemap.xml` if there is one,
86
+ else the links on the home page (two levels deep, up to 25 pages, same site only). If the site is not up it writes just the home page
87
+ and says what to do next. `--sitemap URL|FILE` takes another sitemap; `--no-discover` skips the lookup.
88
+ In an empty folder, run `npm init -y` before the install. Without the install, `npx shapewall ...` downloads the package on first use,
89
+ as in the three lines at the top.
90
+
91
+ `npx shapewall` runs the copy installed in the project. The rest of this README shortens the command to `shapewall`.
92
+
93
+ For the latest unreleased build, install from GitHub with `npm install --save-dev github:danbaruch/shapewall` (npm clones the
94
+ repository and builds the board: about a minute), or from a clone:
95
+
96
+ ```sh
97
+ git clone https://github.com/danbaruch/shapewall.git
98
+ cd shapewall
99
+ npm ci # installs the locked dependencies and builds the board
100
+ npm link # optional: puts `shapewall` on your PATH
101
+ ```
102
+
103
+ Without `npm link`, run `node /absolute/path/to/shapewall/bin/shapewall.js` from your project. A global install straight from GitHub
104
+ (`npm install -g github:...`) fails, because npm cannot build a git package in global mode.
105
+
106
+ Good to know:
107
+
108
+ - To capture with a Chrome you already have, set `"browser": { "channel": "chrome" }` and skip `--install-browser`.
109
+ - `shapewall doctor` checks the browser (by starting it), the config, the output folder, the port and notifications.
110
+ - `init` adds `.shapewall/`, `shapewall-export/` and `*.auth.json` to `.gitignore`. Captures and saved sign-ins of a private site are
111
+ private: keep them out of git.
112
+ - Edits to titles, pages and journeys in the config show up on the next refresh of the board, with no restart.
113
+
114
+ Next: [configuration and sign-in](docs/config.md#auth), [capture warnings and pacing](docs/capture-warnings.md),
115
+ [local accounts](docs/local-accounts.md), [updates](docs/updates.md) and [deployment](docs/deployment.md).
116
+
117
+ ### Multiplayer on your own server
118
+
119
+ **Beta.** The team server is in beta: keep backups and expect changes between releases.
120
+
121
+ ```sh
122
+ shapewall hosted --data ./hosted-data --tailscale --tailscale-port 8443
123
+ ```
124
+
125
+ Run that on one machine. Teammates open its HTTPS address over Tailscale, sign in with their own passkeys and join a workspace you
126
+ invite them to. Captures still run on your machine: `shapewall share --remote URL` moves an existing project to the server, or `login`
127
+ and `push` upload new captures. Comments, roles, scoped agents and live presence work on the shared server. You need no public domain
128
+ and no Shapewall account.
129
+
130
+ The command runs in the foreground and sets up Tailscale Serve; running it as a service and backing it up are covered in
131
+ [the hosted guide](docs/hosted.md), with a [checklist to walk through before you invite the team](docs/hosted.md#before-you-invite-the-team).
132
+ `shapewall serve --tailscale` is the single-player counterpart: your own board on your other devices.
133
+
134
+ ### The demo
135
+
136
+ ```sh
137
+ git clone https://github.com/danbaruch/shapewall.git
138
+ cd shapewall
139
+ npm ci # also builds the clients
140
+ node bin/shapewall.js doctor --install-browser # once (no config needed); or use your installed Chrome (see Config)
141
+ npm run demo # captures the bundled demo site and serves its board
142
+ npm run demo -- --full # the whole fictional product, as in the live demo (26 pages)
143
+ ```
144
+
145
+ Open http://127.0.0.1:4600/ and try it: zoom in on a page, click **Comment**, click a button on the page, write a note.
146
+
147
+ ## How it works
148
+
149
+ 1. **Capture.** Playwright opens each page in Chromium at every viewport (default 1440x2200 desktop and 390x1800 phone; add a tablet
150
+ or your own; fixed frames, not full-page). It waits for the network to settle, your `waitFor` selector and any `actions`, and for images in view to finish loading. It
151
+ writes a PNG, a thumbnail of the same frame, a live HTML snapshot and its element map. Runs hold a lock, so two captures of one board never overlap; a
152
+ full run is written to a staging folder and swapped in at the end, so a failed run keeps the previous captures.
153
+ 2. **Board.** `shapewall serve` starts a small Express server (127.0.0.1 only by default) with the API and the React Flow client. The
154
+ canvas only loads full-size images and live HTML for frames that are big enough on screen, at most two live documents at a time.
155
+ 3. **Comments.** Stored in `.shapewall/<board>/comments.json`, written atomically under a file lock, so the server and the CLI can change
156
+ them at the same time.
157
+
158
+ ### How live HTML is sandboxed
159
+
160
+ A captured page is turned into one self-contained document and shown inside the board. It must never run code from the captured site, so
161
+ there are three independent layers, any one of which is enough on its own:
162
+
163
+ 1. **Sanitized at capture.** The rendered DOM is cloned in the page (so client-rendered content is included), then rebuilt by a strict
164
+ allowlist sanitizer in Node (parse5, the HTML spec parser): no `script`, `iframe`, `object`, `embed`, `base`, `link`, `template` or SVG
165
+ animation elements; no `on*` handlers, `srcset`, `formaction` or `target`; links only `http(s)`, `mailto`, `tel` and `#`; images and
166
+ fonts only as complete, inlined `data:` URIs; CSS without `@import`, `expression()` or remote `url()`, including when spelled with CSS
167
+ escapes. Hidden inputs and password values are dropped, so CSRF tokens and typed secrets never reach the file. Stylesheets keep their
168
+ `@media` rules, so the snapshot stays responsive. Images are re-encoded from the decoded pixels and identical images are stored once.
169
+ 2. **Served with a strict CSP.** `default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:; base-uri 'none';
170
+ form-action 'none'; frame-ancestors 'self'`. No script source at all. The same policy is also embedded as a `<meta>` tag, for static
171
+ exports where no headers are sent.
172
+ 3. **Framed in a sandbox.** `<iframe sandbox="">` gives the document an opaque origin, with no scripts. Pins and click targets come
173
+ from the captured element map, so the board never reads the frame's DOM. Only older captures without a map on a local board keep
174
+ `allow-same-origin` until their next recapture; hosted boards and static exports always use an opaque frame.
175
+
176
+ Details and limits: [docs/architecture.md](docs/architecture.md).
177
+
178
+ ## The agent loop
179
+
180
+ Shapewall is vendor neutral: any coding agent that can run a shell command and read JSON can use it.
181
+
182
+ ```sh
183
+ shapewall comments --open --json > feedback.json
184
+ ```
185
+
186
+ One item of its `comments` array, from the demo board (abridged):
187
+
188
+ ```json
189
+ {
190
+ "id": 1,
191
+ "status": "open",
192
+ "body": "Make the Plus button stand out more. Maybe show the yearly price too?",
193
+ "author": "Robin",
194
+ "page": { "id": "pricing", "path": "/pricing/", "title": "Pricing", "url": "http://127.0.0.1:4601/pricing/" },
195
+ "viewport": { "name": "desktop", "width": 1440, "height": 2200 },
196
+ "position": { "xPercent": 50, "yPercent": 27.05, "x": 720, "y": 595 },
197
+ "element": { "selector": "a[data-testid=\"plus-cta\"]", "text": "Try Plus free" },
198
+ "files": {
199
+ "screenshot": "/path/to/project/.shapewall/demo/captures/pricing.desktop.png",
200
+ "liveHtml": "/path/to/project/.shapewall/demo/captures/pricing.desktop.html"
201
+ },
202
+ "agentStatus": null,
203
+ "replies": []
204
+ }
205
+ ```
206
+
207
+ Then:
208
+
209
+ 1. **Comment** on the board (people do this part).
210
+ 2. **Fix.** Give the agent the JSON (or tell it to run the command). The selector and text point it at the element; the screenshot shows
211
+ what the reviewer saw.
212
+ 3. **Recapture** the pages it touched: `shapewall capture --only pricing`.
213
+ 4. **Report.** The agent replies and marks its work: `shapewall comments reply 1 --body "Bolder button, yearly price under it"` and
214
+ `shapewall comments status 1 done` (or `needs-human` with a question).
215
+ 5. **Check** the board. Pins on live HTML follow their elements; resolve what is done, or let the agent do it:
216
+ `shapewall comments resolve 1 --note "Bolder Plus button, yearly price under it"`.
217
+
218
+ To close the loop without anyone typing a command:
219
+
220
+ - `shapewall watch` hands every new open comment to an agent exactly once: as a JSON line on stdout, or by running your command per comment.
221
+ - `shapewall watch --exec "claude -p '...'"` (or `codex exec '...'`) gets the comment JSON on stdin, no shell involved.
222
+ - `shapewall watch --mention agent` only hands out comments that tag `@agent` (in the text or a reply), so people can talk first.
223
+ - Its status goes `queued`, `working`, then `done` or `needs-human`; a restart or a second watcher never hands one out twice.
224
+ - `shapewall mcp` is an MCP server with tools to list, read (with a crop of the screenshot), reply, set status, resolve and recapture.
225
+ - With Shapewall installed in your project: `claude mcp add shapewall -- npx shapewall mcp`; Codex and other clients in
226
+ [docs/agent-workflow.md](docs/agent-workflow.md).
227
+
228
+ An agent you connect on the board edits the folder the config is in, shown as **Source folder on the Shapewall computer** in Settings.
229
+ So put `shapewall.config.json` in the checkout the agent should change, and serve one project per repository. More in
230
+ [source folder and agent sign-in](docs/agents.md#source-folder-and-agent-sign-in).
231
+
232
+ ### GitHub connect
233
+
234
+ Set `"github": { "repo": "owner/name" }` in the config and a token in `GITHUB_TOKEN` (or `SHAPEWALL_GITHUB_TOKEN`; never in the config).
235
+ Then a comment becomes a GitHub issue with one click (**GitHub issue** on the board, `shapewall github issue 12`, the API or MCP), with the
236
+ comment text, page URL, element, screenshot link and a link back to the board. Pull requests that say `shapewall:12` or
237
+ `Fixes shapewall#12` (or close the comment's issue) are linked to it by `shapewall github sync` or a signed webhook, and when one merges,
238
+ the comment resolves with the PR as its fix. Details: [docs/github.md](docs/github.md).
239
+
240
+ Prompts that work, the data shapes, and how to keep it safe (comments are untrusted input): [docs/agent-workflow.md](docs/agent-workflow.md).
241
+ Copy-paste setups for Claude Code, Codex, goose, Ollama and chat bots: [docs/agent-recipes.md](docs/agent-recipes.md).
242
+ Optional integrations: [notifications](#notifications), GitHub connect above, and a [bridge to agents in a Buzz chat](docs/buzz.md).
243
+
244
+ ### Chat with an agent
245
+
246
+ The board has a chat panel: a thread for the board and one per comment, streaming answers, images (paste, drop, or a page or element
247
+ crop from the board), voice in, and read aloud with the system voice or natural voices that run in your browser (Kokoro, a
248
+ one-time download of about 90 MB; the text never leaves the browser). Connect any OpenAI-compatible endpoint with `"agent": { "baseUrl", "model" }` and the key
249
+ in `SHAPEWALL_AGENT_API_KEY` (OpenAI, DeepSeek, OpenRouter, or Ollama with no key), or an agent CLI on your machine over ACP with its
250
+ own subscription login: `shapewall serve --agent-acp "claude-agent-acp"` (also `codex-acp`, `goose acp`, `gemini --acp`). Or skip the
251
+ flags: open the board with `shapewall serve --open` and click **Connect** next to the agent CLI it found on your machine. Board text
252
+ goes to the agent as quoted data, never as instructions. Details: [docs/agents.md](docs/agents.md).
253
+
254
+ ### The sandboxed starter agent
255
+
256
+ For shared boards, `shapewall agent run --comment 12` (or `agent watch`) works on a comment inside a podman or docker container: only a
257
+ fresh checkout of the repo (no .git) mounted, egress to the package registry only, the model called from the host so the key never enters the container,
258
+ fixed tools, shell commands only with your approval on the board, a per-board list of who may dispatch work (guest comments never), and
259
+ budgets. The output is a branch, optionally a pull request, never a push to main. `shapewall agent doctor` checks the sandbox. Setup,
260
+ threat model and what each runtime enforces: [docs/starter-agent.md](docs/starter-agent.md).
261
+
262
+ ## Config
263
+
264
+ `shapewall.config.json` (all paths relative to the file):
265
+
266
+ ```json
267
+ {
268
+ "title": "My site",
269
+ "baseUrl": "http://localhost:3000",
270
+ "publicUrl": "https://www.example.com",
271
+ "outputDir": ".shapewall",
272
+ "concurrency": 2,
273
+ "viewports": {
274
+ "desktop": { "width": 1440, "height": 2200 },
275
+ "phone": { "width": 390, "height": 1800 }
276
+ },
277
+ "auth": { "storageState": "./reviewer.auth.json" },
278
+ "groups": ["Marketing", "App"],
279
+ "pages": [
280
+ { "id": "home", "path": "/", "title": "Home", "group": "Marketing" },
281
+ { "id": "pricing", "path": "/pricing", "title": "Pricing", "group": "Marketing", "waitFor": ".plans" },
282
+ {
283
+ "id": "settings",
284
+ "path": "/settings?tab=billing",
285
+ "title": "Billing settings",
286
+ "group": "App",
287
+ "note": "Sample data",
288
+ "actions": [{ "click": "button[aria-label='Open billing']" }, { "waitFor": ".invoice-list" }]
289
+ }
290
+ ]
291
+ }
292
+ ```
293
+
294
+ | Key | What it does |
295
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
296
+ | `baseUrl` | Where pages are captured from (a dev server, a preview deploy). Required. |
297
+ | `publicUrl` | Optional. Links in live HTML and "Open page" use it instead of `baseUrl`. |
298
+ | `pages[]` | `id` (lowercase, dashes), `path` (starts with `/`, may have a query), `title`, `group`, `note`. |
299
+ | `pages[].waitFor` | CSS selector that must be visible before the shot. |
300
+ | `pages[].actions` | Steps before the shot: `click`, `tap`, `fill`, `press`, `hover`, `wait`, `waitFor`, `waitForFunction`, `scrollTo`, `mouse`, `hold`, `keyDown`/`keyUp`. |
301
+ | | Any action may add `optional`, `viewports`, `timeout` and (for `click`, `tap`, `hover`, `fill`) `force`. |
302
+ | `pages[].viewports` | Only some viewports for this page, e.g. `["desktop"]`. Its card on the board shows only those frames. |
303
+ | `pages[].frameHeight` | This page's own frame height: a number, or `{ "desktop": 900, "phone": 844 }`. For screen-sized app pages beside long marketing pages. |
304
+ | `pages[].localStorage` | Keys set before the page's scripts run, e.g. `{ "tutorialSeen": "1" }`. Also at the top level and per board. |
305
+ | `pages[].timeout` | Milliseconds this page may take, instead of `timeouts.page`. |
306
+ | `viewports` | Keyed by name: `desktop`, `tablet`, `phone` or your own (`phone-landscape`), each `{ width, height }` plus optional `layoutHeight`, `mobile`, `touch`, `userAgent`. |
307
+ | `setup` | Actions run once per viewport (dismiss a cookie banner, start a game); the pages in scope start from the state they leave. |
308
+ | `block` | Requests to block during capture: `"analytics"` (a built-in list) and URL patterns. |
309
+ | `reducedMotion` | `"reduce"` (default) or `"no-preference"`: what `prefers-reduced-motion` the capture browser reports. |
310
+ | `sitemap` | Default source for `shapewall sitemap`: a URL or file, or `{ source, limit?, group?, exclude? }`. |
311
+ | `auth.storageState` | A saved sign-in (cookies, localStorage) for signed-in pages; `shapewall auth record` writes one. Keep it out of git. |
312
+ | `auth.loginScript` | A module whose default export logs in: `async ({ page, context, baseUrl }) => {}`. Credentials from env vars. |
313
+ | `browser.channel` | `"chrome"` to use an installed Chrome instead of Playwright's Chromium (or `executablePath`). |
314
+ | `concurrency` | Pages captured in parallel (1 to 8, default 2). |
315
+ | `capturePacing` | `{ intervalMs, rateLimitCooldownMs }` to slow captures down for a site that rate limits. |
316
+ | `timeouts` | `{ "page": 45000, "settle": 8000 }` in ms. |
317
+ | `liveHtml` | `false` to capture screenshots only. |
318
+ | `boards[]` | Several boards in one file: each `{ id, title, baseUrl?, publicUrl?, groups?, pages }`, with its own `viewports`, `setup`, `auth`, `block`. |
319
+ | `journeys[]` | `{ id, name, steps, description? }`; steps are page ids, and may fork. See [docs/journeys.md](docs/journeys.md). |
320
+ | `environments[]` | `{ id, baseUrl, publicUrl?, title? }`; the first is the default. For `capture --env` and compare mode. |
321
+ | `versions` | Previous captures kept per page and viewport for before/after (default 5, `0` for none). |
322
+ | `checks` | `{ seo, budgets }` for [page checks](docs/page-checks.md). |
323
+ | `notifications` | Webhook, Slack, Discord and email messages for comment events. See [docs/notifications.md](docs/notifications.md). |
324
+ | `github` | `{ repo, boardUrl?, labels? }` for GitHub connect. The token comes from the environment only. See [docs/github.md](docs/github.md). |
325
+ | `agent` | `{ baseUrl, model }` for the board chat. The key comes from the environment only. See [docs/agents.md](docs/agents.md). |
326
+ | `starterAgent` | `{ trusted, testCommand, setupCommand, budget, ... }` for the sandboxed starter agent. See [docs/starter-agent.md](docs/starter-agent.md). |
327
+
328
+ Full reference: [docs/config.md](docs/config.md). Example login hook:
329
+ [examples/auth/login.example.mjs](https://github.com/danbaruch/shapewall/blob/main/examples/auth/login.example.mjs).
330
+
331
+ ## CLI
332
+
333
+ The commands you will use most:
334
+
335
+ ```text
336
+ shapewall init [--base-url URL] [--sitemap [URL|FILE]] write shapewall.config.json
337
+ shapewall auth record sign in by hand and save the session for captures
338
+ shapewall capture [--only ID|PATH ...] [--env ID] [--json] capture pages and check their links
339
+ shapewall serve [--open] [--tailscale] [--accounts] the board, on http://127.0.0.1:4600/
340
+ shapewall comments [--open|--resolved|--all] [--json] feedback for you or a coding agent
341
+ shapewall comments reply|status|resolve|reopen ID ... what the agent reports back
342
+ shapewall watch [--exec "CMD ARGS"] [--mention NAME] hand each new comment to an agent
343
+ shapewall mcp MCP server for coding agents
344
+ shapewall checks | audit page checks and Lighthouse lab audits
345
+ shapewall export [--out DIR] a static, read-only copy
346
+ shapewall hosted | share | login | push the self-hosted team server and its clients
347
+ shapewall doctor [--install-browser] check the setup
348
+ ```
349
+
350
+ `--config FILE` works with every command, and `shapewall <command> --help` prints one command's options. An option a command does not
351
+ take is an error with a "did you mean" hint.
352
+
353
+ <details>
354
+ <summary>Every command and option (<code>shapewall --help</code>)</summary>
355
+
356
+ ```text
357
+ Usage: shapewall <command> [options]
358
+
359
+ Commands
360
+ buzz-bridge run a private foreground gateway to existing Buzz agents
361
+ --bridge-config FILE private operator map outside project/capture data; Ctrl-C stops it
362
+ no new agent, session, model, or automatic completion (docs/buzz.md)
363
+ settings open temporary host-only agent settings (no board or chat)
364
+ --port N loopback port (default: a free port)
365
+ --open open the private settings link in your browser
366
+ auth record open a fresh browser for manual capture sign-in
367
+ --board ID board to sign in to (default: the first)
368
+ --env ID environment to sign in to (default: the first)
369
+ --url URL optional sign-in page (never printed)
370
+ --timeout SECONDS time to finish (default 600, maximum 1800)
371
+ --overwrite explicitly replace this board/environment's saved state
372
+ press Enter to save; Ctrl-C, browser close or timeout discards
373
+ saves a private .shapewall-auth/*.auth.json; config stays unchanged
374
+ init write shapewall.config.json in this folder
375
+ --base-url URL the site to capture (default http://localhost:3000); finds its
376
+ pages: <base URL>/sitemap.xml, else links from the home page
377
+ (2 levels, 25 pages, same site only)
378
+ --sitemap [URL|FILE] take the pages from this sitemap instead
379
+ (alone: <base URL>/sitemap.xml)
380
+ (with --limit, --group, --exclude as for sitemap)
381
+ --no-discover do not look for pages: write the home page only
382
+ --force overwrite an existing config
383
+ sitemap [URL|FILE] add the pages of a sitemap.xml (or sitemap index) to the config
384
+ (default: the board's "sitemap" setting)
385
+ --limit N at most N new pages, the shallowest first (default 100)
386
+ --group NAME put them all in one group (default: by first path segment)
387
+ --exclude /PREFIX leave out paths starting with this (repeat or comma-separate)
388
+ --board ID board to add them to (default: the first)
389
+ --dry-run show what would be added, change nothing
390
+ --json machine-readable result
391
+ capture capture every page (desktop + phone, PNG + live HTML) and check its links
392
+ --board ID board to capture (default: the first)
393
+ --only ID|PATH only these pages (repeat or comma-separate)
394
+ --env ID capture this environment (default: the first)
395
+ --check-external also check links to other sites (default: same-site links only)
396
+ --json machine-readable summary on stdout (shots, failures, broken links); progress on stderr
397
+ -y, --yes never ask anything (capture does not prompt; for CI scripts)
398
+ exit code: 0 all shots ok, 2 some failed (an "expectStatus" page is ok), 1 error
399
+ checks [run|list] check original pages and save private diagnostic reports
400
+ checks flow --flow-file FILE run one explicit interaction flow, with an optional final accessibility snapshot
401
+ checks accessibility --only ID [--viewport NAME] audit one original page state with axe
402
+ --board ID board to check (default: the first)
403
+ --env ID environment to check (default: the first)
404
+ --only ID|PATH only these pages (repeat or comma-separate)
405
+ --seo | --no-seo include public SEO and social-image checks, or leave them out when the config turns them on
406
+ --limit N maximum page views to check (default 20)
407
+ --source-build SHA source revision for report provenance
408
+ --json machine-readable reports; progress on stderr
409
+ audit [board] run bounded Chrome Lighthouse lab audits on original pages
410
+ --board ID board to audit (default: the first)
411
+ --env ID environment to audit (default: the first)
412
+ --only ID only these page ids (repeat or comma-separate)
413
+ --viewports NAMES configured viewport names, comma-separated
414
+ --samples N repeated samples per view (default 1, maximum 10)
415
+ --max-pages N explicit page cap (default 5, maximum 20)
416
+ --max-runs N explicit navigation cap (default 10, maximum 40)
417
+ --cache MODE cold, warm or auth-preserved
418
+ --production MODE production, development or unknown
419
+ --source-build SHA source build identifier for provenance
420
+ --browser-version V require this installed browser version
421
+ --seo | --no-seo include optional Lighthouse SEO checks, or leave them out when the config turns them on
422
+ --json machine-readable reports; progress on stderr
423
+ serve serve the board (http://127.0.0.1:4600/ by default)
424
+ --port N default 4600
425
+ --host ADDR default 127.0.0.1 (see docs/deployment.md before changing)
426
+ --tailscale[=print] private HTTPS over Tailscale; =print changes nothing
427
+ --no-identity pair even devices signed in as the Tailscale owner
428
+ --lan[=IP|INTERFACE] pair devices on your network (HTTP cookies can be sniffed)
429
+ --tls-cert FILE with --lan: HTTPS certificate (also --tls-key FILE)
430
+ --no-remote-chat paired devices cannot use the agent
431
+ --approve-on-host paired devices cannot approve agent commands
432
+ --open also open the board in your browser, with agent settings
433
+ --read-only no comments or captures from the UI
434
+ --accounts require local passkey accounts after owner setup (Node 22.13+)
435
+ --accounts-origin URL fixed HTTPS origin (default: loopback URL or --tailscale URL)
436
+ --no-capture comments allowed, captures only from the CLI
437
+ --buzz-bridge FILE owner-only existing Buzz conversation (private operator map; docs/buzz.md)
438
+ --allowed-host NAME extra Host header to accept (repeatable; also $SHAPEWALL_ALLOWED_HOSTS, "*" = any)
439
+ --chat | --no-chat the board chat with your agent (default on, off when shared beyond this machine)
440
+ --agent-acp "CMD" chat with an agent CLI over ACP, e.g. "claude-agent-acp" (installed globally)
441
+ (also $SHAPEWALL_AGENT_ACP; never read from the config; docs/agents.md)
442
+ --allow-remote-agent with --chat on a shared board, let an ACP agent run anyway (anyone reaching it acts as you)
443
+ devices list paired devices and pending requests for this project [--json]
444
+ devices approve CODE approve after matching the code on your device
445
+ devices deny CODE deny a pending request
446
+ devices revoke ID|--all revoke a device or all devices immediately
447
+ comments [list] print comments (feedback for you or a coding agent)
448
+ --open | --resolved | --all which ones (default --open)
449
+ --page ID only comments on this page
450
+ --mention NAME only comments that mention @NAME (in the text or a reply)
451
+ --since ID|TIME only comments after this comment id, or created or changed after this ISO time
452
+ --json machine-readable, with selectors, file paths and replies
453
+ --for-agent each comment quoted as untrusted data (<shapewall-data>), for an agent to read
454
+ comments get ID one comment, everything about it [--json] [--for-agent]
455
+ comments add add a comment --page ID --body TEXT [--viewport NAME (default the page's first)]
456
+ [--selector CSS (pin it to that element)] [--author NAME (default agent)] [--json]
457
+ comments resolve ID mark a comment resolved [--note TEXT] [--ref URL|COMMIT] [--author NAME] [--json]
458
+ comments reopen ID reopen a comment [--author NAME] [--json]
459
+ comments reply ID add a reply --body TEXT [--author NAME (default agent)] [--json]
460
+ comments status ID S agent status: queued, working, done, needs-human or clear [--note TEXT] [--author NAME] [--json]
461
+ --board ID board (default: the first); --remote URL for a hosted board (see push)
462
+ events comment events from every process (the shared log); never claims anything
463
+ --follow keep printing new events until Ctrl+C
464
+ --since ID|TIME after this event id (from --json) or ISO time
465
+ --limit N without --follow or --since: the last N (default 20)
466
+ --json one JSON line per event [--board ID]
467
+ journeys [list] print the board's journeys, with every fork and branch
468
+ --json machine-readable: steps (forks included), pages and every path
469
+ links links between the board's pages, from the last capture
470
+ --broken only links that lead to an error (4xx/5xx or no answer)
471
+ --board ID | --env ID | --json
472
+ watch hand each new open comment to an agent (runs until Ctrl+C)
473
+ --exec "CMD ARGS" run this command per comment (comment JSON on stdin; no shell)
474
+ without --exec, print one JSON line per comment
475
+ --concurrency N commands at once, 1 to 4 (default 1)
476
+ --recapture recapture the comment page after a successful --exec (local only)
477
+ --new-only skip comments that exist when the watch starts
478
+ --once hand out what is open now, wait for the commands, exit
479
+ --timeout MIN stop a command after this many minutes (default 60)
480
+ --mention NAME only comments that mention @NAME, e.g. --mention agent
481
+ --no-claim hand out every open comment once without claiming it (no agent status, beside other watchers)
482
+ a command that exits 0 must reply or set a status itself, else the
483
+ comment becomes needs-human (docs/agent-workflow.md)
484
+ agent run --comment ID the sandboxed starter agent on one comment: a container with only a fresh
485
+ worktree, egress to the package registry only (the model is called from here), a branch
486
+ --pr also push the branch and open a pull request (GitHub connect); not when it
487
+ touches CI config, manifests or build files unless --allow-ci-push
488
+ --git-remote NAME the git remote --pr pushes to (default origin; never from the config)
489
+ --fork-remote NAME push to your fork (a git remote) instead, and open the PR from it
490
+ --retry take a comment whose agent status is done or needs-human too
491
+ --trust-comment run a comment the trigger gate holds back (never a guest's)
492
+ --max-turns N | --max-tokens N | --max-minutes N budget for this comment
493
+ --max-disk SIZE disk cap on the checkout (default 2g; the run stops over it)
494
+ --model-timeout S seconds a model call may take to start answering, 1 to 900 (default 180 for
495
+ the first call, 60 after; tried once more on a timeout)
496
+ --trusted NAME may dispatch work (repeatable; adds to starterAgent.trusted)
497
+ --runtime podman|docker --image NAME --profile openai-compatible
498
+ --allow-host HOST[:PORT] extra egress host (repeatable) --registry HOST|none
499
+ --work-dir DIR where worktrees go (default: the cache folder)
500
+ agent watch run the starter agent on each comment the trigger gate lets through [--once]
501
+ agent doctor check the runtime, image, model, trust lists and the sandbox itself [--no-egress]
502
+ agent build-image build the agent's image from this package's Dockerfile.agent
503
+ --runtime podman|docker --image NAME (default localhost/shapewall-agent:latest)
504
+ (docs/starter-agent.md; --remote URL works for run and watch)
505
+ github issue ID open a GitHub issue from a comment (or show the one it has)
506
+ github link ID PR link a pull request (12, #12 or its URL) to a comment
507
+ github sync link pull requests that name a comment; resolve comments whose PR merged
508
+ (repo: "github.repo" in the config; token: $SHAPEWALL_GITHUB_TOKEN or $GITHUB_TOKEN,
509
+ else a signed-in GitHub CLI ("gh auth token"))
510
+ mcp MCP server on stdio for coding agents
511
+ --read-only | --no-capture
512
+ notify list notification channels, their events and what each still needs [--json]
513
+ notify test CHANNEL send a test message to one channel [--to EMAIL for email channels]
514
+ doctor check Node, the browser, the config, the port, the output folder, notifications and chat
515
+ --install-browser download the Chromium this Shapewall needs first (no config needed for this)
516
+ --port N port to check (default 4600)
517
+ --no-launch find the browser and the ACP agent without starting them
518
+ --agent-acp "CMD" the ACP agent to check: starts it, does the handshake, stops it (also $SHAPEWALL_AGENT_ACP)
519
+ --json machine-readable report
520
+ variant add PAGE capture another version of a page beside it
521
+ --url URL | --path /p the version to capture (path is on the board's baseUrl)
522
+ --title TEXT [--note TEXT] [--source TEXT] [--id ID] [--viewport desktop,phone]
523
+ the id is --id, else the title as a slug plus 4 random characters
524
+ variant rm ID | variant list
525
+ export static read-only copy of the boards
526
+ --include-checks explicitly include private diagnostic reports
527
+ --out DIR default shapewall-export
528
+ --no-comments leave comments out
529
+ --browser-comments visitors may comment; their comments stay in their own browser
530
+ --noindex ask search engines not to index the export
531
+ share --remote URL move local captures, history and comments to a shared project
532
+ --include-checks explicitly include private diagnostic reports
533
+ --board ID move only this board (default all)
534
+ --dry-run show counts; sends nothing
535
+ --no-comments captures, history and journeys only
536
+
537
+ Hosted Shapewall (docs/hosted.md)
538
+ login --remote URL get a project token through the browser; saved for the --remote commands
539
+ push upload the latest captures to a hosted project
540
+ --include-checks explicitly include private diagnostic reports
541
+ --remote URL the hosted Shapewall (or $SHAPEWALL_REMOTE)
542
+ --board ID only this board (default: every board)
543
+ comments | watch | mcp --remote URL
544
+ the same commands against a hosted board (--board ID picks one)
545
+ token: $SHAPEWALL_TOKEN or --token-file FILE (a project token, swp_...)
546
+ watch --exec commands get no token unless --pass-token
547
+ --include-guests comments and watch: also share link guests' comments (untrusted)
548
+ hosted run the hosted server (accounts, workspaces, pushed boards)
549
+ --data DIR default ./shapewall-hosted-data (or $SHAPEWALL_HOSTED_DATA)
550
+ --origin URL public origin, e.g. https://app.example.com (default http://HOST:PORT)
551
+ --port N | --host ADDR default 4700 on 127.0.0.1
552
+ --signup invite|open default invite (the first account uses the setup link)
553
+ --trust-proxy behind a reverse proxy on this host (client IPs from X-Forwarded-For)
554
+ --usercontent-origin URL serve live HTML only from this other origin (or $SHAPEWALL_USERCONTENT_ORIGIN)
555
+ --previous-origin URL while moving to a new origin: the old one (sign-in moves, up to 30 days)
556
+ --report-email ADDR where "Report this board" on public projects goes
557
+ --tailscale on your tailnet through tailscale serve (https://<machine>.<tailnet>.ts.net)
558
+ --tailscale-port N default 443; --funnel: share links public through Tailscale Funnel
559
+ (share pages only, never the console), on --funnel-port 8443|443|10000
560
+ --quotas FILE per-workspace quotas (default <data>/quotas.json when it exists)
561
+ --retention-hours N prune old versions every N hours (default 6, 0 = off); --retention-keep N (2)
562
+ hosted setup-link print the first account's one-time link (it is not in the log)
563
+ --data DIR | --new --new: make a new link (the old one stops working)
564
+ hosted move-origin --to URL move the server to a new origin (passkeys move with a rebind)
565
+ --data DIR | --days N | --status window 1 to 30 days (default 30)
566
+ hosted --setup --domain HOST write a Docker Compose + Caddy folder for your own domain
567
+ --usercontent-domain HOST live HTML on its own domain; --email (TLS); --dir (./shapewall-hosted)
568
+ --source DIR a Shapewall checkout to build from; --dry-run; --force; --start (build, start, setup link)
569
+ hosted admin list|suspend|resume|delete|export|reports|retention|log the operator's commands
570
+ hosted backup --to DIR [--keep-days N] a consistent copy while the server runs
571
+ hosted restore --from BACKUP --data NEW | --from BACKUP --check (the restore drill)
572
+
573
+ Global
574
+ --config FILE default ./shapewall.config.json (or $SHAPEWALL_CONFIG)
575
+ -h, --help | -v, --version (shapewall <command> --help shows one command)
576
+ ```
577
+
578
+ </details>
579
+
580
+ `shapewall capture` also checks the links on your pages and reports the broken ones (the summary, `shapewall links --broken`, a count
581
+ on the board's Links button); a page with `"expectStatus": 404` is captured as an error page on purpose. `capture --json` prints a
582
+ summary for CI. `shapewall export` writes a static, read-only copy of the boards that any static host can serve, compare data included.
583
+ `--browser-comments` lets visitors comment anyway, kept only in their own browser (localStorage), as in the live demo.
584
+ `shapewall sitemap` adds a sitemap's pages to the config: it follows sitemap indexes (and `.xml.gz`), keeps one site's URLs, skips paths
585
+ already on the board and repeats, groups pages by their first path segment, and with more than `--limit` (default 100) keeps the
586
+ shallowest. Run it again later to pick up only the new pages; `--dry-run` shows what it would add. More in
587
+ [docs/config.md](docs/config.md#sitemap-import).
588
+ `hosted`, `share`, `login`, `push` and `--remote` are the self-hosted team server and its clients (passkey accounts, workspaces,
589
+ pushed boards, project tokens): see [docs/hosted.md](docs/hosted.md).
590
+
591
+ ![A variant beside its page](docs/images/variant.png)
592
+
593
+ ## Notifications
594
+
595
+ Comment events (created, replied, mentioned, agent status changed, resolved, reopened) can go to a signed webhook, Slack, Discord or
596
+ email through Resend, each message with a link to the comment on the board. Mentions route per person (`@robin` pings Robin's Slack id or
597
+ emails Robin). Secrets live only in environment variables; the config names them. Sending never blocks the board, and failed sends
598
+ retry with backoff. The quickest start is one variable:
599
+
600
+ ```sh
601
+ SHAPEWALL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... shapewall serve
602
+ shapewall notify test slack
603
+ ```
604
+
605
+ Everything else: [docs/notifications.md](docs/notifications.md).
606
+
607
+ ## Exposing the board
608
+
609
+ `shapewall serve` has no login and listens on 127.0.0.1. It refuses requests whose `Host` header is not local (DNS rebinding) and accepts
610
+ writes only as JSON (no cross-site form posts). For your own other devices, use `shapewall serve --tailscale` (or `--lan`) and pair
611
+ each device. For a team, run [`shapewall hosted`](#multiplayer-on-your-own-server), or use `shapewall export` for a read-only copy. See
612
+ [docs/deployment.md](docs/deployment.md).
613
+
614
+ ## FAQ
615
+
616
+ **Does it work with single-page apps?** Yes. The capture snapshots the rendered DOM after your `waitFor` and `actions`, so client-rendered
617
+ content is in both the screenshot and the live HTML. Scripts are removed, so the live HTML is a frozen state, not a running app.
618
+
619
+ **Why fixed-height frames instead of full-page screenshots?** Comparable cards on one canvas, predictable memory, and the top of a page is
620
+ what reviewers look at first. Make `height` larger for long pages.
621
+
622
+ **My site needs a login.** Run `shapewall auth record`, sign in by hand in the fresh browser it opens, then press Enter to save. It
623
+ prints the `auth.storageState` line to add to your config. A `loginScript` is the alternative for automation. Use a test account, and never commit credentials. See [guided sign-in](docs/config.md#auth).
624
+
625
+ **Are captured pages safe to share?** Live HTML drops hidden inputs, password values, scripts and data attributes that could carry tokens,
626
+ and links to private hosts are removed. Screenshots show exactly what the page showed, so capture with test data.
627
+
628
+ **Can I use Firefox or WebKit?** No. Captures use Chromium, and thumbnails use a Chromium DevTools call.
629
+
630
+ **Does it send anything anywhere?** Not by itself: there is no account and no telemetry. Captures load your pages; an agent endpoint,
631
+ notifications, GitHub connect or a team server you set up receive what you send them.
632
+
633
+ **Where is my data?** In `outputDir` (default `.shapewall/`): PNGs, HTML snapshots, `manifest.json`, `comments.json`, `variants.json`,
634
+ `journeys.json`, previous captures in `versions/`, other environments in `envs/`, cached diffs in `diffs/` and `agent/` (what
635
+ `shapewall watch` handed to your command, with its log). Delete the folder to start over.
636
+
637
+ ## Contributing
638
+
639
+ Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Security
640
+ reports: [SECURITY.md](SECURITY.md).
641
+
642
+ ## License
643
+
644
+ Shapewall has two licenses:
645
+
646
+ - **Apache 2.0** ([LICENSE](LICENSE)) for everything except `src/hosted`: the CLI, capture, the board, MCP, the agents and the clients
647
+ of the team server (`push`, `share`, `--remote`, in `src/remote`). Open source.
648
+ - **Functional Source License 1.1, Apache 2.0 future license** ([src/hosted/LICENSE.md](src/hosted/LICENSE.md)) for the self-hosted
649
+ team server in `src/hosted`. Source-available: you can read, modify and run it for yourself or your company, but not offer it as a
650
+ competing commercial service. Each release becomes Apache 2.0 two years later.
651
+
652
+ Copyright Dan Baruch and Shapewall contributors. See [NOTICE](NOTICE) and [THIRD_PARTY.md](THIRD_PARTY.md).