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
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -0,0 +1,40 @@
1
+ # Explicit interaction flows and accessibility
2
+
3
+ ```sh
4
+ shapewall checks flow --flow-file checks/checkout.json --json
5
+ shapewall checks accessibility --only checkout --viewport phone --json
6
+ ```
7
+
8
+ The packaged [example definition](../examples/audits/interaction.audit.json) uses fictional checkout selectors; adapt its page and selectors to a configured safe fixture. Flow definitions are separate local JSON files. They do not execute visual board journeys, and ordinary capture, hosted uploads and opening Checks never run them. One explicit invocation selects one configured page and viewport, runs each step once and saves a timespan report. It does not replay `page.actions`, navigate twice for a warmup, repeat samples or retry the whole flow. A flow can mutate the original application; use deliberate test fixtures and accounts.
9
+
10
+ ```json
11
+ {
12
+ "schemaVersion": 1,
13
+ "pageId": "checkout",
14
+ "viewport": "desktop",
15
+ "accessibility": true,
16
+ "steps": [
17
+ {
18
+ "action": { "click": "button.cart" },
19
+ "ready": "section.cart",
20
+ "maxDurationMs": 1500
21
+ },
22
+ {
23
+ "action": { "fill": ["input.quantity", "2"] },
24
+ "ready": "button.update"
25
+ }
26
+ ]
27
+ }
28
+ ```
29
+
30
+ Supported actions are `click`, `fill`, `press`, `hover`, `waitFor`, `wait` and `scrollTo`. Files are limited to 32 KiB and 20 steps; selectors to 500 characters, fill values to 2,000 characters, key combinations to 80 characters and explicit waits to five seconds. Optional `maxDurationMs` is a one-to-20,000 millisecond budget for that successful step. Values and selectors are never written into reports. Store sensitive flow files privately, just like authentication fixtures.
31
+
32
+ Timings include browser automation and the configured visible ready selector. They measure elapsed lab steps, not field INP, user-perceived responsiveness or a Lighthouse performance score. Reports retain `step1DurationMs` through the configured step count, `flowDurationMs`, `completedSteps` and `configuredSteps`. A failed step keeps its timing and the total unknown; completed steps retain their observations. Budget findings are local evidence requiring interpretation. Changing the normalized flow changes its profile hash, preventing silent comparison of different sequences.
33
+
34
+ The engine runs in a private Chromium execution world, so application globals cannot replace the audit engine or fake its results. The optional final accessibility snapshot runs [axe-core](https://github.com/dequelabs/axe-core) 4.14.0, pinned locally. It checks WCAG 2.0 A/AA, 2.1 A/AA and 2.2 AA tags on the final document, with frames and external asset preloading disabled. This is a separate `axe` snapshot report, not an interaction score. Standalone `checks accessibility` selects exactly one page and one viewport, uses its configured ready state and runs its configured page actions once before the snapshot. The default viewport is desktop when configured, otherwise the first configured viewport.
35
+
36
+ The engine preflight stops above 10,000 document elements, including reachable open shadow trees. Closed shadow roots and frames remain untested. A run records bounded rule identifiers, numeric counts and fixed guidance; raw DOM, selectors, text, resource addresses, traces, credentials and engine HTML are never saved. Up to 60 violation rules become findings; incomplete rules and truncation explicitly remain partial. A clean automated report is not accessibility certification. Verify keyboard operation, focus order and assistive technology separately. Engine behavior follows the [axe API](https://github.com/dequelabs/axe-core/blob/v4.14.0/doc/API.md).
37
+
38
+ Both commands use the selected board/environment and the existing storage-state or trusted login-script mechanism once. Configured authentication requires a visible `waitFor` marker for the intended signed-in state. Initial redirects to another route fail before steps; flows may move within the original origin. Main-document redirects are intercepted before each outgoing hop. Off-origin document navigations and all popups fail the audit before later actions can run. This restricts automated top-level navigation, not the application’s ordinary resource requests. A source build can be supplied with `--source-build`. Authentication content is hashed for comparison and never stored in reports.
39
+
40
+ Each step and accessibility inspection has a 20-second maximum; navigation uses the lower of that maximum and the configured page timeout. The entire invocation has a deadline of at most two minutes, including browser authentication operations. Trusted login scripts remain local code; browser deadlines cannot preempt arbitrary host-language work in those scripts. Prefer a saved storage state for tightly bounded CI runs. Interrupting the command closes its contexts and preserves a failed report where possible. The library also accepts an abort signal. Failed or cancelled flows do not replay earlier mutations. These manual commands create no schedules and do not dispatch agent work.
@@ -0,0 +1,137 @@
1
+ # Journeys and links
2
+
3
+ A board shows every page; a journey shows the path people take through them. "Sign up" is the home page, then pricing, then the sign-in
4
+ form, then the dashboard. Reviewing a journey step by step catches what reviewing pages one at a time misses: a button that promises
5
+ something the next page does not deliver, a step that looks different on a phone, a dead end.
6
+
7
+ ![The Sign up journey on the demo board](images/journeys.png)
8
+
9
+ ## Links between pages
10
+
11
+ Every capture records which other configured pages each page links to. Turn on **Links** on the board to see them as arrows:
12
+
13
+ - With no card active, every link arrow is drawn, thin and quiet. On a big board (over 150 links) nothing is drawn until you hover or
14
+ select a card, so the board stays readable.
15
+ - Hover a card (or tap it on a phone) to see only its own links: arrows going out in the accent color, arrows coming in in grey.
16
+
17
+ Only links to pages in your config count. A link matches a page when it points at the same origin, under the base URL's path, with the
18
+ same path (a trailing slash, `index.html` and repeated slashes do not matter) and the same query. A page without a query in the config
19
+ also matches links that add one (`/pricing?utm_source=nav`). Links are stored as page ids in the capture's `manifest.json`
20
+ (`pages.<id>.<viewport>.links`); the hrefs themselves are never stored or shown, since they come from the page under review.
21
+
22
+ ## Journeys in the config
23
+
24
+ ```json
25
+ {
26
+ "pages": [
27
+ { "id": "home", "path": "/" },
28
+ { "id": "pricing", "path": "/pricing" },
29
+ { "id": "login", "path": "/login" },
30
+ { "id": "dashboard", "path": "/app" }
31
+ ],
32
+ "journeys": [
33
+ {
34
+ "id": "sign-up",
35
+ "name": "Sign up",
36
+ "description": "From the landing page to the first notes",
37
+ "steps": ["home", "pricing", "login", "dashboard"]
38
+ }
39
+ ]
40
+ }
41
+ ```
42
+
43
+ | Key | Type | Notes |
44
+ | ------------- | ------ | -------------------------------------------------------------- |
45
+ | `id` | string | Lowercase letters, digits and dashes. Unique on the board. |
46
+ | `name` | string | Up to 120 characters. Shown in the picker and the journey bar. |
47
+ | `steps` | array | 2 to 50 page ids, in order, or forks (below). Repeats allowed. |
48
+ | `description` | string | Optional, up to 500 characters. |
49
+
50
+ In a multi-board config, put `journeys` inside each board. Journeys from the config are read-only on the board; change them in the file.
51
+
52
+ ## Branches
53
+
54
+ Real flows fork: the email link works or has expired, the card is accepted or declined, the visitor is signed in or not. Instead of a
55
+ page id, any step after a page can be a fork:
56
+
57
+ ```json
58
+ {
59
+ "id": "sign-up",
60
+ "name": "Sign up",
61
+ "steps": [
62
+ "home",
63
+ "signup",
64
+ {
65
+ "branches": [
66
+ { "id": "link-works", "label": "Link works", "steps": ["verify"] },
67
+ { "id": "link-expired", "label": "Link expired", "steps": ["verify-expired", "verify"] },
68
+ { "label": "Never clicks it", "steps": ["reminder-email"], "end": true }
69
+ ]
70
+ },
71
+ "welcome",
72
+ "dashboard"
73
+ ]
74
+ }
75
+ ```
76
+
77
+ | Key | Type | Notes |
78
+ | ------- | ------- | ------------------------------------------------------------------------------------------------------- |
79
+ | `label` | string | 1 to 60 characters. Shown on the arrow into the branch and on the button that picks it. |
80
+ | `id` | string | Optional; lowercase letters, digits and dashes, unique within the fork. Defaults to the label, slugged. |
81
+ | `steps` | array | The branch's pages (and forks). Empty means "skip straight to the step after the fork". |
82
+ | `end` | boolean | Optional. `true`: the journey stops at the end of this branch instead of rejoining. |
83
+
84
+ - Every branch rejoins at the step after the fork, unless it has `end: true`. In the example, both links lead on to `welcome`.
85
+ - A fork has 2 to 6 branches and follows a page (it cannot be the first step, or come right after another fork). Branches may fork
86
+ again, up to 3 deep. If every branch ends, nothing may follow the fork.
87
+ - The 50-step limit counts the pages on every branch, and a journey allows at most 64 different paths through its forks.
88
+ - A list of plain page ids is a linear journey, exactly as before. Existing configs and `journeys.json` files need no migration; a
89
+ journey branches as soon as one of its steps is a fork. Mistakes are reported with their JSON path, e.g.
90
+ `journeys[0].steps[2].branches[1].label: 1 to 60 characters`.
91
+
92
+ ## Journeys made on the board
93
+
94
+ Pick **New journey** in the journey picker (on a phone: the **...** menu), then click pages in the order people visit them. Name the
95
+ journey and save. Journeys made this way are stored in `.shapewall/<board>/journeys.json`, with the same atomic writes and file lock as
96
+ comments, and can be edited or deleted from the journey bar. If a page leaves the config, its steps drop out of the journey (a fork left
97
+ with one branch becomes that branch's steps).
98
+
99
+ The builder clicks out linear journeys. To make a board journey branch, send forked `steps` through the API; such a journey can be
100
+ deleted from the journey bar but not reopened in the builder, so a click cannot flatten its branches.
101
+
102
+ API (JSON only, refused in read-only mode):
103
+
104
+ ```text
105
+ GET /api/boards/:board/journeys { journeys: [{ id, name, description, steps, source, branching, pages, paths }] }
106
+ POST /api/boards/:board/journeys { name, steps, description? } -> 201 { journey }
107
+ PATCH /api/boards/:board/journeys/:id { name?, steps?, description? } -> { journey }
108
+ DELETE /api/boards/:board/journeys/:id -> { ok: true }
109
+ ```
110
+
111
+ `source` is `config` or `board`; changing a config journey answers 409 `config_journey`. `steps` comes back as written, forks included.
112
+ Read from it: `branching` (whether any step forks), `pages` (every page on any branch, once each) and `paths`, every way through the
113
+ forks as `{ choices: [branch id per fork], labels, steps: [page ids], ended }`. A linear journey has one path.
114
+
115
+ The same structure is in `shapewall journeys --json`, the MCP tool `list_journeys`, and a static export (`data/boards/<board>.json` and
116
+ `data/boards/<board>/journeys.json`). `shapewall journeys` prints it as text, one step per line with each fork's branches indented.
117
+
118
+ ## Stepping through
119
+
120
+ Selecting a journey highlights its pages with numbered badges, draws arrows between consecutive steps and fades everything else. The
121
+ journey bar steps through it:
122
+
123
+ - **Previous / Next** buttons (full-width on a phone), or the left and right arrow keys.
124
+ - Each step flies the camera to that page.
125
+ - Back (the browser's, or Android's) closes the journey, like every other overlay on the board.
126
+ - **Only <journey>** in the comments panel narrows the comments to the journey's pages, on every branch.
127
+
128
+ In a branching journey you step through one path at a time, the first branch of each fork unless you pick another:
129
+
130
+ - Arrows on the current path are numbered, and the arrow into a branch carries its label ("3 Link expired"). The branches not taken
131
+ are drawn dashed with their label, and their pages stay half visible with a dashed outline instead of fading out.
132
+ - At a step where the journey forks, the bar asks **Which way?** with a button per branch (a branch that ends the journey says so).
133
+ Next follows the branch picked; picking another one at an earlier fork resets the later ones to their first branch.
134
+ - The step line shows the branch you are on ("Step 4 of 8 (Link expired): Verify: link expired"), and the total follows the path.
135
+
136
+ The journey, the branches picked and the step live in the URL (`?j=sign-up&jb=link-expired&step=4`), so a link opens the same step on
137
+ the same path. `jb` lists the branch id taken at each fork reached, in order.
@@ -0,0 +1,80 @@
1
+ # Local accounts and profile images
2
+
3
+ Local accounts are opt-in. Ordinary `shapewall serve` keeps its existing access model and does not create an account database.
4
+ Use Node 22.13 or newer and start with `shapewall serve --accounts`. On a loopback listener its fixed origin uses `localhost` and
5
+ the serving port. Passkeys require a hostname; IP origins are rejected. Existing IP bookmarks redirect to the configured account
6
+ hostname. Behind a proxy, pass `--accounts-origin https://wall.example.test` or set `SHAPEWALL_ACCOUNTS_ORIGIN`.
7
+ `SHAPEWALL_ACCOUNTS=1` also enables the feature. A non-loopback account origin must use HTTPS. Changing the origin later requires
8
+ a deliberate passkey migration; credentials belong to their relying-party hostname.
9
+
10
+ The database lives at `<outputDir>/.accounts/accounts.sqlite`, in a service-owned directory with mode 0700; the database is mode 0600. Include its SQLite WAL state in a consistent backup. This database stores accounts, passkey public keys, hashed sessions,
11
+ hashed recovery codes, account activity and canonical profile images. Existing capture, comment and journey files are not
12
+ imported, renamed or rewritten. CLI and MCP commands continue to use their existing plain-file interface.
13
+
14
+ ## First owner
15
+
16
+ Before the first account is created, existing Host, network and device-pairing gates remain in force. Registration additionally
17
+ requires the private owner capability from a direct local `serve --open`, the verified Tailscale owner identity described below,
18
+ or a separate operator-configured `SHAPEWALL_ACCOUNT_SETUP_TOKEN`
19
+ matched against `X-Shapewall-Account-Setup-Token`. A trusted loopback proxy may inject that header after its existing owner gate;
20
+ it must overwrite inbound values. Never put the secret in browser code, configuration exports, request URLs or logs.
21
+
22
+ Visit the installation's `/signup` page using that owner access. The human must complete the browser's passkey registration
23
+ prompt and save the recovery codes shown once. No account or authenticator is created automatically. Both registration steps
24
+ require one of these owner-setup proofs, and verification rechecks the first-account condition inside the database transaction. Further
25
+ account registration is closed in this initial local mode.
26
+
27
+ ### Tailscale account origin
28
+
29
+ The operating-system user running Shapewall must already be permitted to configure Tailscale Serve. A `serve config denied`
30
+ error is a host permission failure before account enrollment, not a passkey or Tailscale identity failure. Ask the host operator to
31
+ complete the existing supported Serve permission/setup process for the intended port, then retry deliberately. Do not run Shapewall
32
+ as root, change account origins or relax identity checks to bypass it.
33
+
34
+ With `shapewall serve --tailscale --accounts --open`, use the printed private HTTPS account origin. The existing Tailscale owner
35
+ identity can authorize the first enrollment when the request comes through the loopback Tailscale proxy, its Host exactly matches the
36
+ configured node hostname, and its verified owner login matches. `--no-identity` disables that route; device pairing alone does not
37
+ authorize account setup. Registration still closes after the first account. The configured origin, WebAuthn checks and human passkey
38
+ prompt remain required. Do not change hostnames or weaken the origin gate to enroll.
39
+
40
+ In this mode, `serve --open` opens the ordinary account board URL. The terminal separately prints a **Host agent settings** command:
41
+
42
+ ```sh
43
+ shapewall settings --config /path/to/source/shapewall.config.json --open
44
+ ```
45
+
46
+ Run it on the Shapewall computer as the same OS user to configure the agent. It opens a temporary loopback-only management window
47
+ with its own private capability and source-folder confirmation. It has no board or chat routes and cannot enroll or sign in an
48
+ account. Account sign-in and Tailscale owner identity do not grant remote Agent Settings write access.
49
+
50
+ After enrolling, sign out and back in, and try a recovery code, on the devices you will use. Shapewall's tests use virtual
51
+ authenticators, so phone passkeys, passkey sync and your Tailscale setup are yours to check.
52
+
53
+ After enrollment, board APIs, captures, live snapshots and installation operations require the account session cookie. Public
54
+ application shells and static interface assets can still load to explain sign-in. `/auth/*` implements the actual passkey,
55
+ recovery, profile, session and security-log API used by Account and security. The account cookie is HttpOnly and SameSite=Lax,
56
+ with Secure and a `__Host-` prefix on HTTPS. Hosted and local account cookies have different names.
57
+
58
+ Accounts are an additional gate. They do not remove Tailscale/device pairing or grant the separate Agent Settings and managed
59
+ update capabilities. Signing out ends account access; it does not revoke a Tailscale login or paired-device credential. The last
60
+ local account cannot be deleted, and account deletion never deletes local board data.
61
+
62
+ ## Account and security in the app
63
+
64
+ After enrollment, open the profile menu and **Account and security** to review signed-in devices, passkeys, recovery tools and account
65
+ activity. To add a profile picture, choose **Upload photo** and select a PNG, JPEG or WebP under 5 MB. The browser crops it to a square
66
+ and saves the canonical image. **Remove photo** restores initials; a failed upload keeps the previous picture. No account is created
67
+ by merely opening the console, and the passkey prompt must be completed by the account owner.
68
+
69
+ ## Profile images
70
+
71
+ `PUT /auth/me/avatar` accepts JSON `{ "png": "<base64 PNG bytes>" }`. The browser crops and converts the selected picture to a
72
+ 256 by 256 RGBA8, non-interlaced PNG. The server validates the signature, dimensions, chunk boundaries, CRCs and exact bounded
73
+ inflated size, then decodes and reencodes the pixels. Animated images, unsupported formats, trailing data and invalid images are
74
+ rejected. Input bytes are capped at 512 KiB, with a separate bounded JSON parser. Original filenames and image metadata are not
75
+ stored. Failed uploads leave the existing image unchanged.
76
+
77
+ PUT and DELETE return `{ "avatarUrl": "..." }` (null after deletion). Refresh `/auth/me` for the complete profile. The
78
+ same-origin `GET /auth/me/avatar?v=<content hash>` returns only the signed-in user's canonical PNG, with private no-store caching
79
+ and nosniff headers. No arbitrary user ID, remote URL or file path is accepted. Hosted accounts use the same image validator,
80
+ storage schema and endpoints. Existing profiles retain initials until an image is uploaded.
@@ -0,0 +1,237 @@
1
+ # Notifications
2
+
3
+ Shapewall can tell people when something happens to a comment: a signed webhook for your own tools, Slack, Discord, and email through
4
+ [Resend](https://resend.com). It is off until you configure a channel. Every message links back to the comment on the board.
5
+
6
+ ## Events
7
+
8
+ | Event | When |
9
+ | ------------------------ | ---------------------------------------------------------------------------------- |
10
+ | `comment.created` | A new comment. |
11
+ | `comment.replied` | A reply on a comment (from a person, `shapewall comments reply`, MCP or `watch`). |
12
+ | `comment.mentioned` | Someone is @mentioned in a new comment, a reply, or an edit that adds the mention. |
13
+ | `comment.status_changed` | The agent status changes (`queued`, `working`, `done`, `needs-human`, cleared). |
14
+ | `comment.resolved` | A comment is resolved. |
15
+ | `comment.reopened` | A resolved comment is reopened. |
16
+
17
+ Events come from whatever changes the comment: the board (`shapewall serve`), the CLI (`shapewall comments add|resolve|reopen|reply|status`),
18
+ `shapewall watch`, `shapewall mcp` and the starter agent. Every process appends them to a shared event log in the output folder
19
+ (`.shapewall/events.jsonl`, see [the event log](#the-event-log)), and exactly one process sends each message:
20
+
21
+ - **While `shapewall serve` runs, it is the notifier.** It sends every change made from the moment it started, whichever process made
22
+ it, with serve's own environment: a `comments resolve` in another shell needs no `SHAPEWALL_WEBHOOK_SECRET` of its own. It records
23
+ this in `.shapewall/notifier.json` (its pid and a heartbeat every 10 seconds). A second `serve` on the same output folder leaves it to
24
+ the first, and takes over if that one stops. A server starts at the end of the log, so a restart never sends old events again. When
25
+ it stops cleanly (Ctrl+C, SIGTERM) it reads the log one last time before giving the lease back.
26
+ - **Without a running server** each command sends the changes it makes itself, and waits up to 15 seconds for its messages before it
27
+ exits. A `notifier.json` whose process is gone, or whose heartbeat is more than a minute old, counts as no server.
28
+ - **Nothing twice, nothing lost.** An event that happened after the server took over is the server's; anything earlier, or anything
29
+ that could not be written to the log, is sent by the process that made it. A server that stalls for more than a minute (a suspended
30
+ laptop, a blocked process) counts as gone meanwhile, so other processes send their own changes; when it wakes it skips the events from
31
+ that gap instead of sending them again.
32
+ - **The gap left:** a server killed with SIGKILL (or one that crashes) cannot read the log a last time or give the lease back. Changes
33
+ other processes make after its last read, and until its heartbeat is a minute old, are sent by nobody.
34
+
35
+ `actor` says who made the change: the author of a new comment or reply; for resolve, reopen and agent status changes, `--author` on the
36
+ CLI (default `agent`), `agent` from MCP, `shapewall` from `watch`, `github` when a merged pull request resolves it, and the commenter's
37
+ name from the board. It is `null` when nobody said. `actor` and comment authors are self-reported, not attested: anyone who can run the
38
+ CLI or comment on the board can give any name, so a bot must not treat a name as proof of who acted.
39
+
40
+ ## Config
41
+
42
+ Secrets never go in `shapewall.config.json`. The config names environment variables (`urlEnv`, `secretEnv`, `apiKeyEnv`) and Shapewall
43
+ reads them when it sends, so a config file, an export or a log line never holds a secret. Keys like `secret`, `apiKey` or `token`, and a
44
+ Slack or Discord `url` (the URL is the secret), are refused with a pointer to the right key.
45
+
46
+ ```json
47
+ {
48
+ "notifications": {
49
+ "boardUrl": "https://shapewall.example.com/",
50
+ "people": {
51
+ "robin": { "email": "robin@example.com", "slack": "U012AB3CD", "discord": "123456789012345678" }
52
+ },
53
+ "channels": [
54
+ { "id": "team", "type": "slack", "urlEnv": "SHAPEWALL_SLACK_WEBHOOK_URL" },
55
+ { "id": "ops", "type": "discord", "events": ["resolved", "reopened"] },
56
+ { "id": "hooks", "type": "webhook", "url": "https://ci.example.com/shapewall", "secretEnv": "SHAPEWALL_WEBHOOK_SECRET" },
57
+ { "id": "mail", "type": "email", "from": "Shapewall <reviews@example.com>" }
58
+ ]
59
+ }
60
+ }
61
+ ```
62
+
63
+ | Key | Type | Default | Notes |
64
+ | ---------- | ----------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65
+ | `boardUrl` | http(s) URL | the `serve` address | Where people open the board, for links in messages. Else the top-level `boardUrl`, the address of a running `shapewall serve`, then port 4600. `$SHAPEWALL_BOARD_URL` overrides it. |
66
+ | `people` | object | none | Mention handle to `{ email, slack, discord }` (any of them). Slack member ids look like `U012AB3CD`. |
67
+ | `retries` | 0-10 | `3` | Retries after a failed send. |
68
+ | `channels` | Channel[] | from the environment | Up to 20. Without this key, channels come from environment variables alone (below). |
69
+
70
+ ### Channel
71
+
72
+ | Key | Types | Default | Notes |
73
+ | ----------- | --------------------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
74
+ | `id` | all | the type | Used by `shapewall notify test ID`. Lowercase letters, digits, dashes. |
75
+ | `type` | all | required | `webhook`, `slack`, `discord` or `email`. |
76
+ | `events` | all | see below | Event names, with or without `comment.`; `"all"` for every one. |
77
+ | `boards` | all | every board | Only these board ids. |
78
+ | `urlEnv` | webhook/slack/discord | per type, as in the environment table below | The variable holding the webhook URL. |
79
+ | `url` | webhook | none | A generic webhook may give its URL in the config instead. |
80
+ | `secretEnv` | webhook | `SHAPEWALL_WEBHOOK_SECRET` | The signing secret. Required: unsigned webhooks are not sent. |
81
+ | `apiKeyEnv` | email | `RESEND_API_KEY` | The Resend API key. Must be `RESEND_API_KEY` or a name starting `SHAPEWALL_`. |
82
+ | `from` | email | required | `Name <reviews@example.com>`, on a domain you verified with Resend. |
83
+ | `to` | email | none | Addresses for events other than mentions. |
84
+ | `fallback` | email | `"none"` | `"outbox"`: with no API key, write `.eml` files instead of sending (below). |
85
+
86
+ Default events: webhooks get all six; Slack and Discord get created, replied, resolved and reopened (a mention pings the person inside
87
+ that message, so a separate mention message would be a duplicate); email gets `comment.mentioned` only.
88
+
89
+ ### Per-person routing
90
+
91
+ `people` maps a mention handle to where that person is reached:
92
+
93
+ - **Slack and Discord**: `@robin` in a comment or reply becomes a real ping (`<@U012AB3CD>`) for mapped people; everyone else stays plain
94
+ text. A `comment.mentioned` message starts with the ping.
95
+ - **Email**: a `comment.mentioned` event goes to the mentioned person's `email`. A mention of someone with no email is skipped (logged
96
+ once). Other events go to the channel's `to` list.
97
+ - **Webhooks** carry the handle only, never anyone's email or chat ids.
98
+
99
+ ### Channels from the environment
100
+
101
+ With no `channels` key, these variables set up channels by themselves (ids in brackets):
102
+
103
+ | Variables | Channel |
104
+ | -------------------------------------------------------------------------------- | -------------------------------- |
105
+ | `SHAPEWALL_WEBHOOK_URL` and `SHAPEWALL_WEBHOOK_SECRET` | signed webhook (`webhook`) |
106
+ | `SHAPEWALL_SLACK_WEBHOOK_URL` | Slack incoming webhook (`slack`) |
107
+ | `SHAPEWALL_DISCORD_WEBHOOK_URL` | Discord webhook (`discord`) |
108
+ | `RESEND_API_KEY`, `SHAPEWALL_EMAIL_FROM` and optionally `SHAPEWALL_EMAIL_TO` (,) | email (`email`) |
109
+
110
+ `SHAPEWALL_BOARD_URL` sets the link base; `SHAPEWALL_RESEND_URL` points email at another Resend-compatible endpoint (a proxy, or a stub in
111
+ tests).
112
+
113
+ ## Delivery
114
+
115
+ - **Never in the way.** A change is saved and answered first; its messages are queued and sent in the background, in order per channel.
116
+ A slow or broken endpoint never slows the board or the CLI.
117
+ - **Retries.** Network errors, timeouts (10 seconds), `408`, `429` and `5xx` are retried with exponential backoff (1 s, 2 s, 4 s, with
118
+ jitter), honouring `Retry-After` up to a minute. Other answers (`400`, `401`, `404`) are final. A channel queues at most 200 messages;
119
+ past that the oldest is dropped, with a log line.
120
+ - **Logs** say which channel, which event and the HTTP status or error code. They never include a URL, a header, a body or a secret.
121
+ - **Pings.** Comment text is escaped for each format: a comment cannot write `<!channel>`, `@everyone` or a link of its own. Discord
122
+ messages set `allowed_mentions` to the mapped people only.
123
+
124
+ ## The signed webhook
125
+
126
+ A `POST` with a JSON body:
127
+
128
+ ```json
129
+ {
130
+ "id": "6f0c5d2e-...",
131
+ "type": "comment.created",
132
+ "at": "2026-11-04T18:21:07.512Z",
133
+ "board": { "id": "site", "title": "My site" },
134
+ "text": "Robin commented on Pricing (desktop)",
135
+ "url": "https://shapewall.example.com/?board=site&c=12&filter=all",
136
+ "comment": {
137
+ "id": 12,
138
+ "pageId": "pricing",
139
+ "pageTitle": "Pricing",
140
+ "viewport": "desktop",
141
+ "author": "Robin",
142
+ "body": "The annual toggle hides the monthly price, @sam",
143
+ "status": "open",
144
+ "agentStatus": null,
145
+ "mentions": ["sam"],
146
+ "replyCount": 0,
147
+ "resolution": null,
148
+ "fixRef": null,
149
+ "createdAt": "2026-11-04T18:21:07.512Z",
150
+ "updatedAt": "2026-11-04T18:21:07.512Z"
151
+ },
152
+ "actor": "Robin"
153
+ }
154
+ ```
155
+
156
+ `comment.replied` adds `reply`, `comment.mentioned` adds `handle` (and `reply` when the mention was in one), `status_changed`,
157
+ `resolved` and `reopened` add `previous`. Headers:
158
+
159
+ | Header | Value |
160
+ | ----------------------- | ------------------------------------------------------------- |
161
+ | `X-Shapewall-Event` | The event type. |
162
+ | `X-Shapewall-Delivery` | The event id; the same on every retry, so you can de-dupe. |
163
+ | `X-Shapewall-Timestamp` | Unix seconds when it was signed. |
164
+ | `X-Shapewall-Signature` | `sha256=` and the hex HMAC-SHA256 of `timestamp + "." + body` |
165
+
166
+ Verify it before trusting the body, and reject old timestamps:
167
+
168
+ ```js
169
+ import { createHmac, timingSafeEqual } from 'node:crypto'
170
+
171
+ function verify(req, rawBody, secret) {
172
+ const timestamp = req.headers['x-shapewall-timestamp']
173
+ if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
174
+ const expected = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`
175
+ const given = String(req.headers['x-shapewall-signature'] || '')
176
+ return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected))
177
+ }
178
+ ```
179
+
180
+ ## The event log
181
+
182
+ `.shapewall/events.jsonl` holds one JSON line per event, from every process, appended under a file lock (so lines never interleave).
183
+ Past 5 MB it is renamed to `events.1.jsonl` (one older file is kept) and a new one starts. Each line is what `shapewall events --json`
184
+ prints:
185
+
186
+ ```json
187
+ {
188
+ "id": "5b0c...",
189
+ "type": "comment.resolved",
190
+ "at": "2026-11-05T19:09:41.015Z",
191
+ "board": "site",
192
+ "commentId": 2,
193
+ "actor": "review-bot",
194
+ "comment": {
195
+ "id": 2,
196
+ "pageId": "signup",
197
+ "viewport": "phone",
198
+ "author": "sam",
199
+ "body": "the signup button is hard to see on phone",
200
+ "status": "resolved",
201
+ "agentStatus": null,
202
+ "resolution": "Bigger and darker now",
203
+ "fixRef": null,
204
+ "mentions": [],
205
+ "replyCount": 2,
206
+ "element": { "selector": "button[data-testid=\"signup-submit\"]", "text": "Create account" },
207
+ "captureVersion": "20261105T183551624Z-d37e",
208
+ "createdAt": "2026-11-05T18:38:20.614Z",
209
+ "updatedAt": "2026-11-05T19:09:41.015Z"
210
+ },
211
+ "previous": { "status": "open" }
212
+ }
213
+ ```
214
+
215
+ `comment.replied` and mentions in a reply add `reply` (`{ id, author, body, createdAt }`), `comment.mentioned` adds `handle`, and
216
+ `comment.status_changed` adds `agentStatus` beside `previous`. The comment is a summary (no thread, no file paths); `shapewall comments
217
+ get ID --json` has the rest. The log is local data in the output folder, like `comments.json`: keep it out of git. Deleting a comment
218
+ does not remove it from the log: the bodies and replies of a deleted comment stay in `events.jsonl` (and `events.1.jsonl`) until rotation
219
+ pushes them out, after up to two 5 MB files of newer events. To remove them sooner, delete both files while no Shapewall process runs.
220
+
221
+ ## Email without an API key
222
+
223
+ Email is off without `RESEND_API_KEY` (or the channel's `apiKeyEnv`): there is no SMTP fallback. To see what would be sent, or to hand
224
+ messages to a local mail pickup, set `"fallback": "outbox"` on the channel: each message is written to
225
+ `<outputDir>/notifications/outbox/` as an `.eml` file (readable only by you) instead.
226
+
227
+ ## Commands
228
+
229
+ ```text
230
+ shapewall notify list [--json] every channel, its events, and what it still needs (variable names only)
231
+ shapewall notify test CHANNEL [--to EMAIL] send a test message; exit 1 if it fails
232
+ shapewall doctor includes a notifications line: warn when a channel is missing a variable
233
+ shapewall events --follow --json the same events as JSON lines, for a bot of your own (no webhook needed)
234
+ ```
235
+
236
+ `notify test` sends a message marked as a test, through the same path as real ones (retries included), and prints the HTTP status.
237
+ For email it goes to the channel's `to` list, or `--to`.
@@ -0,0 +1,69 @@
1
+ # Page checks
2
+
3
+ Page checks are a manually invoked diagnostic pass against the original configured site. They use the same selected environment, saved authentication, ready selector and page actions as capture. They do not audit Shapewall's sanitized HTML or change screenshots, comments or agent queues.
4
+
5
+ ```sh
6
+ shapewall checks run --board site --only home --limit 4
7
+ shapewall checks run --board site --only home,about --seo --limit 8 --json
8
+ shapewall checks list --board site --json
9
+ ```
10
+
11
+ The default cap is 20 page/device views; the explicit maximum is 100. Runs are serial and never scheduled automatically. A selected page with desktop and phone consumes two views. Configured actions run again, so use a dedicated test account and safe fixtures where actions change application state.
12
+
13
+ The Playwright pass records document status, error responses including API 429s, failed requests, browser error counts, changed navigation destinations and basic document semantics. Expected main-document error statuses are honored. A ready selector can establish the expected signed-in state. Optional page `errorSelectors` explicitly identify known app error states; visible matches create a reliability finding without storing selectors or page text. Hidden matches do not count. Selectors are limited to 10, 500 characters each and 1,000 inspected elements each; invalid or broader selectors produce an incomplete-coverage advisory. Redirect findings require human interpretation because intentional redirects and login redirects can look alike.
14
+
15
+ SEO is off unless `--seo` is supplied or the config sets `checks.seo` (`true` for every page, or a list of page ids; `--no-seo` turns it off for one run). Opt in only pages intended to be public and indexable in the selected environment. Checks cover title, description, title and description length (by rendered width, the way search results cut them: about 580 px of title and 920 px of description), duplicates among the selected distinct pages, canonical syntax and whether the canonical names another path, robots meta and response directives, and social title, description and image URL metadata. Missing metadata and `noindex` are advisory observations. Intentional private or staging `noindex` is expected. Set page `seo: { "indexable": false }` for intentional private pages: public metadata, robots and image probes are skipped, including duplicate comparisons, and the board shows them as private rather than failing. Omitted or true applicability preserves the opt-in.
16
+
17
+ Each SEO-enabled page check also saves a local search preview beside its report (`checks/seo/<report id>.json`): the page's title, description, canonical, robots meta, social tags and a small JPEG re-encode of the first Open Graph image made by the browser. Previews contain page text and URLs, so unlike reports they stay on the installation: only the private local checks API serves them, and they are never part of a checks bundle, push, share or static export.
18
+
19
+ For applicable pages the CLI fetches the original origin's robots text and observes Googlebot rules: specific groups replace wildcard groups, duplicate groups merge, longest matching paths win and allow wins ties, with wildcard, end-anchor and percent-encoding handling. Non-429 client error responses mean no rules were available; server errors, throttling and incomplete probes remain unknown. This follows [Google's robots specification](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec) and [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309.html). Crawl restrictions do not prove search exclusion. Search inclusion, crawler access from the internet and rankings are not checked.
20
+
21
+ The first Open Graph image is fetched and decoded as PNG, JPEG or WebP. Actual decoded dimensions and bytes are separate from declared dimensions; mismatches are advisory. Error HTTP responses and invalid images produce findings. Other formats, off-origin images and redirected responses remain explicitly unknown. This is not a social platform preview renderer, and additional Open Graph or Twitter image candidates are not sampled.
22
+
23
+ Both probes execute inside the original local browser with credentials and referrers omitted, same-origin enforcement, no redirects followed, and no hosted fetch endpoint. They run after load measurement stops, so diagnostic requests do not inflate navigation request/error metrics. Each probe has a six-second deadline. Robots responses have a 500 KiB, 10,000-line and 4,096-character line limit; oversized files remain unknown rather than yielding a partial allow result. Image responses have a 5 MiB byte limit and a 16-megapixel dimension preflight before decoding. CSP and network restrictions can make results unavailable. Probes are skipped when a service worker controls the document, because it can intercept or proxy requests. Rule matching also has a shared two-million-step cap. Image URLs are capped at 4,096 characters. Across a run, the existing page-view limit also caps robots and image requests at one each per selected view. No response body or image URL is saved.
24
+
25
+ Load observations are navigation timings in milliseconds, request counts and resource bytes where available. Transfer bytes and decoded bytes are different metrics. Cross-origin timing restrictions, caches and service workers can make byte sizes unknown; unknown is stored as null, never a fabricated zero. The resource timing buffer and load window have explicit completeness limits. Capture elapsed time and PNG size are never performance metrics. This is a local lab navigation observation, not real-user Web Vitals or an accessibility certification.
26
+
27
+ Each schema-versioned report records capture-version association, audit time, separately sampled status, runner conditions, actual browser information and hashes of configured state and prepared authentication. It does not establish that a later navigation matches the state of an older screenshot. Recapture, URL, action, viewport, error-selector, SEO applicability or auth-fixture changes make the old report stale. Before comparing, `compareProfiles` rejects differing runner, viewport, build or configured state. Failed, stale, unsupported and not-run states are distinct from a completed report.
28
+
29
+ Reports live under `<output>/<board>/checks/`, with at most 200 immutable artifacts per board and 128 KiB per report. Normal filesystem backups preserve them. Old screenshot expiry does not delete reports. The private read API never starts a browser or fetches a target. Report text contains fixed observations and counts, not raw URLs, resource paths, page text, console messages, credentials or network bodies.
30
+
31
+ Shared and public exports exclude diagnostic reports by default. The `checksBundle` and `importChecks` adapters require an explicit include-checks choice and validation after the enclosing board-access check. Hosted storage must only validate and display a pushed artifact; it must never execute checks against user-supplied URLs. Report uploads do not authorize an agent. A finding can inform a human-edited comment through the existing comment and agent authorization flow.
32
+
33
+ ## Checks on the wall
34
+
35
+ Open **Checks** from the desktop toolbar, the phone **More** menu, a page action bar or an actionable page badge. The desktop pane replaces Comments or Agent; phones use the existing sheet pattern. The panel starts with four tiles (Reliability, Performance, Accessibility, SEO) showing what needs fixing and, for Performance and SEO, the median Lighthouse lab score; a tile filters the issues. Tabs:
36
+
37
+ - **Issues** (default): every current finding across pages and devices, the ones that need a person first, then notes. SEO findings take the SEO tab's level everywhere: its errors and warnings need attention (and count in the SEO tile's "to fix" and on page cards), its tips are notes.
38
+ - **Pages**: one card per page and device with each runner's state and headline number; measurements, conditions and report ids sit behind **Technical details**.
39
+ - **SEO**: how many public pages are indexable (search may list them), a filter for pages with no issues and pages that need work, missing titles and descriptions, duplicates across all checked pages (not just one run), share image, canonical and robots problems, and per page an approximate Google result, a share card preview, and each issue in plain English with a fix. Pages marked `seo.indexable: false` show as private. Hosted and imported boards show the issues without previews.
40
+ - **Performance**: Lighthouse score, LCP, TBT and CLS per page and device, with recorded budgets as bars.
41
+ - **History**: before and after comparison of retained reports.
42
+
43
+ Scores are secondary Lighthouse lab scores, never a blended board score or a claim about real users.
44
+
45
+ ### Running checks from the board
46
+
47
+ On a local installation the owner can press **Run checks** in the panel: the signed-in account, the private link printed by `shapewall serve`, or a paired owner device. It starts the same `shapewall checks run` as the terminal in a child process, with the same limits, configured sign-in and page actions, and shows progress until the reports arrive. **Include SEO** starts on (off when the config sets `checks.seo: false`); private pages are skipped either way. One run at a time per server, at most 100 page views per run, never while a capture of the board is running, and only from the board's own page. Read-only boards, boards with captures turned off, and hosted boards cannot start runs; hosted storage never executes checks.
48
+
49
+ **Stop** (and the run's time limit, 5 minutes plus 3 per page view) ends the run after abandoning the page view in progress: only the views that finished are saved, every other view keeps its earlier results, and the panel reads "Stopped after N of M page views". In the terminal, SIGTERM or Ctrl-C does the same and `shapewall checks run` exits with code 3; a second Ctrl-C exits at once.
50
+
51
+ **Create comment** (and **Fix with agent** on an SEO issue, which addresses the draft to `@agent`) keeps the finding in a draft, closes Checks and asks you to choose a pin on the actual page. The normal editable composer opens at that chosen point. Only saving that reviewed comment creates a comment; the finding itself never creates an agent claim or calls Send to agent. Normal project comment and agent authorization policies still apply.
52
+
53
+ ## Moving and exporting reports
54
+
55
+ `shapewall push --include-checks` and `shapewall share --include-checks` explicitly include a validated checks bundle. Source environment IDs are preserved in up to eight bounded diagnostic descriptors, without URLs. The hosted capture remains a single environment; the separate Checks environment picker labels other environments as diagnostics only and disables canvas pins for them. Legacy remapped reports retain their immutable identity. Bundles are limited to 1 MiB and 200 reports. Servers reject wrong board/page/viewport associations, descriptor collisions and overflows atomically and include report bytes in workspace quotas.
56
+
57
+ Hosted reports are member-only by default. When creating a guest share link, an admin can explicitly enable **Include page checks**; the default is off, including for existing links. This grants read access to retained project reports and history, not execution. Every request rechecks the link, guest session, project, expiration and revocation. Public board routes never include diagnostics. Ordinary pushes preserve existing report history and descriptors without uploading new reports. Hosted storage cannot verify private authentication or configured actions; Checks states this limitation. Report text is inert data and cannot start a browser or an agent.
58
+
59
+ `shapewall export --include-checks` writes separately selectable environment views and the validated retained report bundle into the static export. Without this option, diagnostic files and the Checks entry are excluded, including when replacing an older opted-in export. Anyone receiving an opted-in static export can read its diagnostics. Normal filesystem backups include report artifacts.
60
+
61
+ ## History and performance budgets
62
+
63
+ Each runner/device view has explicit Before and After report selectors. Comparison requires matching runner, browser, viewport, throttling, authentication, flow, state and observation conditions. A declared build may differ only after the reviewer explicitly enables that changed variable. Missing older profile evidence is incomparable. Numeric deltas preserve unknown values; small changes are labeled, and incomplete coverage or changed budget policies prevent false finding-resolution claims.
64
+
65
+ `checks.budgets` records explicit metric maximums in each new navigation report. Existing reports are never reinterpreted under a newer policy. Over-budget observations are findings; missing metrics remain unknown. Problems-first ordering, device selection, performance filtering and LCP ordering prioritize work without a blended board score. Explicit flow files separately support per-step `maxDurationMs` budgets.
66
+
67
+ ## Interaction and accessibility audits
68
+
69
+ See [explicit interaction flows and accessibility](interaction-audits.md) for single-sample step budgets, bounded local axe snapshots, configuration and limits.