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.
- package/CHANGELOG.md +139 -0
- package/Dockerfile.agent +45 -0
- package/LICENSE +202 -0
- package/NOTICE +12 -0
- package/README.md +651 -2
- package/THIRD_PARTY.md +165 -0
- package/bin/shapewall.js +29 -0
- package/dist/agent/package-lock.json +8384 -0
- package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
- package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
- package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
- package/dist/client/assets/History-CEv6b-av.js +1 -0
- package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
- package/dist/client/assets/Management-DCfhcEUY.js +1 -0
- package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
- package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
- package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
- package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
- package/dist/client/assets/index-ByQRKVit.css +2 -0
- package/dist/client/assets/index-DweQ8Qtu.js +29 -0
- package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
- package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
- package/dist/client/assets/square-A8EnIYLR.js +1 -0
- package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
- package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
- package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
- package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
- package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
- package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
- package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
- package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
- package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
- package/dist/client/assets/ui-CLbws0rx.js +41 -0
- package/dist/client/build-info.json +1 -0
- package/dist/client/favicon.svg +7 -0
- package/dist/client/icons/apple-touch-icon.png +0 -0
- package/dist/client/icons/icon-192.png +0 -0
- package/dist/client/icons/icon-512.png +0 -0
- package/dist/client/icons/maskable-512.png +0 -0
- package/dist/client/index.html +25 -0
- package/dist/client/manifest.webmanifest +15 -0
- package/dist/client/sw.js +53 -0
- package/dist/client/theme-boot.js +27 -0
- package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
- package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
- package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
- package/dist/console/assets/console-C7uJLLOn.js +51 -0
- package/dist/console/assets/console-R8IBY3Am.css +2 -0
- package/dist/console/build-info.json +1 -0
- package/dist/console/console.html +21 -0
- package/dist/console/favicon.svg +7 -0
- package/dist/console/icons/apple-touch-icon.png +0 -0
- package/dist/console/icons/icon-192.png +0 -0
- package/dist/console/icons/icon-512.png +0 -0
- package/dist/console/icons/maskable-512.png +0 -0
- package/dist/console/manifest.webmanifest +15 -0
- package/dist/console/theme-boot.js +27 -0
- package/docs/agent-hardening.md +342 -0
- package/docs/agent-recipes.md +187 -0
- package/docs/agent-workflow.md +320 -0
- package/docs/agents.md +894 -0
- package/docs/architecture.md +242 -0
- package/docs/buzz.md +140 -0
- package/docs/capture-warnings.md +57 -0
- package/docs/config.md +489 -0
- package/docs/deployment.md +289 -0
- package/docs/design-system.md +162 -0
- package/docs/github.md +107 -0
- package/docs/hosted.md +764 -0
- package/docs/images/board-overview.png +0 -0
- package/docs/images/journeys.png +0 -0
- package/docs/images/live-comment.png +0 -0
- package/docs/images/phone-comment.png +0 -0
- package/docs/images/phone-overview.png +0 -0
- package/docs/images/variant.png +0 -0
- package/docs/interaction-audits.md +40 -0
- package/docs/journeys.md +137 -0
- package/docs/local-accounts.md +80 -0
- package/docs/notifications.md +237 -0
- package/docs/page-checks.md +69 -0
- package/docs/performance.md +174 -0
- package/docs/starter-agent.md +325 -0
- package/docs/updates.md +87 -0
- package/examples/audits/interaction.audit.json +17 -0
- package/package.json +132 -4
- package/src/accounts/avatar.js +121 -0
- package/src/accounts/local.js +464 -0
- package/src/agent/acp/command.js +204 -0
- package/src/agent/acp/detect.js +75 -0
- package/src/agent/acp/sandbox.js +160 -0
- package/src/agent/agent-health.js +75 -0
- package/src/agent/backends/acp.js +1297 -0
- package/src/agent/backends/index.js +61 -0
- package/src/agent/backends/openai.js +308 -0
- package/src/agent/composer.js +221 -0
- package/src/agent/config.js +338 -0
- package/src/agent/context.js +191 -0
- package/src/agent/control.js +122 -0
- package/src/agent/errors.js +17 -0
- package/src/agent/feedback-loop.js +137 -0
- package/src/agent/manage.js +94 -0
- package/src/agent/next-steps.js +51 -0
- package/src/agent/owner-mcp.js +38 -0
- package/src/agent/plain-text.js +52 -0
- package/src/agent/ratings-core.js +213 -0
- package/src/agent/ratings.js +100 -0
- package/src/agent/reply-text.js +67 -0
- package/src/agent/routes.js +1065 -0
- package/src/agent/run.js +326 -0
- package/src/agent/settings-routes.js +704 -0
- package/src/agent/showable.js +23 -0
- package/src/agent/starter/approvals.js +181 -0
- package/src/agent/starter/build-image.js +90 -0
- package/src/agent/starter/cli.js +163 -0
- package/src/agent/starter/disk.js +53 -0
- package/src/agent/starter/doctor.js +180 -0
- package/src/agent/starter/egress-proxy.js +351 -0
- package/src/agent/starter/gate.js +90 -0
- package/src/agent/starter/loop.js +114 -0
- package/src/agent/starter/model-relay.js +289 -0
- package/src/agent/starter/pause.js +14 -0
- package/src/agent/starter/probe.js +272 -0
- package/src/agent/starter/prompt.js +41 -0
- package/src/agent/starter/push-guard.js +146 -0
- package/src/agent/starter/rpc.js +164 -0
- package/src/agent/starter/runtime.js +287 -0
- package/src/agent/starter/sandbox-main.js +121 -0
- package/src/agent/starter/settings.js +290 -0
- package/src/agent/starter/source.js +69 -0
- package/src/agent/starter/supervisor.js +755 -0
- package/src/agent/starter/sweep.js +46 -0
- package/src/agent/starter/tools.js +524 -0
- package/src/agent/starter/watch.js +84 -0
- package/src/agent/starter/worktree.js +409 -0
- package/src/agent/text-diff.js +210 -0
- package/src/agent/thread-history.js +223 -0
- package/src/agent/threads.js +399 -0
- package/src/agent/tools.js +200 -0
- package/src/agent/turn-changes.js +424 -0
- package/src/agent/undo-state.js +26 -0
- package/src/agent/user-settings.js +308 -0
- package/src/auth/record.js +375 -0
- package/src/broken-links.js +164 -0
- package/src/buzz/client.js +75 -0
- package/src/buzz/config.js +151 -0
- package/src/buzz/environment.js +13 -0
- package/src/buzz/gateway.js +192 -0
- package/src/buzz/routes.js +61 -0
- package/src/buzz/signer-child.js +205 -0
- package/src/buzz/store.js +89 -0
- package/src/buzz/transport.js +60 -0
- package/src/buzz/verify.js +140 -0
- package/src/capture/actions.js +159 -0
- package/src/capture/capture.js +776 -0
- package/src/capture/dom-names.js +189 -0
- package/src/capture/element-map.js +509 -0
- package/src/capture/live.js +827 -0
- package/src/capture/media-scheme.js +317 -0
- package/src/capture/network-summary.js +86 -0
- package/src/capture/pacing.js +34 -0
- package/src/capture/requests.js +167 -0
- package/src/capture/sanitize.js +752 -0
- package/src/checks/accessibility.js +134 -0
- package/src/checks/budgets.js +58 -0
- package/src/checks/cli.js +55 -0
- package/src/checks/comparison.js +113 -0
- package/src/checks/environments.js +32 -0
- package/src/checks/flow-config.js +82 -0
- package/src/checks/flow-origin.js +53 -0
- package/src/checks/flows.js +398 -0
- package/src/checks/lighthouse-auth.js +145 -0
- package/src/checks/lighthouse-findings.js +130 -0
- package/src/checks/lighthouse.js +395 -0
- package/src/checks/robots.js +85 -0
- package/src/checks/routes.js +52 -0
- package/src/checks/run-control.js +259 -0
- package/src/checks/runner.js +724 -0
- package/src/checks/schema.js +133 -0
- package/src/checks/seo-analysis.js +443 -0
- package/src/checks/seo-probe.js +190 -0
- package/src/checks/seo-snapshot.js +99 -0
- package/src/checks/store.js +214 -0
- package/src/checks/transport.js +47 -0
- package/src/cli/args.js +319 -0
- package/src/cli/capture.js +79 -0
- package/src/cli/commands.js +92 -0
- package/src/cli/comments.js +84 -0
- package/src/cli/help.js +243 -0
- package/src/cli/init.js +214 -0
- package/src/cli/misc.js +64 -0
- package/src/cli/notify.js +87 -0
- package/src/cli/open.js +22 -0
- package/src/cli/serve.js +274 -0
- package/src/cli/variant.js +82 -0
- package/src/cli/watch.js +70 -0
- package/src/cli.js +130 -0
- package/src/comment-fields.js +76 -0
- package/src/comments-cli.js +208 -0
- package/src/config-reload.js +100 -0
- package/src/config.js +1061 -0
- package/src/devices-cli.js +21 -0
- package/src/diff.js +95 -0
- package/src/discover.js +284 -0
- package/src/doctor.js +295 -0
- package/src/event-log.js +268 -0
- package/src/events-cli.js +102 -0
- package/src/events.js +113 -0
- package/src/export.js +119 -0
- package/src/feedback.js +246 -0
- package/src/github.js +551 -0
- package/src/hosted/LICENSE.md +105 -0
- package/src/hosted/access-cli.js +78 -0
- package/src/hosted/admin.js +682 -0
- package/src/hosted/agent-approvals.js +163 -0
- package/src/hosted/agent-policy.js +189 -0
- package/src/hosted/app.js +510 -0
- package/src/hosted/auth-routes.js +540 -0
- package/src/hosted/auth.js +536 -0
- package/src/hosted/backup.js +483 -0
- package/src/hosted/board-context.js +35 -0
- package/src/hosted/board-routes.js +486 -0
- package/src/hosted/board-view.js +94 -0
- package/src/hosted/clean-worker.js +24 -0
- package/src/hosted/cleaner.js +89 -0
- package/src/hosted/comments.js +355 -0
- package/src/hosted/console-routes.js +401 -0
- package/src/hosted/cookies.js +18 -0
- package/src/hosted/crypto.js +80 -0
- package/src/hosted/db.js +496 -0
- package/src/hosted/device-routes.js +175 -0
- package/src/hosted/device.js +233 -0
- package/src/hosted/events.js +63 -0
- package/src/hosted/guards.js +172 -0
- package/src/hosted/guest-view.js +65 -0
- package/src/hosted/http.js +39 -0
- package/src/hosted/import.js +300 -0
- package/src/hosted/mail.js +73 -0
- package/src/hosted/mcp-http.js +71 -0
- package/src/hosted/membership.js +114 -0
- package/src/hosted/operator.js +478 -0
- package/src/hosted/ops-cli.js +345 -0
- package/src/hosted/pages.js +146 -0
- package/src/hosted/permissions.js +113 -0
- package/src/hosted/presence.js +372 -0
- package/src/hosted/projects.js +124 -0
- package/src/hosted/public.js +109 -0
- package/src/hosted/push.js +622 -0
- package/src/hosted/quotas.js +115 -0
- package/src/hosted/ratelimit.js +96 -0
- package/src/hosted/rebind.js +316 -0
- package/src/hosted/retention.js +128 -0
- package/src/hosted/server.js +260 -0
- package/src/hosted/setup-link.js +64 -0
- package/src/hosted/setup.js +323 -0
- package/src/hosted/shares.js +444 -0
- package/src/hosted/tailscale.js +204 -0
- package/src/hosted/tenancy.js +301 -0
- package/src/hosted/token-api.js +455 -0
- package/src/hosted/token-events.js +60 -0
- package/src/hosted/tokens.js +57 -0
- package/src/hosted/turnstile.js +49 -0
- package/src/hosted/usercontent.js +154 -0
- package/src/hosted/zip.js +155 -0
- package/src/invocation.js +58 -0
- package/src/journey-paths.js +282 -0
- package/src/journeys.js +189 -0
- package/src/links.js +106 -0
- package/src/local-projects.js +182 -0
- package/src/lock.js +193 -0
- package/src/mcp.js +417 -0
- package/src/mentions.js +151 -0
- package/src/net.js +15 -0
- package/src/notify/config.js +275 -0
- package/src/notify/index.js +301 -0
- package/src/notify/lease.js +73 -0
- package/src/notify/messages.js +212 -0
- package/src/notify/run.js +174 -0
- package/src/pixeldiff.js +49 -0
- package/src/png.js +143 -0
- package/src/reactions.js +111 -0
- package/src/remote/cli.js +133 -0
- package/src/remote/credentials.js +62 -0
- package/src/remote/ids.js +12 -0
- package/src/remote/login.js +155 -0
- package/src/remote/remote-mcp.js +237 -0
- package/src/remote/remote-watch.js +291 -0
- package/src/remote/remote.js +313 -0
- package/src/remote/share-state.js +78 -0
- package/src/remote/share.js +369 -0
- package/src/remote/terminal.js +13 -0
- package/src/serve-state.js +64 -0
- package/src/server/app.js +824 -0
- package/src/server/devices.js +186 -0
- package/src/server/local-console.js +28 -0
- package/src/server/local-user.js +59 -0
- package/src/server/pairing-routes.js +159 -0
- package/src/server/share-routes.js +89 -0
- package/src/server/tailscale.js +97 -0
- package/src/sitemap.js +431 -0
- package/src/store.js +983 -0
- package/src/tokens.js +11 -0
- package/src/update/routes.js +245 -0
- package/src/watch.js +403 -0
- package/src/which.js +58 -0
package/README.md
CHANGED
|
@@ -1,3 +1,652 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Shapewall
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/shapewall)
|
|
4
|
+
[](https://github.com/danbaruch/shapewall/actions/workflows/ci.yml)
|
|
5
|
+
[](#license)
|
|
6
|
+
|
|
7
|
+
**Every page of your site on one zoomable wall, with comments pinned to elements that your coding agent can act on.**
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
With your dev server running, in its project folder:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npx shapewall doctor --install-browser # once: downloads the Chromium that captures use
|
|
15
|
+
npx shapewall init --base-url http://localhost:3000 # your dev server: finds its pages
|
|
16
|
+
npx shapewall capture # every page, desktop and phone
|
|
17
|
+
npx shapewall serve --open # the board, in your browser
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**[Live demo](https://shapewall.com/demo/)** (no install: a board of a fictional product, 26 pages, comments in every state; comments
|
|
21
|
+
you add stay in your browser) · **[Docs](https://shapewall.com/docs)** · [Quickstart details](#quickstart)
|
|
22
|
+
|
|
23
|
+
Shapewall captures each page at desktop and phone width, lays them out on a canvas grouped by section, and lets you pin comments to the
|
|
24
|
+
exact element that needs work. Zoom out to see the whole product at once; zoom in and the screenshot turns into the real, captured
|
|
25
|
+
HTML, with responsive CSS intact and every script stripped. Comments come out as structured JSON, so a coding agent can read the
|
|
26
|
+
feedback, fix the code, and you recapture to check.
|
|
27
|
+
|
|
28
|
+
- **Whole-site view.** Desktop, tablet and phone captures side by side, grouped (Marketing, App, ...), with per-page notes like
|
|
29
|
+
"signed-out state". Add your own viewports, such as a landscape phone.
|
|
30
|
+
- **Screenshots far out, live HTML up close.** Zoomed out you see light thumbnails; zoomed in (or with "Open live") a frame swaps to a
|
|
31
|
+
self-contained HTML snapshot you can select text in. It runs no JavaScript: three independent locks keep it inert.
|
|
32
|
+
- **Comments that stay put.** On live HTML a comment is anchored to the element under your click (a CSS selector plus its text), so after
|
|
33
|
+
the next capture the pin follows the button, not the old pixel. Resolve, reopen, edit, reply in a thread, and **@mention** people or
|
|
34
|
+
`@agent`. Search the comments and narrow them by state (agent working, needs a person, reopened, ...) or by who is mentioned.
|
|
35
|
+
- **Variants.** Put another version of a page (a branch preview, a redesign) right beside the original.
|
|
36
|
+
- **Journeys.** Name the path people take ("Sign up": home, pricing, sign in, dashboard) in the config or by clicking pages on the board,
|
|
37
|
+
then step through it with arrows between the steps. A journey can fork ("link works" or "link expired") and rejoin; pick a branch as
|
|
38
|
+
you step through. **Links** draws the links each capture found between your pages.
|
|
39
|
+
- **Before and after.** Every recapture keeps the previous shot, so a resolved comment shows before and after near its pin, with a link
|
|
40
|
+
to the pull request or commit that fixed it.
|
|
41
|
+
- **Page history.** Every page keeps its earlier captures: open a page's history to see an earlier capture beside the current one,
|
|
42
|
+
with the changed pixels in red and the comments that were made on each.
|
|
43
|
+
- **Pages from your sitemap.** `shapewall sitemap https://www.example.com/sitemap.xml` fills the page list from a sitemap (or a sitemap
|
|
44
|
+
index), grouped by path, without repeats.
|
|
45
|
+
- **Compare environments.** Capture staging and production, then see each page in both with the changed pixels in red, and filter to the
|
|
46
|
+
pages that changed.
|
|
47
|
+
- **Installs as an app.** The board is a PWA: add it to a phone's home screen and it opens full screen.
|
|
48
|
+
- **Made for the agent loop.** `shapewall comments --json` hands any coding agent the page, viewport, selector, element text, position and
|
|
49
|
+
screenshot path for each open comment. `shapewall watch` dispatches new comments to your agent by itself, and `shapewall mcp` gives it
|
|
50
|
+
tools. It fixes, recaptures, replies on the comment; the pins tell you if it worked.
|
|
51
|
+
- **Works on a phone.** 44 px touch targets, a bottom sheet for comments, and Back closes the topmost panel instead of leaving the board.
|
|
52
|
+
- **Small and local.** Node 22, Playwright, Express, React Flow. Data is plain JSON files in `.shapewall/`. No account, no cloud.
|
|
53
|
+
- **A team server when you want one.** `shapewall hosted` adds passkey accounts, workspaces with roles, share links and live presence
|
|
54
|
+
on a server you run. [Multiplayer (beta)](#multiplayer-on-your-own-server).
|
|
55
|
+
- **Switch local projects.** Serve each project on its own port; the site dropdown lists them together while keeping every project's
|
|
56
|
+
agent and files separate. [Several local projects](docs/deployment.md#several-local-projects).
|
|
57
|
+
|
|
58
|
+
| Live HTML with an element-anchored comment | On a phone |
|
|
59
|
+
| ---------------------------------------------------------------- | ------------------------------------------------------ |
|
|
60
|
+
|  |  |
|
|
61
|
+
|
|
62
|
+

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

|
|
592
|
+
|
|
593
|
+
## Notifications
|
|
594
|
+
|
|
595
|
+
Comment events (created, replied, mentioned, agent status changed, resolved, reopened) can go to a signed webhook, Slack, Discord or
|
|
596
|
+
email through Resend, each message with a link to the comment on the board. Mentions route per person (`@robin` pings Robin's Slack id or
|
|
597
|
+
emails Robin). Secrets live only in environment variables; the config names them. Sending never blocks the board, and failed sends
|
|
598
|
+
retry with backoff. The quickest start is one variable:
|
|
599
|
+
|
|
600
|
+
```sh
|
|
601
|
+
SHAPEWALL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... shapewall serve
|
|
602
|
+
shapewall notify test slack
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
Everything else: [docs/notifications.md](docs/notifications.md).
|
|
606
|
+
|
|
607
|
+
## Exposing the board
|
|
608
|
+
|
|
609
|
+
`shapewall serve` has no login and listens on 127.0.0.1. It refuses requests whose `Host` header is not local (DNS rebinding) and accepts
|
|
610
|
+
writes only as JSON (no cross-site form posts). For your own other devices, use `shapewall serve --tailscale` (or `--lan`) and pair
|
|
611
|
+
each device. For a team, run [`shapewall hosted`](#multiplayer-on-your-own-server), or use `shapewall export` for a read-only copy. See
|
|
612
|
+
[docs/deployment.md](docs/deployment.md).
|
|
613
|
+
|
|
614
|
+
## FAQ
|
|
615
|
+
|
|
616
|
+
**Does it work with single-page apps?** Yes. The capture snapshots the rendered DOM after your `waitFor` and `actions`, so client-rendered
|
|
617
|
+
content is in both the screenshot and the live HTML. Scripts are removed, so the live HTML is a frozen state, not a running app.
|
|
618
|
+
|
|
619
|
+
**Why fixed-height frames instead of full-page screenshots?** Comparable cards on one canvas, predictable memory, and the top of a page is
|
|
620
|
+
what reviewers look at first. Make `height` larger for long pages.
|
|
621
|
+
|
|
622
|
+
**My site needs a login.** Run `shapewall auth record`, sign in by hand in the fresh browser it opens, then press Enter to save. It
|
|
623
|
+
prints the `auth.storageState` line to add to your config. A `loginScript` is the alternative for automation. Use a test account, and never commit credentials. See [guided sign-in](docs/config.md#auth).
|
|
624
|
+
|
|
625
|
+
**Are captured pages safe to share?** Live HTML drops hidden inputs, password values, scripts and data attributes that could carry tokens,
|
|
626
|
+
and links to private hosts are removed. Screenshots show exactly what the page showed, so capture with test data.
|
|
627
|
+
|
|
628
|
+
**Can I use Firefox or WebKit?** No. Captures use Chromium, and thumbnails use a Chromium DevTools call.
|
|
629
|
+
|
|
630
|
+
**Does it send anything anywhere?** Not by itself: there is no account and no telemetry. Captures load your pages; an agent endpoint,
|
|
631
|
+
notifications, GitHub connect or a team server you set up receive what you send them.
|
|
632
|
+
|
|
633
|
+
**Where is my data?** In `outputDir` (default `.shapewall/`): PNGs, HTML snapshots, `manifest.json`, `comments.json`, `variants.json`,
|
|
634
|
+
`journeys.json`, previous captures in `versions/`, other environments in `envs/`, cached diffs in `diffs/` and `agent/` (what
|
|
635
|
+
`shapewall watch` handed to your command, with its log). Delete the folder to start over.
|
|
636
|
+
|
|
637
|
+
## Contributing
|
|
638
|
+
|
|
639
|
+
Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Security
|
|
640
|
+
reports: [SECURITY.md](SECURITY.md).
|
|
641
|
+
|
|
642
|
+
## License
|
|
643
|
+
|
|
644
|
+
Shapewall has two licenses:
|
|
645
|
+
|
|
646
|
+
- **Apache 2.0** ([LICENSE](LICENSE)) for everything except `src/hosted`: the CLI, capture, the board, MCP, the agents and the clients
|
|
647
|
+
of the team server (`push`, `share`, `--remote`, in `src/remote`). Open source.
|
|
648
|
+
- **Functional Source License 1.1, Apache 2.0 future license** ([src/hosted/LICENSE.md](src/hosted/LICENSE.md)) for the self-hosted
|
|
649
|
+
team server in `src/hosted`. Source-available: you can read, modify and run it for yourself or your company, but not offer it as a
|
|
650
|
+
competing commercial service. Each release becomes Apache 2.0 two years later.
|
|
651
|
+
|
|
652
|
+
Copyright Dan Baruch and Shapewall contributors. See [NOTICE](NOTICE) and [THIRD_PARTY.md](THIRD_PARTY.md).
|