shapewall 0.7.3 → 0.9.0

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 (105) hide show
  1. package/CHANGELOG.md +121 -0
  2. package/README.md +7 -3
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +130 -72
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-DwEAN6va.js → BuzzDialog-DnjF36OB.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  8. package/dist/client/assets/{History-Cp4QRJti.js → History-FzpzGmXZ.js} +1 -1
  9. package/dist/client/assets/LocalSettings-BGFl4VKr.js +1 -0
  10. package/dist/client/assets/{Management-B-x1faV8.js → Management-BGdmGtby.js} +1 -1
  11. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  12. package/dist/client/assets/{ShareDialog-CdLdd6WQ.js → ShareDialog-D0tmOGcQ.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-BneaJeqQ.js → app-update-dialog-BQxVHa5e.js} +1 -1
  14. package/dist/client/assets/{circle-x-D5MkDLJk.js → circle-x-Dxsku6s6.js} +1 -1
  15. package/dist/client/assets/error-reports-sdk-COuSIAQO.js +15 -0
  16. package/dist/client/assets/index-B_m65HWT.css +2 -0
  17. package/dist/client/assets/index-C1ZwriJU.js +37 -0
  18. package/dist/client/assets/{play--xrZ7VCR.js → play-vJhLsLhL.js} +1 -1
  19. package/dist/client/assets/{refresh-cw-B-npxKae.js → refresh-cw-TbGHlgDq.js} +1 -1
  20. package/dist/client/assets/ui-CogdFhRH.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/{LocalAccountsApp-uKpz8EwR.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  25. package/dist/console/assets/{LocalConsole-XeqnTeRB.js → LocalConsole-Rg-MTvSJ.js} +2 -2
  26. package/dist/console/assets/{LocalUsage-Br3Ddp7_.js → LocalUsage-BGCSfmBU.js} +1 -1
  27. package/dist/console/assets/{app-update-dialog-h11DnNZi.js → app-update-dialog-CEhV7th4.js} +1 -1
  28. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  29. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  30. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  31. package/dist/console/assets/error-reports-sdk-COuSIAQO.js +15 -0
  32. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  33. package/dist/console/assets/minus-Cnq0kKnu.js +1 -0
  34. package/dist/console/assets/{tailnet-DJGcztR5.js → tailnet-Cqtbptzq.js} +2 -2
  35. package/dist/console/assets/theme-CB-cwoG6.js +1 -0
  36. package/dist/console/assets/ui-HgfwUo3E.js +41 -0
  37. package/dist/console/assets/{usage-fzmilDTS.js → usage-BCIwgDP9.js} +2 -2
  38. package/dist/console/assets/{usage-DjmUlnXL.js → usage-CeY6XnGX.js} +1 -1
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -8
  41. package/docs/README.md +64 -0
  42. package/docs/agent-hardening.md +3 -3
  43. package/docs/agent-recipes.md +3 -3
  44. package/docs/agent-workflow.md +6 -4
  45. package/docs/agents.md +25 -16
  46. package/docs/architecture.md +9 -2
  47. package/docs/config.md +53 -25
  48. package/docs/deployment.md +19 -3
  49. package/docs/github.md +1 -1
  50. package/docs/hosted.md +265 -70
  51. package/docs/local-accounts.md +1 -1
  52. package/docs/performance.md +3 -2
  53. package/docs/pull-requests.md +1 -1
  54. package/docs/starter-agent.md +4 -4
  55. package/docs/where-to-run.md +1 -1
  56. package/package.json +5 -2
  57. package/src/agent/backends/acp.js +39 -9
  58. package/src/capture/capture.js +35 -5
  59. package/src/capture/destination.js +67 -0
  60. package/src/capture/load-errors.js +82 -0
  61. package/src/checks/cli.js +41 -5
  62. package/src/cli/args.js +1 -0
  63. package/src/cli/capture.js +5 -0
  64. package/src/cli/comments.js +41 -3
  65. package/src/cli/help.js +4 -1
  66. package/src/cli/init.js +8 -4
  67. package/src/cli/misc.js +3 -3
  68. package/src/cli/serve.js +37 -6
  69. package/src/comment-fields.js +5 -0
  70. package/src/comments-cli.js +26 -5
  71. package/src/config-keys.js +191 -0
  72. package/src/config-reload.js +4 -1
  73. package/src/config.js +33 -2
  74. package/src/doctor.js +188 -39
  75. package/src/error-scrub.js +135 -0
  76. package/src/error-tracking.js +105 -0
  77. package/src/feedback.js +36 -2
  78. package/src/hosted/app.js +9 -3
  79. package/src/hosted/auth.js +14 -8
  80. package/src/hosted/board-routes.js +6 -6
  81. package/src/hosted/db.js +50 -0
  82. package/src/hosted/pages.js +16 -7
  83. package/src/hosted/server.js +4 -0
  84. package/src/hosted/token-api.js +17 -1
  85. package/src/hosted/usage-shape.js +1 -1
  86. package/src/missing-package.js +11 -0
  87. package/src/ports.js +35 -0
  88. package/src/serve-state.js +16 -0
  89. package/src/server/app.js +18 -14
  90. package/src/server/local-console.js +7 -3
  91. package/src/watch.js +6 -0
  92. package/dist/client/assets/BoardChat-BVbIXN0v.js +0 -27
  93. package/dist/client/assets/ChecksPanel-BJmSzge1.js +0 -1
  94. package/dist/client/assets/LocalSettings-Bt52or8s.js +0 -1
  95. package/dist/client/assets/QuickConnect-C6sW-MA7.js +0 -1
  96. package/dist/client/assets/index-C-pM8Kf2.js +0 -37
  97. package/dist/client/assets/index-C2_XIPRO.css +0 -2
  98. package/dist/client/assets/ui-2lMx-4bc.js +0 -41
  99. package/dist/console/assets/app-version-IdaEWb4n.js +0 -1
  100. package/dist/console/assets/console-BDuWmrw9.js +0 -11
  101. package/dist/console/assets/console-BGRSS8Ru.css +0 -2
  102. package/dist/console/assets/local-agents-BkSN9lXJ.js +0 -6
  103. package/dist/console/assets/minus-887msXez.js +0 -1
  104. package/dist/console/assets/theme-CPfJOmcz.js +0 -1
  105. package/dist/console/assets/ui-DnyJhoQU.js +0 -41
package/docs/agents.md CHANGED
@@ -158,7 +158,7 @@ init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a
158
158
 
159
159
  ## Name and icon
160
160
 
161
- Every connected agent has a name you choose and an icon, so a board with two agents reads "Harry" and "Fixer", not "Claude Code"
161
+ Every connected agent has a name you choose and an icon, so a board with two agents reads "Reviewer" and "Fixer", not "Claude Code"
162
162
  twice. Both are display only: they change nothing an agent runs with.
163
163
 
164
164
  - **At Connect.** The **Allow this?** confirmation of a one-click Connect (in the Agent panel and on the Agents page) has a **Name**
@@ -181,7 +181,7 @@ twice. Both are display only: they change nothing an agent runs with.
181
181
  are in `THIRD_PARTY.md`. A colour (one of eight) tints a built-in avatar or the initials, never a mark or a picture.
182
182
  - **An uploaded picture** is a PNG, JPEG or WebP of up to 2 MB. The board crops it to a square and sends a 256 by 256 PNG; the server
183
183
  checks it byte by byte, decodes it and writes the pixels out again, the same way as a profile photo
184
- ([local-accounts.md](local-accounts.md#profile-images)), so no metadata and never an SVG is stored. It is kept next to the agent
184
+ ([Local accounts and photos](local-accounts.md#profile-images)), so no metadata and never an SVG is stored. It is kept next to the agent
185
185
  settings (`agent-icons/<hash>.png` beside `agents.json`, private to you), served only as an image (`GET /api/agent/icons/<hash>`,
186
186
  `image/png`, `nosniff`, cached by its content hash), and removed when no agent uses it any more.
187
187
 
@@ -261,7 +261,7 @@ remote mode has the same feedback tools. Shared `--chat` boards never gain these
261
261
  is checked again on each turn, and trusted and untrusted ACP sessions are separate. Approving a permission, stopping an owner turn, or clearing its thread requires the same owner capability, including while its ACP session is idle. `--no-capture` hides Fix and removes recapture tools.
262
262
 
263
263
  For an external coding session, open **Chat settings** in the chat panel: **Use with Claude Code / Codex** shows copyable MCP setup
264
- commands (before an agent is connected, the same commands are folded under the connect options). See [agent-workflow.md](agent-workflow.md#mcp-server-shapewall-mcp).
264
+ commands (before an agent is connected, the same commands are folded under the connect options). See [The agent workflow](agent-workflow.md#mcp-server-shapewall-mcp).
265
265
 
266
266
  ## Undo an agent's change
267
267
 
@@ -707,7 +707,15 @@ Older Gemini CLI versions call the flag `--experimental-acp` (still accepted, de
707
707
  the panel shows a card with the agent's options (**Allow**, **Reject**, and any "always" choices it offers). An edit or a write
708
708
  shows its diff on the card, computed by Shapewall from the file as it is and the new text (the first 80 lines or 8 KB, with **Show
709
709
  the whole diff** for up to 1500 lines or 64 KB). No answer within 2 minutes counts as a deny, and so does Stop. Whether the agent asks at all is the agent's own setting (Claude Code's permission mode,
710
- Codex's approval policy, goose's mode): Shapewall does not change it.
710
+ Codex's approval policy, goose's mode): Shapewall does not change it. One-click **Connect** saves the bare command
711
+ (`claude-agent-acp`), so the agent starts in whatever mode its own settings give it, and some adapters start in one that acts without
712
+ asking (`claude-agent-acp` 0.106.0 starts a new session in `auto` when no `permissions.defaultMode` is set).
713
+ - **The mode in effect.** The panel's line about a local agent says it runs under its own permission settings. Once its session has
714
+ started and it reports a mode, the line names it: **Auto, which acts without asking** (any mode whose name says so: auto, accept
715
+ edits, bypass, full access, yolo and the like), **Default: it asks here before an edit or a command its own settings do not already
716
+ allow** (Claude Code's `default`, goose's `approve`), **Plan: it reads and answers** (Claude Code's `plan`, Codex's `read-only`,
717
+ goose's `chat`), or just the mode's name for any other. To be asked first, pick an asking mode in the composer's options, or set
718
+ one in the agent's own settings ([Restrict the agent's own tools](#restrict-the-agents-own-tools)).
711
719
 
712
720
  ### What the agent may do through Shapewall
713
721
 
@@ -746,12 +754,13 @@ quote each comment in the same `<shapewall-data trust="untrusted">` element.
746
754
  The agent works with its own tools under its own settings, and Shapewall cannot sandbox them. Run it the way you would run it on a repo
747
755
  full of other people's text:
748
756
 
749
- - **Claude Code** (`claude-agent-acp`) follows your Claude Code settings. Keep `permissions.defaultMode` at `default` (asks before
750
- edits and commands) or `plan` (read-only), never `bypassPermissions`. A separate config folder for Shapewall works too:
757
+ - **Claude Code** (`claude-agent-acp`) follows your Claude Code settings. Set `permissions.defaultMode` to `default` (asks before
758
+ edits and commands your allow rules do not cover) or `plan` (read-only), never `auto`, `acceptEdits` or `bypassPermissions`. Set
759
+ it explicitly: with none set, `claude-agent-acp` 0.106.0 starts in `auto`, which acts without asking. A separate config folder for Shapewall works too:
751
760
  `CLAUDE_CONFIG_DIR` is passed to the agent.
752
761
  - **Codex** (`codex-acp`) follows `~/.codex/config.toml` (or `CODEX_HOME`). Use `sandbox_mode = "workspace-write"` (or
753
762
  `"read-only"`) with `approval_policy = "on-request"`, never `danger-full-access`.
754
- - **goose** loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
763
+ - **goose** asks only in `GOOSE_MODE=approve` (or `smart_approve`); its default, `auto`, acts without asking. It also loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
755
764
  extension, and start it with that extension named:
756
765
 
757
766
  ```sh
@@ -791,8 +800,8 @@ What the bridge protects against, and what it does not:
791
800
  - **Who can chat:** anyone who can reach a board with chat can drive the agent, with your login, on your machine. `shapewall serve`
792
801
  keeps chat off for boards shared beyond this machine unless you pass `--chat`, and with an ACP agent it refuses to start a shared
793
802
  board with `--chat` unless you also pass `--allow-remote-agent`: that combination is remote command execution as you, for anyone
794
- who reaches the board. For shared boards, use the sandboxed starter agent ([starter-agent.md](starter-agent.md)), and see
795
- [agent-hardening.md](agent-hardening.md).
803
+ who reaches the board. For shared boards, use the [sandboxed starter agent](starter-agent.md), and see
804
+ [Agent hardening](agent-hardening.md).
796
805
  - **Not covered:** the agent's own tools and its own sandbox (or lack of one), what its model provider sees, and anything you allow.
797
806
  A command you approve runs as you in the project, so the project's own config still applies to it (a repo's `.git/config` can make
798
807
  `git status` run a program): approve commands only in repos you trust.
@@ -903,8 +912,8 @@ What the bridge protects against, and what it does not:
903
912
  own name (**Effort**, **Thinking**), and anything else it offers (a mode such as Ask or Plan) under **More options**. When the panel
904
913
  is too narrow for them, one control holds every option in sections. They come from an ACP agent's own session (`session/new`
905
914
  config options and its older modes), or the model list an OpenAI-compatible endpoint reports at `/models`. Never a permission or
906
- sandbox setting, and never a mode that acts without asking (bypass, auto, yolo and the like), so the agent still asks before it
907
- changes files or runs commands. Values show the agent's real names: a value that is just the agent's default says **Default
915
+ sandbox setting, and never a switch to a mode that acts without asking (bypass, auto, yolo and the like). A session that is
916
+ already in such a mode (its own settings started it there) keeps it until you pick another, and the panel's line says so. Values show the agent's real names: a value that is just the agent's default says **Default
908
917
  model**, or the model it says it currently is. The keyboard works as in any menu: the current choice has the focus when it opens,
909
918
  the arrows and Home and End move, Escape closes it back to its button.
910
919
  - **Options before the first message.** As soon as the panel is open and on screen for the owner, a new chat (New chat included)
@@ -1009,14 +1018,14 @@ Markdown to share it.
1009
1018
 
1010
1019
  ## Board tools
1011
1020
 
1012
- Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([agent-workflow.md](agent-workflow.md)).
1021
+ Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([The agent workflow](agent-workflow.md)).
1013
1022
 
1014
1023
  Agents with only a shell, and chat bots that relay a board to people, use the CLI: `shapewall comments get|add|reply|resolve|status`
1015
1024
  (all with `--json`; `comments` and `comments get` also take `--for-agent`, each comment quoted as untrusted `<shapewall-data>` for a
1016
1025
  model to read), `shapewall comments --since ID|TIME` for what is new, and `shapewall events --follow --json` for a live stream of
1017
1026
  every comment event from every process that never claims anything (`shapewall watch --no-claim` likewise). While `shapewall serve` runs,
1018
- it sends the notifications for all of those changes ([agent-workflow.md](agent-workflow.md#a-chat-bot-telegram-slack-discord),
1019
- [notifications.md](notifications.md#events)).
1027
+ it sends the notifications for all of those changes ([The agent workflow](agent-workflow.md#a-chat-bot-telegram-slack-discord),
1028
+ [Notifications](notifications.md#events)).
1020
1029
 
1021
1030
  An ACP agent reads the project with its own tools; board data comes with each message. On trusted owner turns, its ACP session also receives a Shapewall stdio MCP server scoped to this board. It provides board reads plus replies, agent status, resolution and optional recapture, with no GitHub actions. Ask it to call `recapture_pages` with any other configured pages it changed; Shapewall automatically recaptures the comment page after the turn.
1022
1031
 
@@ -1034,7 +1043,7 @@ Anyone who can comment can write text that a model will read. Shapewall keeps th
1034
1043
  That lowers the risk; it does not remove it. Models can still be talked into a wrong answer, so treat answers about untrusted comments
1035
1044
  with care, and do not point a chat at a board you share with strangers using a key that has other powers.
1036
1045
 
1037
- Connecting an agent to a board other people can write on? Read [agent-hardening.md](agent-hardening.md) first (also as a printable
1046
+ Connecting an agent to a board other people can write on? Read [Agent hardening](agent-hardening.md) first (also as a printable
1038
1047
  [PDF](https://shapewall.com/downloads/shapewall-agent-hardening.pdf)): how injected text reaches an agent, least privilege, a sandbox checklist and what to do if something goes wrong.
1039
1048
 
1040
1049
  ## Sharing a board
@@ -1131,5 +1140,5 @@ chosen, expiresAt }`, state `pending`, then `approved`, `denied`, `expired` or `
1131
1140
  ## Shared boards
1132
1141
 
1133
1142
  The chat runs the agent as you. For boards where not everyone who comments should drive an agent on your machine, use the
1134
- [starter-agent.md](starter-agent.md): work on a comment runs in a container with only a fresh worktree, an egress allow list, fixed tools, a trigger gate, budgets, and a branch as
1143
+ [Sandboxed starter agent](starter-agent.md): work on a comment runs in a container with only a fresh worktree, an egress allow list, fixed tools, a trigger gate, budgets, and a branch as
1135
1144
  the output.
@@ -167,7 +167,9 @@ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page b
167
167
  - 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
168
168
  branching journey is shown one path at a time (`resolvePath` with the branches picked); the other branches' arrows are dashed.
169
169
  - Compare mode lays two frames per viewport side by side (one per environment) and shows screenshots only, with the cached diff mask
170
- over the second.
170
+ over the second. A variant keeps its single frame there, beside its page's pair: it is one capture of one idea, with no second
171
+ environment to compare it against. New comments are off while comparing (a comment belongs to a page, not to one environment, so
172
+ which capture a click meant is unanswerable); the compare bar says so, and replies, resolving and "jump to comment" all work.
171
173
  - Each frame's label (viewport, environment, live) sits in a strip between the card header and the frame, never on the captured page.
172
174
  - The selected card's action bar belongs to one view: switching viewport, compare or a journey, and Fit view, clear the selection, and
173
175
  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
@@ -205,7 +207,12 @@ count, and clicking it zooms in until they part (`clusterPins` in `client/src/bo
205
207
  a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
206
208
 
207
209
  C (or the Comment tool, in the board tools at the bottom of the canvas, or Comment on the selected page's bar, which also names that page in the hint) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
208
- it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The open thread is a popover at
210
+ it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The composer, the reply box and
211
+ the edit box have a microphone where the browser has speech recognition (`client/src/board/DictationButton.jsx`): the browser's
212
+ `SpeechRecognition` writes at the caret, the rules for joining words to the text around them and the session states are pure
213
+ (`client/src/board/dictation.js`, tested in `test/comment-dictation.test.js`), and `hooks/useCommentDictation.js` drives one
214
+ recognizer at a time and releases it on posting, Esc, unmount and a hidden tab. Shapewall never receives the audio; the browser's
215
+ speech service does the transcription. The open thread is a popover at
209
216
  its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
210
217
  history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
211
218
  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
package/docs/config.md CHANGED
@@ -10,11 +10,21 @@ each board (including a board's own `viewports`, `block`, `setup` and `auth`), `
10
10
  in the serve log and the board keeps the last good config. `outputDir`, `boardUrl`, `auth`, `browser`, `liveHtml`, `agent`,
11
11
  `starterAgent`, `notifications` and `github` still need a restart (the log says so).
12
12
 
13
+ `checks` and `ci` are in neither list, so an edit to either is silently not picked up and the log says nothing about it. Restart
14
+ `serve` for a `checks` change to reach the board's **Run checks**; `ci` is read by `shapewall ci` in its own run, so a running board
15
+ never uses it anyway.
16
+
17
+ A key Shapewall does not use (a typo like `"viewport"` for `"viewports"`, or a page key such as `waitFor` set at the top level) is
18
+ ignored, and `shapewall doctor`, `capture` and `serve` warn about it with the key it most likely meant; the config still loads.
19
+ Unknown keys are refused outright only inside `capturePacing`, `checks`, `setup`, `ci`, an action's options and a page's `seo`,
20
+ plus the secret and command key lists in `agent` and `github`. A required key under the wrong case (`"baseURL"`) is an error that
21
+ says to rename it. `$schema` is allowed anywhere.
22
+
13
23
  ## Top level
14
24
 
15
25
  | Key | Type | Default | Notes |
16
26
  | --------------- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
- | `title` | string | `"Shapewall"` | Board title (single-board configs). |
27
+ | `title` | string | `"Shapewall"` | The config's title, on the board and in exports and hosted pushes. In a single-board config the board takes it too; a board with none is titled by its id. |
18
28
  | `id` | string | `"site"` | Board id for single-board configs. Lowercase letters, digits, dashes. |
19
29
  | `baseUrl` | http(s) URL | required | Where pages are loaded from. May include a base path: `http://localhost:3000/app`. |
20
30
  | `publicUrl` | http(s) URL | none | Used for "Open page" links and to rewrite links in live HTML. |
@@ -29,18 +39,19 @@ in the serve log and the board keeps the last good config. `outputDir`, `boardUr
29
39
  | `liveHtml` | boolean | `true` | `false` captures screenshots only. |
30
40
  | `versions` | 0-50 | `5` | Previous captures kept per page and viewport, for before/after. `0` keeps none. |
31
41
  | `boardUrl` | http(s) URL | the running `serve` address | Where people open the board, for links in notifications and GitHub issues. Without it, links use a running `shapewall serve` for this config, else port 4600. |
32
- | `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. See below. |
33
- | `journeys` | Journey[] | none | Named page sequences, which may fork. See [journeys.md](journeys.md). |
42
+ | `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. 1 to 8 of them. See below. |
43
+ | `journeys` | Journey[] | none | Named page sequences, which may fork. See [Journeys and links](journeys.md). |
34
44
  | `auth` | object | none | See below. |
35
45
  | `browser` | object | Playwright's Chromium | `{ "channel": "chrome" }` or `{ "executablePath": "/path/to/chrome" }` (absolute, outside the project). |
36
46
  | `groups` | string[] | order of first use | Group order on the board. |
37
47
  | `pages` | Page[] | required (or `boards`) | See below. |
38
48
  | `boards` | Board[] | none | Several boards in one file, instead of top-level `pages`. |
39
- | `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [notifications.md](notifications.md). |
49
+ | `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [Notifications](notifications.md). |
40
50
  | `github` | object | none | GitHub connect: `repo`, `boardUrl`, `labels`. See [GitHub](#github) below. |
41
51
  | `agent` | object | none | The board chat's model endpoint. See [Agent](#agent) below. |
42
- | `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [starter-agent.md](starter-agent.md). |
52
+ | `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [Sandboxed starter agent](starter-agent.md). |
43
53
  | `sitemap` | URL, file or object | none | Default source for `shapewall sitemap`. See [Sitemap import](#sitemap-import). |
54
+ | `checks` | object | none | Defaults for page checks. Only `seo` and `budgets` are accepted. See [Checks SEO](#checks-seo) and [Checks budgets](#checks-budgets) below. |
44
55
  | `ci` | object | none | Capture on pull requests: threshold, pages, ignore selectors, build and serve commands. See [CI](#ci) below. |
45
56
 
46
57
  Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
@@ -58,11 +69,11 @@ Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
58
69
  | `group` | string | Card group on the board. Defaults to `Pages`. |
59
70
  | `note` | string | Up to 200 characters, shown on the card and with its comments: "Sample data", "Signed-out state". |
60
71
  | `waitFor` | selector | Must be visible before the shot. |
61
- | `actions` | Action[] | Run in order after loading, before the shot. |
72
+ | `actions` | Action[] | Run in order after loading, before the shot. At most 30. |
62
73
  | `viewports` | string[] | A subset of the configured viewports for this page. |
63
74
  | `expectStatus` | number or number[] | An error page captured on purpose, e.g. `404` or `[404, 410]`. It is captured like any page; another status is the failure. |
64
75
  | `errorSelectors` | string[] | Optional known error-state CSS selectors for checks. At most 10 selectors of 500 characters each. Visible matches produce a reliability finding; no page-text guessing. |
65
- | `seo` | object | Optional `{ "indexable": false }` skips public SEO diagnostics even with `--seo`. Omit or use `true` for selected public pages. SEO remains off without `--seo`. |
76
+ | `seo` | object | An object whose only key is a boolean `indexable`. `{ "indexable": false }` skips public SEO diagnostics even with `--seo`; omit it for public pages. SEO is off without `--seo`. |
66
77
  | `timeout` | ms | This page's budget for loading, `waitFor` and its actions, 1000-300000. Replaces `timeouts.page` for it, and lets its `wait` and `hold` actions run that long. |
67
78
  | `localStorage` | object | Seeds for this page, on top of the board's. See [localStorage seeds](#localstorage-seeds). |
68
79
  | `frameHeight` | number or object | This page's own frame height, 240-8000: one number for all its viewports, or `{ "desktop": 900, "phone": 844 }`. The browser window stays the viewport's. See [Viewports](#viewports). |
@@ -203,8 +214,9 @@ A board for a guest-first app and a canvas game might read:
203
214
 
204
215
  ## Viewports
205
216
 
206
- `viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; any other lowercase name works
207
- too (`phone-landscape`, `kiosk`). Up to 8.
217
+ `viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; a name of your own works too
218
+ (`phone-landscape`, `kiosk`), as long as it is lowercase letters, digits and dashes, starts with a letter and is at most 32
219
+ characters: `Kiosk` and `4k` are rejected. Up to 8.
208
220
 
209
221
  | Key | Notes |
210
222
  | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
@@ -242,6 +254,7 @@ heights.
242
254
  - `"analytics"` is a built-in list: Google Analytics and Tag Manager, Plausible, Umami Cloud, Cloudflare Web Analytics and RUM, Segment,
243
255
  Hotjar, Clarity, Mixpanel, Amplitude, PostHog, Heap, FullStory, Fathom, Simple Analytics, GoatCounter, and the Meta, Bing, LinkedIn,
244
256
  X, TikTok and HubSpot pixels. A self-hosted analytics endpoint needs its own pattern (`"*/umami/*"`).
257
+ - A list holds at most 50 entries, each at most 300 characters and without whitespace.
245
258
 
246
259
  The top-level list applies to every board; a board's `block` adds to it. Blocked requests are not network failures in the capture
247
260
  warnings or in page checks. Page checks apply the same list.
@@ -254,9 +267,10 @@ warnings or in page checks. Page checks apply the same list.
254
267
  { "localStorage": { "game.trailerSeen": "1", "settings": { "music": false } } }
255
268
  ```
256
269
 
257
- Strings are stored as they are; numbers, booleans, objects and arrays as JSON. A page's keys win over its board's, a board's over the
258
- top level's. They are set on every load of that origin in the shot. Use them for flags an app checks at start (a tutorial seen, a saved
259
- setting) instead of clicking through to set them.
270
+ Strings are stored as they are; numbers, booleans, objects and arrays as JSON. Each object takes at most 50 keys, a key at most 200
271
+ characters and a stored value at most 20000. A page's keys win over its board's, a board's over the top level's. They are set on
272
+ every load of that origin in the shot. Use them for flags an app checks at start (a tutorial seen, a saved setting) instead of
273
+ clicking through to set them.
260
274
 
261
275
  ## Setup (shared state)
262
276
 
@@ -275,7 +289,7 @@ and the pages in its scope start from the browser state it left: cookies, localS
275
289
  }
276
290
  ```
277
291
 
278
- - `actions` (required): any page actions, including `viewports` guards and `optional`.
292
+ - `actions` (required): any page actions, including `viewports` guards and `optional`. At most 30, as on a page.
279
293
  - `path`: where it starts, default `/`.
280
294
  - `groups` and `pages`: its scope. Without either, every page of the board uses it; with them, only pages in those groups or with
281
295
  those ids (marketing pages keep a clean first visit).
@@ -311,8 +325,8 @@ page only.
311
325
  - With more than `--limit` pages (default 100, at most 1000), the shallowest are kept, so the top of the site wins over deep archives.
312
326
  - `--board ID` adds them to one board of a multi-board config. Nothing is captured; run `shapewall capture` next.
313
327
 
314
- To set the source once, add `sitemap` to the config (or to a board in `boards[]`). `shapewall sitemap` with no argument reads it, and
315
- `init --sitemap` records it:
328
+ To set the source once, add `sitemap` to the config, or, in a multi-board config, to each board inside `boards[]` (a top-level
329
+ `sitemap` beside `boards` is an error). `shapewall sitemap` with no argument reads it, and `init --sitemap` records it:
316
330
 
317
331
  ```json
318
332
  { "sitemap": { "source": "https://www.example.com/sitemap.xml", "limit": 50, "exclude": ["/tag/"], "group": "Site" } }
@@ -393,13 +407,13 @@ Versions are kept for the default environment only.
393
407
  `repo` (`owner/name`), `boardUrl` (where the board is served, for links from issues; default `http://127.0.0.1:4600/`), `labels` (up to
394
408
  10, put on new issues), `board` (the board that bare `shapewall:<id>` markers mean) and `apiUrl` (GitHub Enterprise Server). Top level
395
409
  only. The token comes from `SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN` and the webhook secret from `SHAPEWALL_GITHUB_WEBHOOK_SECRET`; a
396
- `token` or `webhookSecret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
397
- `SHAPEWALL_GITHUB_API_URL`. See [github.md](github.md).
410
+ `token`, `webhookSecret` or `secret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
411
+ `SHAPEWALL_GITHUB_API_URL`. See [GitHub connect](github.md).
398
412
 
399
413
  ## CI
400
414
 
401
415
  Capture on every pull request: what `shapewall ci` and the workflow from `shapewall init --ci` read. See
402
- [pull-requests.md](pull-requests.md).
416
+ [Capture on pull requests](pull-requests.md).
403
417
 
404
418
  ```json
405
419
  {
@@ -419,10 +433,10 @@ Capture on every pull request: what `shapewall ci` and the workflow from `shapew
419
433
  | `threshold` | 0-1 | `0.00001` | Share of pixels below which a shot counts as unchanged (0.00001 is 0.001%). A size change always counts. `--threshold` overrides it. |
420
434
  | `pages` | string[] | every page | Page ids to compare (an allow-list), in the config's order. |
421
435
  | `viewports` | string[] | each page's own | Viewport names to compare. |
422
- | `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50. |
436
+ | `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50, each at most 300 characters. |
423
437
  | `images` | string | `"links"` | `"links"`: the comment links to the workflow artifact. `"branch"`: thumbnails committed to a `shapewall-ci` branch and shown inline (public repositories only; needs `contents: write`). |
424
438
  | `maxPages` | 1-500 | `50` | Compare at most this many pages. `--max-pages` overrides it. |
425
- | `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (default 180000). |
439
+ | `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (1000 to 1800000, default 180000). With `start`, `serve` is required. |
426
440
 
427
441
  `start` commands are argv arrays (`["npm", "run", "build"]`): a program name found on `PATH`, then its arguments, run without a shell.
428
442
  A string is an error, and so are paths (`./build.sh`, so a config cannot name a program the repository ships), shells and launchers
@@ -438,10 +452,15 @@ from `shapewall ci capture --allow-start` inside a CI job (`GITHUB_ACTIONS` or `
438
452
  ```
439
453
 
440
454
  The board chat's endpoint: any OpenAI-compatible chat completions API. `baseUrl` and `model` are required to connect; `apiKeyEnv` (the
441
- variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [agents.md](agents.md#name-and-icon)), `vision` (default `true`), `tools` (default `true`), `maxTokens`,
442
- `temperature` and `backend` (`"openai-compatible"`) are optional. Top level only. An `apiKey`, `key` or `token` key here is an error, and `apiKeyEnv` may only name `SHAPEWALL_AGENT_*` or a `*_API_KEY`
455
+ variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [Chat with an agent](agents.md#name-and-icon)), `vision` (default `true`), `tools` (default `true`), `maxTokens`,
456
+ `temperature` (0 to 2) and `backend` are optional. `maxTokens` is a whole number from 1 to 200000. `backend` is
457
+ `"openai-compatible"` (the default) or `"acp"`, which chats with an agent CLI over ACP instead; that command comes from
458
+ `serve --agent-acp`, `SHAPEWALL_AGENT_ACP` or the host's saved agent settings, never from the config. Top level only. An `apiKey`,
459
+ `key`, `token`, `secret` or `password` key here is an error, and so is any key that could name a command to run (`command`, `cmd`,
460
+ `exec`, `acp`, `acpCommand`, `program`, `args`, `argv`, `env`), because a committed config would run it on the machine of whoever
461
+ chats from that repo. `apiKeyEnv` may only name `SHAPEWALL_AGENT_*` or a `*_API_KEY`
443
462
  variable. A key goes only to this machine, a known hosted API, or a host confirmed in `SHAPEWALL_AGENT_KEY_HOSTS`.
444
- Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [agents.md](agents.md).
463
+ Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [Chat with an agent](agents.md).
445
464
 
446
465
  How fixes run, both off by default and also on the Agents page of the Workspace Console (saved settings win over these):
447
466
  `branchMode` (`true` runs an agent CLI's fixes on a branch of their own) with `branchPrefix` (default `"shapewall/"`), see
@@ -450,6 +469,11 @@ How fixes run, both off by default and also on the Agents page of the Workspace
450
469
 
451
470
  ## Auth
452
471
 
472
+ A page that needs a sign-in usually redirects to the sign-in page, and without a login a capture is a picture of that page. Each
473
+ shot keeps the URL it landed on (`finalUrl` in `capture --json`, with `redirected: true` when it is not the page asked for), the
474
+ capture line says "landed on /login/, not /app/", the capture ends with a warning that points here, and the board marks the card
475
+ "Redirected". `shapewall checks` prints the same as a warning.
476
+
453
477
  Never put credentials in the config. Two options:
454
478
 
455
479
  **Guided manual sign-in.** Run this on the desktop that will capture the site:
@@ -482,8 +506,12 @@ record and capture locally, then use the normal capture-push workflow instead of
482
506
 
483
507
  **Login script.** An ES module whose default export signs in. It runs once per capture; its cookies and storage are reused for every page.
484
508
 
485
- Capture also refuses a `baseUrl` whose public-looking hostname resolves to a private or loopback address, so a config from someone
486
- else cannot point captures at your internal network through DNS. Use `localhost` or the address itself for your own dev server.
509
+ When the page being captured is loaded from a public host, the capture browser refuses that page's own requests to loopback, private
510
+ and internal hosts, including a public name that resolves to one, so a public page cannot make the browser fetch from this machine or
511
+ its network (a router page, a local dev server, cloud metadata). The `baseUrl` itself is never refused, and a `baseUrl` that is
512
+ already local or private -- the usual dev site -- keeps all of its requests, including those to other hosts on your network. So the
513
+ guard bounds what a public page may reach through the capture browser; it is not a check on where a config may point. Read a config
514
+ you did not write before you capture with it.
487
515
 
488
516
  A login script is code: `shapewall capture`, the board's Capture button and page checks run it on your machine, as you, with your
489
517
  environment. Capture prints a line the first time it runs one. Only use a config with `auth.loginScript` from a repo you trust, and read
@@ -78,13 +78,13 @@ Any proxy works (nginx with `auth_basic`, an SSO proxy such as oauth2-proxy, a T
78
78
  - Anyone who can reach the board can read every capture and comment and, unless you pass `--read-only` or `--no-capture`, add comments
79
79
  and start captures.
80
80
  - The board chat spends your model key, so it is off on a shared board unless you pass `--chat` (with a rate limit, a cap on answers at
81
- once and a storage quota per board). See [agents.md](agents.md#sharing-a-board).
81
+ once and a storage quota per board). See [Chat with an agent](agents.md#sharing-a-board).
82
82
  - The comment author is a free-text name, not an identity. If you need accountability, put identity in the proxy and its logs.
83
83
  - Binding to a non-loopback address (`--host 0.0.0.0`) without a proxy exposes the board unauthenticated; Shapewall prints a warning. With
84
84
  a non-loopback `--host` and no allowed host names, the Host check is off.
85
85
  - With GitHub connect, anyone who can use the board can open issues with the server's token. A GitHub webhook
86
86
  (`POST /api/github/webhook`, only when `SHAPEWALL_GITHUB_WEBHOOK_SECRET` is set) must reach the board without the proxy's login; it is
87
- protected by its signature instead. See [github.md](github.md#webhook).
87
+ protected by its signature instead. See [GitHub connect](github.md#webhook).
88
88
  - `SHAPEWALL_ALLOWED_HOSTS` (comma-separated) adds names the same way as `--allowed-host`, and keeps the Host check on for a non-loopback
89
89
  `--host`. The value `*` turns the check off on purpose, for when the proxy in front already restricts the Host.
90
90
 
@@ -137,13 +137,29 @@ stay read-only.
137
137
  The demo on shapewall.com goes further: `node scripts/demo-export.js` exports with the demo client (`npm run build:demo`, into
138
138
  `dist/demo-app`), which bundles the board and the hosted console with an in-browser backend (`client/src/demo/`). Visitors get a
139
139
  fictional workspace with people in every role, invites, share links, tokens, an audit log and a scripted agent in the chat, switch
140
- roles with View as, and keep their changes in localStorage. Nothing is sent to a server.
140
+ roles with View as, and keep their changes in localStorage. Nothing they do is sent to a server.
141
141
 
142
142
  Serve the board from its folder with the trailing slash (`/demo/`, not `/demo`): its URLs are relative. If the host sends
143
143
  `X-Frame-Options` or a `frame-ancestors` policy, let the board frame its own `data/**/*.html` files (same origin).
144
144
 
145
145
  Treat an export like the site itself: if the captured pages are not public, do not publish the export publicly either.
146
146
 
147
+ ## Error reports (opt-in)
148
+
149
+ Off by default: Shapewall has no telemetry, no usage stats and no update check, and it never sends anything to the Shapewall team. If
150
+ you want your own server's errors reported to an error tracker you run or use (Sentry, GlitchTip or anything that accepts a Sentry DSN),
151
+ set its DSN before `shapewall serve` or `shapewall hosted` starts:
152
+
153
+ ```sh
154
+ SHAPEWALL_ERROR_DSN=https://<public key>@errors.example.com/<project id>
155
+ SHAPEWALL_ERROR_ENVIRONMENT=production # optional, default production
156
+ ```
157
+
158
+ The server then reports its own unhandled errors, and the pages it serves report browser errors to the same DSN (their CSP allows that
159
+ one origin). Without the variable the error-reporting SDK is never loaded, on the server or in the browser. A report holds the error, its
160
+ stack trace, the URL path, the browser or Node version and the release. It never holds board, page or comment content, request bodies,
161
+ cookies, headers other than the user agent, query strings, user identities, local variables or console output.
162
+
147
163
  ## Updates
148
164
 
149
165
  The small version below the UI opens **About & Updates**. Updates are manual: update the same way you installed, or give the board an
package/docs/github.md CHANGED
@@ -94,7 +94,7 @@ Every delivery must carry a valid `X-Hub-Signature-256` for the secret (checked
94
94
  nothing. `ping` answers 200; `pull_request` events of the configured repo link and resolve as above; other events and other repos are
95
95
  acknowledged and ignored. The webhook needs no token: the event carries the pull request. A `--read-only` server refuses deliveries.
96
96
 
97
- The board's Host check still applies, so add the public name with `--allowed-host` (see [deployment.md](deployment.md)). If an
97
+ The board's Host check still applies, so add the public name with `--allowed-host` (see [Deployment and self-hosting](deployment.md)). If an
98
98
  authenticating proxy sits in front of the board, let `POST /api/github/webhook` through without the login; the signature is what protects
99
99
  it.
100
100