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