shapewall 0.0.0-stage → 0.2.1

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