@erclx/canon 5.67.0 → 5.68.0

package/src/commands/take.ts

@@ -5,6 +5,7 @@ import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { readTakePlan } from '@/take/plan'
 import type { TakePlanRefusal } from '@/take/plan'
 import type { TakeRefusal } from '@/take/film'
+import { renderReel } from '@/take/reel'
 import {
   intro,
   logError,
@@ -24,6 +25,7 @@ type Take = typeof import('@/take/film')
 
 interface RunOptions {
   readonly out: string
+  readonly reel?: string
   readonly json?: boolean
 }
 
@@ -60,14 +62,19 @@ export function register(program: Command): void {
     .argument('<plan>', 'JSON file naming the beats and their steps')
     .requiredOption('--out <dir>', 'Folder the clips, logs, and tracks land in')
     .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--reel <file>',
+      'Also join the beats into one animated WebP with the pointer drawn',
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
       [
         '',
         'Films each beat from a fresh load of the page into its own folder under',
-        '--out, numbered in plan order: clip.mp4, log.json, and camera.json.',
-        'take.json beside them lists every beat and the route that filmed it.',
+        '--out, numbered in plan order: clip.mp4, log.json, camera.json, and',
+        "still.jpg, the clip's closing frame. take.json beside them lists every",
+        'beat and the route that filmed it.',
         '',
         'A step beat is filmed by frame stepping in chrome-headless-shell, at',
         '3840x2160 and exactly 60 fps, with the page clock advancing one frame',
@@ -77,7 +84,13 @@ export function register(program: Command): void {
         '',
         'No cursor is drawn in a clip. The edit draws it from the log at a',
         'constant size, and the camera track carries the cursor and click ring',
-        'per frame beside the view. Canon renders nothing past the clip.',
+        'per frame beside the view. Canon renders nothing past the clip, save',
+        'the reel below.',
+        '',
+        '--reel <file> joins every beat in plan order into one looping animated',
+        'WebP at 960 wide and 20 fps, keeping every third frame, with the cursor',
+        'and click ring drawn from each camera track. It carries no zoom, so a',
+        "reviewer sees the whole page. clip.mp4 stays each beat's raw take.",
         '',
         '  {',
         '    "beats": [',
@@ -118,14 +131,16 @@ export function register(program: Command): void {
         '  server-unreachable  nothing answered at the URL',
         '  target-missing      a step names a target the page does not carry',
         '  take-failed         the take failed against a reachable page',
+        '  reel-failed         every beat was filmed and the reel did not encode',
         '',
         'Exit codes:',
-        '  0  every beat was filmed',
+        '  0  every beat was filmed, and the reel written when asked for',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Examples:',
         '  canon take http://localhost:4173 plan.json --out .canon/tmp/demo/takes',
         '  canon take http://localhost:4173 plan.json --out takes --json',
+        '  canon take http://localhost:4173 plan.json --out takes --reel takes/reel.webp',
         '',
       ].join('\n'),
     )
@@ -222,16 +237,37 @@ async function runTake(
     )
     if (beat.fallback) logWarn(`  filmed by screencast: ${beat.fallback}`)
   }
-  outro()
 
-  emit(emitJson, {
+  const filmed = {
     url,
     plan: path,
     out: result.out,
     beats: result.beats,
     durationMs: result.durationMs,
-  })
-  return 0
+  }
+  if (!opts.reel) {
+    outro()
+    emit(emitJson, filmed)
+    return 0
+  }
+
+  logStep('Reel')
+  try {
+    const reel = await renderReel(result.out, result.beats, resolve(opts.reel))
+    logInfo(
+      `${reel.file}  ${plural(reel.frames, 'frame')}  ${reel.seconds} s  ${(reel.bytes / 1e6).toFixed(1)} MB`,
+    )
+    outro()
+    emit(emitJson, { ...filmed, reel })
+    return 0
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    logWarn('Every beat was filmed, and the reel did not encode.')
+    logWarn(message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, { ...filmed, reason: 'reel-failed', message })
+    return 1
+  }
 }
 
 /**

package/src/pr/evidence.ts

@@ -1,3 +1,5 @@
+import { isPainted, type PaintedPatterns } from '@/pr/painted'
+
 /** The path segment that marks an image as evidence a pull request should compare. */
 const EVIDENCE_SEGMENT = 'evidence'
 
@@ -16,9 +18,22 @@ const PREVIEW_PREFIX = '**Preview:**'
 /** How the address line names the branch's server on the operator's own machine, after any hosted segment. */
 const LOCAL_PREFIX = '**Local preview:**'
 
+/** How the reel line under the addresses opens. */
+const REEL_PREFIX = '**Reel** filmed at'
+
+/** The reel line as `renderEvidenceBody` writes it, read back for the link and the head label. */
+const REEL_LINE =
+  /^\*\*Reel\*\* filmed at `([0-9a-f]{7,40})`:<br><img src="([^"]+)"/
+
+/** The width a reel is filmed at, which it asks for in the comment. */
+const REEL_WIDTH = 960
+
 /** What joins the hosted and local segments on the one address line. */
 const ADDRESS_SEPARATOR = ' · '
 
+/** The summary of the block holding every case whose pixels matched its base. */
+const FOLDED_SUMMARY = 'Within tolerance'
+
 /** The heading every body opens with. */
 const EVIDENCE_HEADING = '## Evidence'
 
@@ -61,6 +76,8 @@ export interface EvidenceItem {
   readonly width?: number
   /** Pixel width of the base image, absent for an added case or an unread header. */
   readonly baseWidth?: number
+  /** Whether the head differs from its base by no more than sub-visual noise. Absent when the pair was not compared. */
+  readonly withinTolerance?: boolean
 }
 
 export interface EvidenceState {
@@ -144,9 +161,9 @@ function rawUrl(repo: string, sha: string, path: string): string {
 }
 
 /**
- * The most pixels a screenshot asks for. GitHub sizes a comment table to its
- * content and clamps an image to its cell, so a width past any comment fills
- * the cell, where `width="100%"` leaves a narrow screenshot narrow. An image
+ * The most pixels a screenshot asks for. GitHub clamps an image to the comment
+ * column, so a width past any comment fills the column, where `width="100%"`
+ * would stretch a narrow screenshot to fill it too. An image
  * asks for the smaller of its own width and this ceiling, so a small crop
  * shows at its true size and is never scaled up. An image whose width was not
  * read asks for the ceiling.
@@ -171,7 +188,7 @@ export function readPngWidth(bytes: Uint8Array): number | undefined {
   return width > 0 ? width : undefined
 }
 
-/** A table cell and an attribute value share one escape, since a stem is a path segment placed in both. */
+/** A label and an attribute value share one escape, since a stem is a path segment placed in both. The pipe stays escaped, since a label once sat in a table cell. */
 function escapeCell(text: string): string {
   return text
     .replaceAll('&', '&amp;')
@@ -238,14 +255,21 @@ function commitLink(repo: string, sha: string): string {
   return `[\`${sha.slice(0, SHORT_SHA_LENGTH)}\`](https://github.com/${repo}/commit/${sha})`
 }
 
-function baseImage(item: EvidenceItem, repo: string, base: string): string {
-  return item.added
-    ? '*(new)*'
-    : evidenceImage(
-        rawUrl(repo, base, item.path),
-        `${escapeCell(item.stem)} base`,
-        item.baseWidth,
-      )
+/** The base folded under its head, so a reviewer reads the new state first and opens the old one on a click. */
+function baseFold(item: EvidenceItem, repo: string, base: string): string[] {
+  return [
+    '<details>',
+    '<summary>Base</summary>',
+    '',
+    evidenceImage(
+      rawUrl(repo, base, item.path),
+      `${escapeCell(item.stem)} base`,
+      item.baseWidth,
+    ),
+    '',
+    '</details>',
+    '',
+  ]
 }
 
 function headImage(item: EvidenceItem, repo: string, head: string): string {
@@ -256,25 +280,45 @@ function headImage(item: EvidenceItem, repo: string, head: string): string {
   )
 }
 
+/**
+ * One case as a label line, its head image on a line of its own, and its base
+ * folded beneath. An added case has no base, so it shows its head alone, and
+ * its label carries the new mark only where the block also holds a base for
+ * the mark to set it apart from.
+ */
+function caseLines(
+  label: string,
+  item: EvidenceItem,
+  hasBase: boolean,
+  repo: string,
+  base: string,
+  head: string,
+): string[] {
+  const mark = item.added && hasBase ? ' *(new)*' : ''
+  return [
+    `**${label}**${mark}`,
+    '',
+    headImage(item, repo, head),
+    '',
+    ...(item.added ? [] : baseFold(item, repo, base)),
+  ]
+}
+
 function block(
   opener: string,
   summary: string,
-  header: readonly string[],
-  rows: readonly string[],
+  cases: readonly string[][],
 ): string {
   return [
     opener,
     `<summary>${summary}</summary>`,
     '',
-    `| ${header.join(' | ')} |`,
-    `| ${header.map(() => '---').join(' | ')} |`,
-    ...rows,
-    '',
+    ...cases.flat(),
     '</details>',
   ].join('\n')
 }
 
-/** One block for the cases of a state that did not name a view, one case per row. */
+/** One block for the cases of a state that did not name a view, each labeled by its name. */
 function renderFlat(
   label: string,
   items: readonly EvidenceItem[],
@@ -284,22 +328,13 @@ function renderFlat(
   opener: string,
 ): string {
   const hasBase = items.some((item) => !item.added)
-  const rows = items.map((item) => {
-    const stem = escapeCell(item.stem)
-    const after = headImage(item, repo, head)
-    return hasBase
-      ? `| ${stem} | ${baseImage(item, repo, base)} | ${after} |`
-      : `| ${stem} | ${after} |`
-  })
-  return block(
-    opener,
-    `${label} (${items.length})`,
-    hasBase ? ['Case', 'Base', 'Head'] : ['Case', 'Head'],
-    rows,
+  const cases = items.map((item) =>
+    caseLines(escapeCell(item.stem), item, hasBase, repo, base, head),
   )
+  return block(opener, `${label} (${items.length})`, cases)
 }
 
-/** One block for a view, a width per row and a theme per column, each theme taking a base column when the view already exists at the base. */
+/** One block for a view, its cases by width and then dark before light, each labeled by width and theme, so a theme missing at a width renders nothing. */
 function renderView(
   label: string,
   cases: readonly ViewCase[],
@@ -308,38 +343,29 @@ function renderView(
   head: string,
   opener: string,
 ): string {
-  const themes = THEMES.filter((theme) =>
-    cases.some((entry) => entry.theme === theme),
-  )
   const hasBase = cases.some((entry) => !entry.item.added)
-  const widths = [...new Set(cases.map((entry) => entry.width))].sort(
-    compareWidths,
+  const ordered = [...cases].sort(
+    (a, b) =>
+      compareWidths(a.width, b.width) ||
+      THEMES.indexOf(a.theme) - THEMES.indexOf(b.theme),
   )
-  const header = [
-    'Width',
-    ...themes.flatMap((theme) => {
-      const name = theme === 'dark' ? 'Dark' : 'Light'
-      return hasBase ? [`${name} base`, `${name} head`] : [name]
-    }),
-  ]
-  const rows = widths.map((width) => {
-    const cells = themes.flatMap((theme) => {
-      const found = cases.find(
-        (entry) => entry.theme === theme && entry.width === width,
-      )
-      if (found === undefined) return hasBase ? ['', ''] : ['']
-      const after = headImage(found.item, repo, head)
-      return hasBase ? [baseImage(found.item, repo, base), after] : [after]
-    })
-    return `| ${[width, ...cells].join(' | ')} |`
-  })
-  return block(opener, `${label} (${cases.length})`, header, rows)
+  const lines = ordered.map((entry) =>
+    caseLines(
+      `${entry.width} · ${entry.theme}`,
+      entry.item,
+      hasBase,
+      repo,
+      base,
+      head,
+    ),
+  )
+  return block(opener, `${label} (${cases.length})`, lines)
 }
 
 /**
  * Renders the blocks of one state: a block per view the case names split
  * into, then one flat block for the names that did not. Nothing is dropped,
- * so a state of unparsed names reads as the flat table it always was.
+ * so a state of unparsed names reads as one flat block.
  */
 function renderState(
   entry: EvidenceState,
@@ -387,18 +413,57 @@ function renderState(
   return blocks
 }
 
+/** A folded case's label, naming its state and view, since the block gathers cases from every state. */
+function foldedLabel(state: string, item: EvidenceItem): string {
+  const name = readCaseName(item.stem)
+  const caseLabel =
+    name === undefined
+      ? escapeCell(item.stem)
+      : `${escapeCell(name.view)} · ${name.width} · ${name.theme}`
+  return state === '' ? caseLabel : `${escapeCell(state)} / ${caseLabel}`
+}
+
+/** One closed block for every case whose pixels matched its base, so the open blocks hold only what visibly moved. */
+function renderFolded(
+  states: readonly EvidenceState[],
+  repo: string,
+  base: string,
+  head: string,
+): string {
+  const cases = states.flatMap((entry) =>
+    entry.items.map((item) =>
+      caseLines(foldedLabel(entry.state, item), item, false, repo, base, head),
+    ),
+  )
+  return block('<details>', `${FOLDED_SUMMARY} (${cases.length})`, cases)
+}
+
+/** A reel embedded in the comment, and the head it was filmed at. */
+export interface EvidenceReel {
+  readonly link: string
+  readonly head: string
+}
+
+function reelLine(reel: EvidenceReel): string {
+  const head = reel.head.slice(0, SHORT_SHA_LENGTH)
+  return `${REEL_PREFIX} \`${head}\`:<br><img src="${escapeCell(reel.link)}" width="${REEL_WIDTH}" alt="reel filmed at ${head}">`
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
 
 /**
  * Renders the whole comment body: one `<details>` block per view within each
- * state, a width per row with a column per theme, a flat Base/Head table for
- * the case names that do not split into a view, and the trailing marker naming
- * the head this body describes.
+ * state, a flat block for the case names that do not split into a view, and
+ * the trailing marker naming the head this body describes. Each case shows its
+ * head at the comment's width with its base folded beneath, since a table
+ * split the column between the two and shrank both to a quarter of their size.
  * Every state opens while the comment carries at most `EVIDENCE_OPEN_LIMIT`
- * images, one per row for the head plus one per row not added, and every state
- * closes past it, so a comment is never half open. A visible line under
+ * head images, and every state closes past it, so a comment is never half
+ * open. A folded base takes no room until opened, so it is not counted. A case
+ * whose pixels matched its base moves to one closed `Within tolerance` block
+ * after the states, still named and embedded, and is not counted either. A visible line under
  * `## Evidence` names the base and head as short shas, each linking its commit. Every image URL is
  * pinned to a commit sha rather than a branch, so the comment keeps showing
  * what it claimed even after the branch moves.
@@ -412,6 +477,9 @@ export function evidenceMarker(head: string): string {
  *
  * A checklist closes the body, below the comparison it annotates, so one
  * comment carries the addresses, the screenshots, and what to look at.
+ *
+ * A reel sits on its own line under the addresses, labeled with the head it
+ * was filmed at, so a reel carried past a later push never reads as current.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -421,6 +489,7 @@ export function renderEvidenceBody(
   preview?: string,
   checklist?: string,
   local?: string,
+  reel?: EvidenceReel,
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -430,6 +499,7 @@ export function renderEvidenceBody(
     EVIDENCE_HEADING,
     '',
     ...(segments.length === 0 ? [] : [segments.join(ADDRESS_SEPARATOR), '']),
+    ...(reel === undefined ? [] : [reelLine(reel), '']),
   ]
   const closing =
     checklist === undefined
@@ -439,17 +509,21 @@ export function renderEvidenceBody(
     return [...opening, ...closing, evidenceMarker(head)].join('\n')
   }
 
-  const imageCount = states.reduce(
-    (total, entry) =>
-      total + entry.items.reduce((sum, item) => sum + (item.added ? 1 : 2), 0),
-    0,
-  )
+  const split = (keep: (item: EvidenceItem) => boolean): EvidenceState[] =>
+    states
+      .map((entry) => ({ ...entry, items: entry.items.filter(keep) }))
+      .filter((entry) => entry.items.length > 0)
+  const open = split((item) => item.withinTolerance !== true)
+  const folded = split((item) => item.withinTolerance === true)
+
+  const headCount = open.reduce((total, entry) => total + entry.items.length, 0)
   const opener =
-    imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
+    headCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
 
-  const sections = states.flatMap((entry) =>
-    renderState(entry, repo, base, head, opener),
-  )
+  const sections = [
+    ...open.flatMap((entry) => renderState(entry, repo, base, head, opener)),
+    ...(folded.length === 0 ? [] : [renderFolded(folded, repo, base, head)]),
+  ]
 
   return [
     ...opening,
@@ -464,18 +538,18 @@ export function renderEvidenceBody(
 
 /**
  * How many cases a rendered body carries. Every case has exactly one head
- * image, so a row counts the head images it holds, which is one in the flat
- * table and up to two in a view's row. A row from before the alt text named
- * its head image counts as one case when it matches the old row shape, so a
- * comment posted before the change still counts its cases and the
- * `would-empty` guard holds.
+ * image, so the count is the head images on any line, whether a table row
+ * holding one or two or a line of its own. A table row from before the alt
+ * text named its head image counts as one case when it matches the old row
+ * shape, so a comment posted in any earlier layout still counts its cases and
+ * the `would-empty` guard holds.
  */
 export function countEvidenceCases(body: string): number {
   let total = 0
   for (const line of body.split('\n')) {
-    if (!line.startsWith('| ')) continue
     const heads = line.match(HEAD_IMAGE_PATTERN)?.length ?? 0
-    total += heads > 0 ? heads : LEGACY_ROW_PATTERN.test(line) ? 1 : 0
+    if (heads > 0) total += heads
+    else if (line.startsWith('| ') && LEGACY_ROW_PATTERN.test(line)) total += 1
   }
   return total
 }
@@ -529,6 +603,34 @@ export function readOwed(input: OwedInput): OwedStep[] {
   return owed
 }
 
+/**
+ * Design references are redrawn rather than captured, so recapturing them
+ * neither owes nor stands in for an evidence capture.
+ */
+const DESIGN_FOLDER = 'canon/design/'
+
+/**
+ * The painted paths a pull request changed while no evidence image did, in a
+ * project whose base keeps captures. Undefined when the base keeps none or
+ * was not read, since an empty list reads as checked and clean. Any changed
+ * evidence image clears the list, since this names a skipped capture rather
+ * than judging which views a capture covered.
+ */
+export function readUncaptured(
+  changed: readonly string[],
+  patterns: PaintedPatterns,
+  keepsCaptures: boolean | undefined,
+): string[] | undefined {
+  if (keepsCaptures !== true) return undefined
+  if (changed.some(isEvidencePath)) return []
+  return changed.filter(
+    (path) =>
+      evidencePosition(path) === -1 &&
+      !path.startsWith(DESIGN_FOLDER) &&
+      isPainted(path, patterns),
+  )
+}
+
 /**
  * The REST id of the comment this module already posted, read off its `url`
  * field, since `gh pr view --json comments` reports only a GraphQL id there
@@ -639,6 +741,34 @@ export function findEvidenceLocal(
   return marked === undefined ? undefined : readAddresses(marked.body).local
 }
 
+/** The reel the marked comment already embeds, with the head it was filmed at. */
+export function findEvidenceReel(
+  comments: readonly EvidenceComment[],
+): EvidenceReel | undefined {
+  const marked = findMarked(comments)
+  if (marked === undefined) return undefined
+  for (const line of marked.body.split('\n')) {
+    const match = REEL_LINE.exec(line.trim())
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      return { link: match[2].replaceAll('&amp;', '&'), head: match[1] }
+    }
+  }
+  return undefined
+}
+
+/**
+ * The reel a render embeds: a passed link, filmed at this head, replaces
+ * whatever the comment carries, and with none passed the posted reel carries
+ * forward under the head it was filmed at.
+ */
+export function nextEvidenceReel(
+  link: string | undefined,
+  head: string,
+  comments: readonly EvidenceComment[],
+): EvidenceReel | undefined {
+  return link === undefined ? findEvidenceReel(comments) : { link, head }
+}
+
 /**
  * The checklist the marked comment already carries, read back out of its
  * delimiters. The handoff file is deleted once posted, so every later render

package/src/pr/frames.ts

@@ -9,6 +9,16 @@ export const LEGACY_FRAMES_BRANCH = 'canon-frames'
 /** The eight bytes every PNG opens with. A frame that lacks them embeds as a broken image. */
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
 
+/** A WebP opens on `RIFF`, four bytes of size, then `WEBP`. */
+const RIFF = [0x52, 0x49, 0x46, 0x46]
+const WEBP = [0x57, 0x45, 0x42, 0x50]
+
+/**
+ * The largest reel an add takes, GitHub's cap on an image in a comment, so a
+ * reel that would not render is refused before it reaches the branch.
+ */
+export const REEL_MAX_BYTES = 10_000_000
+
 const SHORT_HEAD_LENGTH = 7
 
 const HEAD_PATTERN = /^[0-9a-f]{7,40}$/
@@ -86,9 +96,16 @@ export interface FrameInput {
   readonly box?: number
   readonly reference?: string
   readonly theme?: FrameTheme
+  /** The pass's reel, in place of a box or a reference. */
+  readonly reel?: boolean
   readonly bytes: Uint8Array
 }
 
+export type ReelRead =
+  | { readonly kind: 'read'; readonly bytes: Uint8Array }
+  | { readonly kind: 'unreadable' }
+  | { readonly kind: 'too-large'; readonly size: number }
+
 export type PushResult =
   | {
       readonly kind: 'pushed'
@@ -206,6 +223,25 @@ export function referencePath(
   return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/ref-${slug}.png`
 }
 
+/** Where a pass's reel lands, one per pass beside its box frames. */
+export function reelPath(number: number, head: string, pass: string): string {
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/reel.webp`
+}
+
+/** The reel's bytes, refusing a file that is absent, not a WebP, or past the cap. */
+export async function readReel(path: string): Promise<ReelRead> {
+  const bytes = await readFile(path).catch(() => undefined)
+  if (bytes === undefined || bytes.length <= 12) return { kind: 'unreadable' }
+  const webp =
+    RIFF.every((byte, index) => bytes[index] === byte) &&
+    WEBP.every((byte, index) => bytes[index + 8] === byte)
+  if (!webp) return { kind: 'unreadable' }
+  if (bytes.length > REEL_MAX_BYTES) {
+    return { kind: 'too-large', size: bytes.length }
+  }
+  return { kind: 'read', bytes: new Uint8Array(bytes) }
+}
+
 /** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
 export async function readFrame(path: string): Promise<Uint8Array | undefined> {
   const bytes = await readFile(path).catch(() => undefined)
@@ -227,8 +263,9 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path =
-    input.reference === undefined
+  const path = input.reel
+    ? reelPath(input.number, input.head, input.pass)
+    : input.reference === undefined
       ? framePath(
           input.number,
           input.head,
@@ -241,8 +278,9 @@ export async function pushFrame(
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
-  const message =
-    input.reference === undefined
+  const message = input.reel
+    ? `chore(frames): add reel of #${input.number}`
+    : input.reference === undefined
       ? `chore(frames): add box ${input.box} of #${input.number}`
       : `chore(frames): add reference ${input.reference} of #${input.number}`
 

package/src/pr/pixels.ts

@@ -0,0 +1,44 @@
+import pixelmatch from 'pixelmatch'
+import { PNG } from 'pngjs'
+
+/** How different two colors must be for a pixel to count, where 1 is black against white. Playwright's 0.2 passed a real contrast fix. */
+const COLOR_THRESHOLD = 0.1
+
+/** The side of the square the count is taken over, so noise scattered across the image never adds up while a compact change does. */
+const WINDOW_SIZE = 16
+
+/** The most differing pixels any window may hold and still read as noise. Measured on Frameboard, noise counted 2 or fewer and real changes 14 or more. */
+const MAX_WINDOW_PIXELS = 6
+
+function decode(bytes: Uint8Array): PNG | undefined {
+  try {
+    return PNG.sync.read(Buffer.from(bytes))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether two PNG captures differ by no more than sub-visual noise. Anti-aliased
+ * pixels are counted rather than skipped, since antialias detection reads a
+ * changed 1px border as an edge artifact, and the windowed count separates
+ * scattered edge noise from a compact change on its own. A pair that does not decode or differs in size reads as changed, so
+ * nothing the comparison cannot read is ever folded.
+ */
+export function isWithinTolerance(base: Uint8Array, head: Uint8Array): boolean {
+  const before = decode(base)
+  const after = decode(head)
+  if (before === undefined || after === undefined) return false
+  if (before.width !== after.width || before.height !== after.height) {
+    return false
+  }
+  const count = pixelmatch(
+    before.data,
+    after.data,
+    null,
+    before.width,
+    before.height,
+    { threshold: COLOR_THRESHOLD, includeAA: true, windowSize: WINDOW_SIZE },
+  )
+  return count <= MAX_WINDOW_PIXELS
+}