@erclx/canon 5.66.0 → 5.68.0

package/src/commands/pr.ts

@@ -32,17 +32,22 @@ import {
   findEvidenceHead,
   findEvidenceLocal,
   findEvidencePreview,
+  findEvidenceReel,
   type EvidenceItem,
   type EvidenceReading,
   groupEvidence,
   hasMarkedEvidenceComment,
+  isEvidencePath,
   PNG_HEADER_BYTES,
   readChecklistBoxes,
   readOwed,
   readPngWidth,
+  readUncaptured,
+  nextEvidenceReel,
   renderEvidenceBody,
   settleChecklist,
 } from '@/pr/evidence'
+import { isWithinTolerance } from '@/pr/pixels'
 import {
   dropFramesWithLegacy,
   FRAMES_BRANCH,
@@ -56,7 +61,9 @@ import {
   LEGACY_FRAMES_BRANCH,
   pruneFramesWithLegacy,
   pushFrame,
+  REEL_MAX_BYTES,
   readFrame,
+  readReel,
   isDesignReference,
   referenceSlug,
   type TreeEntry,
@@ -83,14 +90,12 @@ import {
   type MergeRequest,
 } from '@/pr/merge'
 import { listWorktrees } from '@/git/worktree'
+import { branchSlug, buildDriveCopy, loadPreviewConfig } from '@/pr/drive-copy'
 import {
-  branchSlug,
-  buildDriveCopy,
   changedSince,
-  loadPreviewConfig,
   readWorktreeStatus,
   type StatusEntry,
-} from '@/pr/drive-copy'
+} from '@/git/status'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import { LOCAL_CONFIG_REL, readHealthPaths } from '@/pr/health'
@@ -164,6 +169,7 @@ interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
   readonly local?: string
+  readonly reel?: string
   readonly check?: boolean
 }
 
@@ -274,6 +280,7 @@ interface FramesOptions extends ReadOptions {
   readonly head?: string
   readonly pass?: string
   readonly theme?: string
+  readonly reel?: string
   readonly drop?: boolean
   readonly prune?: string
 }
@@ -289,6 +296,8 @@ type FramesCommandRefusal =
   | 'bad-theme'
   | 'bad-days'
   | 'unreadable-frame'
+  | 'unreadable-reel'
+  | 'reel-too-large'
   | 'read-only'
   | 'gh-missing'
   | 'gh-failed'
@@ -296,22 +305,25 @@ type FramesCommandRefusal =
 
 const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
   'bad-mode':
-    'Pass exactly one of --add, --drop, or --prune. --prune reads every pull request on the branch, so it takes no number.',
+    'Pass exactly one of --add, --reel, --drop, or --prune. --prune reads every pull request on the branch, so it takes no number.',
   'no-number':
-    '--add and --drop write for one pull request, so name its number.',
+    '--add, --reel, and --drop write for one pull request, so name its number.',
   'bad-box':
-    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference, as <page>/<frame> or a tracked canon/design/<surface>/<name> path, never both.',
+    '--add takes --box <n>, a positive whole number naming the checklist box, or --reference, as <page>/<frame> or a tracked canon/design/<surface>/<name> path, never both. --reel takes neither, since a pass has one reel.',
   'bad-reference':
     '--reference takes <page>/<frame> or a tracked canon/design/<surface>/<name> path, each half opening on a letter or digit and holding only letters, digits, dots, underscores, and dashes, with no `--` in either, so the capture files under a name that reads back as the frame.',
   'bad-head':
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
-    '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
+    '--add and --reel take --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
   'bad-theme':
     '--theme takes dark or light and goes with --add --box, so a second shot of one box never replaces the first.',
   'bad-days': '--prune takes a positive whole number of days.',
   'unreadable-frame':
     'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
+  'unreadable-reel':
+    'The file named by --reel is missing, empty, or not a WebP, so it would not play in the comment. Nothing is pushed.',
+  'reel-too-large': `The file named by --reel is past ${REEL_MAX_BYTES / 1_000_000} MB, the most GitHub renders as an image in a comment. Film fewer or shorter beats. Nothing is pushed.`,
   'read-only': `GitHub refused the write to ${FRAMES_BRANCH}. The token cannot write this repository, which is what a fork pull request's workflow token gets, so describe the frame in words instead.`,
   'gh-missing':
     'gh is not on the path, so the branch could not be read or written.',
@@ -417,7 +429,7 @@ type EvidenceRefusal =
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'check-writes':
-    '--check is a read and renders no body, so it takes none of --preview, --local, or --checklist. Run the check and the render as two calls.',
+    '--check is a read and renders no body, so it takes none of --preview, --local, --checklist, or --reel. Run the check and the render as two calls.',
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
@@ -754,6 +766,10 @@ export function register(program: Command): void {
       '--local <url>',
       "Add this worktree's running server to the address line, from canon pr local",
     )
+    .option(
+      '--reel <link>',
+      'Embed this reel under the address line, filmed at the head, from canon pr frames --reel',
+    )
     .option(
       '--check',
       'Report which post-pull-request steps the thread is still owed, rendering nothing',
@@ -784,6 +800,19 @@ export function register(program: Command): void {
         'the hosted and local previews with " · ", carrying whichever apply,',
         'then the Base and Head line when there are screenshots.',
         '',
+        'Each case shows its head image at the comment width under a bold',
+        'label, with its base folded beneath in a <details> block, and an',
+        'added case shows its head alone. Every state opens while the comment',
+        'carries at most six head images and closes past that.',
+        '',
+        'Each modified PNG is compared with its base pixel by pixel. A case',
+        'whose densest 16px square holds 6 or fewer differing pixels moves to',
+        'one closed "Within tolerance" block after the states, still named and',
+        'embedded, and stops counting toward the six. Its item on the record',
+        'carries `withinTolerance`, which is absent for an added case, a',
+        'format other than PNG, or a pair with a failed read. None of those',
+        'folds, and neither does a pair that differs in size or will not decode.',
+        '',
         '--preview puts the hosted address on that line. With no evidence in',
         'the diff, the body is the heading, that line, and the marker alone,',
         'reported as ok, so the preview still lands in one comment a later',
@@ -813,6 +842,13 @@ export function register(program: Command): void {
         'comment. Together with --checklist the link and the checklist land in',
         'one comment.',
         '',
+        '--reel embeds an animated reel on its own line under the addresses,',
+        'labeled with the head this render describes as the one it was filmed',
+        'at. Without --reel, a reel the marked comment already embeds is carried',
+        'forward under the head it names, so a stale reel never reads as',
+        'current, and a passed one replaces it. Like --local it rides on a',
+        'checklist or a comparison and never opens a comment alone.',
+        '',
         "A render at a new head also resets the pull request body's UI pass",
         'line, the one `canon pr tick` writes under ## Testing, to unchecked',
         'naming that head. It touches no other body text, leaves a line already',
@@ -822,6 +858,7 @@ export function register(program: Command): void {
         'present only when that comment holds it:',
         '  preview    the hosted **Preview:** address the comment carries',
         '  local      the **Local preview:** address beside it',
+        '  reel       the embedded reel, as `link` and the `head` it was filmed at',
         '  checklist  the checklist between its delimiters, ticks included',
         '  boxes      each checklist box with its number, tick, stamp, and taste',
         '             mark, the numbering `canon pr tick` takes',
@@ -831,6 +868,16 @@ export function register(program: Command): void {
         'unread thread refuses as gh-failed on both reasons rather than',
         'reporting the fields absent.',
         '',
+        'The ok, no-evidence, and --check records carry `uncaptured`, the',
+        'painted paths the pull request changed while no evidence image did, in',
+        "a project whose base branch's tree holds one. Painted is the set",
+        '`canon/config/painted.json` tunes, minus any path under an evidence/',
+        'segment or canon/design/, and any changed evidence image empties the',
+        'list. The field is absent when the base tree holds no capture or could',
+        'not be read, a cut-short listing showing none included, so absent means',
+        'unchecked rather than clean. It never adds to `owed`, since no step of',
+        'the ship chain can take a capture.',
+        '',
         '--check reads the same changed set and thread, renders no body, and',
         'reports what the ship chain still owes the pull request:',
         '  settled  nothing is owed',
@@ -841,7 +888,7 @@ export function register(program: Command): void {
         'request changed, and the marked comment carries no **Preview:**',
         'address. A failed deploy reads the same as a skipped one.',
         'The record carries `owed` and the same marked fields. --check refuses',
-        'with --preview, --local, or --checklist as check-writes.',
+        'with --preview, --local, --checklist, or --reel as check-writes.',
         '',
         'Refusals, read off `reason`:',
         '  unreadable-checklist  --checklist named a path that could not be read,',
@@ -864,6 +911,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
         '  canon pr evidence 1341 --local http://localhost:5173 --json',
+        '  canon pr evidence 1341 --reel <link from canon pr frames --reel> --json',
         '  canon pr evidence 1341 --check --json',
         '',
       ].join('\n'),
@@ -1306,18 +1354,28 @@ export function register(program: Command): void {
       [
         '',
         'A project names what its preview writes in',
-        '`canon/config/preview.json` as `{ "writes": [path], "env": "<NAME>" }`.',
+        '`canon/config/preview.json` as',
+        '`{ "writes": [path], "keep": [path], "env": "<NAME>" }`.',
         'Each `writes` path is relative to the worktree, and `env`, defaulting',
         'to `CANON_PREVIEW_ROOT`, is the variable the server reads for the copy',
         'root. The server resolves each declared path under that root.',
         '',
+        'Each `keep` path sits below a `writes` path, never equal to one, and',
+        'names state the running server owns there, such as a run file. A',
+        "rebuild leaves it in the copy and never copies the worktree's own, so",
+        'list it for a server that writes under a declared path. The key is',
+        'optional.',
+        '',
         'The copy lives at `.canon/tmp/pr/review-ui/<slug>/board/` at the main',
         'worktree root, where `<slug>` is the branch with a leading type',
         'segment dropped and each `/` made `-`. With a number the branch is the',
         "pull request's head, and without one it is the checkout's, so the",
         'worker starting its server before a pull request exists and the',
         'reviewer naming the number land on one copy. Every run but --check',
-        "rebuilds it from the worktree, dropping the last pass's drives.",
+        "resets each declared path from the worktree, dropping the last pass's",
+        'drives, and leaves the rest of the copy root and each `keep` path as',
+        'they are. A page added only to the copy, inside a declared path, is',
+        'wiped.',
         '',
         '--baseline records `git status` for the worktree under',
         '`.canon/tmp/pr/review-ui/<number>/`, and --check reports each path',
@@ -1388,6 +1446,10 @@ export function register(program: Command): void {
       '--theme <theme>',
       'The theme the frame was shot at, dark or light, with --add, keeping two shots of one box apart',
     )
+    .option(
+      '--reel <file>',
+      "Push this animated WebP as the pass's reel, in place of --add",
+    )
     .option('--drop', "Rewrite the branch without this pull request's frames")
     .option(
       '--prune <days>',
@@ -1409,6 +1471,11 @@ export function register(program: Command): void {
         'segment keeps a second pass at one head and box from replacing an image',
         'an earlier comment shows. The first --add creates the branch.',
         '',
+        `--reel <file> pushes one animated WebP of at most ${REEL_MAX_BYTES / 1_000_000} MB to`,
+        'pr-<number>/<short-head>/<pass>/reel.webp beside the box frames, taking',
+        '--pass and --head the way --add does, and carries `reel: true` in place of',
+        'a box. A drop or a prune clears it with the rest of the folder.',
+        '',
         '--drop and --prune write one root commit and force-move the ref,',
         'since a delete commit would keep every image reachable through history.',
         'A rewrite that empties the branch deletes it. --prune keeps a pull',
@@ -1422,15 +1489,17 @@ export function register(program: Command): void {
         '',
         'Read `reason` on the JSON record:',
         '  ok                an add pushed, or a drop or prune finished',
-        '  bad-mode          not exactly one of --add, --drop, --prune',
-        '  no-number         --add or --drop named no pull request',
-        '  bad-box           --add with both --box and --reference, or neither',
+        '  bad-mode          not exactly one of --add, --reel, --drop, --prune',
+        '  no-number         --add, --reel, or --drop named no pull request',
+        '  bad-box           --add with both --box and --reference, or neither, or --reel with either',
         '  bad-reference     --reference is not <page>/<frame> or canon/design/<surface>/<name> in the safe name form, or the tracked path is no file',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
-        '  bad-pass          --add without a compact UTC --pass stamp',
+        '  bad-pass          --add or --reel without a compact UTC --pass stamp',
         '  bad-theme         --theme is not dark or light, or no --add, or rides a --reference',
         '  bad-days          --prune without a positive number of days',
         '  unreadable-frame  the --add file is missing, empty, or not a PNG',
+        '  unreadable-reel   the --reel file is missing, empty, or not a WebP',
+        `  reel-too-large    the --reel file is past ${REEL_MAX_BYTES / 1_000_000} MB`,
         '  read-only         GitHub refused the write, as on a fork token',
         '  unreadable-tip    the branch could not be read',
         '  push-failed       a write failed and the ref did not move',
@@ -1445,6 +1514,7 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon pr frames 1341 --add frames/3.png --box 3 --pass 20261002T154450Z --json',
+        '  canon pr frames 1341 --reel reel.webp --pass 20261002T154450Z --json',
         '  canon pr frames 1341 --drop --json',
         '  canon pr frames --prune 30 --json',
         '',
@@ -2358,6 +2428,31 @@ function everyChangedPath(files: PullFiles): string[] {
   return [...files.present.keys(), ...files.removed]
 }
 
+/**
+ * Whether the base branch's tree holds an evidence image, read recursively
+ * over the API so the answer is the same from any checkout. GitHub cuts a
+ * large listing short, and a cut listing proves captures only when one
+ * arrived before the cut, so it reads as unread otherwise. Undefined on any
+ * failed read.
+ */
+async function readBaseKeepsCaptures(
+  cwd: string,
+  baseRef: string | undefined,
+): Promise<boolean | undefined> {
+  if (baseRef === undefined || baseRef === '') return undefined
+  const stdout = await gh(cwd, [
+    'api',
+    `repos/{owner}/{repo}/git/trees/${baseRef}?recursive=1`,
+    '--jq',
+    '.truncated, (.tree[] | select(.type == "blob") | .path)',
+  ])
+  if (stdout === null) return undefined
+  const [truncated, ...paths] = stdout.split('\n').filter(Boolean)
+  if (truncated !== 'true' && truncated !== 'false') return undefined
+  if (paths.some(isEvidencePath)) return true
+  return truncated === 'true' ? undefined : false
+}
+
 /**
  * The commit the pull request diverged from its base at, from the compare
  * endpoint, since a checkout on another branch resolves its own trunk tip
@@ -2378,25 +2473,30 @@ async function readPullMergeBase(
   return sha === null || sha.trim() === '' ? undefined : sha.trim()
 }
 
-/** How many width reads run at once, since each downloads a whole image. */
-const WIDTH_READ_CONCURRENCY = 4
+/** How many cases are read at once. Each reads its images one after another, so this bounds both the downloads in flight and the pairs held for comparison. */
+const IMAGE_READ_CONCURRENCY = 4
 
-type WidthRead =
-  | { readonly kind: 'read'; readonly width?: number }
+type ImageRead =
+  | {
+      readonly kind: 'read'
+      readonly width?: number
+      readonly bytes?: Uint8Array
+    }
   | { readonly kind: 'failed' }
 
 /**
- * The pixel width of a PNG at `sha`, read over the contents API like every
- * other evidence read. The endpoint ignores a `Range` header, so the whole
- * file arrives and only its first bytes are read. A format other than PNG
- * reads without a width, and a refused or timed-out call reads as failed, so
- * the caller can keep the ceiling width and still report the cause.
+ * A PNG at `sha`, read over the contents API like every other evidence read,
+ * with its pixel width from the header. The endpoint ignores a `Range` header,
+ * so the whole file arrives, and its bytes are kept for the pixel comparison.
+ * A format other than PNG reads with neither, and a refused or timed-out call
+ * reads as failed, so the caller can keep the ceiling width and still report
+ * the cause.
  */
-async function readImageWidth(
+async function readImage(
   cwd: string,
   path: string,
   sha: string,
-): Promise<WidthRead> {
+): Promise<ImageRead> {
   if (!/\.png$/i.test(path)) return { kind: 'read' }
   try {
     const result = await execa(
@@ -2415,8 +2515,11 @@ async function readImageWidth(
         encoding: 'buffer',
       },
     )
-    const width = readPngWidth(result.stdout.subarray(0, PNG_HEADER_BYTES))
-    return width === undefined ? { kind: 'read' } : { kind: 'read', width }
+    const bytes = result.stdout
+    const width = readPngWidth(bytes.subarray(0, PNG_HEADER_BYTES))
+    return width === undefined
+      ? { kind: 'read', bytes }
+      : { kind: 'read', width, bytes }
   } catch {
     return { kind: 'failed' }
   }
@@ -2444,66 +2547,79 @@ async function mapPool<T, R>(
 
 interface SizedEvidence {
   readonly reading: EvidenceReading
-  /** Each image whose width read failed, as `head:<path>` or `base:<path>`, which rendered at the ceiling. */
+  /** Each image whose read failed, as `head:<path>` or `base:<path>`, which rendered at the ceiling and left its case uncompared. */
   readonly unread: readonly string[]
 }
 
-/** Each item with the pixel width of its head image and, when it has one, its base image. */
-async function withImageWidths(
+interface MeasuredItem {
+  readonly item: EvidenceItem
+  readonly unread: readonly string[]
+}
+
+/**
+ * One case with the pixel width of its head image and, when it has one, its
+ * base image, and whether the two match within tolerance. The pair is compared
+ * as soon as both reads land, so its bytes are dropped before the pool takes
+ * the next case. A case missing either PNG carries no verdict.
+ */
+async function measureItem(
+  cwd: string,
+  item: EvidenceItem,
+  base: string | undefined,
+  head: string,
+): Promise<MeasuredItem> {
+  const headRead = await readImage(cwd, item.path, head)
+  const baseRead =
+    item.added || base === undefined
+      ? undefined
+      : await readImage(cwd, item.path, base)
+  const unread = [
+    ...(headRead.kind === 'failed' ? [`head:${item.path}`] : []),
+    ...(baseRead?.kind === 'failed' ? [`base:${item.path}`] : []),
+  ]
+  const headBytes = headRead.kind === 'read' ? headRead.bytes : undefined
+  const baseBytes = baseRead?.kind === 'read' ? baseRead.bytes : undefined
+  return {
+    item: {
+      ...item,
+      ...(headRead.kind === 'read' &&
+        headRead.width !== undefined && { width: headRead.width }),
+      ...(baseRead?.kind === 'read' &&
+        baseRead.width !== undefined && { baseWidth: baseRead.width }),
+      ...(headBytes !== undefined &&
+        baseBytes !== undefined && {
+          withinTolerance: isWithinTolerance(baseBytes, headBytes),
+        }),
+    },
+    unread,
+  }
+}
+
+/** Each item measured by `measureItem`, in the reading's order. */
+async function withImageReads(
   cwd: string,
   reading: EvidenceReading,
   base: string | undefined,
   head: string,
 ): Promise<SizedEvidence> {
   if (reading.kind === 'refused') return { reading, unread: [] }
-  const jobs = reading.states.flatMap((entry, stateIndex) =>
-    entry.items.flatMap((item, itemIndex) => [
-      {
-        stateIndex,
-        itemIndex,
-        side: 'head' as const,
-        path: item.path,
-        sha: head,
-      },
-      ...(item.added || base === undefined
-        ? []
-        : [
-            {
-              stateIndex,
-              itemIndex,
-              side: 'base' as const,
-              path: item.path,
-              sha: base,
-            },
-          ]),
-    ]),
-  )
-  const reads = await mapPool(jobs, WIDTH_READ_CONCURRENCY, (job) =>
-    readImageWidth(cwd, job.path, job.sha),
+  const measured = await mapPool(
+    reading.states.flatMap((entry) => entry.items),
+    IMAGE_READ_CONCURRENCY,
+    (item) => measureItem(cwd, item, base, head),
   )
-  const unread: string[] = []
-  const states = reading.states.map((entry, stateIndex) => ({
-    ...entry,
-    items: entry.items.map((item, itemIndex): EvidenceItem => {
-      const widths: { width?: number; baseWidth?: number } = {}
-      jobs.forEach((job, index) => {
-        const read = reads[index]
-        if (
-          job.stateIndex !== stateIndex ||
-          job.itemIndex !== itemIndex ||
-          read === undefined
-        ) {
-          return
-        }
-        if (read.kind === 'failed') unread.push(`${job.side}:${job.path}`)
-        else if (read.width !== undefined) {
-          widths[job.side === 'head' ? 'width' : 'baseWidth'] = read.width
-        }
-      })
-      return { ...item, ...widths }
-    }),
-  }))
-  return { reading: { kind: 'read', states }, unread }
+  let offset = 0
+  const states = reading.states.map((entry) => {
+    const items = measured
+      .slice(offset, offset + entry.items.length)
+      .map((read) => read.item)
+    offset += entry.items.length
+    return { ...entry, items }
+  })
+  return {
+    reading: { kind: 'read', states },
+    unread: measured.flatMap((entry) => entry.unread),
+  }
 }
 
 async function runEvidence(
@@ -2520,7 +2636,8 @@ async function runEvidence(
     isCheck &&
     (opts.preview !== undefined ||
       opts.local !== undefined ||
-      opts.checklist !== undefined)
+      opts.checklist !== undefined ||
+      opts.reel !== undefined)
   ) {
     return refuseWith(
       'check-writes',
@@ -2573,9 +2690,10 @@ async function runEvidence(
 
   // The check never reads the merge base, so it skips the compare call and
   // a failed one cannot hold a draft lift for a reason the check never had.
-  const [pullFiles, base] = await Promise.all([
+  const [pullFiles, base, keepsCaptures] = await Promise.all([
     listPullFiles(root, identity.number),
     isCheck ? undefined : readPullMergeBase(root, identity.base, identity.head),
+    readBaseKeepsCaptures(root, identity.base),
   ])
   if (pullFiles === undefined) {
     return refuseWith(
@@ -2590,6 +2708,11 @@ async function runEvidence(
     [...pullFiles.present.keys()],
     async (path) => pullFiles.present.get(path) === false,
   )
+  const uncaptured = readUncaptured(
+    everyChangedPath(pullFiles),
+    loadPaintedPatterns(root),
+    keepsCaptures,
+  )
 
   let existingCases = 0
   let commentId: number | undefined
@@ -2615,12 +2738,14 @@ async function runEvidence(
   carriedPreview = findEvidencePreview(comments)
   carriedChecklist = findEvidenceChecklist(comments)
   carriedLocal = findEvidenceLocal(comments)
+  const carriedReel = findEvidenceReel(comments)
 
   // What the marked comment already shows a reviewer, kept apart from the
   // flags this call passed so a reader learns what is posted.
   const carried = {
     ...(carriedPreview !== undefined && { preview: carriedPreview }),
     ...(carriedLocal !== undefined && { local: carriedLocal }),
+    ...(carriedReel !== undefined && { reel: carriedReel }),
     ...(carriedChecklist !== undefined && {
       checklist: carriedChecklist,
       boxes: readChecklistBoxes(carriedChecklist),
@@ -2635,6 +2760,16 @@ async function runEvidence(
     servesChange(deploy.filter, everyChangedPath(pullFiles))
   const isUnserved = deploy.kind === 'found' && !deployServesChange
 
+  // Reported on every record that read the changed set, and never owed,
+  // since no step of the ship chain can take the capture a skip left out.
+  const uncapturedField = uncaptured !== undefined && { uncaptured }
+  const warnUncaptured = (): void => {
+    if (uncaptured === undefined || uncaptured.length === 0) return
+    logWarn(
+      `${plural(uncaptured.length, 'painted path')} changed with no evidence capture: ${uncaptured.join(', ')}`,
+    )
+  }
+
   if (isCheck) {
     const owed = readOwed({
       hasEvidenceChange: grouped.kind === 'read',
@@ -2648,6 +2783,7 @@ async function runEvidence(
         ? 'Nothing the ship chain posts after the pull request is missing.'
         : `missing ${owed.join(', ')}`,
     )
+    warnUncaptured()
     outro()
     if (emitJson) {
       process.stdout.write(
@@ -2656,6 +2792,7 @@ async function runEvidence(
           number: identity.number,
           reason: owed.length === 0 ? 'settled' : 'owed',
           owed,
+          ...uncapturedField,
           ...(commentId !== undefined && { commentId }),
           ...carried,
         })}\n`,
@@ -2683,6 +2820,7 @@ async function runEvidence(
     logInfo(
       'No changed path carries an evidence/ segment, so there is nothing to post.',
     )
+    warnUncaptured()
     outro()
     if (emitJson) {
       process.stdout.write(
@@ -2690,6 +2828,7 @@ async function runEvidence(
           root,
           ...(identity.number !== undefined && { number: identity.number }),
           reason: 'no-evidence',
+          ...uncapturedField,
           ...carried,
         })}\n`,
       )
@@ -2709,12 +2848,13 @@ async function runEvidence(
 
   const preview = opts.preview ?? (isUnserved ? undefined : carriedPreview)
   const local = opts.local ?? carriedLocal
+  const reel = nextEvidenceReel(opts.reel, identity.head, comments)
   const unsettled = suppliedChecklist ?? carriedChecklist
   const checklist =
     unsettled === undefined
       ? undefined
       : settleChecklist(unsettled, identity.head, findEvidenceHead(comments))
-  const sized = await withImageWidths(root, grouped, base, identity.head)
+  const sized = await withImageReads(root, grouped, base, identity.head)
   const states = sized.reading.kind === 'read' ? sized.reading.states : []
   const body = renderEvidenceBody(
     states,
@@ -2724,6 +2864,7 @@ async function runEvidence(
     preview,
     checklist,
     local,
+    reel,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -2781,6 +2922,13 @@ async function runEvidence(
   }
   if (preview !== undefined) logInfo(`preview ${preview}`)
   if (local !== undefined) logInfo(`local preview ${local}`)
+  if (reel !== undefined) {
+    logInfo(
+      opts.reel === undefined
+        ? `reel carried forward, filmed at ${reel.head.slice(0, 7)}`
+        : 'reel embedded under the addresses',
+    )
+  }
   if (checklist !== undefined) {
     logInfo(
       suppliedChecklist === undefined
@@ -2788,6 +2936,7 @@ async function runEvidence(
         : 'checklist folded in below the comparison',
     )
   }
+  warnUncaptured()
 
   outro()
 
@@ -2803,6 +2952,7 @@ async function runEvidence(
         states,
         ...(sized.unread.length > 0 && { widthUnread: sized.unread }),
         ...(uiPass !== undefined && { uiPass }),
+        ...uncapturedField,
         ...(commentId !== undefined && { commentId }),
         ...carried,
       })}\n`,
@@ -3664,6 +3814,7 @@ function framesArgumentRefusal(
 ): FramesCommandRefusal | undefined {
   const modes = [
     opts.add !== undefined,
+    opts.reel !== undefined,
     opts.drop === true,
     opts.prune !== undefined,
   ]
@@ -3673,6 +3824,12 @@ function framesArgumentRefusal(
     return POSITIVE_WHOLE.test(opts.prune) ? undefined : 'bad-days'
   }
   if (number === undefined || !POSITIVE_WHOLE.test(number)) return 'no-number'
+  if (
+    opts.reel !== undefined &&
+    (opts.box !== undefined || opts.reference !== undefined)
+  ) {
+    return 'bad-box'
+  }
   if (
     opts.add !== undefined &&
     (opts.box === undefined) === (opts.reference === undefined)
@@ -3689,7 +3846,7 @@ function framesArgumentRefusal(
   }
   if (opts.head !== undefined && !isFrameHead(opts.head)) return 'bad-head'
   if (
-    opts.add !== undefined &&
+    (opts.add !== undefined || opts.reel !== undefined) &&
     (opts.pass === undefined || !isFramePass(opts.pass))
   ) {
     return 'bad-pass'
@@ -3757,6 +3914,10 @@ async function runFrames(
   if (opts.add !== undefined && bytes === undefined) {
     return refuseFrames('unreadable-frame')
   }
+  const reel =
+    opts.reel === undefined ? undefined : await readReel(resolve(opts.reel))
+  if (reel?.kind === 'unreadable') return refuseFrames('unreadable-reel')
+  if (reel?.kind === 'too-large') return refuseFrames('reel-too-large')
 
   if (Bun.which('gh') === null) return refuseFrames('gh-missing')
   const runner = ghApiRunner(root)
@@ -3832,14 +3993,19 @@ async function runFrames(
     box,
     reference,
     theme,
-    bytes: bytes ?? new Uint8Array(),
+    reel: reel !== undefined,
+    bytes: reel?.bytes ?? bytes ?? new Uint8Array(),
   })
   if (result.kind === 'refused') return refuseWrite(result.reason)
   const link = frameLink(repo, result.path)
   return finish(
     {
       number: pull,
-      ...(box === undefined ? { reference } : { box }),
+      ...(reel !== undefined
+        ? { reel: true }
+        : box === undefined
+          ? { reference }
+          : { box }),
       ...(theme === undefined ? {} : { theme }),
       head,
       pass,
@@ -4485,6 +4651,7 @@ async function runDriveCopy(
       target.worktree,
       copyRoot,
       config.config.writes,
+      config.config.keep,
     )
     logStep('Copied')
     logInfo(`${config.config.env}=${copyRoot}`)