shapewall 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
@@ -0,0 +1,776 @@
1
+ // Captures every page of a board with Playwright (Chromium): a fixed-size
2
+ // frame per viewport as PNG, a thumbnail of the same frame for zoomed-out
3
+ // views, and a sanitized live HTML snapshot (live.js).
4
+ //
5
+ // A full run writes into captures.next/ and swaps it in at the end, so a
6
+ // failed or interrupted run never leaves a half-empty board. `only` captures a
7
+ // few pages straight into captures/ and updates their manifest entries.
8
+ // The run holds <board>/capture.lock (lock.js) and keeps status.json current.
9
+
10
+ import fs from 'node:fs'
11
+ import path from 'node:path'
12
+ import { pathToFileURL } from 'node:url'
13
+ import {
14
+ authFor,
15
+ boardViewports,
16
+ frameSize,
17
+ getBoard,
18
+ getEnvironment,
19
+ inSetupScope,
20
+ joinUrl,
21
+ selectPages,
22
+ thumbScale,
23
+ viewportDevice,
24
+ } from '../config.js'
25
+ import { compareEnvironments } from '../diff.js'
26
+ import { READ_LINKS_JS, linkTargets } from '../links.js'
27
+ import { acquireLock, releaseLock } from '../lock.js'
28
+ import {
29
+ archiveVersion,
30
+ boardDir,
31
+ capturesDir,
32
+ entryVersion,
33
+ pruneVersions,
34
+ readJson,
35
+ versionId,
36
+ writeFileAtomic,
37
+ writeJsonAtomic,
38
+ } from '../store.js'
39
+ import { checkLinks, collectLinks, formatBroken, mergeBroken } from '../broken-links.js'
40
+ import { cliCommand } from '../invocation.js'
41
+ import { writeLiveHtml } from './live.js'
42
+ import { observeCaptureNetwork, captureWarningText } from './network-summary.js'
43
+ import { capturePacer } from './pacing.js'
44
+ import { StepError, isTimeout, runActions, seconds, stepFailure } from './actions.js'
45
+ import { installRequestRules, seedLocalStorage } from './requests.js'
46
+
47
+ // A navigation timeout says so plainly; other load errors keep their own first line.
48
+ const loadFailure = (error, timeout) => (isTimeout(error) ? new StepError(`loading the page timed out after ${seconds(timeout)}`) : error)
49
+
50
+ const IMAGE_WAIT_MS = 8000
51
+
52
+ // Images in the frame must have arrived before the shot, or it shows alt
53
+ // text. Lazy images in view are switched to eager, then we poll until every
54
+ // image intersecting the frame is complete, capped at IMAGE_WAIT_MS.
55
+ const PENDING_IMAGES_JS = `(() => {
56
+ const inView = (el) => {
57
+ const r = el.getBoundingClientRect();
58
+ return r.width > 0 && r.height > 0 && r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth;
59
+ };
60
+ let pending = 0;
61
+ for (const img of document.images) {
62
+ if (!inView(img)) continue;
63
+ if (img.loading === 'lazy') img.loading = 'eager';
64
+ if (!(img.complete && img.naturalWidth > 0)) pending += 1;
65
+ }
66
+ return pending;
67
+ })()`
68
+
69
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
70
+
71
+ async function waitForImages(page, capMs) {
72
+ const until = Date.now() + capMs
73
+ for (;;) {
74
+ let pending = 0
75
+ try {
76
+ pending = Number(await page.evaluate(PENDING_IMAGES_JS)) || 0
77
+ } catch {
78
+ return
79
+ }
80
+ if (!pending || Date.now() >= until) return
81
+ await sleep(200)
82
+ }
83
+ }
84
+
85
+ // Browser context options for a viewport: its device (viewportDevice), its
86
+ // layout height (the frame's height unless it sets layoutHeight) and the
87
+ // board's reducedMotion. `size` is the viewport's config entry. The color
88
+ // scheme is fixed (light, the browser default) so captures never follow the
89
+ // machine they run on; the live snapshot is frozen to it (media-scheme.js).
90
+ export function contextOptions(viewportName, size, storageState, { reducedMotion = 'reduce', colorScheme = 'light' } = {}) {
91
+ const device = viewportDevice(viewportName, size)
92
+ return {
93
+ viewport: { width: size.width, height: size.layoutHeight || size.height },
94
+ deviceScaleFactor: 1,
95
+ isMobile: device.mobile,
96
+ hasTouch: device.touch,
97
+ ...(device.userAgent ? { userAgent: device.userAgent } : {}),
98
+ ...(storageState ? { storageState } : {}),
99
+ // Captures are of your own site; animations would make shots flaky. A
100
+ // board may opt out ("reducedMotion": "no-preference"), for games that
101
+ // behave differently with it.
102
+ reducedMotion,
103
+ colorScheme,
104
+ }
105
+ }
106
+
107
+ // The scroll position the frame is shot at. The DevTools clip is in document
108
+ // coordinates, so a page scrolled by an action or a hash link is shot where
109
+ // it is, not at the top of the document. Read from the page, so bounded.
110
+ async function scrollOffset(page) {
111
+ const value = await page.evaluate('[window.scrollX, window.scrollY]').catch(() => null)
112
+ const clean = (n) => (Number.isFinite(n) && n > 0 ? Math.min(Math.round(n), 1000000) : 0)
113
+ return Array.isArray(value) ? { x: clean(value[0]), y: clean(value[1]) } : { x: 0, y: 0 }
114
+ }
115
+
116
+ function liveSummary(live) {
117
+ if (!live) return null
118
+ if (live.error) return { status: 'failed', error: String(live.error).slice(0, 200) }
119
+ return {
120
+ status: 'ok',
121
+ bytes: live.bytes,
122
+ sha256: live.sha256,
123
+ images: live.stats.images,
124
+ imagesDropped: live.stats.imagesDropped,
125
+ fonts: live.stats.fonts,
126
+ fontsDropped: live.stats.fontsDropped,
127
+ // The scheme the snapshot is frozen to (its prefers-color-scheme rules).
128
+ ...(live.colorScheme ? { colorScheme: live.colorScheme } : {}),
129
+ // The element map the board places pins from (element-map.js).
130
+ ...(live.elements ? { elements: live.elements } : {}),
131
+ }
132
+ }
133
+
134
+ // The private-host guard alone (requests.js has it and the block list).
135
+ // Returns whether the guard is on.
136
+ export async function installPrivateHostGuard(context, rootUrl, options = {}) {
137
+ return (await installRequestRules(context, rootUrl, options)).guarded
138
+ }
139
+
140
+ // One shot: new context at the viewport, load, settle, actions, screenshot
141
+ // plus thumbnail, then live HTML. Returns a manifest entry. `options`: the
142
+ // board's capture settings (captureOptions): block, reducedMotion, localStorage.
143
+ export async function shootPage({
144
+ browser,
145
+ url,
146
+ viewportName,
147
+ size,
148
+ outDir,
149
+ name,
150
+ page: pageConfig = {},
151
+ timeouts,
152
+ storageState,
153
+ liveHtml = true,
154
+ links = null,
155
+ matchLinks = null,
156
+ onHrefs = null,
157
+ options = {},
158
+ }) {
159
+ const began = Date.now()
160
+ let httpStatus = null
161
+ let finishNetwork = null,
162
+ networkSummary = null
163
+ let skipped = []
164
+ // A page's own timeout replaces timeouts.page for it.
165
+ const pageTimeout = pageConfig.timeout || timeouts.page
166
+ const cap = pageTimeout + timeouts.settle + 20000
167
+ // The shot's frame: the viewport's, or the page's own frameHeight. The
168
+ // browser window (contextOptions) stays the viewport's either way.
169
+ const frame = frameSize(size, pageConfig, viewportName)
170
+ const context = await browser.newContext(contextOptions(viewportName, size, storageState, options))
171
+ const responses = new Map()
172
+ let cancelled = false
173
+ // What the shot is doing, so a timeout says where it stalled.
174
+ let stage = 'loading the page'
175
+ const timer = setTimeout(() => {
176
+ cancelled = true
177
+ context.close().catch(() => {})
178
+ }, cap)
179
+ const files = {
180
+ png: path.join(outDir, `${name}.${viewportName}.png`),
181
+ thumb: path.join(outDir, `${name}.${viewportName}.thumb.png`),
182
+ html: path.join(outDir, `${name}.${viewportName}.html`),
183
+ elements: path.join(outDir, `${name}.${viewportName}.elements.json`),
184
+ }
185
+ // Old files stay until this shot succeeds (a failed --only run keeps them).
186
+ try {
187
+ const rules = await installRequestRules(context, url, { block: options.block })
188
+ await seedLocalStorage(context, url, { ...options.localStorage, ...pageConfig.localStorage })
189
+ const page = await context.newPage()
190
+ finishNetwork = observeCaptureNetwork(page, pageConfig.expectStatus || [], { isBlocked: rules.isBlocked })
191
+ page.on('response', (response) => {
192
+ if (response.status() < 400) responses.set(response.url().split('#')[0], response)
193
+ })
194
+ const response = await page.goto(url, { waitUntil: 'load', timeout: pageTimeout }).catch((error) => {
195
+ throw cancelled ? error : loadFailure(error, pageTimeout)
196
+ })
197
+ httpStatus = response ? response.status() : null
198
+ // An error page on purpose ("expectStatus": 404) is captured like any
199
+ // other; then any other status is the surprise.
200
+ const expected = pageConfig.expectStatus
201
+ if (expected?.length && httpStatus !== null && !expected.includes(httpStatus)) {
202
+ throw new Error(`HTTP ${httpStatus} (expected ${expected.join(' or ')})`)
203
+ }
204
+ if (!expected?.length && httpStatus >= 400) throw new Error(`HTTP ${httpStatus}`)
205
+ stage = 'waiting for the network to settle'
206
+ await page.waitForLoadState('networkidle', { timeout: timeouts.settle }).catch(() => {})
207
+ if (pageConfig.waitFor) {
208
+ stage = `waitFor ${JSON.stringify(pageConfig.waitFor)}`
209
+ await page.waitForSelector(pageConfig.waitFor, { timeout: pageTimeout, state: 'visible' }).catch((error) => {
210
+ throw cancelled ? error : stepFailure(stage, error, pageTimeout)
211
+ })
212
+ }
213
+ if (pageConfig.actions?.length) {
214
+ const result = await runActions(page, pageConfig.actions, {
215
+ timeout: pageTimeout,
216
+ viewport: viewportName,
217
+ onStep: (step) => (stage = step),
218
+ })
219
+ skipped = result.skipped
220
+ }
221
+ stage = 'waiting for images'
222
+ await waitForImages(page, IMAGE_WAIT_MS)
223
+ // A short pause for late renders, decodes and transitions.
224
+ await sleep(400)
225
+ stage = 'the screenshot'
226
+ // The DevTools protocol can scale a clip, which Playwright's own
227
+ // screenshot cannot: the thumbnail is the same frame, smaller.
228
+ const cdp = await context.newCDPSession(page)
229
+ const { x, y } = await scrollOffset(page)
230
+ // A frame taller than the browser window (layoutHeight) reaches past the fold.
231
+ const beyond = Boolean(frame.layoutHeight && frame.height > frame.layoutHeight)
232
+ const shot = async (scale) => {
233
+ const result = await cdp.send('Page.captureScreenshot', {
234
+ format: 'png',
235
+ clip: { x, y, width: frame.width, height: frame.height, scale },
236
+ ...(beyond ? { captureBeyondViewport: true } : {}),
237
+ })
238
+ return Buffer.from(result.data, 'base64')
239
+ }
240
+ const full = await shot(1)
241
+ writeFileAtomic(files.png, full)
242
+ writeFileAtomic(files.thumb, await shot(thumbScale(viewportName, size) || 0.25))
243
+ networkSummary = finishNetwork()
244
+ stage = 'the live HTML'
245
+ // Links to other pages on the board, as page ids (untrusted hrefs never leave this call).
246
+ const hrefs = matchLinks || onHrefs ? await page.evaluate(READ_LINKS_JS).catch(() => []) : null
247
+ const linked = matchLinks ? matchLinks(hrefs) : null
248
+ // Every link, for the broken-link check (the caller keeps only http(s) URLs).
249
+ if (onHrefs) onHrefs(hrefs)
250
+ let live = null
251
+ if (liveHtml) {
252
+ try {
253
+ // The board shows the live HTML at the frame's size.
254
+ live = await writeLiveHtml({
255
+ page,
256
+ responses,
257
+ file: files.html,
258
+ links,
259
+ isCancelled: () => cancelled,
260
+ size: frame,
261
+ isInternal: rules.isInternal,
262
+ })
263
+ } catch (error) {
264
+ live = { error: error.message }
265
+ }
266
+ }
267
+ // A live HTML file (and its element map) from an older capture must not sit beside the new PNG.
268
+ if (!live || live.error) {
269
+ fs.rmSync(files.html, { force: true })
270
+ fs.rmSync(files.elements, { force: true })
271
+ }
272
+ return {
273
+ status: 'ok',
274
+ url,
275
+ httpStatus,
276
+ networkSummary,
277
+ ...(pageConfig.expectStatus?.length ? { expectedStatus: true } : {}),
278
+ bytes: full.length,
279
+ ms: Date.now() - began,
280
+ html: liveSummary(live),
281
+ ...(linked ? { links: linked } : {}),
282
+ ...(skipped.length ? { skippedActions: skipped } : {}),
283
+ }
284
+ } catch (error) {
285
+ const message = cancelled ? `timed out after ${seconds(cap)} (during ${stage})` : String(error?.message || error).split('\n')[0]
286
+ return {
287
+ status: 'failed',
288
+ url,
289
+ httpStatus,
290
+ networkSummary: networkSummary || finishNetwork?.() || null,
291
+ error: message.slice(0, 300),
292
+ ms: Date.now() - began,
293
+ }
294
+ } finally {
295
+ clearTimeout(timer)
296
+ finishNetwork?.()
297
+ await context.close().catch(() => {})
298
+ }
299
+ }
300
+
301
+ // Runs a board's setup (config `setup`) for one viewport: a fresh context
302
+ // with the board's auth state, setup.path, its actions, then the browser
303
+ // state they left (cookies, localStorage, IndexedDB). Pages in the setup's
304
+ // scope start from that state. Throws an Error naming the step that failed.
305
+ export async function runSetup({ browser, setup, baseUrl, viewportName, size, storageState, timeouts, options = {} }) {
306
+ const timeout = setup.timeout || timeouts.page
307
+ const cap = timeout + timeouts.settle + 20000
308
+ const context = await browser.newContext(contextOptions(viewportName, size, storageState, options))
309
+ let cancelled = false
310
+ let stage = 'loading the page'
311
+ const timer = setTimeout(() => {
312
+ cancelled = true
313
+ context.close().catch(() => {})
314
+ }, cap)
315
+ const url = joinUrl(baseUrl, setup.path)
316
+ try {
317
+ await installRequestRules(context, url, { block: options.block })
318
+ await seedLocalStorage(context, url, options.localStorage)
319
+ const page = await context.newPage()
320
+ const response = await page.goto(url, { waitUntil: 'load', timeout }).catch((error) => {
321
+ throw cancelled ? error : loadFailure(error, timeout)
322
+ })
323
+ if (response && response.status() >= 400) throw new Error(`HTTP ${response.status()}`)
324
+ stage = 'waiting for the network to settle'
325
+ await page.waitForLoadState('networkidle', { timeout: timeouts.settle }).catch(() => {})
326
+ await runActions(page, setup.actions, { timeout, viewport: viewportName, onStep: (step) => (stage = step) })
327
+ stage = 'saving the browser state'
328
+ // Requests the last action started (a guest token, a saved flag) finish first.
329
+ await page.waitForLoadState('networkidle', { timeout: Math.min(timeouts.settle, 5000) }).catch(() => {})
330
+ return await context.storageState({ indexedDB: true })
331
+ } catch (error) {
332
+ const message = cancelled ? `timed out after ${seconds(cap)} (during ${stage})` : String(error?.message || error).split('\n')[0]
333
+ throw new Error(`setup failed: ${message}`.slice(0, 300), { cause: error })
334
+ } finally {
335
+ clearTimeout(timer)
336
+ await context.close().catch(() => {})
337
+ }
338
+ }
339
+
340
+ // A board's capture settings for shootPage and runSetup.
341
+ export const captureOptions = (config, board) => ({
342
+ block: board?.block || config.block || [],
343
+ reducedMotion: board?.reducedMotion || config.reducedMotion || 'reduce',
344
+ localStorage: board?.localStorage || null,
345
+ })
346
+
347
+ // The state each shot starts from: the auth state (`base`), or for a page in
348
+ // the setup's scope the setup's state for that viewport, run once on first
349
+ // use and shared (concurrent shots wait on the same run, a failure fails them all).
350
+ export function setupStates({ browser, board, config, baseUrl, base, viewports, run = runSetup }) {
351
+ const runs = new Map()
352
+ return (page, viewportName) => {
353
+ if (!inSetupScope(board.setup, page)) return Promise.resolve(base)
354
+ if (!runs.has(viewportName)) {
355
+ const promise = run({
356
+ browser,
357
+ setup: board.setup,
358
+ baseUrl,
359
+ viewportName,
360
+ size: viewports[viewportName],
361
+ storageState: base,
362
+ timeouts: config.timeouts,
363
+ options: captureOptions(config, board),
364
+ })
365
+ // Seen by every waiting shot; never an unhandled rejection.
366
+ promise.catch(() => {})
367
+ runs.set(viewportName, promise)
368
+ }
369
+ return runs.get(viewportName)
370
+ }
371
+ }
372
+
373
+ // What to tell someone whose Playwright Chromium did not launch: it was never
374
+ // downloaded, or (a bare Linux server, container or WSL) it is there and the
375
+ // system libraries it needs are not.
376
+ export function browserLaunchHelp(error, engine, { exists = fs.existsSync, platform = process.platform } = {}) {
377
+ let installed = false
378
+ try {
379
+ installed = exists(engine.executablePath())
380
+ } catch {
381
+ /* no path to check */
382
+ }
383
+ if (!installed || /Executable doesn't exist/.test(error?.message || '')) {
384
+ return `Playwright has no Chromium yet. Run "${cliCommand('doctor --install-browser')}" (it downloads the build this Shapewall needs), or set browser.channel to "chrome" in the config to use an installed Chrome.`
385
+ }
386
+ const why = String(error?.message || '')
387
+ .split('\n')
388
+ .map((line) => line.trim())
389
+ .filter(Boolean)[0]
390
+ return platform === 'linux'
391
+ ? `Chromium is installed but does not start${why ? ` (${why.slice(0, 160)})` : ''}. On Linux that usually means missing system libraries: run "npx playwright install-deps chromium" once as root (with sudo), then try again. "${cliCommand('doctor')}" checks it.`
392
+ : `Chromium is installed but does not start${why ? ` (${why.slice(0, 160)})` : ''}. "${cliCommand('doctor')}" checks it; setting browser.channel to "chrome" in the config uses an installed Chrome instead.`
393
+ }
394
+
395
+ // `handleSignals: false` for callers that handle SIGTERM/SIGINT themselves
396
+ // and close the browser when they are done (a stoppable checks run).
397
+ export async function launchBrowser(config, { chromium, handleSignals = true } = {}) {
398
+ const engine = chromium || (await import('playwright')).chromium
399
+ const options = { args: ['--hide-scrollbars', '--disable-dev-shm-usage'] }
400
+ if (!handleSignals) Object.assign(options, { handleSIGTERM: false, handleSIGINT: false, handleSIGHUP: false })
401
+ const channel = process.env.SHAPEWALL_BROWSER_CHANNEL || config.browser.channel
402
+ const executablePath = process.env.SHAPEWALL_BROWSER_PATH || config.browser.executablePath
403
+ if (executablePath) options.executablePath = executablePath
404
+ else if (channel) options.channel = channel
405
+ try {
406
+ return await engine.launch(options)
407
+ } catch (error) {
408
+ if (/Executable doesn't exist|browserType\.launch/.test(error.message) && !executablePath && !channel) {
409
+ throw new Error(browserLaunchHelp(error, engine), { cause: error })
410
+ }
411
+ throw error
412
+ }
413
+ }
414
+
415
+ // Auth: a login script (run once, its cookies and storage reused for every
416
+ // shot) or a saved Playwright storageState file. Neither belongs in git. A
417
+ // board's own `auth` replaces the top-level one for that board.
418
+ //
419
+ // A login script is code from the config's folder that runs as you, so the
420
+ // first run of each one in this process says so (to `log`, else stderr).
421
+ const announcedLoginScripts = new Set()
422
+ export function announceLoginScript(file, log = (line) => console.error(line)) {
423
+ if (announcedLoginScripts.has(file)) return false
424
+ announcedLoginScripts.add(file)
425
+ log(
426
+ `Running the login script named in the config: ${file}. auth.loginScript is code that runs on this machine as you; remove it from the config if you did not put it there.`,
427
+ )
428
+ return true
429
+ }
430
+ export async function resolveStorageState(browser, config, board, { log } = {}) {
431
+ const auth = authFor(config, board)
432
+ if (auth.loginScript) {
433
+ if (!fs.existsSync(auth.loginScript)) throw new Error(`auth.loginScript ${auth.loginScript} does not exist`)
434
+ announceLoginScript(auth.loginScript, log)
435
+ const mod = await import(pathToFileURL(auth.loginScript).href)
436
+ const login = mod.default || mod.login
437
+ if (typeof login !== 'function') throw new Error('auth.loginScript must export a default async function ({ page, context, baseUrl })')
438
+ const context = await browser.newContext()
439
+ try {
440
+ const page = await context.newPage()
441
+ await login({ page, context, baseUrl: board.baseUrl })
442
+ return await context.storageState()
443
+ } finally {
444
+ await context.close().catch(() => {})
445
+ }
446
+ }
447
+ if (auth.storageState) {
448
+ if (!fs.existsSync(auth.storageState)) throw new Error(`auth.storageState ${auth.storageState} does not exist`)
449
+ return auth.storageState
450
+ }
451
+ return null
452
+ }
453
+
454
+ async function pool(items, size, worker) {
455
+ let next = 0
456
+ const runners = Array.from({ length: Math.min(size, items.length) }, async () => {
457
+ while (next < items.length) {
458
+ const index = next
459
+ next += 1
460
+ await worker(items[index], index)
461
+ }
462
+ })
463
+ await Promise.all(runners)
464
+ }
465
+
466
+ // Runs a capture of one environment (default: the board's first). Returns
467
+ // { ok, done, failed, expected, total, dir, durationMs, shots, brokenLinks,
468
+ // linksChecked }. On the default environment the shots being replaced are
469
+ // kept as versions (config.versions per page and viewport). Links found on
470
+ // the pages are checked afterwards (broken-links.js); `checkExternal` checks
471
+ // links to other sites too.
472
+ export async function runCapture({
473
+ config,
474
+ boardId,
475
+ envId = null,
476
+ only = null,
477
+ log = () => {},
478
+ chromium = null,
479
+ checkLinks: linkCheck = true,
480
+ checkExternal = false,
481
+ // The CLI only: Ctrl+C or SIGTERM marks the capture stopped and exits.
482
+ exitOnSignal = false,
483
+ }) {
484
+ const board = getBoard(config, boardId)
485
+ const env = getEnvironment(board, envId)
486
+ const isDefault = env.id === board.environments[0].id
487
+ const keepVersions = isDefault && config.versions > 0
488
+ const pages = selectPages(board, only)
489
+ const dir = boardDir(config, board.id)
490
+ fs.mkdirSync(dir, { recursive: true })
491
+ const lockFile = path.join(dir, 'capture.lock')
492
+ if (!acquireLock(lockFile)) throw new Error(`A capture of "${board.id}" is already running.`)
493
+ const statusFile = path.join(dir, 'status.json')
494
+ const partial = Boolean(only && only.length)
495
+ const finalDir = capturesDir(config, board.id, env.id)
496
+ const workDir = partial ? finalDir : `${finalDir}.next`
497
+ const tasks = pages.flatMap((page) => page.viewports.map((viewportName) => ({ page, viewportName })))
498
+ const viewports = boardViewports(config, board)
499
+ const status = {
500
+ state: 'running',
501
+ startedAt: new Date().toISOString(),
502
+ finishedAt: null,
503
+ done: 0,
504
+ total: tasks.length,
505
+ failed: 0,
506
+ error: null,
507
+ env: isDefault ? null : env.id,
508
+ pid: process.pid,
509
+ }
510
+ const writeStatus = () => writeJsonAtomic(statusFile, status)
511
+ let browser = null
512
+ const onSignal = (signal) => {
513
+ status.state = 'failed'
514
+ status.error = `stopped by ${signal}`
515
+ status.finishedAt = new Date().toISOString()
516
+ try {
517
+ writeStatus()
518
+ } finally {
519
+ releaseLock(lockFile)
520
+ process.exit(signal === 'SIGINT' ? 130 : 143)
521
+ }
522
+ }
523
+ // Only the CLI's own capture exits on Ctrl+C: in a server (agent tools,
524
+ // MCP, the feedback loop) the process's own handlers decide.
525
+ if (exitOnSignal) {
526
+ process.once('SIGINT', onSignal)
527
+ process.once('SIGTERM', onSignal)
528
+ }
529
+ const started = Date.now()
530
+ try {
531
+ // Inside the try: a failed write still releases the lock.
532
+ writeStatus()
533
+ if (!partial) fs.rmSync(workDir, { recursive: true, force: true })
534
+ fs.mkdirSync(workDir, { recursive: true })
535
+ const previous = readJson(path.join(finalDir, 'manifest.json'))
536
+ const manifest = {
537
+ board: board.id,
538
+ capturedAt: null,
539
+ durationMs: null,
540
+ viewports,
541
+ pages: partial && previous?.pages ? { ...previous.pages } : {},
542
+ }
543
+ browser = await launchBrowser(config, { chromium })
544
+ const storageState = await resolveStorageState(browser, config, board, { log })
545
+ // The default environment is the board's baseUrl (which callers may override).
546
+ const baseUrl = isDefault ? board.baseUrl : env.baseUrl
547
+ const options = captureOptions(config, board)
548
+ const stateFor = setupStates({ browser, board, config, baseUrl, base: storageState, viewports })
549
+ if (board.setup)
550
+ log(
551
+ `Setup: ${board.setup.actions.length} action${board.setup.actions.length === 1 ? '' : 's'} from ${board.setup.path}, once per viewport`,
552
+ )
553
+ const links = { from: baseUrl, to: isDefault ? board.publicUrl : env.publicUrl }
554
+ const where = isDefault ? baseUrl : `${env.id} (${baseUrl})`
555
+ log(`Capturing ${pages.length} page${pages.length === 1 ? '' : 's'} (${tasks.length} shots) from ${where}`)
556
+ for (const page of pages) manifest.pages[page.id] = {}
557
+ const found = new Map()
558
+ const pacing = capturePacer(config.capturePacing)
559
+ await pool(tasks, config.concurrency, async ({ page, viewportName }) => {
560
+ await pacing.wait()
561
+ const url = joinUrl(baseUrl, page.path)
562
+ // --only writes over the current shot: keep a copy first, dropped again if the shot fails.
563
+ const before = previous?.pages?.[page.id]?.[viewportName]
564
+ const archived =
565
+ partial && keepVersions
566
+ ? archiveVersion(config, board.id, {
567
+ fromDir: finalDir,
568
+ pageId: page.id,
569
+ viewport: viewportName,
570
+ version: entryVersion(before, previous),
571
+ })
572
+ : []
573
+ const shotAt = new Date()
574
+ const setupStarted = Date.now()
575
+ let state = storageState
576
+ let setupError = null
577
+ try {
578
+ state = await stateFor(page, viewportName)
579
+ } catch (error) {
580
+ setupError = String(error?.message || error).slice(0, 300)
581
+ }
582
+ const entry = setupError
583
+ ? { status: 'failed', url, httpStatus: null, networkSummary: null, error: setupError, ms: Date.now() - setupStarted }
584
+ : await shootPage({
585
+ browser,
586
+ url,
587
+ viewportName,
588
+ size: viewports[viewportName],
589
+ outDir: workDir,
590
+ name: page.id,
591
+ page,
592
+ timeouts: config.timeouts,
593
+ storageState: state,
594
+ liveHtml: config.liveHtml,
595
+ links,
596
+ matchLinks: (hrefs) => linkTargets(hrefs, board, { baseUrl: baseUrl, self: page.id }),
597
+ onHrefs: linkCheck ? (hrefs) => collectLinks(found, hrefs, { baseUrl, pageId: page.id, external: checkExternal }) : null,
598
+ options,
599
+ })
600
+ if (entry.networkSummary?.rateLimited) pacing.rateLimited()
601
+ if (entry.status === 'ok') entry.version = versionId(shotAt)
602
+ else for (const file of archived) fs.rmSync(file, { force: true })
603
+ manifest.pages[page.id][viewportName] = entry
604
+ status.done += 1
605
+ if (entry.status !== 'ok') status.failed += 1
606
+ writeStatus()
607
+ const liveNote = entry.html?.status === 'failed' ? ` (live HTML failed: ${entry.html.error})` : ''
608
+ const expectedNote = entry.expectedStatus ? ` (HTTP ${entry.httpStatus}, expected)` : ''
609
+ const warning = captureWarningText(entry.networkSummary)
610
+ const warningNote = warning ? ` (network warning: ${warning})` : ''
611
+ const skippedNote = entry.skippedActions?.length
612
+ ? ` (skipped optional action${entry.skippedActions.length === 1 ? '' : 's'} ${entry.skippedActions.join(', ')})`
613
+ : ''
614
+ log(
615
+ ` ${entry.status === 'ok' ? 'ok ' : 'FAIL'} ${page.id} ${viewportName} ${entry.status === 'ok' ? `${entry.ms} ms${expectedNote}${skippedNote}${liveNote}${warningNote}` : entry.error}`,
616
+ )
617
+ })
618
+ let linksChecked = 0
619
+ if (linkCheck) {
620
+ let context = null
621
+ try {
622
+ context = await browser.newContext(storageState ? { storageState } : {})
623
+ const request = async (url) => {
624
+ const response = await context.request.get(url, { timeout: 15000, maxRedirects: 10, failOnStatusCode: false })
625
+ const answer = { status: response.status() }
626
+ await response.dispose().catch(() => {})
627
+ return answer
628
+ }
629
+ const result = await checkLinks(found, { board, baseUrl, manifestPages: manifest.pages, request })
630
+ linksChecked = result.checked
631
+ manifest.brokenLinks = partial
632
+ ? mergeBroken(previous?.brokenLinks, result.broken, {
633
+ recaptured: pages.map((page) => page.id),
634
+ board,
635
+ baseUrl,
636
+ manifestPages: manifest.pages,
637
+ })
638
+ : result.broken
639
+ if (result.skipped) log(` (${result.skipped} more links were not checked)`)
640
+ } catch (error) {
641
+ log(` (links not checked: ${String(error.message || error).split('\n')[0]})`)
642
+ if (partial && previous?.brokenLinks) manifest.brokenLinks = previous.brokenLinks
643
+ } finally {
644
+ await context?.close().catch(() => {})
645
+ }
646
+ } else if (partial && previous?.brokenLinks) {
647
+ manifest.brokenLinks = previous.brokenLinks
648
+ }
649
+ manifest.capturedAt = new Date().toISOString()
650
+ manifest.durationMs = Date.now() - started
651
+ writeJsonAtomic(path.join(workDir, 'manifest.json'), manifest)
652
+ if (!partial) {
653
+ if (status.failed === status.total) throw new Error('every shot failed; the previous captures were kept')
654
+ const old = `${finalDir}.prev`
655
+ fs.rmSync(old, { recursive: true, force: true })
656
+ if (fs.existsSync(finalDir)) fs.renameSync(finalDir, old)
657
+ try {
658
+ fs.renameSync(workDir, finalDir)
659
+ } catch (error) {
660
+ // The previous captures go back where they were.
661
+ if (fs.existsSync(old) && !fs.existsSync(finalDir)) fs.renameSync(old, finalDir)
662
+ throw error
663
+ }
664
+ // Shots that were replaced become versions.
665
+ if (keepVersions && previous?.pages) {
666
+ for (const page of pages) {
667
+ for (const viewportName of page.viewports) {
668
+ if (manifest.pages[page.id]?.[viewportName]?.status !== 'ok') continue
669
+ const version = entryVersion(previous.pages[page.id]?.[viewportName], previous)
670
+ archiveVersion(config, board.id, { fromDir: old, pageId: page.id, viewport: viewportName, version })
671
+ }
672
+ }
673
+ }
674
+ fs.rmSync(old, { recursive: true, force: true })
675
+ }
676
+ if (keepVersions) pruneVersions(config, board.id)
677
+ if (!isDefault) {
678
+ // Warm the pixel diffs against the default environment for compare mode.
679
+ await compareEnvironments(config, board, board.environments[0].id, env.id).catch((error) =>
680
+ log(` (diffs not computed: ${error.message})`),
681
+ )
682
+ }
683
+ status.state = 'done'
684
+ status.finishedAt = new Date().toISOString()
685
+ writeStatus()
686
+ const shots = tasks.map(({ page, viewportName }) => {
687
+ const entry = manifest.pages[page.id][viewportName]
688
+ return {
689
+ page: page.id,
690
+ viewport: viewportName,
691
+ url: entry.url,
692
+ status: entry.status,
693
+ httpStatus: entry.httpStatus ?? null,
694
+ expectedStatus: Boolean(entry.expectedStatus),
695
+ networkSummary: entry.networkSummary || null,
696
+ error: entry.error || null,
697
+ ms: entry.ms,
698
+ }
699
+ })
700
+ const expected = shots.filter((shot) => shot.status === 'ok' && shot.expectedStatus).length
701
+ const brokenLinks = manifest.brokenLinks || []
702
+ log(
703
+ `Done: ${status.done - status.failed} ok${expected ? ` (${expected} expected error page${expected === 1 ? '' : 's'})` : ''}, ${status.failed} failed, ${Math.round(manifest.durationMs / 100) / 10}s. Files in ${finalDir}`,
704
+ )
705
+ if (brokenLinks.length) {
706
+ log(`Broken links: ${brokenLinks.length} ("${cliCommand('links --broken')}" lists them)`)
707
+ for (const line of formatBroken(brokenLinks, { max: 10 })) log(line)
708
+ }
709
+ return {
710
+ ok: status.failed === 0,
711
+ board: board.id,
712
+ env: env.id,
713
+ done: status.done,
714
+ failed: status.failed,
715
+ expected,
716
+ total: status.total,
717
+ dir: finalDir,
718
+ durationMs: manifest.durationMs,
719
+ shots,
720
+ brokenLinks,
721
+ linksChecked,
722
+ }
723
+ } catch (error) {
724
+ status.state = 'failed'
725
+ status.error = String(error.message || error).slice(0, 300)
726
+ status.finishedAt = new Date().toISOString()
727
+ writeStatus()
728
+ if (!partial) fs.rmSync(workDir, { recursive: true, force: true })
729
+ throw error
730
+ } finally {
731
+ process.removeListener('SIGINT', onSignal)
732
+ process.removeListener('SIGTERM', onSignal)
733
+ if (browser) await browser.close().catch(() => {})
734
+ releaseLock(lockFile)
735
+ }
736
+ }
737
+
738
+ // Captures one URL as a variant of a page: the same shots, written under
739
+ // variants/<variantId>.*. The caller records it in variants.json.
740
+ export async function captureVariant({ config, boardId, pageId, variantId, url, viewports = null, log = () => {}, chromium = null }) {
741
+ const board = getBoard(config, boardId)
742
+ const page = board.pages.find((item) => item.id === pageId)
743
+ if (!page) throw new Error(`No page "${pageId}" on board "${board.id}"`)
744
+ const outDir = path.join(boardDir(config, board.id), 'variants')
745
+ fs.mkdirSync(outDir, { recursive: true })
746
+ const names = viewports || page.viewports
747
+ const browser = await launchBrowser(config, { chromium })
748
+ const results = {}
749
+ try {
750
+ const storageState = await resolveStorageState(browser, config, board, { log })
751
+ for (const viewportName of names) {
752
+ const entry = await shootPage({
753
+ browser,
754
+ url,
755
+ viewportName,
756
+ size: boardViewports(config, board)[viewportName],
757
+ outDir,
758
+ name: variantId,
759
+ // A variant is drawn in its page's card: the same frame height.
760
+ page: page.frameHeight ? { frameHeight: page.frameHeight } : {},
761
+ timeouts: config.timeouts,
762
+ storageState,
763
+ liveHtml: config.liveHtml,
764
+ links: { from: url, to: null },
765
+ options: captureOptions(config, board),
766
+ })
767
+ results[viewportName] = entry
768
+ log(
769
+ ` ${entry.status === 'ok' ? 'ok ' : 'FAIL'} ${variantId} ${viewportName} ${entry.status === 'ok' ? `${entry.ms} ms` : entry.error}`,
770
+ )
771
+ }
772
+ return results
773
+ } finally {
774
+ await browser.close().catch(() => {})
775
+ }
776
+ }