@sixb/agent 0.2.3 → 0.2.5

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 (149) hide show
  1. package/README.md +3 -3
  2. package/dist/agent-prompt.d.ts.map +1 -1
  3. package/dist/artifacts/layout-check/layout-check.d.ts +21 -24
  4. package/dist/artifacts/layout-check/layout-check.d.ts.map +1 -1
  5. package/dist/artifacts/publish-tool.d.ts +26 -44
  6. package/dist/artifacts/publish-tool.d.ts.map +1 -1
  7. package/dist/ask-tool.d.ts +62 -0
  8. package/dist/ask-tool.d.ts.map +1 -0
  9. package/dist/attachments.d.ts +1 -1
  10. package/dist/attachments.d.ts.map +1 -1
  11. package/dist/background-commands.d.ts +3 -3
  12. package/dist/background-commands.d.ts.map +1 -1
  13. package/dist/background-notices.d.ts.map +1 -1
  14. package/dist/child-files.d.ts +1 -1
  15. package/dist/child-questions.d.ts +1 -1
  16. package/dist/index.d.ts +1 -2
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +10457 -7971
  19. package/dist/index.js.map +46 -38
  20. package/dist/run-agent-turn.d.ts +3 -14
  21. package/dist/run-agent-turn.d.ts.map +1 -1
  22. package/dist/run-conversation-turn.d.ts.map +1 -1
  23. package/dist/run-environment.d.ts +4 -1
  24. package/dist/run-environment.d.ts.map +1 -1
  25. package/dist/run-subagent.d.ts +1 -1
  26. package/dist/run-subagent.d.ts.map +1 -1
  27. package/dist/sandbox-api-context.d.ts.map +1 -1
  28. package/dist/search-script.d.ts +7 -0
  29. package/dist/search-script.d.ts.map +1 -0
  30. package/dist/skills/built-in.d.ts.map +1 -1
  31. package/dist/subagent-tools.d.ts +20 -1
  32. package/dist/subagent-tools.d.ts.map +1 -1
  33. package/dist/tools/background.d.ts +50 -18
  34. package/dist/tools/background.d.ts.map +1 -1
  35. package/dist/tools/bash.d.ts +1 -0
  36. package/dist/tools/bash.d.ts.map +1 -1
  37. package/dist/tools/edit-text.d.ts +22 -0
  38. package/dist/tools/edit-text.d.ts.map +1 -0
  39. package/dist/tools/edit.d.ts +54 -0
  40. package/dist/tools/edit.d.ts.map +1 -0
  41. package/dist/tools/file-writes.d.ts +52 -0
  42. package/dist/tools/file-writes.d.ts.map +1 -0
  43. package/dist/tools/glob.d.ts +41 -0
  44. package/dist/tools/glob.d.ts.map +1 -0
  45. package/dist/tools/grep.d.ts +64 -0
  46. package/dist/tools/grep.d.ts.map +1 -0
  47. package/dist/tools/model-spec.d.ts.map +1 -1
  48. package/dist/tools/read.d.ts +16 -3
  49. package/dist/tools/read.d.ts.map +1 -1
  50. package/dist/tools/sandbox-search.d.ts +26 -0
  51. package/dist/tools/sandbox-search.d.ts.map +1 -0
  52. package/dist/tools/search/command.d.ts +15 -0
  53. package/dist/tools/search/command.d.ts.map +1 -0
  54. package/dist/tools/search/gitignore.d.ts +28 -0
  55. package/dist/tools/search/gitignore.d.ts.map +1 -0
  56. package/dist/tools/search/glob.d.ts +15 -0
  57. package/dist/tools/search/glob.d.ts.map +1 -0
  58. package/dist/tools/search/main.d.ts +2 -0
  59. package/dist/tools/search/main.d.ts.map +1 -0
  60. package/dist/tools/search/match.d.ts +30 -0
  61. package/dist/tools/search/match.d.ts.map +1 -0
  62. package/dist/tools/search/pattern.d.ts +19 -0
  63. package/dist/tools/search/pattern.d.ts.map +1 -0
  64. package/dist/tools/search/read.d.ts +62 -0
  65. package/dist/tools/search/read.d.ts.map +1 -0
  66. package/dist/tools/search/request.d.ts +80 -0
  67. package/dist/tools/search/request.d.ts.map +1 -0
  68. package/dist/tools/search/search.d.ts +4 -0
  69. package/dist/tools/search/search.d.ts.map +1 -0
  70. package/dist/tools/search/walk.d.ts +43 -0
  71. package/dist/tools/search/walk.d.ts.map +1 -0
  72. package/dist/tools/tool-outputs.d.ts.map +1 -1
  73. package/dist/tools/view-file.d.ts +20 -23
  74. package/dist/tools/view-file.d.ts.map +1 -1
  75. package/dist/tools/web-fetch/tool.d.ts +1 -0
  76. package/dist/tools/web-fetch/tool.d.ts.map +1 -1
  77. package/dist/tools/web-search.d.ts +1 -0
  78. package/dist/tools/web-search.d.ts.map +1 -1
  79. package/dist/tools/write.d.ts +36 -0
  80. package/dist/tools/write.d.ts.map +1 -0
  81. package/dist/turn-inbox.d.ts +75 -0
  82. package/dist/turn-inbox.d.ts.map +1 -0
  83. package/package.json +6 -4
  84. package/src/agent-prompt.ts +10 -9
  85. package/src/agent-runtime/preflight.ts +1 -0
  86. package/src/artifacts/layout-check/check.cjs +176 -95
  87. package/src/artifacts/layout-check/layout-check.ts +118 -76
  88. package/src/artifacts/publish-tool.ts +123 -192
  89. package/src/ask-tool.ts +223 -0
  90. package/src/attachments.ts +7 -6
  91. package/src/background-commands.ts +5 -5
  92. package/src/background-notices.ts +5 -12
  93. package/src/child-files.ts +1 -1
  94. package/src/child-questions.ts +1 -1
  95. package/src/context-compaction.ts +4 -1
  96. package/src/generated/search.mjs +985 -0
  97. package/src/index.ts +1 -2
  98. package/src/run-agent-turn.ts +99 -133
  99. package/src/run-child.ts +1 -1
  100. package/src/run-conversation-turn.ts +8 -5
  101. package/src/run-environment.ts +40 -21
  102. package/src/run-subagent.ts +4 -4
  103. package/src/sandbox-api-context.ts +3 -0
  104. package/src/search-script-assets.d.ts +5 -0
  105. package/src/search-script.ts +9 -0
  106. package/src/skills/built-in.ts +16 -0
  107. package/src/skills/sixb-artifacts/SKILL.md +13 -13
  108. package/src/skills/sixb-artifacts/canvas.md +5 -4
  109. package/src/skills/sixb-artifacts/document.md +92 -5
  110. package/src/skills/sixb-artifacts/examples/document/service-proposal/design.css +114 -0
  111. package/src/skills/sixb-artifacts/examples/document/service-proposal/document.html +159 -0
  112. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/fieldwise.svg +1 -0
  113. package/src/skills/sixb-artifacts/examples/document/service-proposal/images/harbor-pine.svg +1 -0
  114. package/src/skills/sixb-artifacts/page.md +2 -2
  115. package/src/skills/sixb-artifacts/queries.md +2 -1
  116. package/src/skills/sixb-artifacts/slides.md +2 -2
  117. package/src/subagent-tools.ts +115 -81
  118. package/src/tools/background.ts +227 -67
  119. package/src/tools/bash.ts +2 -1
  120. package/src/tools/edit-text.ts +241 -0
  121. package/src/tools/edit.ts +166 -0
  122. package/src/tools/file-writes.ts +270 -0
  123. package/src/tools/glob.ts +124 -0
  124. package/src/tools/grep.ts +190 -0
  125. package/src/tools/model-spec.ts +13 -13
  126. package/src/tools/read.ts +75 -9
  127. package/src/tools/sandbox-search.ts +219 -0
  128. package/src/tools/search/command.ts +116 -0
  129. package/src/tools/search/gitignore.ts +101 -0
  130. package/src/tools/search/glob.ts +90 -0
  131. package/src/tools/search/main.ts +9 -0
  132. package/src/tools/search/match.ts +278 -0
  133. package/src/tools/search/pattern.ts +178 -0
  134. package/src/tools/search/read.ts +237 -0
  135. package/src/tools/search/request.ts +101 -0
  136. package/src/tools/search/search.ts +297 -0
  137. package/src/tools/search/walk.ts +145 -0
  138. package/src/tools/tool-outputs.ts +9 -4
  139. package/src/tools/view-file.ts +78 -80
  140. package/src/tools/web-fetch/tool.ts +2 -1
  141. package/src/tools/web-search.ts +1 -0
  142. package/src/tools/write.ts +95 -0
  143. package/src/turn-inbox.ts +283 -0
  144. package/dist/artifacts/board-previews.d.ts +0 -41
  145. package/dist/artifacts/board-previews.d.ts.map +0 -1
  146. package/dist/ask-parent-tool.d.ts +0 -36
  147. package/dist/ask-parent-tool.d.ts.map +0 -1
  148. package/src/artifacts/board-previews.ts +0 -218
  149. package/src/ask-parent-tool.ts +0 -100
@@ -1,7 +1,6 @@
1
1
  import { posix } from "node:path"
2
2
  import type { Sandbox } from "@sixb/core"
3
- import type { ArtifactTheme, ArtifactThemeMode, Canvas } from "@sixb/core/artifacts"
4
- import { SMALL_BOARD_PREVIEW_WIDTH } from "@sixb/core/artifacts"
3
+ import type { ArtifactTheme, Canvas, DocumentPaper } from "@sixb/core/artifacts"
5
4
  import {
6
5
  FRAME_ASSETS,
7
6
  FRAME_DEFAULT_THEMES,
@@ -12,7 +11,6 @@ import {
12
11
  rewriteFrameReferences,
13
12
  } from "@sixb/core/internal/artifacts/frames"
14
13
  import { type ArtifactQueryAnswer, artifactThemeModes } from "@sixb/core/internal/artifacts/publish"
15
- import type { ArtifactBoardPreviewSize } from "@sixb/core/storage"
16
14
  import { loginShellArgs } from "../../login-shell"
17
15
  import { type AgentSandboxHandle, contextPath } from "../../sandbox-handle"
18
16
  import checkScript from "./check.cjs" with { type: "text" }
@@ -34,10 +32,10 @@ export type LayoutCheck =
34
32
  | {
35
33
  readonly status: "checked"
36
34
  readonly warnings: readonly LayoutWarning[]
37
- /** One per slide, or a page's at each width, as the agent names them. */
35
+ /** One per slide, a page's at each width, or a document's pages, as the agent names them. */
38
36
  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[]
37
+ /** How many pages a designed document with paper was cut into. */
38
+ readonly pages?: number
41
39
  /** A canvas as it opens in the app, as the agent names it, when the check took it. */
42
40
  readonly overview?: string
43
41
  }
@@ -61,34 +59,18 @@ export interface CheckedBoard {
61
59
  readonly w: number
62
60
  readonly h: number
63
61
  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
78
62
  }
79
63
 
80
64
  interface CheckReport {
81
65
  /** The layout the check laid the entry out in, which says it ran to the end of its setup. */
82
66
  readonly layout?: CheckLayout
83
67
  readonly slides?: number
68
+ readonly pages?: number
84
69
  readonly problems?: readonly CheckedProblem[]
85
70
  readonly errors?: readonly string[]
86
71
  readonly screenshots?: readonly string[]
87
- readonly previews?: readonly CheckedPreview[]
88
72
  /** A canvas's boards whose page draws larger than the board's `w` by `h`. */
89
73
  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
74
  /** A canvas's boards that stopped answering, which the check went on without. */
93
75
  readonly stalls?: readonly { readonly board: string; readonly message: string }[]
94
76
  readonly overview?: string
@@ -109,10 +91,11 @@ export type CheckedQuery = ArtifactQueryAnswer
109
91
  export type PageView = "desktop" | "phone"
110
92
 
111
93
  /**
112
- * Lays a published deck, page, or canvas out in the sandbox's headless Chromium, as the app's
113
- * frame does, and reports what a reader would find wrong: on each slide of a deck, on a page at a
114
- * laptop's width and a phone's, or on each of a canvas's boards at its own size, with a screenshot
115
- * of each for the Agent to look at. A sandbox without the agent image's browser skips it; so does
94
+ * Lays a published deck, page, designed document, or canvas out in the sandbox's headless
95
+ * Chromium, as the app's frame does, and reports what a reader would find wrong: on each slide of
96
+ * a deck, on a page at a laptop's width and a phone's, on a designed document as one sheet and on
97
+ * each of its pages, or on each of a canvas's boards at its own size, with a screenshot of each for
98
+ * the Agent to look at. A sandbox without the agent image's browser skips it; so does
116
99
  * a check that fails, which never costs the Agent its publish.
117
100
  */
118
101
  export async function checkLayout(
@@ -132,7 +115,12 @@ export async function checkLayout(
132
115
  /** Test seam; production allows 120 seconds. */
133
116
  readonly timeoutMs?: number
134
117
  } & (
135
- | { readonly layout: FrameLayout; readonly entry: Uint8Array }
118
+ | {
119
+ readonly layout: FrameLayout
120
+ readonly entry: Uint8Array
121
+ /** A designed document's paper, which its runtime cuts it into pages by. */
122
+ readonly paper?: DocumentPaper
123
+ }
136
124
  | {
137
125
  readonly layout: "canvas"
138
126
  readonly boards: readonly CheckedBoard[]
@@ -155,13 +143,21 @@ export async function checkLayout(
155
143
  layout: "page" as const,
156
144
  html: board.html,
157
145
  }))
158
- : [{ path: "index.html", layout: input.layout, html: input.entry }]
146
+ : [
147
+ {
148
+ path: input.layout === "document" ? "document.html" : "index.html",
149
+ layout: input.layout,
150
+ html: input.entry,
151
+ },
152
+ ]
153
+ const paper = input.layout !== "canvas" ? input.paper : undefined
159
154
  const entries = pages.map((page) => ({
160
155
  path: page.path,
161
156
  contents: injectFrameAssets(
162
157
  rewriteFrameReferences(new TextDecoder().decode(page.html), [], page.path),
163
158
  page.layout,
164
- page.path
159
+ page.path,
160
+ paper
165
161
  ),
166
162
  }))
167
163
  await sandbox.writeFiles([
@@ -171,6 +167,7 @@ export async function checkLayout(
171
167
  { path: posix.join(library, "check.cjs"), contents: checkScript },
172
168
  { path: posix.join(library, "deck.css"), contents: asset("__sixb/deck.css") },
173
169
  { path: posix.join(library, "page.css"), contents: asset("__sixb/page.css") },
170
+ { path: posix.join(library, "document.css"), contents: asset("__sixb/document.css") },
174
171
  { path: posix.join(library, "runtime.js"), contents: asset("__sixb/runtime.js") },
175
172
  { path: posix.join(library, "probe.js"), contents: `(${layoutProbe.toString()})` },
176
173
  ]),
@@ -189,14 +186,7 @@ export async function checkLayout(
189
186
  {
190
187
  path: posix.join(output, "boards.json"),
191
188
  contents: JSON.stringify(
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
- }))
189
+ input.boards.map(({ id, file, w, h }) => ({ id, file, w, h }))
200
190
  ),
201
191
  },
202
192
  ...overviewFiles(output, input.canvas, input.theme),
@@ -249,30 +239,24 @@ export async function checkLayout(
249
239
  console.warn(`[SixbAgent] The layout check failed: ${detail.slice(0, 500)}`)
250
240
  return { status: "skipped", reason: "the check failed in the sandbox" }
251
241
  }
252
- const noun = { deck: "deck", page: "page", canvas: "canvas" }[input.layout]
253
- const reached = { deck: "Slides", page: "Widths", canvas: "Boards" }[input.layout]
242
+ const noun = { deck: "deck", page: "page", document: "document", canvas: "canvas" }[input.layout]
243
+ const reached = { deck: "Slides", page: "Widths", document: "Pages", canvas: "Boards" }[
244
+ input.layout
245
+ ]
254
246
  const checks = posix.join(input.handle.contextDirectory, CHECKS, input.name)
255
247
  const named = (path: string) => posix.join(checks, posix.relative(output, path))
256
248
  const screenshots = (report.screenshots ?? []).map(named)
257
249
  return {
258
250
  status: "checked",
259
251
  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
- ),
252
+ ...(report.pages ? { pages: report.pages } : {}),
267
253
  ...(report.overview ? { overview: named(report.overview) } : {}),
268
254
  warnings: [
269
- ...layoutWarnings(report.problems ?? []),
255
+ ...layoutWarnings(
256
+ report.problems ?? [],
257
+ input.layout === "document" ? "document" : undefined
258
+ ),
270
259
  ...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
260
  ...(report.stalls ?? []).map(({ board, message }) => ({
277
261
  code: "layout_incomplete",
278
262
  part: board,
@@ -412,10 +396,16 @@ const SEVERITY: readonly LayoutProblem["code"][] = [
412
396
  ]
413
397
  const VIEWS: readonly PageView[] = ["desktop", "phone"]
414
398
 
415
- /** A problem where the check found it: on a deck's slide, or on a page at one width. */
399
+ /**
400
+ * A problem where the check found it: on a deck's slide, on a page at one width, on a designed
401
+ * document's page, or on a designed document as one sheet, at its paper's width, which names none
402
+ * of them, or on a phone.
403
+ */
416
404
  type CheckedProblem = LayoutProblem & {
417
405
  readonly theme: "light" | "dark"
418
406
  readonly slide?: number
407
+ /** A designed document's page. */
408
+ readonly page?: number
419
409
  readonly view?: PageView
420
410
  /** The canvas's board it is on. */
421
411
  readonly board?: string
@@ -427,20 +417,28 @@ type CheckedProblem = LayoutProblem & {
427
417
  * same colors, is one warning naming every slide or width it is at, so a deck's eyebrow at 17px
428
418
  * is one line, not nine. Contrast says which theme it fails in when it fails in one.
429
419
  */
430
- export function layoutWarnings(problems: readonly CheckedProblem[]): LayoutWarning[] {
420
+ export function layoutWarnings(
421
+ problems: readonly CheckedProblem[],
422
+ /** What was checked when it is a designed document, whose problems at a width are its own. */
423
+ checked?: "document"
424
+ ): LayoutWarning[] {
431
425
  const groups = new Map<
432
426
  string,
433
427
  {
434
428
  problem: CheckedProblem
435
429
  slides: Set<number>
430
+ pages: Set<number>
436
431
  views: Set<PageView>
437
432
  boards: Set<string>
433
+ /** Whether it is on a designed document's sheet, at its paper's width: everywhere it shows. */
434
+ sheet: boolean
438
435
  texts: Set<string>
439
436
  themes: Set<string>
440
437
  }
441
438
  >()
442
439
  for (const problem of problems) {
443
- const at = problem.slide ?? problem.view ?? problem.board
440
+ const at =
441
+ problem.slide ?? (problem.page && `page ${problem.page}`) ?? problem.view ?? problem.board
444
442
  const cause =
445
443
  problem.code === "small_text" || problem.code === "small_target"
446
444
  ? `${problem.selector}|${problem.size}`
@@ -451,14 +449,18 @@ export function layoutWarnings(problems: readonly CheckedProblem[]): LayoutWarni
451
449
  const group = groups.get(key) ?? {
452
450
  problem,
453
451
  slides: new Set(),
452
+ pages: new Set(),
454
453
  views: new Set(),
455
454
  boards: new Set(),
455
+ sheet: false,
456
456
  texts: new Set(),
457
457
  themes: new Set(),
458
458
  }
459
459
  if (problem.slide !== undefined) group.slides.add(problem.slide)
460
+ if (problem.page !== undefined) group.pages.add(problem.page)
460
461
  if (problem.view) group.views.add(problem.view)
461
462
  if (problem.board) group.boards.add(problem.board)
463
+ if (at === undefined) group.sheet = true
462
464
  group.texts.add(problem.text)
463
465
  group.themes.add(problem.theme)
464
466
  groups.set(key, group)
@@ -467,37 +469,61 @@ export function layoutWarnings(problems: readonly CheckedProblem[]): LayoutWarni
467
469
  const boardOrder = [
468
470
  ...new Set(problems.flatMap((problem) => (problem.board ? [problem.board] : []))),
469
471
  ]
470
- const first = (group: { slides: Set<number>; views: Set<PageView>; boards: Set<string> }) =>
472
+ const first = (group: {
473
+ slides: Set<number>
474
+ pages: Set<number>
475
+ views: Set<PageView>
476
+ boards: Set<string>
477
+ }) =>
471
478
  group.slides.size > 0
472
479
  ? Math.min(...group.slides)
473
- : group.boards.size > 0
474
- ? Math.min(...[...group.boards].map((board) => boardOrder.indexOf(board)))
475
- : Math.min(...[...group.views].map((view) => VIEWS.indexOf(view)))
480
+ : group.pages.size > 0
481
+ ? Math.min(...group.pages)
482
+ : group.boards.size > 0
483
+ ? Math.min(...[...group.boards].map((board) => boardOrder.indexOf(board)))
484
+ : group.views.size > 0
485
+ ? Math.min(...[...group.views].map((view) => VIEWS.indexOf(view)))
486
+ : 0
476
487
  const ordered = [...groups.values()].sort(
477
488
  (a, b) =>
478
489
  SEVERITY.indexOf(a.problem.code) - SEVERITY.indexOf(b.problem.code) || first(a) - first(b)
479
490
  )
480
491
  const warnings: LayoutWarning[] = ordered
481
492
  .slice(0, MAX_WARNINGS)
482
- .map(({ problem, slides, views, boards, texts, themes }) => {
493
+ .map(({ problem, slides, pages, views, boards, sheet, texts, themes }) => {
483
494
  const theme =
484
495
  problem.code === "contrast" && themes.size === 1 ? ` in ${[...themes][0]} mode` : ""
485
- const page = slides.size === 0
486
496
  const onBoards = boardOrder.filter((board) => boards.has(board))
497
+ // A designed document's problem names its pages, a phone, or, found on its sheet, nothing.
498
+ const place: Place =
499
+ slides.size > 0
500
+ ? "slide"
501
+ : checked !== "document" && (boards.size > 0 || views.size > 0)
502
+ ? "page"
503
+ : "document"
487
504
  const where =
488
505
  onBoards.length > 0
489
506
  ? boardList(onBoards)
490
- : page
491
- ? viewList([...views])
492
- : slideList([...slides])
507
+ : slides.size > 0
508
+ ? slideList([...slides])
509
+ : pages.size > 0
510
+ ? numberedList("Page", [...pages])
511
+ : views.size > 0 && !sheet
512
+ ? viewList([...views])
513
+ : "In the document"
514
+ const part =
515
+ onBoards[0] ??
516
+ (slides.size > 0
517
+ ? String(Math.min(...slides))
518
+ : pages.size > 0
519
+ ? `page ${Math.min(...pages)}`
520
+ : views.size > 0 && !sheet
521
+ ? (VIEWS.find((view) => views.has(view)) ?? "desktop")
522
+ : undefined)
493
523
  return {
494
524
  code: `layout_${problem.code}`,
495
- part:
496
- onBoards[0] ??
497
- (page
498
- ? (VIEWS.find((view) => views.has(view)) ?? "desktop")
499
- : String(Math.min(...slides))),
500
- message: `${where}: ${describeProblem(problem, [...texts], page)}${theme}.`,
525
+ ...(part ? { part } : {}),
526
+ message: `${where}: ${describeProblem(problem, [...texts], place)}${theme}.`,
501
527
  }
502
528
  })
503
529
  const more = ordered.length - warnings.length
@@ -519,7 +545,12 @@ function boardList(boards: readonly string[]): string {
519
545
 
520
546
  /** `Slide 3`, `Slides 1–4 and 7`. */
521
547
  function slideList(slides: number[]): string {
522
- const sorted = [...slides].sort((a, b) => a - b)
548
+ return numberedList("Slide", slides)
549
+ }
550
+
551
+ /** `Page 3`, `Pages 1–4 and 7`: what `noun` names, by number. */
552
+ function numberedList(noun: string, numbers: number[]): string {
553
+ const sorted = [...numbers].sort((a, b) => a - b)
523
554
  const runs: string[] = []
524
555
  for (let index = 0; index < sorted.length; ) {
525
556
  let end = index
@@ -528,7 +559,7 @@ function slideList(slides: number[]): string {
528
559
  index = end + 1
529
560
  }
530
561
  const label = runs.length > 1 ? `${runs.slice(0, -1).join(", ")} and ${runs.at(-1)}` : runs[0]
531
- return `${sorted.length === 1 ? "Slide" : "Slides"} ${label}`
562
+ return `${sorted.length === 1 ? noun : `${noun}s`} ${label}`
532
563
  }
533
564
 
534
565
  /** `On a phone (390px)`, `At 1280px and on a phone`. */
@@ -537,7 +568,10 @@ function viewList(views: PageView[]): string {
537
568
  return views[0] === "phone" ? "On a phone (390px)" : "At 1280px"
538
569
  }
539
570
 
540
- function describeProblem(problem: LayoutProblem, texts: readonly string[], page: boolean): string {
571
+ /** Where a problem is: on a slide, on a web page, or in a designed document. */
572
+ type Place = "slide" | "page" | "document"
573
+
574
+ function describeProblem(problem: CheckedProblem, texts: readonly string[], place: Place): string {
541
575
  const { x, y, width, height } = problem.rect
542
576
  const where = `at ${x},${y} (${width}×${height})`
543
577
  const quoted = texts
@@ -547,17 +581,25 @@ function describeProblem(problem: LayoutProblem, texts: readonly string[], page:
547
581
  const what = `${problem.selector} ${quoted}${texts.length > 2 ? ` and ${texts.length - 2} more` : ""}`
548
582
  switch (problem.code) {
549
583
  case "outside":
550
- return `${what} runs past the slide's edge ${where}, which cuts it off`
584
+ return place === "document"
585
+ ? `${what} runs past the page's edge ${where}, which cuts it off; let it wrap or shrink, or give it a page of its own`
586
+ : `${what} runs past the slide's edge ${where}, which cuts it off`
551
587
  case "footer":
552
588
  return `${what} runs into the footer ${where}; keep content above the source line`
553
589
  case "wide":
590
+ if (place === "document" && problem.view === "phone") {
591
+ return `${what} runs past the screen's right edge ${where}, so the document scrolls sideways; let it wrap, or stack it in an @media screen and (max-width: 600px) rule`
592
+ }
593
+ if (place === "document") {
594
+ return `${what} runs past the sheet's right edge ${where}, past where it can print; let it wrap or shrink`
595
+ }
554
596
  return `${what} runs past the screen's right edge ${where}, so the whole page scrolls sideways; let it wrap or shrink, or put it in a box that scrolls (.table-scroll)`
555
597
  case "overlap":
556
598
  return `${what} is drawn over “${problem.other}” ${where}`
557
599
  case "clipped":
558
600
  return `${what} is cut off by its own box ${where}`
559
601
  case "small_text":
560
- return page
602
+ return place !== "slide"
561
603
  ? `${what} ${texts.length === 1 ? "is" : "are"} ${problem.size}px; nothing on a page may be under 12px`
562
604
  : `${what} ${texts.length === 1 ? "is" : "are"} ${problem.size}px; nothing on a slide may be under 18px`
563
605
  case "small_target":