@sixb/agent 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/README.md +2 -2
  2. package/dist/artifacts/board-previews.d.ts +41 -0
  3. package/dist/artifacts/board-previews.d.ts.map +1 -0
  4. package/dist/artifacts/layout-check/layout-check.d.ts +38 -6
  5. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  6. package/dist/artifacts/layout-check/overview.d.ts +17 -0
  7. package/dist/artifacts/layout-check/overview.d.ts.map +1 -0
  8. package/dist/artifacts/materialize.d.ts +56 -24
  9. package/dist/artifacts/materialize.d.ts.map +1 -1
  10. package/dist/artifacts/publish-tool.d.ts +35 -27
  11. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  12. package/dist/ask-tool.d.ts +62 -0
  13. package/dist/ask-tool.d.ts.map +1 -0
  14. package/dist/attachments.d.ts +1 -1
  15. package/dist/attachments.d.ts.map +1 -1
  16. package/dist/background-commands.d.ts +3 -3
  17. package/dist/background-commands.d.ts.map +1 -1
  18. package/dist/background-notices.d.ts.map +1 -1
  19. package/dist/child-files.d.ts +1 -1
  20. package/dist/child-questions.d.ts +1 -1
  21. package/dist/index.d.ts +2 -1
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +12309 -10490
  24. package/dist/index.js.map +41 -35
  25. package/dist/run-agent-turn.d.ts.map +1 -1
  26. package/dist/run-conversation-turn.d.ts.map +1 -1
  27. package/dist/run-environment.d.ts +4 -1
  28. package/dist/run-environment.d.ts.map +1 -1
  29. package/dist/run-subagent.d.ts +1 -1
  30. package/dist/sandbox-files.d.ts +19 -0
  31. package/dist/sandbox-files.d.ts.map +1 -1
  32. package/dist/subagent-tools.d.ts +23 -2
  33. package/dist/subagent-tools.d.ts.map +1 -1
  34. package/dist/tools/background.d.ts +50 -18
  35. package/dist/tools/background.d.ts.map +1 -1
  36. package/dist/tools/bash.d.ts +1 -0
  37. package/dist/tools/bash.d.ts.map +1 -1
  38. package/dist/tools/edit-text.d.ts +22 -0
  39. package/dist/tools/edit-text.d.ts.map +1 -0
  40. package/dist/tools/edit.d.ts +54 -0
  41. package/dist/tools/edit.d.ts.map +1 -0
  42. package/dist/tools/file-writes.d.ts +52 -0
  43. package/dist/tools/file-writes.d.ts.map +1 -0
  44. package/dist/tools/model-spec.d.ts.map +1 -1
  45. package/dist/tools/read.d.ts +16 -3
  46. package/dist/tools/read.d.ts.map +1 -1
  47. package/dist/tools/tool-files.d.ts.map +1 -1
  48. package/dist/tools/view-file.d.ts +20 -23
  49. package/dist/tools/view-file.d.ts.map +1 -1
  50. package/dist/tools/web-fetch/tool.d.ts +1 -0
  51. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  52. package/dist/tools/web-search.d.ts +1 -0
  53. package/dist/tools/web-search.d.ts.map +1 -1
  54. package/dist/tools/write.d.ts +36 -0
  55. package/dist/tools/write.d.ts.map +1 -0
  56. package/dist/types.d.ts +5 -4
  57. package/dist/types.d.ts.map +1 -1
  58. package/package.json +7 -6
  59. package/src/agent-prompt.ts +10 -10
  60. package/src/artifacts/board-previews.ts +218 -0
  61. package/src/artifacts/layout-check/check.cjs +304 -80
  62. package/src/artifacts/layout-check/layout-check.ts +119 -9
  63. package/src/artifacts/layout-check/overview.ts +291 -0
  64. package/src/artifacts/materialize.ts +181 -55
  65. package/src/artifacts/publish-tool.ts +475 -163
  66. package/src/ask-tool.ts +223 -0
  67. package/src/attachments.ts +7 -6
  68. package/src/background-commands.ts +5 -5
  69. package/src/background-notices.ts +5 -12
  70. package/src/child-files.ts +1 -1
  71. package/src/child-questions.ts +1 -1
  72. package/src/context-compaction.ts +4 -1
  73. package/src/index.ts +2 -1
  74. package/src/run-agent-turn.ts +14 -4
  75. package/src/run-child.ts +1 -1
  76. package/src/run-conversation-turn.ts +4 -1
  77. package/src/run-environment.ts +40 -26
  78. package/src/run-subagent.ts +3 -3
  79. package/src/sandbox-api-context.ts +1 -1
  80. package/src/sandbox-files.ts +86 -0
  81. package/src/skills/sixb-artifacts/SKILL.md +48 -25
  82. package/src/skills/sixb-artifacts/canvas.md +140 -18
  83. package/src/skills/sixb-artifacts/examples/canvas/onboarding-flow/canvas.json +1 -1
  84. package/src/skills/sixb-artifacts/page.md +2 -2
  85. package/src/skills/sixb-artifacts/references.md +15 -12
  86. package/src/skills/sixb-artifacts/sheet.md +1 -1
  87. package/src/skills/sixb-artifacts/slides.md +2 -2
  88. package/src/subagent-tools.ts +134 -88
  89. package/src/tools/background.ts +227 -67
  90. package/src/tools/bash.ts +2 -1
  91. package/src/tools/edit-text.ts +241 -0
  92. package/src/tools/edit.ts +166 -0
  93. package/src/tools/file-writes.ts +270 -0
  94. package/src/tools/model-spec.ts +9 -12
  95. package/src/tools/read.ts +75 -9
  96. package/src/tools/tool-files.ts +3 -1
  97. package/src/tools/tool-outputs.ts +2 -2
  98. package/src/tools/view-file.ts +78 -80
  99. package/src/tools/web-fetch/tool.ts +2 -1
  100. package/src/tools/web-search.ts +1 -0
  101. package/src/tools/write.ts +95 -0
  102. package/src/types.ts +5 -4
  103. package/dist/ask-parent-tool.d.ts +0 -36
  104. package/dist/ask-parent-tool.d.ts.map +0 -1
  105. package/src/ask-parent-tool.ts +0 -100
@@ -3,15 +3,22 @@
3
3
  // sandbox's headless Chromium. A deck shows at 1280×720 with each slide filling the page, and every
4
4
  // slide is measured in each of its themes with the layout probe and screenshot in the first. A page
5
5
  // loads at 1280px and at a phone's 390px, is measured whole in each theme, its top 4000px, and
6
- // screenshot at each width. A canvas's boards load each at its own size, measured as a page is and
7
- // screenshot as boards/<id>.png. It writes one line of JSON:
8
- // { layout, slides, problems, errors, screenshots, stopped? } or { skipped }.
6
+ // screenshot at each width. A canvas's boards load each at its own size, four at a time, measured
7
+ // as a page is and screenshot as boards/<id>.png; a board boards.json marks `pictured` also in
8
+ // each other theme, as boards/<id>.<theme>.png, and each of its pictures for readers also at most
9
+ // `smallWidth` wide, as boards/<id>.<theme>.small.webp; a board whose page did not load whole is
10
+ // not pictured, but listed in `unpictured`, as a broken picture would stay. With overview.html, the
11
+ // whole canvas as it opens is screenshot as overview.png. It writes one line of JSON:
12
+ // { layout, slides, problems, errors, screenshots, previews, unpictured, oversized, stalls,
13
+ // overview?, stopped? } or
14
+ // { skipped }.
9
15
  //
10
16
  // node check.cjs <directory> <output directory> <library directory> <deadline in ms> <layout>
11
17
  //
12
18
  // The library holds what the worker installs beside this script: deck.css, page.css, runtime.js,
13
19
  // probe.js. The output directory holds entries.json, each page the check opens by its path, with
14
- // the kit and runtime in it; boards.json, a canvas's boards and their sizes; files.json,
20
+ // the kit and runtime in it; boards.json, a canvas's boards and their sizes; overview.html and
21
+ // overview.json, a canvas's page of itself and the window it opens in; files.json,
15
22
  // the paths the version publishes: only those are served, since the reader gets only those; and
16
23
  // themes.json, the themes the reader sees it in: Sixb's light and dark, or the mode its
17
24
  // theme.json pins, with its tokens; and queries.json, the version's queries by name with the
@@ -27,6 +34,7 @@
27
34
  const http = require("node:http")
28
35
  const fs = require("node:fs")
29
36
  const path = require("node:path")
37
+ const { pathToFileURL } = require("node:url")
30
38
 
31
39
  const [deck, out, lib, deadline, layout = "deck"] = process.argv.slice(2)
32
40
  const DEADLINE_MS = Number(deadline) || 100_000
@@ -63,9 +71,66 @@ const TYPES = {
63
71
  ".otf": "font/otf",
64
72
  }
65
73
 
74
+ /**
75
+ * How large a board's page draws, in CSS pixels: its document's scroll size, or its largest
76
+ * element's, which a page that clips its overflow still lays out, such as a fixed 1280×720 frame.
77
+ * Run in the page.
78
+ */
79
+ function contentSize() {
80
+ const root = document.documentElement
81
+ let w = Math.max(root.scrollWidth, document.body?.scrollWidth ?? 0)
82
+ let h = Math.max(root.scrollHeight, document.body?.scrollHeight ?? 0)
83
+ for (const element of document.body?.querySelectorAll("*") ?? []) {
84
+ const rect = element.getBoundingClientRect()
85
+ w = Math.max(w, rect.width)
86
+ h = Math.max(h, rect.height)
87
+ }
88
+ return { w: Math.round(w), h: Math.round(h) }
89
+ }
90
+
91
+ /** How far a page may pass its board before it is too large for it: a scrollbar, a rounding. */
92
+ const slack = (size) => Math.max(4, Math.round(size * 0.02))
93
+
94
+ /** How many of a canvas's boards the check opens at once, each in a browser context of its own. */
95
+ const LANES = 4
96
+ /** A laptop's width, and reduced motion: what animates in is measured and shown where it lands. */
97
+ const PAGE_OPTIONS = {
98
+ viewport: { width: 1280, height: 720 },
99
+ deviceScaleFactor: 1,
100
+ reducedMotion: "reduce",
101
+ }
102
+ const NOUN = { canvas: "the canvas", page: "the page" }[layout] ?? "the deck"
103
+
66
104
  /** What the check has found so far, which a check that stops early reports. */
67
- const found = { layout, slides: 0, problems: [], errors: [], screenshots: [] }
68
- const findings = () => ({ ...found, errors: [...new Set(found.errors)].slice(0, 10) })
105
+ const found = {
106
+ layout,
107
+ slides: 0,
108
+ problems: [],
109
+ errors: [],
110
+ screenshots: [],
111
+ // A canvas's: each board's picture in each theme the reader sees it in, the boards that stopped
112
+ // answering, and the whole canvas as it opens.
113
+ previews: [],
114
+ unpictured: [],
115
+ // A canvas's boards whose page draws larger than the board shows.
116
+ oversized: [],
117
+ stalls: [],
118
+ overview: undefined,
119
+ }
120
+ /** A canvas's boards by their place in it: its lanes finish in any order. */
121
+ let boardOrder = new Map()
122
+ const byBoard = (left, right) =>
123
+ (boardOrder.get(left.board) ?? 0) - (boardOrder.get(right.board) ?? 0)
124
+ const findings = () => ({
125
+ ...found,
126
+ errors: [...new Set(found.errors)].slice(0, 10),
127
+ problems: [...found.problems].sort(byBoard),
128
+ screenshots: [...found.screenshots].sort(
129
+ (left, right) => byBoard({ board: shotBoard(left) }, { board: shotBoard(right) })
130
+ ),
131
+ previews: [...found.previews].sort(byBoard),
132
+ })
133
+ const shotBoard = (file) => path.basename(file, ".png")
69
134
 
70
135
  let reported = false
71
136
  /** Writes the report, then exits once it is written. */
@@ -103,6 +168,230 @@ function loadPlaywright() {
103
168
  return null
104
169
  }
105
170
 
171
+ /** A stall: a bound of the check's, or one of Playwright's, ran out. */
172
+ function isStall(error) {
173
+ return error instanceof Stalled || error?.name === "TimeoutError"
174
+ }
175
+
176
+ /**
177
+ * A page the check opens, with what it reports of loading listened for, and the ways to drive it,
178
+ * each bounded and named after the step `stepOf` says it is at.
179
+ */
180
+ function openTab(page, stepOf) {
181
+ const { errors } = found
182
+ // What failed to load since the page last loaded: a picture of it would show it broken.
183
+ const failures = []
184
+ const failed = (message) => {
185
+ errors.push(message)
186
+ failures.push(message)
187
+ }
188
+ page.on("pageerror", (error) => errors.push(error.message))
189
+ // A file that fails names itself; Chromium's console line for it does not.
190
+ const local = (url) => url.replace(/^http:\/\/127\.0\.0\.1:\d+\//, "")
191
+ page.on("console", (message) => {
192
+ if (message.type() === "error" && !message.text().startsWith("Failed to load resource")) {
193
+ errors.push(message.text())
194
+ }
195
+ })
196
+ page.on("requestfailed", (request) => failed(`${local(request.url())} did not load`))
197
+ page.on("response", (response) => {
198
+ if (response.status() >= 400) {
199
+ failed(`${local(response.url())} did not load (${response.status()})`)
200
+ }
201
+ })
202
+
203
+ // A font or a library from a CDN may be out of reach; the entry is measured as it loaded.
204
+ const load = async (url) => {
205
+ failures.length = 0
206
+ await page
207
+ .goto(url, { waitUntil: "load", timeout: 15_000 })
208
+ .catch((error) => failed(`${NOUN} did not finish loading: ${error.message}`))
209
+ // Each theme is measured as it settles, not on its way there.
210
+ await within(
211
+ stepOf(),
212
+ page.addStyleTag({
213
+ content: "*, *::before, *::after { transition-duration: 0s !important; transition-delay: 0s !important; }",
214
+ })
215
+ ).catch(() => {})
216
+ await within(`${NOUN}'s fonts`, page.evaluate(() => document.fonts?.ready)).catch(() => {})
217
+ }
218
+ const settle = () =>
219
+ within(
220
+ stepOf(),
221
+ page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))))
222
+ )
223
+ const send = (method, params) =>
224
+ within(
225
+ stepOf(),
226
+ page.evaluate(
227
+ ({ protocol, method, params }) =>
228
+ window.postMessage({ protocol, id: 0, method, params }, "*"),
229
+ { protocol: PROTOCOL, method, params }
230
+ )
231
+ )
232
+ return { page, load, settle, send, failures }
233
+ }
234
+
235
+ /**
236
+ * A canvas's boards, each at its own size in each theme, a few at once. Each lane is a browser
237
+ * context of its own, so a board that stops answering costs only its lane, which goes on in a new
238
+ * one. A board's first theme is screenshot as boards/<id>.png; a board marked `pictured`, which
239
+ * the reader sees as a picture until they open it, in every theme, the others as
240
+ * boards/<id>.<theme>.png. Then the whole canvas as it opens, when overview.html says how. Returns
241
+ * whether a board stalled.
242
+ */
243
+ async function checkCanvas(browser, port, probe, themes) {
244
+ const boards = JSON.parse(fs.readFileSync(path.join(out, "boards.json"), "utf8"))
245
+ boardOrder = new Map(boards.map((board, index) => [board.id, index]))
246
+ fs.mkdirSync(path.join(out, "boards"), { recursive: true })
247
+
248
+ const names = Object.keys(themes)
249
+ const waiting = [...boards]
250
+ let stalled = false
251
+
252
+ const open = async () => {
253
+ const context = await within("the browser", browser.newContext(PAGE_OPTIONS))
254
+ let step = NOUN
255
+ const tab = openTab(await within("the browser", context.newPage()), () => step)
256
+ return { ...tab, context, at: (next) => (step = next) }
257
+ }
258
+
259
+ const checkBoard = async (tab, board) => {
260
+ tab.at(`board '${board.id}'`)
261
+ await tab.page.setViewportSize({ width: board.w, height: Math.min(board.h, PAGE_HEIGHT) })
262
+ await tab.load(`http://127.0.0.1:${port}/${board.file.split("/").map(encodeURIComponent).join("/")}`)
263
+
264
+ const pictures = []
265
+ for (const [index, name] of names.entries()) {
266
+ const step = tab.at(`board '${board.id}' in ${name} mode`)
267
+ await tab.send("theme", themes[name])
268
+ await tab.settle()
269
+ for (const problem of await within(step, tab.page.evaluate(`(${probe})("page")`))) {
270
+ found.problems.push({ ...problem, board: board.id, theme: name })
271
+ }
272
+ if (index === 0) {
273
+ const page = await within(step, tab.page.evaluate(contentSize))
274
+ if (page.w > board.w + slack(board.w) || page.h > board.h + slack(board.h)) {
275
+ found.oversized.push({ board: board.id, w: board.w, h: board.h, page })
276
+ }
277
+ }
278
+
279
+ if (index > 0 && !board.pictured) continue
280
+ const file = path.join(out, "boards", index === 0 ? `${board.id}.png` : `${board.id}.${name}.png`)
281
+ const png = await tab.page.screenshot({ path: file, timeout: STEP_MS })
282
+ if (index === 0) found.screenshots.push(file)
283
+ if (!board.pictured || tab.failures.length > 0) continue
284
+
285
+ const small = path.join(out, "boards", `${board.id}.${name}.small.webp`)
286
+ await shrink(browser, png, board.smallWidth, small)
287
+ pictures.push(
288
+ { board: board.id, theme: name, size: "full", path: file, bytes: png.length },
289
+ { board: board.id, theme: name, size: "small", path: small, bytes: fs.statSync(small).size }
290
+ )
291
+ }
292
+
293
+ // A page that did not load whole is pictured broken, and its picture would stay: none is
294
+ // taken, and the board keeps its outline until it loads.
295
+ if (!board.pictured) return
296
+ if (tab.failures.length > 0) {
297
+ found.unpictured.push({ board: board.id, reason: tab.failures[0] })
298
+ return
299
+ }
300
+ found.previews.push(...pictures)
301
+ }
302
+
303
+ const lane = async () => {
304
+ let tab = await open()
305
+ for (let board = waiting.shift(); board; board = waiting.shift()) {
306
+ try {
307
+ await checkBoard(tab, board)
308
+ } catch (error) {
309
+ if (!isStall(error)) throw error
310
+ stalled = true
311
+ found.stalls.push({
312
+ board: board.id,
313
+ message: error instanceof Stalled ? error.message : `board '${board.id}' did not respond in time`,
314
+ })
315
+ // Its page may be frozen and keep its context from closing: exiting kills both.
316
+ void within("the browser", tab.context.close(), 5_000).catch(() => {})
317
+ tab = await open()
318
+ }
319
+ }
320
+ await within("the browser", tab.context.close(), 5_000).catch(() => {})
321
+ }
322
+
323
+ await Promise.all(Array.from({ length: Math.min(LANES, boards.length) }, lane))
324
+ await overview(browser)
325
+ return stalled
326
+ }
327
+
328
+ /** How a small picture's WebP is encoded: as sharp as text needs at its size, by eye. */
329
+ const SMALL_QUALITY = 0.85
330
+ /** A blank page where small pictures are encoded, apart from every board's scripts. */
331
+ let encoder
332
+
333
+ /**
334
+ * A board's screenshot at most `width` wide, its aspect kept, as WebP in `file`: what a canvas
335
+ * shows when it draws the board small. Encoded by the browser's own canvas.
336
+ */
337
+ async function shrink(browser, png, width, file) {
338
+ encoder ??= within("the browser", browser.newContext()).then((context) =>
339
+ within("the browser", context.newPage())
340
+ )
341
+ const page = await encoder
342
+ const webp = await within(
343
+ "a small picture",
344
+ page.evaluate(
345
+ async ({ data, width, quality }) => {
346
+ const image = new Image()
347
+ image.src = `data:image/png;base64,${data}`
348
+ await image.decode()
349
+ const scale = Math.min(1, width / image.naturalWidth)
350
+ const canvas = document.createElement("canvas")
351
+ canvas.width = Math.max(1, Math.round(image.naturalWidth * scale))
352
+ canvas.height = Math.max(1, Math.round(image.naturalHeight * scale))
353
+ const context = canvas.getContext("2d")
354
+ context.imageSmoothingQuality = "high"
355
+ context.drawImage(image, 0, 0, canvas.width, canvas.height)
356
+ const blob = await new Promise((done) => canvas.toBlob(done, "image/webp", quality))
357
+ if (blob?.type !== "image/webp") throw new Error("this browser does not encode WebP")
358
+ const bytes = new Uint8Array(await blob.arrayBuffer())
359
+ let binary = ""
360
+ for (let at = 0; at < bytes.length; at += 0x8000) {
361
+ binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000))
362
+ }
363
+ return btoa(binary)
364
+ },
365
+ { data: png.toString("base64"), width, quality: SMALL_QUALITY }
366
+ )
367
+ )
368
+ fs.writeFileSync(file, Buffer.from(webp, "base64"))
369
+ }
370
+
371
+ /**
372
+ * overview.html, the whole canvas as the app opens it with each board its picture, screenshot
373
+ * as overview.png at the size overview.json gives. One that fails leaves the check as it is.
374
+ */
375
+ async function overview(browser) {
376
+ const html = path.join(out, "overview.html")
377
+ if (!fs.existsSync(html)) return
378
+
379
+ const viewport = JSON.parse(fs.readFileSync(path.join(out, "overview.json"), "utf8"))
380
+ let context
381
+ try {
382
+ context = await within("the overview", browser.newContext({ viewport, deviceScaleFactor: 1 }))
383
+ const page = await within("the overview", context.newPage())
384
+ await page.goto(pathToFileURL(html).href, { waitUntil: "load", timeout: 15_000 })
385
+ const file = path.join(out, "overview.png")
386
+ await page.screenshot({ path: file, timeout: STEP_MS })
387
+ found.overview = file
388
+ } catch {
389
+ // Without its overview, the Agent still has each board's screenshot.
390
+ } finally {
391
+ if (context) await within("the browser", context.close(), 5_000).catch(() => {})
392
+ }
393
+ }
394
+
106
395
  function serve() {
107
396
  // Each page the check opens, with the kit and the runtime in it, by its path in the version.
108
397
  const entries = JSON.parse(fs.readFileSync(path.join(out, "entries.json"), "utf8"))
@@ -159,84 +448,19 @@ async function main() {
159
448
  server.close()
160
449
  return { skipped: "no_browser", detail: String(error?.message ?? error).slice(0, 300) }
161
450
  }
162
- const noun = { canvas: "the canvas", page: "the page" }[layout] ?? "the deck"
163
- let step = noun
451
+ let step = NOUN
164
452
  let stalled = false
453
+ const { port } = server.address()
165
454
  try {
166
- // Reduced motion, so what animates in is measured and shown where it lands.
167
- const page = await browser.newPage({
168
- viewport: { width: 1280, height: 720 },
169
- deviceScaleFactor: 1,
170
- reducedMotion: "reduce",
171
- })
172
- const { errors, problems, screenshots } = found
173
- page.on("pageerror", (error) => errors.push(error.message))
174
- // A file that fails names itself; Chromium's console line for it does not.
175
- const local = (url) => url.replace(/^http:\/\/127\.0\.0\.1:\d+\//, "")
176
- page.on("console", (message) => {
177
- if (message.type() === "error" && !message.text().startsWith("Failed to load resource")) {
178
- errors.push(message.text())
179
- }
180
- })
181
- page.on("requestfailed", (request) => errors.push(`${local(request.url())} did not load`))
182
- page.on("response", (response) => {
183
- if (response.status() >= 400) {
184
- errors.push(`${local(response.url())} did not load (${response.status()})`)
185
- }
186
- })
187
- const { port } = server.address()
188
- // A font or a library from a CDN may be out of reach; the entry is measured as it loaded.
189
- const load = async (url) => {
190
- await page
191
- .goto(url, { waitUntil: "load", timeout: 15_000 })
192
- .catch((error) => errors.push(`${noun} did not finish loading: ${error.message}`))
193
- // Each theme is measured as it settles, not on its way there.
194
- await within(
195
- step,
196
- page.addStyleTag({
197
- content: "*, *::before, *::after { transition-duration: 0s !important; transition-delay: 0s !important; }",
198
- })
199
- ).catch(() => {})
200
- await within(`${noun}'s fonts`, page.evaluate(() => document.fonts?.ready)).catch(() => {})
201
- }
202
- const settle = () =>
203
- within(
204
- step,
205
- page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))))
206
- )
207
- const send = (method, params) =>
208
- within(
209
- step,
210
- page.evaluate(
211
- ({ protocol, method, params }) =>
212
- window.postMessage({ protocol, id: 0, method, params }, "*"),
213
- { protocol: PROTOCOL, method, params }
214
- )
215
- )
216
455
  if (layout === "canvas") {
217
- // Each board at its own size, as the canvas shows it, in each theme.
218
- const boards = JSON.parse(fs.readFileSync(path.join(out, "boards.json"), "utf8"))
219
- fs.mkdirSync(path.join(out, "boards"), { recursive: true })
220
- for (const board of boards) {
221
- step = `board '${board.id}'`
222
- await page.setViewportSize({ width: board.w, height: Math.min(board.h, PAGE_HEIGHT) })
223
- await load(`http://127.0.0.1:${port}/${board.file.split("/").map(encodeURIComponent).join("/")}`)
224
- for (const [index, name] of Object.keys(themes).entries()) {
225
- step = `board '${board.id}' in ${name} mode`
226
- await send("theme", themes[name])
227
- await settle()
228
- for (const problem of await within(step, page.evaluate(`(${probe})("page")`))) {
229
- problems.push({ ...problem, board: board.id, theme: name })
230
- }
231
- if (index === 0) {
232
- const file = path.join(out, "boards", `${board.id}.png`)
233
- await page.screenshot({ path: file, timeout: STEP_MS })
234
- screenshots.push(file)
235
- }
236
- }
237
- }
456
+ stalled = await checkCanvas(browser, port, probe, themes)
238
457
  return findings()
239
458
  }
459
+ const { page, load, settle, send } = openTab(
460
+ await browser.newPage(PAGE_OPTIONS),
461
+ () => step
462
+ )
463
+ const { problems, screenshots } = found
240
464
  if (layout === "page") {
241
465
  for (const view of VIEWS) {
242
466
  step = `the page at ${view.width}px`
@@ -303,7 +527,7 @@ async function main() {
303
527
  } catch (error) {
304
528
  // Playwright's own timeouts, for a slide that never shows or a screenshot never taken, are
305
529
  // stalls too.
306
- if (!(error instanceof Stalled) && error?.name !== "TimeoutError") throw error
530
+ if (!isStall(error)) throw error
307
531
  stalled = true
308
532
  return {
309
533
  ...findings(),
@@ -1,6 +1,7 @@
1
1
  import { posix } from "node:path"
2
2
  import type { Sandbox } from "@sixb/core"
3
- import type { ArtifactTheme } from "@sixb/core/artifacts"
3
+ import type { ArtifactTheme, ArtifactThemeMode, Canvas } from "@sixb/core/artifacts"
4
+ import { SMALL_BOARD_PREVIEW_WIDTH } from "@sixb/core/artifacts"
4
5
  import {
5
6
  FRAME_ASSETS,
6
7
  FRAME_DEFAULT_THEMES,
@@ -10,9 +11,12 @@ import {
10
11
  layoutProbe,
11
12
  rewriteFrameReferences,
12
13
  } from "@sixb/core/internal/artifacts/frames"
14
+ import { type ArtifactQueryAnswer, artifactThemeModes } from "@sixb/core/internal/artifacts/publish"
15
+ import type { ArtifactBoardPreviewSize } from "@sixb/core/storage"
13
16
  import { loginShellArgs } from "../../login-shell"
14
17
  import { type AgentSandboxHandle, contextPath } from "../../sandbox-handle"
15
18
  import checkScript from "./check.cjs" with { type: "text" }
19
+ import { canvasOverviewHtml, OVERVIEW_VIEWPORT } from "./overview"
16
20
 
17
21
  /** The check's library and each check's files, in the run's context directory. */
18
22
  const LIBRARY = "lib/layout-check"
@@ -32,6 +36,10 @@ export type LayoutCheck =
32
36
  readonly warnings: readonly LayoutWarning[]
33
37
  /** One per slide, or a page's at each width, as the agent names them. */
34
38
  readonly screenshots: readonly string[]
39
+ /** Each `pictured` board in each mode the reader sees it in, at its path in the sandbox. */
40
+ readonly previews: readonly CheckedPreview[]
41
+ /** A canvas as it opens in the app, as the agent names it, when the check took it. */
42
+ readonly overview?: string
35
43
  }
36
44
  | { readonly status: "skipped"; readonly reason: string }
37
45
 
@@ -53,6 +61,20 @@ export interface CheckedBoard {
53
61
  readonly w: number
54
62
  readonly h: number
55
63
  readonly html: Uint8Array
64
+ /** Screenshot in every mode, not only the first: it needs its pictures for readers. */
65
+ readonly pictured?: boolean
66
+ }
67
+
68
+ /** A board's picture in one mode and size, which the check took. */
69
+ export interface CheckedPreview {
70
+ readonly board: string
71
+ readonly theme: ArtifactThemeMode
72
+ /** `full`, a PNG of the board; `small`, a WebP at most 480 pixels wide. */
73
+ readonly size: ArtifactBoardPreviewSize
74
+ /** Absolute, in the sandbox. */
75
+ readonly path: string
76
+ /** How large the check wrote it. */
77
+ readonly bytes?: number
56
78
  }
57
79
 
58
80
  interface CheckReport {
@@ -62,6 +84,14 @@ interface CheckReport {
62
84
  readonly problems?: readonly CheckedProblem[]
63
85
  readonly errors?: readonly string[]
64
86
  readonly screenshots?: readonly string[]
87
+ readonly previews?: readonly CheckedPreview[]
88
+ /** A canvas's boards whose page draws larger than the board's `w` by `h`. */
89
+ readonly oversized?: readonly OversizedBoard[]
90
+ /** A canvas's boards not pictured: something on their page did not load. */
91
+ readonly unpictured?: readonly { readonly board: string; readonly reason: string }[]
92
+ /** A canvas's boards that stopped answering, which the check went on without. */
93
+ readonly stalls?: readonly { readonly board: string; readonly message: string }[]
94
+ readonly overview?: string
65
95
  /** Why the check stopped before it finished; what it found until then is above. */
66
96
  readonly stopped?: string
67
97
  readonly skipped?: string
@@ -73,7 +103,7 @@ interface CheckReport {
73
103
  * What a page's `sixb.query(name)` reads in the check: the query route's JSON as it answers the
74
104
  * requester, or why the query failed for them.
75
105
  */
76
- export type CheckedQuery = { readonly result: unknown } | { readonly error: string }
106
+ export type CheckedQuery = ArtifactQueryAnswer
77
107
 
78
108
  /** A width a page is checked at, as a laptop and a phone show it. */
79
109
  export type PageView = "desktop" | "phone"
@@ -103,7 +133,12 @@ export async function checkLayout(
103
133
  readonly timeoutMs?: number
104
134
  } & (
105
135
  | { readonly layout: FrameLayout; readonly entry: Uint8Array }
106
- | { readonly layout: "canvas"; readonly boards: readonly CheckedBoard[] }
136
+ | {
137
+ readonly layout: "canvas"
138
+ readonly boards: readonly CheckedBoard[]
139
+ /** The canvas's items, for a picture of it as it opens; none without. */
140
+ readonly canvas?: Canvas
141
+ }
107
142
  )
108
143
  ): Promise<LayoutCheck> {
109
144
  const { sandbox } = input.handle
@@ -154,9 +189,17 @@ export async function checkLayout(
154
189
  {
155
190
  path: posix.join(output, "boards.json"),
156
191
  contents: JSON.stringify(
157
- input.boards.map(({ id, file, w, h }) => ({ id, file, w, h }))
192
+ input.boards.map(({ id, file, w, h, pictured }) => ({
193
+ id,
194
+ file,
195
+ w,
196
+ h,
197
+ pictured: pictured === true,
198
+ ...(pictured ? { smallWidth: SMALL_BOARD_PREVIEW_WIDTH } : {}),
199
+ }))
158
200
  ),
159
201
  },
202
+ ...overviewFiles(output, input.canvas, input.theme),
160
203
  ]
161
204
  : []),
162
205
  { path: posix.join(output, "themes.json"), contents: JSON.stringify(deckThemes(input.theme)) },
@@ -209,14 +252,32 @@ export async function checkLayout(
209
252
  const noun = { deck: "deck", page: "page", canvas: "canvas" }[input.layout]
210
253
  const reached = { deck: "Slides", page: "Widths", canvas: "Boards" }[input.layout]
211
254
  const checks = posix.join(input.handle.contextDirectory, CHECKS, input.name)
212
- const screenshots = (report.screenshots ?? []).map((path) =>
213
- posix.join(checks, posix.relative(output, path))
214
- )
255
+ const named = (path: string) => posix.join(checks, posix.relative(output, path))
256
+ const screenshots = (report.screenshots ?? []).map(named)
215
257
  return {
216
258
  status: "checked",
217
259
  screenshots,
260
+ // Only pictures of the boards asked for, where the check writes them.
261
+ previews: (report.previews ?? []).filter(
262
+ ({ board, path }) =>
263
+ input.layout === "canvas" &&
264
+ input.boards.some((each) => each.id === board && each.pictured) &&
265
+ path.startsWith(`${output}/`)
266
+ ),
267
+ ...(report.overview ? { overview: named(report.overview) } : {}),
218
268
  warnings: [
219
269
  ...layoutWarnings(report.problems ?? []),
270
+ ...oversizedWarnings(report.oversized ?? []),
271
+ ...(report.unpictured ?? []).map(({ board, reason }) => ({
272
+ code: "preview_not_taken",
273
+ part: board,
274
+ message: `Board '${board}' has no preview: ${reason.slice(0, 200)}, and a picture of it would show it broken to every reader. It shows its outline until a version loads whole.`,
275
+ })),
276
+ ...(report.stalls ?? []).map(({ board, message }) => ({
277
+ code: "layout_incomplete",
278
+ part: board,
279
+ message: `Board '${board}' stopped answering: ${message.slice(0, 200)}. The check went on without it.`,
280
+ })),
220
281
  ...(report.errors ?? []).map((error) => ({
221
282
  code: "layout_load_error",
222
283
  message: `While the ${noun} loaded: ${error.slice(0, 200)}.`,
@@ -261,15 +322,36 @@ function queryFiles(
261
322
  * pins, each with the deck's tokens over Sixb's.
262
323
  */
263
324
  function deckThemes(theme: ArtifactTheme | undefined) {
264
- const modes = theme?.mode ? [theme.mode] : (["light", "dark"] as const)
265
325
  return Object.fromEntries(
266
- modes.map((mode) => {
326
+ artifactThemeModes(theme).map((mode) => {
267
327
  const base = FRAME_DEFAULT_THEMES[mode]
268
328
  return [mode, { ...base, tokens: { ...base.tokens, ...theme?.tokens } }]
269
329
  })
270
330
  )
271
331
  }
272
332
 
333
+ /**
334
+ * A canvas's page of itself as it opens, in the first theme the reader sees it in, each board
335
+ * the screenshot the check takes of it, and the window to screenshot it in.
336
+ */
337
+ function overviewFiles(
338
+ output: string,
339
+ canvas: Canvas | undefined,
340
+ theme: ArtifactTheme | undefined
341
+ ): { path: string; contents: string }[] {
342
+ if (!canvas) return []
343
+
344
+ const [mode = "light"] = artifactThemeModes(theme)
345
+ const tokens = { ...FRAME_DEFAULT_THEMES[mode].tokens, ...theme?.tokens }
346
+ return [
347
+ {
348
+ path: posix.join(output, "overview.html"),
349
+ contents: canvasOverviewHtml({ canvas, tokens, image: (id) => `boards/${id}.png` }),
350
+ },
351
+ { path: posix.join(output, "overview.json"), contents: JSON.stringify(OVERVIEW_VIEWPORT) },
352
+ ]
353
+ }
354
+
273
355
  function asset(path: string): string {
274
356
  const file = FRAME_ASSETS[path]
275
357
  if (!file) throw new Error(`[SixbAgent] The frame has no '${path}'.`)
@@ -287,6 +369,34 @@ function parseReport(stdout: string): CheckReport | null {
287
369
  }
288
370
  }
289
371
 
372
+ /** A board whose page draws larger than the board, in CSS pixels. */
373
+ interface OversizedBoard {
374
+ readonly board: string
375
+ readonly w: number
376
+ readonly h: number
377
+ readonly page: { readonly w: number; readonly h: number }
378
+ }
379
+
380
+ /**
381
+ * Each board whose page is larger than the board: the canvas, its preview, and the opened board
382
+ * all show only its top left. The board takes the page's size; the canvas's zoom makes it small.
383
+ */
384
+ export function oversizedWarnings(boards: readonly OversizedBoard[]): LayoutWarning[] {
385
+ const warnings: LayoutWarning[] = boards.slice(0, MAX_WARNINGS).map(({ board, w, h, page }) => ({
386
+ code: "layout_board_too_small",
387
+ part: board,
388
+ message: `Board '${board}' is ${w}×${h} but its page draws ${page.w}×${page.h}, so the canvas, its preview and the opened board show only its top left. Set its "w" and "h" in canvas.json to ${Math.max(w, page.w)} and ${Math.max(h, page.h)}: the canvas's zoom draws it small, never a smaller board.`,
389
+ }))
390
+ const more = boards.length - warnings.length
391
+ if (more > 0) {
392
+ warnings.push({
393
+ code: "layout_board_too_small",
394
+ message: `${more} more board${more === 1 ? "" : "s"} draw a page larger than the board; give each board its page's size.`,
395
+ })
396
+ }
397
+ return warnings
398
+ }
399
+
290
400
  /** The most a check reports; the screenshots show the rest. */
291
401
  const MAX_WARNINGS = 12
292
402
  const SEVERITY: readonly LayoutProblem["code"][] = [