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/docs/config.md
ADDED
|
@@ -0,0 +1,489 @@
|
|
|
1
|
+
# Config reference
|
|
2
|
+
|
|
3
|
+
Shapewall reads `shapewall.config.json` from the current folder (or `--config FILE`, or `$SHAPEWALL_CONFIG`). Relative paths in it are
|
|
4
|
+
resolved against the file's folder. `shapewall capture` and `shapewall serve` report every problem at once, with the JSON path of each bad
|
|
5
|
+
value.
|
|
6
|
+
|
|
7
|
+
A running `shapewall serve` watches the file and applies edits to `title`, the pages, groups, journeys, environments and sitemap of
|
|
8
|
+
each board (including a board's own `viewports`, `block`, `setup` and `auth`), `viewports`, `concurrency`, `capturePacing`, `timeouts`,
|
|
9
|
+
`block`, `reducedMotion` and `versions` on the next refresh of the board. An edit with a problem is reported
|
|
10
|
+
in the serve log and the board keeps the last good config. `outputDir`, `boardUrl`, `auth`, `browser`, `liveHtml`, `agent`,
|
|
11
|
+
`starterAgent`, `notifications` and `github` still need a restart (the log says so).
|
|
12
|
+
|
|
13
|
+
## Top level
|
|
14
|
+
|
|
15
|
+
| Key | Type | Default | Notes |
|
|
16
|
+
| --------------- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
17
|
+
| `title` | string | `"Shapewall"` | Board title (single-board configs). |
|
|
18
|
+
| `id` | string | `"site"` | Board id for single-board configs. Lowercase letters, digits, dashes. |
|
|
19
|
+
| `baseUrl` | http(s) URL | required | Where pages are loaded from. May include a base path: `http://localhost:3000/app`. |
|
|
20
|
+
| `publicUrl` | http(s) URL | none | Used for "Open page" links and to rewrite links in live HTML. |
|
|
21
|
+
| `outputDir` | path | `.shapewall` | Captures, comments, variants and run state. |
|
|
22
|
+
| `concurrency` | 1-8 | `2` | Pages captured in parallel. Each one is a browser context. |
|
|
23
|
+
| `viewports` | object | desktop 1440x2200, phone 390x1800 | Keyed by name: `desktop`, `tablet`, `phone` or your own (`phone-landscape`). Width 240-3840, height 240-8000. See [Viewports](#viewports). |
|
|
24
|
+
| `timeouts` | `{ page, settle }` ms | `{ "page": 45000, "settle": 8000 }` | `page` bounds navigation, `waitFor` and actions (a page's own `timeout` replaces it); `settle` bounds the network-idle wait. |
|
|
25
|
+
| `block` | string[] | none | Requests to abort during capture: URL patterns, or `"analytics"`. Boards add their own. See [Blocking requests](#blocking-requests). |
|
|
26
|
+
| `reducedMotion` | string or boolean | `"reduce"` | `prefers-reduced-motion` in the capture browser. `"no-preference"` (or `false`) captures motion as players see it. A board may set its own. |
|
|
27
|
+
| `localStorage` | object | none | Keys and values set before every page's own scripts run, on its origin. Boards and pages add their own. See [localStorage seeds](#localstorage-seeds). |
|
|
28
|
+
| `setup` | Action[] or object | none | Single-board configs: actions run once per viewport, whose state the pages reuse. See [Setup](#setup-shared-state). |
|
|
29
|
+
| `liveHtml` | boolean | `true` | `false` captures screenshots only. |
|
|
30
|
+
| `versions` | 0-50 | `5` | Previous captures kept per page and viewport, for before/after. `0` keeps none. |
|
|
31
|
+
| `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). |
|
|
34
|
+
| `auth` | object | none | See below. |
|
|
35
|
+
| `browser` | object | Playwright's Chromium | `{ "channel": "chrome" }` or `{ "executablePath": "/path/to/chrome" }` (absolute, outside the project). |
|
|
36
|
+
| `groups` | string[] | order of first use | Group order on the board. |
|
|
37
|
+
| `pages` | Page[] | required (or `boards`) | See below. |
|
|
38
|
+
| `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). |
|
|
40
|
+
| `github` | object | none | GitHub connect: `repo`, `boardUrl`, `labels`. See [GitHub](#github) below. |
|
|
41
|
+
| `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). |
|
|
43
|
+
| `sitemap` | URL, file or object | none | Default source for `shapewall sitemap`. See [Sitemap import](#sitemap-import). |
|
|
44
|
+
|
|
45
|
+
Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
|
|
46
|
+
|
|
47
|
+
`capturePacing` controls bounded spacing between foreground capture starts and a cooldown after observed HTTP 429s. Defaults are
|
|
48
|
+
`{ "intervalMs": 250, "rateLimitCooldownMs": 1000 }`; see [capture warnings and pacing](capture-warnings.md).
|
|
49
|
+
|
|
50
|
+
## Page
|
|
51
|
+
|
|
52
|
+
| Key | Type | Notes |
|
|
53
|
+
| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `id` | string | Unique on the board. Lowercase letters, digits, dashes, up to 64. Used in file names and `--only`. |
|
|
55
|
+
| `path` | string | Starts with `/`. May carry a query string (`/search?q=shoes`). Joined to `baseUrl` without double `/`. |
|
|
56
|
+
| `title` | string | Shown on the card. Defaults to the id. |
|
|
57
|
+
| `group` | string | Card group on the board. Defaults to `Pages`. |
|
|
58
|
+
| `note` | string | Up to 200 characters, shown on the card and with its comments: "Sample data", "Signed-out state". |
|
|
59
|
+
| `waitFor` | selector | Must be visible before the shot. |
|
|
60
|
+
| `actions` | Action[] | Run in order after loading, before the shot. |
|
|
61
|
+
| `viewports` | string[] | A subset of the configured viewports for this page. |
|
|
62
|
+
| `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. |
|
|
63
|
+
| `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. |
|
|
64
|
+
| `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`. |
|
|
65
|
+
| `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. |
|
|
66
|
+
| `localStorage` | object | Seeds for this page, on top of the board's. See [localStorage seeds](#localstorage-seeds). |
|
|
67
|
+
| `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). |
|
|
68
|
+
|
|
69
|
+
A page with `viewports` gets only those frames on the board: a desktop-only page has a narrower card with a "Desktop only" tag, the
|
|
70
|
+
cards after it close up, and in Phone mode it shows its desktop frame rather than an empty card.
|
|
71
|
+
|
|
72
|
+
### Actions
|
|
73
|
+
|
|
74
|
+
Each action is an object with exactly one action key:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
[
|
|
78
|
+
{ "click": "button[aria-label='Open menu']" },
|
|
79
|
+
{ "fill": ["input[name=q]", "running shoes"] },
|
|
80
|
+
{ "press": "Enter" },
|
|
81
|
+
{ "hover": ".product-card:first-child" },
|
|
82
|
+
{ "waitFor": ".results" },
|
|
83
|
+
{ "wait": 500 },
|
|
84
|
+
{ "scrollTo": 800 }
|
|
85
|
+
]
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
For apps and games there are more:
|
|
89
|
+
|
|
90
|
+
| Action | Does |
|
|
91
|
+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| `{ "tap": "selector" }` | A touch tap. Needs a touch viewport (`tablet`, `phone`, `phone-*`, or `"touch": true`). |
|
|
93
|
+
| `{ "mouse": [x, y] }` | A mouse click at a point of the viewport, on whatever is on top there (a canvas game's own buttons). |
|
|
94
|
+
| `{ "hold": ["ArrowLeft", 800] }` | Holds a key down for that many milliseconds, then lets go (steer a game). |
|
|
95
|
+
| `{ "keyDown": "Shift" }`, `{ "keyUp": … }` | Presses or releases a key and leaves it there, for combinations. |
|
|
96
|
+
| `{ "waitForFunction": "expression" }` | Waits until a JavaScript expression is truthy in the page, polled every 100 ms: `"window.game?.ready === true"`. See below. |
|
|
97
|
+
|
|
98
|
+
Any action may also carry:
|
|
99
|
+
|
|
100
|
+
- `"optional": true`: if it fails (the element is not there), skip it and go on. It gives up after 5 seconds unless it sets its own
|
|
101
|
+
`timeout`. For a dialog that only shows on some layouts: `{ "click": "[aria-label='Skip quick start']", "optional": true }`.
|
|
102
|
+
- `"viewports": ["phone"]`: run it only on these viewports, so one page can take a different path per device:
|
|
103
|
+
`{ "click": "text=Computer", "viewports": ["desktop"] }, { "click": "text=Touch", "viewports": ["phone-landscape"] }`.
|
|
104
|
+
- `"timeout"`: milliseconds for this action (100-300000) instead of the page's.
|
|
105
|
+
- `"force": true` (`click`, `tap`, `hover`, `fill`): skip the checks that the element is visible, still and not covered. A forced
|
|
106
|
+
`click` delivers its pointer, mouse and click events to the element itself, so a canvas or overlay on top cannot swallow it.
|
|
107
|
+
|
|
108
|
+
`wait` and `hold` last at most 30 seconds, or up to the page's timeout when that is longer (set `timeout` on the page for a long
|
|
109
|
+
game state).
|
|
110
|
+
|
|
111
|
+
The frame is the `height` pixels from where the page is scrolled to: `scrollTo`, or an in-page link that scrolls, changes what is in it.
|
|
112
|
+
|
|
113
|
+
`waitForFunction` runs your expression inside the captured page, which is how a canvas or WebGL game says it is ready (`networkidle`
|
|
114
|
+
means nothing to a render loop). Only whether it became truthy comes back; its value, and the text of any error it throws, never leave
|
|
115
|
+
the page. Write it for your own app; the page can see it, like any action.
|
|
116
|
+
|
|
117
|
+
**When a step fails**, the shot fails with the step's number (from 1), the action and its selector, and why:
|
|
118
|
+
`action 3 (click "button:has-text('Play')") timed out after 45 s`. A click on an element under another one adds "another element covers
|
|
119
|
+
it" with what to try. A shot that runs out of time says where it was: `timed out after 73 s (during action 5 (waitFor "#hud"))`. The
|
|
120
|
+
CLI prints these and the board shows them on the card.
|
|
121
|
+
|
|
122
|
+
### Capturing an app, not just its landing page
|
|
123
|
+
|
|
124
|
+
`shapewall init`, a sitemap and the link map only find pages a visitor can reach by following links. In an app or a game, most screens
|
|
125
|
+
sit behind a button: **Start**, **Continue as guest**, **Play**, a sign-in, a mode picker. A board built from links alone shows the
|
|
126
|
+
marketing site and stops at the door. For anything with an app inside, add the app screens by hand:
|
|
127
|
+
|
|
128
|
+
1. **Walk the app first.** Open it in a clean browser and list what a reviewer would want to see: the entry (guest or demo), every main
|
|
129
|
+
view or tab, settings, key dialogs and menus, empty states, and the end of a flow (results, confirmation). For a game: the menu, mode
|
|
130
|
+
select, a few seconds into play, the pause menu, and the results screen if it is reachable without long play.
|
|
131
|
+
2. **Give app screens screen-sized frames.** A tall frame (1440x2200) stretches an app shell and leaves dialogs floating in empty
|
|
132
|
+
space, and a game renders a huge scene slowly. Keep the tall viewports for the marketing and guide pages, and give each app or game
|
|
133
|
+
page its own [`frameHeight`](#viewports) (`{ "desktop": 900, "tablet": 1180, "phone": 844 }`), so one board mixes long pages and
|
|
134
|
+
screen-sized app cards. Set the viewport's `layoutHeight` to the screen too if the app should lay out in a screen-sized window.
|
|
135
|
+
Add a `phone-landscape` viewport (`844x390`) for a landscape-only game.
|
|
136
|
+
3. **Do the entry once: `setup`.** A guest entry, a dismissed tutorial or a picked starter kit go in the board's [`setup`](#setup-shared-state),
|
|
137
|
+
scoped to the app's groups. It runs once per viewport and every page in scope starts from the state it left (cookies, localStorage),
|
|
138
|
+
still loading its own `path`. Flags an app reads at start (trailer seen, tutorial done) can be [seeded](#localstorage-seeds) instead.
|
|
139
|
+
Leave pages that change server state (start a session, finish a level) out of the scope so each gets its own fresh entry.
|
|
140
|
+
4. **One page per screen, with the clicks from there.** Prefer selectors by role, text or `aria-label`
|
|
141
|
+
(`"button:has-text('Play')"`) over generated class names, and end with a `waitFor` on something only that screen shows, so a click
|
|
142
|
+
that missed fails the shot instead of capturing the wrong screen. One page can differ per device (`"viewports"` on an action) and
|
|
143
|
+
dismiss something that may or may not show (`"optional": true`). For a canvas game: `"force": true` clicks the button under the
|
|
144
|
+
canvas, `mouse` clicks the canvas itself, `hold` steers, and `waitForFunction` waits for the game's own ready flag.
|
|
145
|
+
5. **Group and connect them.** Put app screens in their own `group` (`"App"`, `"Game"`), keep the marketing pages, and add a journey
|
|
146
|
+
for the first session (`landing -> guest entry -> main view -> first action`).
|
|
147
|
+
6. **Use guest or demo paths, or recorded sign-in.** Never put credentials in actions. For signed-in screens use
|
|
148
|
+
[`shapewall auth record`](#auth) (a board can have its own `auth`). Stop before anything that writes real data (payments, invites,
|
|
149
|
+
emails); capture the dialog, not the result. Add `"block": ["analytics"]` so captures do not count as visits.
|
|
150
|
+
7. **Mind the time.** Software-rendered WebGL slows down as the frame grows. Give a long game state its own page `timeout` (a race to
|
|
151
|
+
the finish) instead of raising `timeouts.page` for everything, and `"reducedMotion": "no-preference"` if the game changes with it.
|
|
152
|
+
8. **Look at every shot** after the first capture. A landing page, spinner or error where an app screen should be means an action needs
|
|
153
|
+
a better selector or a `waitFor`. A failed shot names the step that stalled.
|
|
154
|
+
|
|
155
|
+
A board for a guest-first app and a canvas game might read:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"id": "app",
|
|
160
|
+
"baseUrl": "https://app.example.com",
|
|
161
|
+
"viewports": {
|
|
162
|
+
"desktop": { "width": 1440, "height": 2200 },
|
|
163
|
+
"tablet": { "width": 820, "height": 1180 },
|
|
164
|
+
"phone": { "width": 390, "height": 1800 },
|
|
165
|
+
"phone-landscape": { "width": 844, "height": 390 }
|
|
166
|
+
},
|
|
167
|
+
"block": ["analytics", "*/umami/*"],
|
|
168
|
+
"setup": {
|
|
169
|
+
"path": "/",
|
|
170
|
+
"actions": [{ "click": "button:has-text('Continue as guest')" }, { "waitFor": "nav[aria-label='Main']" }],
|
|
171
|
+
"groups": ["App"]
|
|
172
|
+
},
|
|
173
|
+
"pages": [
|
|
174
|
+
{ "id": "home", "path": "/", "group": "Site", "viewports": ["desktop", "tablet", "phone"] },
|
|
175
|
+
{
|
|
176
|
+
"id": "today",
|
|
177
|
+
"path": "/today",
|
|
178
|
+
"group": "App",
|
|
179
|
+
"frameHeight": { "desktop": 900, "phone": 844 },
|
|
180
|
+
"waitFor": "h1:has-text('Today')"
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
"id": "level-1",
|
|
184
|
+
"path": "/play",
|
|
185
|
+
"group": "Game",
|
|
186
|
+
"viewports": ["desktop", "phone-landscape"],
|
|
187
|
+
"frameHeight": { "desktop": 900 },
|
|
188
|
+
"localStorage": { "tutorialSeen": "1" },
|
|
189
|
+
"timeout": 120000,
|
|
190
|
+
"actions": [
|
|
191
|
+
{ "click": "text=Keyboard", "viewports": ["desktop"] },
|
|
192
|
+
{ "click": "text=Touch", "viewports": ["phone-landscape"] },
|
|
193
|
+
{ "click": "[aria-label='Skip tips']", "optional": true },
|
|
194
|
+
{ "click": "#start", "force": true },
|
|
195
|
+
{ "waitForFunction": "window.game?.state === 'playing'" },
|
|
196
|
+
{ "hold": ["ArrowRight", 1500] }
|
|
197
|
+
]
|
|
198
|
+
}
|
|
199
|
+
]
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Viewports
|
|
204
|
+
|
|
205
|
+
`viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; any other lowercase name works
|
|
206
|
+
too (`phone-landscape`, `kiosk`). Up to 8.
|
|
207
|
+
|
|
208
|
+
| Key | Notes |
|
|
209
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
210
|
+
| `width` | 240-3840 CSS pixels. |
|
|
211
|
+
| `height` | 240-8000. The frame on the board, and by default the browser window too. |
|
|
212
|
+
| `layoutHeight` | Optional browser window height when it should differ from the frame: lay out at 1440x900 but shoot 2200 px from the top. |
|
|
213
|
+
| `mobile` | Mobile emulation (`isMobile`) and a mobile user agent. |
|
|
214
|
+
| `touch` | Touch events. |
|
|
215
|
+
| `userAgent` | A user agent string of your own. |
|
|
216
|
+
|
|
217
|
+
A name decides the device unless the flags say otherwise: `phone` and `phone-*` are a phone (mobile, touch, iPhone user agent),
|
|
218
|
+
`tablet` and `tablet-*` a tablet (iPad user agent), anything else a desktop. `"mobile": true` on another name picks a phone or tablet
|
|
219
|
+
user agent by size. The board draws a custom viewport at its device's scale and gives it a toggle ("Phone landscape").
|
|
220
|
+
|
|
221
|
+
A board's `viewports` replace the top-level ones for that board: an object of its own, or a list of top-level names to keep
|
|
222
|
+
(`"viewports": ["desktop", "phone"]`). Page and action `viewports` pick from the board's.
|
|
223
|
+
|
|
224
|
+
A page can set its own frame height: `"frameHeight": 900` for all its viewports, or `{ "desktop": 900, "phone": 844 }` for some (the
|
|
225
|
+
rest keep the viewport's height; names the page does not use are ignored). Only the shot changes: the browser window stays the
|
|
226
|
+
viewport's (`layoutHeight`, else `height`), so the page lays out exactly as its neighbours do. A frame shorter than the window shows the
|
|
227
|
+
top of it (or wherever an action scrolled to); a taller one reaches past the window, like `layoutHeight`. On the board each card takes
|
|
228
|
+
its page's frame heights, so screen-sized app cards and long marketing pages sit on one board; variants of the page use the same
|
|
229
|
+
heights.
|
|
230
|
+
|
|
231
|
+
## Blocking requests
|
|
232
|
+
|
|
233
|
+
`block` lists requests the capture browser aborts, so captures do not count as visits or trigger beacons:
|
|
234
|
+
|
|
235
|
+
```json
|
|
236
|
+
{ "block": ["analytics", "*/umami/*", "tracker.example.com"] }
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
- A bare host (`tracker.example.com`) blocks that host and its subdomains.
|
|
240
|
+
- A pattern with `*` or `/` matches the whole URL; `*` stands for any run of characters: `*/cdn-cgi/rum*`, `https://example.com/api/track*`.
|
|
241
|
+
- `"analytics"` is a built-in list: Google Analytics and Tag Manager, Plausible, Umami Cloud, Cloudflare Web Analytics and RUM, Segment,
|
|
242
|
+
Hotjar, Clarity, Mixpanel, Amplitude, PostHog, Heap, FullStory, Fathom, Simple Analytics, GoatCounter, and the Meta, Bing, LinkedIn,
|
|
243
|
+
X, TikTok and HubSpot pixels. A self-hosted analytics endpoint needs its own pattern (`"*/umami/*"`).
|
|
244
|
+
|
|
245
|
+
The top-level list applies to every board; a board's `block` adds to it. Blocked requests are not network failures in the capture
|
|
246
|
+
warnings or in page checks. Page checks apply the same list.
|
|
247
|
+
|
|
248
|
+
## localStorage seeds
|
|
249
|
+
|
|
250
|
+
`localStorage` (top level, board or page) sets keys before the page's own scripts run, on the page's own origin only:
|
|
251
|
+
|
|
252
|
+
```json
|
|
253
|
+
{ "localStorage": { "game.trailerSeen": "1", "settings": { "music": false } } }
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
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
|
|
257
|
+
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
|
|
258
|
+
setting) instead of clicking through to set them.
|
|
259
|
+
|
|
260
|
+
## Setup (shared state)
|
|
261
|
+
|
|
262
|
+
`setup` on a board (or at the top level of a single-board config) runs a list of actions once per viewport before that board's pages,
|
|
263
|
+
and the pages in its scope start from the browser state it left: cookies, localStorage and IndexedDB. Each page still opens its own
|
|
264
|
+
`path` in a fresh tab. A guest entry, a cookie banner or a first-run picker then happens once per capture, not once per shot.
|
|
265
|
+
|
|
266
|
+
```json
|
|
267
|
+
{
|
|
268
|
+
"setup": {
|
|
269
|
+
"path": "/",
|
|
270
|
+
"actions": [{ "click": "button:has-text('Continue as guest')" }, { "waitFor": "nav[aria-label='Main']" }],
|
|
271
|
+
"groups": ["App"],
|
|
272
|
+
"pages": ["checkout-empty"]
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
- `actions` (required): any page actions, including `viewports` guards and `optional`.
|
|
278
|
+
- `path`: where it starts, default `/`.
|
|
279
|
+
- `groups` and `pages`: its scope. Without either, every page of the board uses it; with them, only pages in those groups or with
|
|
280
|
+
those ids (marketing pages keep a clean first visit).
|
|
281
|
+
- `timeout`: its own budget, else `timeouts.page`.
|
|
282
|
+
- A plain array is short for `{ "actions": [...] }`.
|
|
283
|
+
|
|
284
|
+
It starts from the board's auth state, if any. If it fails, every shot in its scope fails with the step that stalled
|
|
285
|
+
(`setup failed: action 1 (click "...") timed out after 45 s`) and the rest of the board is captured as usual. Page checks use it too.
|
|
286
|
+
State on the server is shared: pages that change it (start a session, spend a turn) should stay out of the scope and do their own entry.
|
|
287
|
+
|
|
288
|
+
## Sitemap import
|
|
289
|
+
|
|
290
|
+
`shapewall sitemap` fills `pages` from a `sitemap.xml` instead of typing them:
|
|
291
|
+
|
|
292
|
+
```sh
|
|
293
|
+
shapewall sitemap https://www.example.com/sitemap.xml --dry-run # see what it would add
|
|
294
|
+
shapewall sitemap https://www.example.com/sitemap.xml --limit 50 --exclude /tag/,/author/
|
|
295
|
+
shapewall init --sitemap ./public/sitemap.xml # a new config with the sitemap's pages
|
|
296
|
+
shapewall init --base-url https://www.example.com --sitemap # the same, from <base URL>/sitemap.xml
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`init --base-url URL` without `--sitemap` tries `<base URL>/sitemap.xml` too (and records it when it has pages); without one it follows
|
|
300
|
+
the home page's same-site links two levels deep, up to 25 pages, titled from each page's `<title>`. `--no-discover` writes the home
|
|
301
|
+
page only.
|
|
302
|
+
|
|
303
|
+
- A sitemap index is followed into its child sitemaps (up to 50, three levels deep, each read once); gzipped `.xml.gz` sitemaps work.
|
|
304
|
+
A child that fails is reported and skipped.
|
|
305
|
+
- One site's URLs are kept: the host of `baseUrl` (or `publicUrl`) if the sitemap uses it, else its most common host. Production URLs
|
|
306
|
+
in a sitemap become paths on your `baseUrl`, and a base path in `baseUrl` (`http://localhost:3000/app`) is taken off.
|
|
307
|
+
- Paths already on the board, repeats and `/pricing` vs `/pricing/` count once, so running it again only adds new pages.
|
|
308
|
+
- Pages are grouped by their first path segment (`/blog/*` in "Blog") when it has more than one page or the board already has a group
|
|
309
|
+
for it; single top-level pages go in "Pages". `--group NAME` puts them all in one group. Titles come from the last path segment.
|
|
310
|
+
- With more than `--limit` pages (default 100, at most 1000), the shallowest are kept, so the top of the site wins over deep archives.
|
|
311
|
+
- `--board ID` adds them to one board of a multi-board config. Nothing is captured; run `shapewall capture` next.
|
|
312
|
+
|
|
313
|
+
To set the source once, add `sitemap` to the config (or to a board in `boards[]`). `shapewall sitemap` with no argument reads it, and
|
|
314
|
+
`init --sitemap` records it:
|
|
315
|
+
|
|
316
|
+
```json
|
|
317
|
+
{ "sitemap": { "source": "https://www.example.com/sitemap.xml", "limit": 50, "exclude": ["/tag/"], "group": "Site" } }
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
`"sitemap": "public/sitemap.xml"` (a URL or a file, relative to the config) works too. Options on the command line win over the config.
|
|
321
|
+
|
|
322
|
+
## Board (multi-board configs)
|
|
323
|
+
|
|
324
|
+
```json
|
|
325
|
+
{
|
|
326
|
+
"baseUrl": "http://localhost:3000",
|
|
327
|
+
"boards": [
|
|
328
|
+
{ "id": "marketing", "title": "Marketing site", "pages": [{ "id": "home", "path": "/" }] },
|
|
329
|
+
{ "id": "docs", "title": "Docs", "baseUrl": "http://localhost:4000", "groups": ["Guides", "API"], "pages": [] }
|
|
330
|
+
]
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
A board may override `baseUrl`, `publicUrl` and `environments`, and has its own `journeys`. `--board ID` selects one for `capture`,
|
|
335
|
+
`comments` and `variant`.
|
|
336
|
+
|
|
337
|
+
A board may also set its own capture settings, so an app or a game captures differently from the marketing site beside it:
|
|
338
|
+
|
|
339
|
+
| Key | Notes |
|
|
340
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
341
|
+
| `viewports` | Its own viewports (an object), or a list of top-level names. Replaces the top-level list for this board. See [Viewports](#viewports). |
|
|
342
|
+
| `block` | Added to the top-level `block`. See [Blocking requests](#blocking-requests). |
|
|
343
|
+
| `reducedMotion` | Replaces the top-level value for this board. |
|
|
344
|
+
| `localStorage` | Merged over the top-level seeds; pages merge theirs over it. |
|
|
345
|
+
| `setup` | Actions run once per viewport; their state is reused by the board's pages. See [Setup](#setup-shared-state). |
|
|
346
|
+
| `auth` | Replaces the top-level `auth` for this board (`null` turns it off). See [Auth](#auth). |
|
|
347
|
+
|
|
348
|
+
## Environments
|
|
349
|
+
|
|
350
|
+
List the places the same pages run, to compare them on the board:
|
|
351
|
+
|
|
352
|
+
```json
|
|
353
|
+
{
|
|
354
|
+
"environments": [
|
|
355
|
+
{ "id": "staging", "title": "Staging", "baseUrl": "https://staging.example.com" },
|
|
356
|
+
{ "id": "production", "baseUrl": "https://www.example.com", "publicUrl": "https://www.example.com" }
|
|
357
|
+
],
|
|
358
|
+
"pages": [{ "id": "home", "path": "/" }]
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
| Key | Type | Notes |
|
|
363
|
+
| ----------- | ----------- | -------------------------------------------------------- |
|
|
364
|
+
| `id` | string | Lowercase letters, digits and dashes. Used with `--env`. |
|
|
365
|
+
| `baseUrl` | http(s) URL | Where this environment's pages load from. |
|
|
366
|
+
| `publicUrl` | http(s) URL | Optional, as at the top level. |
|
|
367
|
+
| `title` | string | Shown on the board. Defaults to the id. |
|
|
368
|
+
|
|
369
|
+
The first environment is the default: `shapewall capture` without `--env` captures it, its captures are the ones you comment on, and it
|
|
370
|
+
sets the board's `baseUrl` (leave `baseUrl` out, or set it to the same URL). `shapewall capture --env production` captures another one
|
|
371
|
+
into `.shapewall/<board>/envs/production/captures/`. Configs without `environments` work as before: one environment, `default`, at
|
|
372
|
+
`baseUrl`.
|
|
373
|
+
|
|
374
|
+
On the board, **Compare** shows each page in two environments side by side, with the changed pixels in red over the second one, the
|
|
375
|
+
changed share on each card and a **Changed pages only** filter. Diffs (pixelmatch, anti-aliasing ignored) are computed when you open
|
|
376
|
+
compare mode or after an environment capture, and cached in `.shapewall/<board>/diffs/<a>_<b>/` until either capture changes. Compare
|
|
377
|
+
works in a static export too: `shapewall export` computes every pair of captured environments.
|
|
378
|
+
|
|
379
|
+
## Versions
|
|
380
|
+
|
|
381
|
+
When a page is captured again, the shot it replaces (PNG, thumbnail and live HTML) moves to `.shapewall/<board>/versions/` as
|
|
382
|
+
`<page>.<viewport>.<version>.*`, and the newest `versions` (default 5) of each page and viewport are kept. A comment stores the version it
|
|
383
|
+
was made on (`captureVersion`), so once it is resolved and the page recaptured, the comments panel shows before and after near the pin.
|
|
384
|
+
Versions are kept for the default environment only.
|
|
385
|
+
|
|
386
|
+
## GitHub
|
|
387
|
+
|
|
388
|
+
```json
|
|
389
|
+
{ "github": { "repo": "acme/site", "boardUrl": "https://review.example.com/", "labels": ["feedback"] } }
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
`repo` (`owner/name`), `boardUrl` (where the board is served, for links from issues; default `http://127.0.0.1:4600/`), `labels` (up to
|
|
393
|
+
10, put on new issues), `board` (the board that bare `shapewall:<id>` markers mean) and `apiUrl` (GitHub Enterprise Server). Top level
|
|
394
|
+
only. The token comes from `SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN` and the webhook secret from `SHAPEWALL_GITHUB_WEBHOOK_SECRET`; a
|
|
395
|
+
`token` or `webhookSecret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
|
|
396
|
+
`SHAPEWALL_GITHUB_API_URL`. See [github.md](github.md).
|
|
397
|
+
|
|
398
|
+
## Agent
|
|
399
|
+
|
|
400
|
+
```json
|
|
401
|
+
{ "agent": { "baseUrl": "http://127.0.0.1:11434/v1", "model": "llama3.2", "vision": false } }
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
The board chat's endpoint: any OpenAI-compatible chat completions API. `baseUrl` and `model` are required to connect; `apiKeyEnv` (the
|
|
405
|
+
variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label`, `vision` (default `true`), `tools` (default `true`), `maxTokens`,
|
|
406
|
+
`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`
|
|
407
|
+
variable. A key goes only to this machine, a known hosted API, or a host confirmed in `SHAPEWALL_AGENT_KEY_HOSTS`.
|
|
408
|
+
Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [agents.md](agents.md).
|
|
409
|
+
|
|
410
|
+
## Auth
|
|
411
|
+
|
|
412
|
+
Never put credentials in the config. Two options:
|
|
413
|
+
|
|
414
|
+
**Guided manual sign-in.** Run this on the desktop that will capture the site:
|
|
415
|
+
|
|
416
|
+
```sh
|
|
417
|
+
shapewall auth record --url https://your-site.example/login
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
Shapewall opens a fresh, isolated Chromium profile using the same `browser.channel` / `browser.executablePath` settings as capture.
|
|
421
|
+
Sign in yourself in that window, return to the terminal, and press Enter to save. Shapewall never enters a password, executes a login
|
|
422
|
+
script, or reuses your personal browser profile. Type `cancel`, press Ctrl-C, close the browser, or let the timeout expire to discard.
|
|
423
|
+
The default timeout is 600 seconds; `--timeout 1800` allows up to 30 minutes. A terminal and desktop display are required; this is not
|
|
424
|
+
a server-side sign-in button or a background service.
|
|
425
|
+
|
|
426
|
+
The command saves Playwright cookies, localStorage and IndexedDB in `.shapewall-auth/<board>[.<environment>].auth.json`.
|
|
427
|
+
That directory is private (0700), contains an ignore-all `.gitignore`, and stays outside capture/export output. State files are 0600.
|
|
428
|
+
Existing recordings need explicit `--overwrite`; symlinks, hard links, Git-tracked state and files changed during recording are refused.
|
|
429
|
+
A crashed recording can leave `.shapewall-auth/.record.lock`; remove it only after confirming no recording is still open.
|
|
430
|
+
|
|
431
|
+
Use `--board ID` and `--env ID` to choose a configured target; otherwise the first board/environment is used. `--url` is optional and
|
|
432
|
+
defaults to that environment's base URL. The command prints the exact config snippet and next capture command, without changing config:
|
|
433
|
+
|
|
434
|
+
```json
|
|
435
|
+
{ "auth": { "storageState": "./.shapewall-auth/your-board.auth.json" } }
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
The state file contains account credentials. Keep it private and use a test account with only the access needed for the capture.
|
|
439
|
+
Authentication and target URLs, cookie values and browser error details are not printed. On a remote capture server without a desktop,
|
|
440
|
+
record and capture locally, then use the normal capture-push workflow instead of attempting an interactive sign-in on the server.
|
|
441
|
+
|
|
442
|
+
**Login script.** An ES module whose default export signs in. It runs once per capture; its cookies and storage are reused for every page.
|
|
443
|
+
|
|
444
|
+
Capture also refuses a `baseUrl` whose public-looking hostname resolves to a private or loopback address, so a config from someone
|
|
445
|
+
else cannot point captures at your internal network through DNS. Use `localhost` or the address itself for your own dev server.
|
|
446
|
+
|
|
447
|
+
A login script is code: `shapewall capture`, the board's Capture button and page checks run it on your machine, as you, with your
|
|
448
|
+
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
|
|
449
|
+
the script first if you did not write it. For the same reason a config cannot point `browser.executablePath` at a file inside the
|
|
450
|
+
project folder (use an installed browser's absolute path, `browser.channel`, or set `SHAPEWALL_BROWSER_PATH` yourself).
|
|
451
|
+
|
|
452
|
+
```json
|
|
453
|
+
{ "auth": { "loginScript": "./shapewall.login.mjs" } }
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
```js
|
|
457
|
+
export default async function login({ page, context, baseUrl }) {
|
|
458
|
+
await page.goto(new URL('/login', baseUrl).toString())
|
|
459
|
+
await page.fill('input[name=email]', process.env.SHAPEWALL_USER)
|
|
460
|
+
await page.fill('input[name=password]', process.env.SHAPEWALL_PASSWORD)
|
|
461
|
+
await page.click('button[type=submit]')
|
|
462
|
+
await page.waitForURL((url) => !url.pathname.startsWith('/login'))
|
|
463
|
+
}
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
If both are set, the login script wins. Use a test account with the least access the pages need, and keep `*.auth.json` out of git
|
|
467
|
+
(`shapewall init` adds it to `.gitignore`).
|
|
468
|
+
|
|
469
|
+
**Per board.** `auth` inside a board of `boards[]` replaces the top-level one for that board only, so a signed-in app board and a
|
|
470
|
+
signed-out marketing board can share one config; `"auth": null` captures a board signed out. For a guest entry that is a few clicks,
|
|
471
|
+
a board [`setup`](#setup-shared-state) is simpler than a login script and is scoped to the pages that need it.
|
|
472
|
+
|
|
473
|
+
### Checks SEO
|
|
474
|
+
|
|
475
|
+
Optional `checks.seo` turns SEO checks on by default for `shapewall checks run`, `shapewall audit` and the board's **Run checks**:
|
|
476
|
+
`true` for every page, `false` to keep them off (the board's Include SEO then starts off), or a list of page ids. `--seo` and
|
|
477
|
+
`--no-seo` override it for one run. Pages with `seo: { "indexable": false }` are always treated as private. See
|
|
478
|
+
[page checks](page-checks.md).
|
|
479
|
+
|
|
480
|
+
```json
|
|
481
|
+
{ "checks": { "seo": ["home", "pricing", "blog"] } }
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
### Checks budgets
|
|
485
|
+
|
|
486
|
+
Optional top-level `checks.budgets` declares explicit maximum performance measurements for manual
|
|
487
|
+
checks and Lighthouse audits. Omitted means no budgets. Each report keeps its policy snapshot;
|
|
488
|
+
unknown measurements do not pass. See [performance budgets and history](performance.md#performance-budgets-and-report-history)
|
|
489
|
+
for the supported metric names, units, example and comparison rules.
|