[miguel-heygen]

What

hyperframes snapshot --output <dir> now deletes only the images a snapshot run writes (its frame, review, --against and contact-sheet names). Every other image in that folder is left alone. Before this change it deleted every .png, .jpg and .jpeg in the folder, so hyperframes snapshot . -o assets or -o . erased the project's own images.

Why

Data loss. The cleanup before each run used /\.(png|jpg|jpeg)$/i on everything in the output folder, and nothing checked that a file had come from an earlier snapshot run. A user who pointed --output at the project folder or its assets/ folder lost every image in it, with no prompt and nothing in the output to say so.

Related work

Builds on the --keep naming from #5605. No overlapping open PR.

How

• One exported pattern, SNAPSHOT_IMAGE_NAME in snapshot.ts, sits next to formatSnapshotTimestamp and covers every image name a run writes into its folder:

  • default stills frame-NN-at-Xs.png
  • --keep stills at-Xs.png
  • --against reference frames ref-[NN-]at-Xs.png and pair sheets pair-[NN-]at-Xs.jpg
  • --review stills beat-NN-at-Xs.png and seam-NN-S-at-Xs.png
  • the sheets contact-sheet[-N].jpg, review-beats[-N].jpg, review-phone[-N].jpg and review-seam-NN.jpg

  --zoom writes under the same frame names. The cleanup uses this pattern instead of the extension check, so the files it reports as replaced are exactly the files it deletes.

• Why a name pattern and not a manifest of what the last run wrote: every name above is fixed by the command, so a pattern needs no extra state. A manifest would add a file the user can delete or edit, and it would miss frames written by versions that never wrote one.

• The match is now case-sensitive. The command only writes lowercase names, so Notes.PNG is a user file.

• The managed default folder needs no special case. Each run gets a fresh folder, so the run has nothing to clear there.

• No new flag and no prompt. Other commands keep the deletes they already do.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (if applicable)
• Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

New tests in packages/cli/src/commands/snapshot-contactSheet.test.ts drive the real command through citty's runCommand, with the browser and server mocked the same way the file's other tests do:

• --output cases. --output points at snapshots/, at the project folder itself, and at assets/. Each folder starts with user images (hero.png, logo.jpg, Notes.PNG, frame-hero.png) and earlier output (default, --keep, --against and review frames, and paged sheets). After the run, every user image is unchanged, every earlier output file is gone, and the new frames are in place.
• Review names. Every name reviewFrames produces matches the pattern, so a later --review change that renames its stills fails here.

What I ran:

• With snapshot.ts from main and the new tests, the three --output cases fail with ENOENT ... hero.png: the user's image was deleted.
• With the fix, snapshot-contactSheet.test.ts, snapshot.test.ts and snapshotReview.test.ts passed 3 runs in a row (100 tests each run).

What I did not exercise: a real browser capture, --review, --against or --zoom run end to end (their names are checked against the pattern, not captured), and Windows.

Size: under the 100-line floor on purpose, a lone urgent data-loss fix with no open PR of this lane to fold into.

[heygengenesis]

Verdict: APPROVE · 0 blocker · 1 important · 0 nits · head 35929f40

I checked the pattern against every name the command writes: frame-NN-at-* and at-* (snapshot.ts:907-914), ref-/pair- (:972-974), beat-/seam- and the review sheets (snapshotReview.ts:237-318), and the paged contact-sheet-N.jpg (contactSheet.ts:157). All of them match. CI is green at this head.

• important (follow-up, not gating): createSnapshotContactSheet (packages/cli/src/capture/contactSheet.ts:222-223) still picks up every frame-*.png in the folder. Before this PR, the cleanup had always deleted those. Now a user image like frame-hero.png, which your own test keeps, survives and ends up as a tile on the new contact-sheet.jpg the agent reviews. Filtering there by /^frame-\d+-at-[\d.]+s\.png$/ (or SNAPSHOT_IMAGE_NAME) would fix it.

— Genesis