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
@@ -0,0 +1,242 @@
1
+ # Architecture
2
+
3
+ Shapewall is three parts that share one folder of plain files.
4
+
5
+ ```
6
+ shapewall.config.json ──► capture (Playwright) ──► .shapewall/<board>/captures/*.png|*.thumb.png|*.html + manifest.json
7
+ │
8
+ shapewall serve (Express) ◄──────────┘ + comments.json, variants.json, journeys.json, versions/,
9
+ │ envs/<env>/captures/, diffs/, status.json, capture.lock
10
+ │
11
+ React Flow client (dist/client)
12
+ ```
13
+
14
+ | Path | Role |
15
+ | --------------------------- | ----------------------------------------------------------------------------------------------- |
16
+ | `src/config.js` | Loads and validates the config, collecting every problem with its JSON path. |
17
+ | `src/capture/capture.js` | Runs captures: browser contexts per viewport, waits, actions, screenshots, live HTML. |
18
+ | `src/capture/actions.js` | Runs page and setup actions (captures and page checks); step-named failures. |
19
+ | `src/capture/requests.js` | The private-host guard, the `block` list and `localStorage` seeds of a capture context. |
20
+ | `src/capture/live.js` | The in-page DOM snapshot and the Node-side build of one self-contained HTML document. |
21
+ | `src/capture/sanitize.js` | The allowlist HTML and CSS sanitizer every snapshot goes through. |
22
+ | `src/lock.js` | The capture lock (pid + process start time) and a short file lock for JSON writes. |
23
+ | `src/store.js` | File layout, atomic JSON writes, comments, variants, capture versions, capture state. |
24
+ | `src/links.js` | Matches the links read from a captured page to configured pages. |
25
+ | `src/journeys.js` | Journeys from the config and the board (journeys.json). |
26
+ | `src/journey-paths.js` | Branching journeys: fork validation, the step graph, paths. Shared with the client. |
27
+ | `src/diff.js` | Pixel diffs between environments (pixelmatch), cached per pair. |
28
+ | `src/server/app.js` | The Express app: API, capture and live files with their headers, the built client. |
29
+ | `src/feedback.js` | Comments as a work list (`shapewall comments`), for people and agents. |
30
+ | `src/watch.js` | `shapewall watch`: claims new comments and hands them to an agent command. |
31
+ | `src/mcp.js` | `shapewall mcp`: the stdio MCP server (comments, replies, status, recapture). |
32
+ | `src/png.js` | A minimal PNG decoder/encoder, to crop a capture around a pin for the MCP server. |
33
+ | `src/agent/` | The board chat: config, `/api/agent/*` routes, threads, prompt and quoted data, backends. |
34
+ | `client/src/chat/` | The chat panel: threads, streaming Markdown, attachments and crops, voice in, read aloud. |
35
+ | `src/hosted/` | The hosted server (FSL): accounts, workspaces, tenancy, tokens, push, share links, audit. |
36
+ | `client/src/console/` | Console (second Vite entry, `dist/console`): hosted accounts, or local Projects and Settings. |
37
+ | `src/doctor.js` | `shapewall doctor`: environment checks and the matching browser download. |
38
+ | `src/export.js` | Static, read-only export. |
39
+ | `client/src/board/` | Canvas, layout, nodes, arrows, journeys, compare, before/after, the comments panel. |
40
+ | `client/src/components/ui/` | The UI kit (Radix + Tailwind): buttons, selects, menus, dialogs, ... (`docs/design-system.md`). |
41
+ | `client/sw.js` | The board's service worker (app shell only), built into `dist/client/sw.js`. |
42
+
43
+ ## Capture
44
+
45
+ For each page and viewport Shapewall opens a fresh browser context with the viewport size (device scale 1; mobile emulation, touch and a
46
+ mobile user agent for `tablet` and `phone`, and for any viewport name that starts with one, such as `phone-landscape`), loads the page,
47
+ waits for `load`, then for network idle (bounded by `timeouts.settle`), then for `waitFor`, then runs `actions`, then waits until every
48
+ image intersecting the frame has decoded (lazy images in view are switched to eager). After a short pause for late renders it takes two
49
+ screenshots of the same fixed frame through the DevTools protocol: full size and a scaled thumbnail (a quarter of the desktop width, half
50
+ of the phone width). The frame starts at the page's current scroll position (the clip is in document coordinates), so an action or a
51
+ hash link that scrolls the page is shot where it scrolled to. A viewport with `layoutHeight` lays the page out in a window of that height
52
+ and shoots the frame's `height` past it.
53
+
54
+ Board settings shape the context too: a board's `viewports` replace the top-level list for it; `block` patterns are aborted by one
55
+ context route (with the private-host guard), and the requests it blocked are left out of the network warnings; `localStorage` seeds go
56
+ in through an init script that only writes on the page's own origin; `reducedMotion` defaults to `reduce`; the color scheme is always
57
+ light. Live HTML is frozen to those preferences (`src/capture/media-scheme.js` rewrites `prefers-color-scheme` and the forced
58
+ `prefers-reduced-motion` queries to always or never match, and pins the root `color-scheme`), so a viewer whose browser prefers dark
59
+ still sees what the screenshot shows. A board `setup` runs once
60
+ per viewport, on first use, in its own context (`runSetup`), and its `storageState()` (cookies, localStorage, IndexedDB) is the state
61
+ every page in its scope starts from, so a guest entry happens once per capture instead of once per shot. Actions run in
62
+ `src/capture/actions.js`, shared with page checks: a failure names the step (`action 3 (click "...") timed out after 45 s`) from the
63
+ config only, never from page text or Playwright's call log.
64
+
65
+ Why fixed frames: comparable cards on one canvas, predictable memory, and headless Chrome's minimum window width does not affect device
66
+ emulation through Playwright, so a 390 px phone capture is a real 390 px layout.
67
+
68
+ Runs are serialized per board by `capture.lock`, created with an exclusive open. A lock counts as held only while its process exists and,
69
+ on Linux, started at the recorded time, so a recycled pid reads as stale and a crashed run never blocks the next one. A full run writes to
70
+ `captures.next/` and swaps it in at the end; `--only` writes straight into `captures/` and merges its manifest entries.
71
+
72
+ Links: after the screenshot, the page's `<a href>` and `<area href>` values (as resolved by the browser, at most 2000) are matched to the
73
+ board's pages in Node (`links.js`) and only the matching page ids are written to the manifest entry (`links`). Unmatched or malformed
74
+ hrefs are dropped there; nothing from them is stored.
75
+
76
+ Versions: each successful shot gets a version id (its time plus a random suffix) in the manifest. On the default environment, the shot it
77
+ replaces is copied to `versions/` first (a full run copies from the old `captures/` after the swap; `--only` copies before the shot and
78
+ removes the copy again if the shot fails), then each page and viewport is pruned to the newest `versions` (config).
79
+
80
+ Environments: `--env ID` captures another environment into `envs/<id>/captures/` (same layout, same lock), then warms the pixel diffs
81
+ against the default environment.
82
+
83
+ ## Live HTML
84
+
85
+ In the page, after the screenshot:
86
+
87
+ - The document element is cloned. Form values are frozen into attributes (text, checkboxes, selects); password and hidden values are not.
88
+ - Stylesheets are walked in cascade order, including `@import`ed sheets and adopted sheets. Rules whose selectors match nothing on the page
89
+ are dropped (bundles are mostly other pages); `@media`, `@supports`, `@layer` and `@container` blocks keep their matching rules.
90
+ - Images are redrawn onto a canvas from their decoded pixels at twice their displayed width and exported as WebP, which makes them small
91
+ and guaranteed complete. Canvas and video elements become still images.
92
+ - Scripts, frames, objects, `link`, `base`, `template`, `meta http-equiv` and every `on*` attribute are removed before anything leaves the
93
+ page.
94
+
95
+ In Node:
96
+
97
+ - Cross-origin stylesheets and images the page could not read are taken from the browser's own response bodies, only when the response was
98
+ a complete 200 (format signature and end marker checked, `Content-Length` compared when the body was not compressed).
99
+ - Every `url()` is resolved to a `data:` URI or replaced with `none`. An image budget (3 MB per page) drops the largest images first;
100
+ dropped images become same-size grey placeholders so the layout holds. Identical images are stored once, as a CSS rule.
101
+ - The whole document goes through `sanitize.js` (allowlist, see the README), then gets its CSP `<meta>` tag. The file is capped at 5 MB.
102
+
103
+ On the board, the live document is rendered at the capture's native width inside the frame and scaled down with a CSS transform, so the
104
+ layout matches the screenshot. Capture also renders the sanitized document at that native size and writes an element map
105
+ (`<page>.<viewport>.elements.json`): selectors, short text, boxes and hit order. The board hit-tests and resolves pins against this map,
106
+ so the frame uses `sandbox=""` with an opaque origin. Controls stay inert while text is selected. Only older local captures without a
107
+ map keep the DOM path and `allow-same-origin` until recaptured; hosted boards and static exports always use an opaque frame.
108
+
109
+ ### Limits
110
+
111
+ - The snapshot is a frozen state: menus that only open with JavaScript stay closed, and `:hover` styles apply only while hovering.
112
+ - Content inside cross-origin iframes (embedded maps, videos) is dropped.
113
+ - Web fonts are inlined up to a budget (1.5 MB); above it the page falls back to system fonts in the live view (the screenshot is exact).
114
+ - Shadow DOM content is not cloned.
115
+
116
+ ## Comment anchors
117
+
118
+ When a comment is made on live HTML, the element under the click is turned into an anchor:
119
+
120
+ - The element itself, or the nearest interactive ancestor (link, button, input, label, image, ...).
121
+ - A selector path from the closest stable hook: a unique `#id`, `[data-testid]` or `[aria-label]`, then `:nth-of-type()` steps. The server
122
+ accepts only this grammar, so a stored selector can never be an arbitrary CSS expression.
123
+ - The element's text (first 80 characters) and the click offset inside it.
124
+ - The element's size as a share of the page (`w`, `h`), so the pin sits on the element's corner (top right, outside it; top left near
125
+ the right edge, below it near the top) in screenshot mode too, instead of on top of what it is about.
126
+
127
+ In comment mode the element a click would pin to is outlined while the mouse is over a live page, with the last step of its selector
128
+ and its text; a large element (a fifth of the page or more) is dashed and labelled as a whole section.
129
+
130
+ To place the pin later: the selector is tried first and accepted only if the text still matches; otherwise the first element of the same
131
+ tag with exactly that text wins. If neither is found the pin stays at its stored position with a dashed ring ("this moved"). In screenshot
132
+ mode pins use the stored position.
133
+
134
+ ## Canvas controls
135
+
136
+ Figma-style, in `client/src/board/navigation.js` (React Flow's own wheel, Space and zoom-key handling is off; it keeps left-drag and
137
+ touch):
138
+
139
+ | Input | Does |
140
+ | ------------------------------------------------- | ----------------------------------------------------------------------- |
141
+ | Wheel | Pan up and down |
142
+ | Shift+wheel | Pan sideways |
143
+ | Trackpad two-finger scroll | Pan in any direction |
144
+ | Ctrl+wheel, Cmd+wheel, trackpad pinch | Zoom about the cursor (0.02x to 4x; a mouse notch is about 1.3x) |
145
+ | Space+drag, middle-button drag, drag on the board | Pan (Space and middle drag work over pages and in comment mode as well) |
146
+ | Touch: one finger, two-finger pinch | Pan, zoom |
147
+
148
+ Space pans while the mouse is over the canvas, except in text fields and on a control reached with the keyboard (Space presses it).
149
+ A Space+click never selects a page or starts a comment. Wheel and drag steps move the camera without saving it; the URL camera and the
150
+ settled zoom update once it rests (150 ms after the last wheel event, or on mouse up). Safari's trackpad pinch (gesture events) zooms
151
+ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page being selected) scrolls it instead.
152
+
153
+ ## Board rendering
154
+
155
+ - Pages are grouped (config order), each group laid out in rows; groups wrap so the board is roughly screen-shaped. Variants sit to the
156
+ right of their page, joined by a dashed edge.
157
+ - Images: thumbnails until a frame is drawn wider on screen than the thumbnail has pixels, then the full PNG. Decided from the zoom once
158
+ the camera has rested, never mid-animation.
159
+ - Live HTML: a frame goes live when it is drawn at least 40% of its native width (or half the canvas, whichever is smaller), or when "Open
160
+ live" pinned it. At most two at once, nearest the center first.
161
+ - Arrows are a custom React Flow edge that runs border to border between two cards, curving slightly so a -> b and b -> a stay apart.
162
+ Thickness and arrowheads are divided by the zoom, so they read the same at any zoom. Link arrows are opt-in (**Links**), and only
163
+ the hovered or selected card's arrows are drawn once a board has more than 150 links. Links into pages that at least half the pages
164
+ link to (the nav and the footer, `globalTargets`) are hidden until "Show them" (`la=1`). Arrows are not tab stops, and their labels
165
+ use page titles.
166
+ - Journeys fade the cards that are not in the journey, put numbered badges on the ones that are, and fly the camera to each step. A
167
+ branching journey is shown one path at a time (`resolvePath` with the branches picked); the other branches' arrows are dashed.
168
+ - Compare mode lays two frames per viewport side by side (one per environment) and shows screenshots only, with the cached diff mask
169
+ over the second.
170
+ - Each frame's label (viewport, environment, live) sits in a strip between the card header and the frame, never on the captured page.
171
+ - The selected card's action bar belongs to one view: switching viewport, compare or a journey, and Fit view, clear the selection, and
172
+ the bar hides while the frame is a thumbnail on screen (its longer side under 160 px). Tapping a thumbnail flies to it first, leaving
173
+ room above the card, so the bar sits above it and never over its title or badges. When the card fills the canvas the bar is one
174
+ button in the card's header. On local boards it has "Capture" (that page only, `POST .../capture { pages: [id] }`).
175
+ - "Go to page" fits the page's content, not its whole fixed frame: the lowest row of the thumbnail that differs from the plain
176
+ background below it (`contentExtent.js`).
177
+ - A variant made only for viewports the mode does not show (a tablet-only variant in Desktop mode) is a short card that says so, with a
178
+ button to show its viewport.
179
+ - Phone-width screens (640 px and narrower) open on the phone viewport when the board has one and the URL names none, on the first
180
+ group at a readable zoom (two cards across), top-aligned. Pins never shrink below their 44 px touch target, and a tap in comment mode
181
+ on a page drawn small zooms to it first, so the next tap can pin to an element.
182
+ - The desktop toolbar never truncates: below 1440 px (1600 px with Capture and Agent) Links and Compare drop their labels, below
183
+ 1280 px the lists become icons and the capture time moves into a tooltip. Notes over the canvas (comment mode, the tip, the
184
+ viewport switch, the links note) are pills in one stack at its top, so turning comment mode on never moves the canvas. The minimap
185
+ can be turned off and hides while a page is live. Resolve and delete show a toast with Undo (a delete is sent after a few seconds,
186
+ or when the page is left).
187
+ - Keyboard: each card is one tab stop; the arrow keys move through its pins and buttons, Esc returns to the card, Enter opens its
188
+ action bar. "Skip to comments" is the first tab stop. After a pick from a toolbar list, focus returns to the canvas, and a closed
189
+ list ignores typed letters (Radix type-ahead), so shortcuts like C keep working. Esc closes a journey.
190
+ - URL state: board, viewport mode, comment filter, selected comment, camera, journey, branches and step, links, and compare pair live in the
191
+ query string.
192
+ - Overlays (dialogs, the comment sheet, the selected card, comment mode) each own a history entry, so Back closes the topmost one.
193
+
194
+ ## Comments on the board
195
+
196
+ Comments work like Figma's. Pins are avatar bubbles (the author's initials and colour, a pointed corner on the spot, a count badge
197
+ for replies, a dot for news) drawn at screen size; pins closer than about 30 screen pixels on a frame merge into one bubble with a
198
+ count, and clicking it zooms in until they part (`clusterPins` in `client/src/board/pins.jsx`). Hovering a pin previews the thread in
199
+ a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
200
+
201
+ C (or the Comment button) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
202
+ it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
203
+ its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
204
+ history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
205
+ that reads the pin's position every frame, bounded by the canvas, so they follow pan and zoom, flip to stay on screen and hide when
206
+ the pin leaves the canvas. On phones the thread and the composer are bottom sheets (`Dialog`) and Back closes them.
207
+
208
+ The list beside the canvas mirrors the pins: picking a row flies to the pin and opens its thread, hovering a row lights up its pin
209
+ and the other way round, and threads with activity since you last opened them carry a dot. "Seen" is per browser
210
+ (`localStorage`, `client/src/lib/unread.js`), not stored on the server.
211
+
212
+ ## Storage
213
+
214
+ All JSON is written to a temporary file, fsynced and renamed over the old one. Comment and variant changes run under
215
+ `<file>.lock` (exclusive create, with stale-lock takeover), so concurrent writers never lose an update and never see a partial file.
216
+ Comment ids are never reused. Journeys made on the board (`journeys.json`) and the diff cache index use the same writes and locks.
217
+
218
+ Replies live inside their comment (`replies: [{ id, author, body, createdAt, reactions? }]`), next to `agentStatus` and `agentStatusAt`.
219
+ A comment or reply may carry `reactions: [{ emoji, by: [{ name, handle?, user? }] }]` (six emoji in `src/reactions.js`; the API
220
+ returns `{ emoji, count, by }`), and `editedAt` once its text is edited. Both are optional, so older files read unchanged; reacting
221
+ does not touch `updatedAt`, and the agent views (`shapewall comments`, MCP, the token API) leave reactions out. The hosted store
222
+ keeps them in the `reactions` and `edited_at` columns (migration 3). The agent
223
+ status is the hand-off between `shapewall watch`, MCP clients and people: a watcher claims a comment by changing `agentStatus` from null to
224
+ `queued` inside the same file lock, so the claim is atomic and survives restarts. `<board>/watch.lock` (the capture lock's pid + start
225
+ time scheme) keeps one watcher per board; `<board>/agent/` holds the JSON and log of each command it ran.
226
+
227
+ ## The board as an app
228
+
229
+ The client ships a web app manifest and a service worker, so the board installs on a phone or desktop and opens in its own window. The
230
+ worker is generated at build time with the list of files of that build (the page, its hashed assets, icons, manifest) and caches only
231
+ those: network first for the page, cache first for the hashed files, and a new cache per build. It never handles `api/` (board data,
232
+ images, live HTML) or a static export's `data/`, so captures and comments are always fresh. It registers only in production builds on
233
+ secure origins (https or localhost); the board works the same without it.
234
+
235
+ ## Local Console
236
+
237
+ `shapewall serve` serves `/console` and its `/_console/` assets behind the same Host and remote-access gates as the board.
238
+ The shell carries a fixed `shapewall-local-console` marker and a fresh style nonce under a strict CSP. The console entry selects
239
+ `LocalConsole`, which reads the existing `/api/info` and `/api/boards` APIs; it never starts a hosted sign-in or creates a hosted session.
240
+ Board links preserve the selected board id. General preferences reuse the board settings content, and the existing Agent and update
241
+ capabilities still decide whether protected controls can mount or mutate anything. Local API requests are absolute so trailing slashes
242
+ and direct Console links work.
package/docs/buzz.md ADDED
@@ -0,0 +1,140 @@
1
+ # Buzz bridge
2
+
3
+ Buzz is a self-hosted team chat built on a Nostr relay, where coding agents such as Claude Code, Codex and goose sit in channels as
4
+ members. If you already run Buzz, this optional bridge lets the owner of a local Shapewall board send feedback to those same running
5
+ agents from the board. If you do not run Buzz, skip this page: [chat with an agent](agents.md) and
6
+ [the agent workflow](agent-workflow.md) need nothing else.
7
+
8
+ The bridge is off unless you configure it. It is Linux-only, for local boards, and addresses three fixed targets: `codex`, `claude`
9
+ and `goose`.
10
+
11
+ ## What it does and does not do
12
+
13
+ - It posts a signed message to one fixed Buzz channel, mentioning one target agent. The agents keep their own workspace, tools,
14
+ models and permissions; the bridge starts no new agent and changes no provider setting.
15
+ - It is a shared conversation, separate from Shapewall's own [chat panel](agents.md). A message can steer work that is already in
16
+ progress in that channel.
17
+ - Channel replies are flat, so the bridge cannot tie a reply to a comment, tell when a task is finished, stream tool calls, approve
18
+ commands or stop the agent. After the agent changes the source, recapture and review the board yourself.
19
+ - A **Sent** receipt means the relay has the exact signed request. Whether the agent accepted and ran it shows in the channel.
20
+ - The source folder you select is sent as context only. The board's project sandbox does not apply to Buzz agents.
21
+
22
+ ## Before you start
23
+
24
+ Check these on the Buzz host. The bridge never changes any of them for you.
25
+
26
+ 1. The relay URL, channel id, owner public key and the three agent public keys in your bridge configuration match your Buzz
27
+ installation. The owner, the transport signer and the target agent are all members of the channel. If a target has
28
+ `channel_add_policy=owner_only`, that agent's own owner has to add it; a channel owner's signature is not enough.
29
+ 2. Each transport signer's latest kind-0 profile carries a valid owner-signed NIP-OA `auth` attestation. The receiving agent service
30
+ checks the profile, so an `auth` tag on the message alone does not pass.
31
+ 3. If a profile needs repair, publish it with your normal Buzz tooling, keeping its content and unrelated tags. Buzz caches a
32
+ rejected signer for the life of the receiving process, so restart that agent service after the repair (it interrupts its sessions).
33
+
34
+ Then send one small request and watch the channel for the agent's answer.
35
+
36
+ ## Configuration
37
+
38
+ The bridge configuration is a JSON file. The values below are placeholders; use the public keys and channel from your own
39
+ installation.
40
+
41
+ ```json
42
+ {
43
+ "version": 1,
44
+ "relayUrl": "wss://relay.example",
45
+ "ownerPubkey": "<owner public key: 64 lowercase hex characters>",
46
+ "channel": { "id": "<channel UUID>", "name": "your-channel" },
47
+ "agents": [
48
+ { "id": "codex", "name": "Codex", "pubkey": "<public key>" },
49
+ { "id": "claude", "name": "Claude Code", "pubkey": "<public key>" },
50
+ { "id": "goose", "name": "goose", "pubkey": "<public key>" }
51
+ ],
52
+ "signerFiles": {
53
+ "codex": "/absolute/path/to/codex.env",
54
+ "claude": "/absolute/path/to/claude.env"
55
+ },
56
+ "projects": [{ "root": "/absolute/path/to/source-folder", "name": "Your project", "boards": ["your-board-id"] }],
57
+ "socketPath": "/absolute/private-folder/buzz.sock",
58
+ "stateDir": "/absolute/private-folder/receipts"
59
+ }
60
+ ```
61
+
62
+ Keep this file, the socket and the receipt journal outside every source project, capture output, export and web root. The file must
63
+ be owned by you with mode `0600`, and its folder and the socket and journal folders `0700`. Symlinked paths are refused.
64
+
65
+ ### Signer files
66
+
67
+ A request to one agent is signed by a sibling agent's existing Buzz identity:
68
+
69
+ | Target | Signed by | Signer file |
70
+ | ----------- | ----------- | -------------------- |
71
+ | Codex | Claude Code | `signerFiles.claude` |
72
+ | Claude Code | Codex | `signerFiles.codex` |
73
+ | goose | Codex | `signerFiles.codex` |
74
+
75
+ `signerFiles` names the two EnvironmentFiles your Buzz agent services already use (absolute paths). Each holds `BUZZ_PRIVATE_KEY`,
76
+ `BUZZ_AUTH_TAG` and `BUZZ_RELAY_URL`. You can set `SHAPEWALL_BUZZ_SIGNER_CODEX` and `SHAPEWALL_BUZZ_SIGNER_CLAUDE` instead; the file
77
+ wins when both are set. There is no default: without both paths the bridge stays off and says which one is missing.
78
+
79
+ Do not copy keys into the bridge configuration or the Shapewall config. An isolated signer process reads those three variables from
80
+ the file without running a shell, and before every publish it checks the signer's identity, its owner attestation, the relay and
81
+ channel membership. No private key reaches Shapewall, the browser, a receipt or a command line. Shapewall and the gateway also drop
82
+ any inherited Buzz credential variables at startup.
83
+
84
+ The gateway runs the Buzz CLI at `~/.local/bin/buzz`.
85
+
86
+ ## Run it
87
+
88
+ Keep the gateway in its own terminal:
89
+
90
+ ```sh
91
+ shapewall buzz-bridge --bridge-config /absolute/private-folder/bridge.json
92
+ ```
93
+
94
+ Then start the board with the same file:
95
+
96
+ ```sh
97
+ shapewall serve --config /absolute/path/to/source-folder/shapewall.config.json \
98
+ --buzz-bridge /absolute/private-folder/bridge.json --open
99
+ ```
100
+
101
+ Neither process installs a background service. Ctrl-C stops the one you started and leaves your Buzz services alone. Only one
102
+ gateway can own a receipt journal and socket.
103
+
104
+ ## Using the panel
105
+
106
+ Open **Existing Buzz conversation** in the board's profile menu. The panel shows the channel, the target, the signer and the source
107
+ context before you send. Choose the target and press **Send to Buzz**; only that agent is mentioned. Expand **Exact transmitted
108
+ envelope** to read the payload: it says the text came from the Shapewall owner, and it never claims the signer wrote it.
109
+
110
+ Who can use it: the verified Tailscale owner, or a local browser holding the server's private owner token. A paired device or an
111
+ account session alone cannot, and account-enabled boards still need the passkey session first. Read-only, shared and hosted boards
112
+ have no bridge, and static exports contain none of its data.
113
+
114
+ **Refresh shared conversation** fetches a bounded recent view of the channel. Every event shown has passed its Nostr hash and
115
+ signature check, belongs to the configured channel and was written by the owner or one of the three agents. It is displayed as plain
116
+ text and never triggers a message, a notification or a comment change. It is not the full channel history.
117
+
118
+ Each request has a durable receipt. Sending the same request again returns its receipt without publishing twice. An interrupted
119
+ publish shows **Delivery unknown** and is never resent by itself; refresh settles it only by finding the exact outgoing message.
120
+ Receipts survive gateway restarts and stay on the host. The journal holds 500 requests: archive it by hand, with the gateway stopped,
121
+ before sending more.
122
+
123
+ ## Sent, but the agent is silent
124
+
125
+ Use the request's event id and channel to trace it on the Buzz host.
126
+
127
+ - **`inbound_author_gate` rejection**: the agent service discarded the request before queuing it. Check the signer's profile
128
+ attestation (step 2 above) and restart the receiving service if it cached the rejection. Resending does not help.
129
+ - **Missing member, or a denied channel add**: a setup problem. Have the target agent's owner add it; do not make the channel public
130
+ or relax its policy.
131
+ - **Admitted, no reply yet**: the agent may be busy. Look at its queue and session before assuming a failure.
132
+ - **Delivery unknown**: check the relay and the channel before you create a new request.
133
+
134
+ A discarded request is not picked up later. Once the cause is fixed, and after checking that the original did not run, send a new
135
+ request.
136
+
137
+ ## Limits
138
+
139
+ The automated tests use fixtures: signatures, attestation, mention isolation, private paths, owner checks, exports, receipts and
140
+ deduplication. Your relay, channel membership and agent logins are yours to check with one real request.
@@ -0,0 +1,57 @@
1
+ # Capture network warnings and pacing
2
+
3
+ A saved screenshot can still show an application whose API was rate limited.
4
+ Ordinary captures now retain a small `networkSummary` alongside the screenshot
5
+ status. A usable screenshot stays `status: "ok"`; a failed navigation keeps the
6
+ existing failure behavior. These observations are part of that capture, not a
7
+ separate Page checks or Lighthouse run.
8
+
9
+ The summary contains only integer counts: observed responses, unexpected 4xx
10
+ and 5xx responses, API errors, HTTP 429 responses, API 429 responses and failed
11
+ requests. API means the browser classified the request as fetch or XHR. It
12
+ contains no resource URL, query value, body, headers, cookie, console message
13
+ or browser failure text. Collection stops after the screenshot and thumbnail,
14
+ before live HTML resource processing or context shutdown. It is bounded to
15
+ 10000 observed response or failed-request events; `capped` means the counts
16
+ are lower bounds. Requests occurring later are not assessed.
17
+
18
+ `expectStatus` continues to apply only to the main document. For example, an
19
+ intentional 404 document succeeds and does not add a network warning by
20
+ itself. An API 429 on that same page still adds a warning. An unexpected main
21
+ document 429 still fails capture. A warning is a pointer, not a verdict: it
22
+ does not mean the whole application is broken, or that every request was seen.
23
+
24
+ The wall's **Network** badge opens a custom, keyboard-accessible popover with
25
+ per-device counts. Close, Escape, outside click or Android Back dismiss it.
26
+ CLI progress reports the safe aggregate warning, and `capture --json` includes
27
+ it in each shot. The same bounded metadata survives local API reads, ordinary
28
+ static exports and hosted pushes. Invalid summaries are dropped; unknown
29
+ fields are discarded at these boundaries.
30
+
31
+ ## Polite foreground pacing
32
+
33
+ Capture navigation starts are spaced across the configured concurrent workers.
34
+ The default is 250 milliseconds between starts. When a shot observes an
35
+ unexpected 429, future shots receive a one-second cooldown; in-flight shots
36
+ continue. The setting applies to the foreground board capture run. It does
37
+ not retry navigation, repeat configured actions, schedule later work or
38
+ create a background job.
39
+
40
+ ```json
41
+ {
42
+ "concurrency": 2,
43
+ "capturePacing": {
44
+ "intervalMs": 250,
45
+ "rateLimitCooldownMs": 1000
46
+ }
47
+ }
48
+ ```
49
+
50
+ `intervalMs` accepts whole milliseconds from 0 to 5000 and
51
+ `rateLimitCooldownMs` from 0 to 30000. Zero explicitly disables that part of
52
+ pacing. Unknown settings and out-of-range values fail configuration validation.
53
+ Changes reload for subsequent captures in a running local server. A cooldown
54
+ cannot extend one admission indefinitely: after reaching the front of the
55
+ queue it waits at most the configured interval plus cooldown. Server
56
+ `Retry-After` values do not trigger arbitrary waits. This pacing reduces bursts;
57
+ it cannot guarantee that the application will never return 429.