chore(storybook): survey component usage from the story shots scripts

.claude/skills/storybook-visual-diff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: storybook-visual-diff
-description: Screenshot a set of SigNoz Storybook stories, then pixel-diff two runs to see what a CSS or component change did, with the changes tinted over the new shot. Use when asked to take story screenshots, capture a visual baseline, compare before/after of a style change, or find which pages a change affects.
+description: Screenshot a set of SigNoz Storybook stories, then pixel-diff two runs to see what a CSS or component change did, with the changes tinted over the new shot. Also surveys where a component is used across the UI, ringing each instance in red and collecting every one into a single contact sheet. Use when asked to take story screenshots, capture a visual baseline, compare before/after of a style change, find which pages a change affects, or show every place a component appears.
 ---
 
 # Storybook visual diff
@@ -22,7 +22,7 @@ says, take it and do not ask again; ask only for what is genuinely missing, in
 
 | To settle | Ask | Options |
 | --- | --- | --- |
-| Job | "What should this run produce?" | shoot only · baseline for a change you are about to make · compare against a change already in the working tree · compare this branch against another (`main` by default, or one the user names) · compare two configurations of the same story (`--args`, clock, width) · noise floor (same tree twice) |
+| Job | "What should this run produce?" | shoot only · survey where a component is used (§4) · baseline for a change you are about to make · compare against a change already in the working tree · compare this branch against another (`main` by default, or one the user names) · compare two configurations of the same story (`--args`, clock, width) · noise floor (same tree twice) |
 | Scope | "Which stories?" | offer 2-3 concrete selections read off `index.json` (a page, a `--title` prefix, everything), never open-ended |
 | Themes | "Which themes?" | dark · dark + light |
 | Read-out | "How should the diff read?" | `green` (changed pixels over the after shot) · `green-parallel` (before \| after \| diff, side by side) · `red` · `red-parallel` · `none` (keep both runs, do not diff) |
@@ -39,6 +39,7 @@ The job decides which loop below to run:
 | Job | Loop |
 | --- | --- |
 | **shoot only** | §1, §2, stop. Report the paths. No diff, no second run. |
+| **usage survey** | §1, §4, stop. One run, no diff: the question is where a component appears, not what moved. |
 | **baseline first** | the full loop, stopping after step 2 to hand the change back. The user makes it, then continue at step 4. |
 | **change already in the tree** | the tree *is* the after state. `git stash` (or check out the base commit) to shoot the before, restore, shoot the after. Confirm the working tree is clean enough to stash before touching it, and restore it even if a capture fails. |
 | **branch vs branch** | shoot the current branch, then `git switch <base>` in place (stash first if the tree is dirty), restart the dev server, shoot again, switch back and unstash. Restart matters: HMR does not survive a whole-branch swap cleanly. Get the tree back to where it started even if a capture fails. |
@@ -122,6 +123,8 @@ node scripts/story-shots.mjs .story-shots/baseline \
 | `--clock <iso\|live>` | wall clock the page reads, passed to the preview as `?storyClock`; `live` unfreezes it |
 | `--motion` | keep animations and transitions running (sets the `motion` global to `live`) |
 | `--ignore <selector>` | hide matching elements, on top of `[data-shot-ignore]` and `[data-chromatic="ignore"]` |
+| `--highlight <selector>` | also write `<id>--highlight.png`, every match ringed in red with 6px of padding |
+| `--crop <selector>` | also write one `crops/<id>--<n>.png` per match, and montage the theme's crops into `crops.png` |
 | `--flat` | write `<out>/<id>.png`, no theme directory |
 | `--no-caption` | leave the caption band off the shots |
 | `--list` | print the matched stories and exit |
@@ -129,8 +132,9 @@ node scripts/story-shots.mjs .story-shots/baseline \
 Files land at `<out>/<theme>/<story-id>.png`, next to a `shots.json` recording
 what each shot is (id, title, name, theme, `ok`/`busy`, the caption's height in
 rows) and how the run was configured (args, clock, width, height, grow, motion,
-settle, ignore). Keep the flags identical between the two runs or the diff pairs
-nothing.
+settle, ignore, highlight, crop). Keep the flags identical between the two runs
+or the diff pairs nothing. `--highlight` and `--crop` write extra files beside
+the shots; §4 is what they are for.
 
 Every shot carries the caption band described below, so a single screenshot says
 what it is on its own. `--no-caption` leaves it off, and so does a machine
@@ -208,10 +212,75 @@ pixelmatch's `includeAA: false`. So the script implements that comparison:
 A pair whose shots are different sizes is compared over the overlap, and every
 row and column that exists in only one of them counts as changed.
 
-Pairing is by `<theme>/<story-id>.png`, so a story that exists on only one side
-(new on the feature branch, renamed, retitled) has nothing to pair with and is
-skipped silently. On a branch-vs-branch run, compare the two runs' file lists
-before reading the numbers.
+Pairing is by `<theme>/<story-id>.png`. A file that exists on one side only (a
+story added on the feature branch, renamed, retitled, or one whose capture
+failed) has nothing to compare against. It is not skipped: the side that has the
+shot is written out, captioned `missing previous` or `missing current`, and every
+one of its pixels counts as changed, so it sorts to the top of the report and is
+printed with that note. In the parallel modes the run that does not have it gets
+a placeholder tile saying so, in the theme's own colours, so the montage keeps
+its three tiles. Without this a whole component going missing reads as a clean
+run.
+
+## 4. Surveying where a component is used
+
+A different question from a diff: not *what moved*, but *where does this
+component appear and what does each instance look like*. One run answers it.
+
+```bash
+node scripts/story-shots.mjs .story-shots/button-group --port 6007 --theme dark,light \
+  --highlight '.ant-btn-group, div[role="group"][class*="button-group"]' \
+  --crop '.ant-btn-group, div[role="group"][class*="button-group"]' \
+  --stories pages-home--default,pages-alerts-history--default,...
+```
+
+Four things come out, per theme:
+
+- `<theme>/<id>.png` — the page as it is.
+- `<theme>/<id>--highlight.png` — the same page with every instance ringed in
+  red. This is what says *where on the page*, which a crop cannot.
+- `<theme>/crops/<id>--<n>.png` — each instance on its own.
+- `<theme>/crops.png` — every crop of that theme in one labelled contact sheet.
+
+The sheet is the useful artifact. Twelve instances across nine pages is one
+image to read, not twelve files to open in turn, and the label under each says
+which story it came from.
+
+### Finding the selector and the stories
+
+1. **Grep the source for the import, not the tag.** `Button.Group` and
+   `ButtonGroup` are two different components in this repo: antd's, and
+   `@signozhq/ui/button`'s. A survey that greps one misses the other.
+2. **Read the rendered markup, not the JSX.** `--crop` takes a CSS selector
+   against the DOM. antd's group is `.ant-btn-group`; the design-system one is a
+   `div[role="group"]` whose class is a hashed CSS module, hence
+   `[class*="button-group"]`. Open the built component under
+   `node_modules/@signozhq/ui/dist/` when the class is not obvious.
+3. **Map each source file to the story that renders it.** Follow the consumers:
+   a container renders inside a page, and the page's story is the one to shoot.
+   A component behind a drawer or a tab needs the story whose `args` open it
+   (`--args drawer:endpoint-stats`), not the page default.
+4. **Let the run itself confirm the mapping.** Each story logs `N cropped`. A
+   `0 cropped` line means that story never reaches the state, so swap the story
+   rather than the selector.
+
+### What a zero means
+
+- **`0 cropped` on a story** — the component is not on that page in that state.
+  Wrong story, or the state is behind an interaction the story has no `play`
+  for. A modal nobody opens cannot be surveyed; say so instead of shooting the
+  page it sits behind.
+- **An instance in the source with no crop** — a container whose children are
+  all conditional renders as a 0x0 box. Both `--crop` and `--highlight` skip
+  anything under 1px, since there is nothing on screen to ring. That is a
+  finding about the component, not a failure of the run: it is in the tree and
+  invisible.
+
+A story logged `viewport-sized content, stopped chasing Npx` is shot back at
+`--height` with its own scrollbar, and what is below the fold there is laid out
+but never painted. The crops of such a story are taken at the chased height
+instead, so they are not the black rectangles the page shot would give; the
+`--highlight` shot still shows only what fits the viewport.
 
 ## What makes a shot reproducible
 
@@ -292,3 +361,6 @@ for `--ignore` when a region cannot be settled.
 - **Stories behind a hover, drawer or modal** only render what their `play`
   reaches. If a state is missing from the shot, the story needs the `play`, not
   the script.
+- **The caption's temporary file is written beside the shot**, not in the system
+  temp directory. `/tmp` is often a different filesystem, and the rename back
+  over the shot then fails with `EXDEV: cross-device link not permitted`.

frontend/scripts/story-shots-caption.mjs

@@ -15,6 +15,8 @@ export const CONFIG_KEYS = [
 	'motion',
 	'settle',
 	'ignore',
+	'highlight',
+	'crop',
 ];
 
 let tools;

frontend/scripts/story-shots-diff.mjs

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import path from 'node:path';
-import os from 'node:os';
 
 import {
 	bodyFont,
@@ -18,7 +17,8 @@ import {
 
 /**
  * Pairs the PNGs of two story-shots.mjs runs by relative path and reports what
- * moved, per pair, largest first.
+ * moved, per pair, largest first. A shot only one run has is reported too,
+ * labelled with the side it is missing from and counted as changed in full.
  *
  * The comparison is Chromatic's: a pixel counts as changed when its YIQ
  * distance from the baseline pixel is over `threshold` of the largest distance
@@ -55,7 +55,8 @@ if (opts.help || !baseDir || !afterDir || !MODES.has(opts.mode)) {
   --tint <#rrggbb>       override the mode's highlight colour
   --no-caption           do not stamp the story and the run settings on top
 
-Prints "<changed pixels>  <relative path>", largest first. Needs ImageMagick.`);
+Prints "<changed pixels>  <relative path>", largest first; a shot only one run
+has is printed as "(missing previous)" or "(missing current)". Needs ImageMagick.`);
 	process.exit(opts.help ? 0 : 1);
 }
 
@@ -325,6 +326,11 @@ const shotOf = (run, rel) =>
 
 const captionOf = (run, rel) => shotOf(run, rel)?.caption ?? 0;
 
+/** What the shot was shot in, falling back to the directory it sits in. */
+const themeOf = (rel) =>
+	(shotOf(afterRun, rel) ?? shotOf(baseRun, rel))?.theme ??
+	rel.split(path.sep)[0];
+
 /** ImageMagick's inline crop, so a tile shows the shot without its caption. */
 const withoutCaption = (file, { width, height }, top) =>
 	top > 0 ? `${file}[${width}x${height}+0+${top}]` : file;
@@ -369,20 +375,156 @@ const pngs = async (dir, prefix = '') => {
 const results = [];
 await mkdir(outDir, { recursive: true });
 
-for (const rel of (await pngs(baseDir)).sort()) {
+/** The half-built tiles, under the output directory so nothing is left elsewhere. */
+const scratch = Object.fromEntries(
+	['body', 'diff', 'shot', 'missing'].map((name) => [
+		name,
+		path.join(outDir, `.story-shots-${process.pid}-${name}.png`),
+	]),
+);
+
+/** One labelled tile of a parallel montage. */
+const tile = (label, file, background) => [
+	'(',
+	`label:${literal(label)}`,
+	file,
+	'-gravity',
+	'center',
+	'-append',
+	'-bordercolor',
+	background,
+	'-border',
+	'12',
+	')',
+];
+
+/** The tiles side by side under one caption. */
+const montage = ({
+	tiles,
+	width,
+	background,
+	foreground,
+	caption,
+	target,
+	theme,
+}) => {
+	magick([
+		'-background',
+		background,
+		'-fill',
+		foreground,
+		...bodyFont(),
+		'-pointsize',
+		// The tiles end up side by side, so they are read at the montage's width.
+		String(Math.round(pointsize(width * 3) * 0.62)),
+		...tiles.flat(),
+		'-gravity',
+		'north',
+		'+append',
+		caption.length ? scratch.body : target,
+	]);
+	if (caption.length) {
+		stamp({ lines: caption, from: scratch.body, to: target, theme });
+	}
+};
+
+/**
+ * A tile standing in for a shot the run does not have, sized like the one it
+ * does. The gutter's colours are the theme's own inverted, so they go back the
+ * other way here and the tile reads as a shot rather than as a hole.
+ */
+const placeholder = (
+	file,
+	{ width, height },
+	text,
+	{ background, foreground },
+) =>
+	magick([
+		'-size',
+		`${width}x${height}`,
+		'-background',
+		foreground,
+		'-fill',
+		background,
+		'-gravity',
+		'center',
+		...bodyFont(),
+		'-pointsize',
+		String(pointsize(width * 3)),
+		`label:${literal(text)}`,
+		file,
+	]);
+
+const [baseFiles, afterFiles] = await Promise.all([
+	pngs(baseDir),
+	pngs(afterDir),
+]);
+const inBase = new Set(baseFiles);
+const inAfter = new Set(afterFiles);
+
+for (const rel of [...new Set([...baseFiles, ...afterFiles])].sort((a, b) =>
+	a.localeCompare(b),
+)) {
 	const afterFile = path.join(afterDir, rel);
-	const base = readRgba(path.join(baseDir, rel), captionOf(baseRun, rel));
-	let after;
-	try {
-		after = readRgba(afterFile, captionOf(afterRun, rel));
-	} catch {
-		console.error(`missing in after: ${rel}`);
+	const target = path.join(outDir, rel);
+	await mkdir(path.join(outDir, path.dirname(rel)), { recursive: true });
+
+	// A story added, removed or renamed since the baseline has nothing to
+	// compare against, so the side that does have it is written out under the
+	// label of the side that does not, and every one of its pixels counts.
+	if (!inBase.has(rel) || !inAfter.has(rel)) {
+		const gone = inAfter.has(rel) ? 'previous' : 'current';
+		const held = gone === 'previous' ? 'current' : 'previous';
+		const run = gone === 'previous' ? afterRun : baseRun;
+		const image = readRgba(
+			gone === 'previous' ? afterFile : path.join(baseDir, rel),
+			captionOf(run, rel),
+		);
+		const theme = themeOf(rel);
+		const colors = palette(theme);
+		const caption = captionLines(rel, [`missing ${gone}`]);
+
+		if (opts.mode.endsWith('-parallel')) {
+			// The montage keeps its three tiles: the run that has the shot shows it,
+			// and the run that does not, like the diff, says so in its place. There
+			// is nothing to compare, so nothing is tinted.
+			await writeRgba(image, scratch.shot);
+			placeholder(scratch.missing, image, `missing ${gone}`, colors);
+
+			const sides = {
+				[held]: tile(sideLabel(held, run), scratch.shot, colors.background),
+				[gone]: tile(
+					sideLabel(gone, gone === 'previous' ? baseRun : afterRun),
+					scratch.missing,
+					colors.background,
+				),
+			};
+			montage({
+				tiles: [
+					sides.previous,
+					sides.current,
+					tile('diff', scratch.missing, colors.background),
+				],
+				width: image.width,
+				...colors,
+				caption,
+				target,
+				theme,
+			});
+		} else {
+			await writeRgba(image, caption.length ? scratch.body : target);
+			if (caption.length) {
+				stamp({ lines: caption, from: scratch.body, to: target, theme });
+			}
+		}
+
+		results.push([image.width * image.height, rel, `missing ${gone}`]);
 		continue;
 	}
 
-	await mkdir(path.join(outDir, path.dirname(rel)), { recursive: true });
+	const base = readRgba(path.join(baseDir, rel), captionOf(baseRun, rel));
+	const after = readRgba(afterFile, captionOf(afterRun, rel));
 	const diff = diffPair(base, after, opts.mode);
-	const target = path.join(outDir, rel);
 	const parallel = opts.mode.endsWith('-parallel');
 	// With no tiles to label, a run's own settings go in the caption instead.
 	const caption = captionLines(
@@ -391,70 +533,54 @@ for (const rel of (await pngs(baseDir)).sort()) {
 			? []
 			: [sideLabel('previous', baseRun), sideLabel('current', afterRun)],
 	);
-	const diffFile = path.join(os.tmpdir(), `story-shots-${process.pid}.png`);
-	const body = path.join(os.tmpdir(), `story-shots-${process.pid}-body.png`);
 
 	// The gutter is the opposite of the theme's own background, so the tiles and
 	// the caption keep an edge instead of bleeding into it.
-	const shot = shotOf(afterRun, rel) ?? shotOf(baseRun, rel);
-	const theme = shot?.theme ?? rel.split(path.sep)[0];
+	const theme = themeOf(rel);
 	const { background, foreground } = palette(theme);
 
 	if (parallel) {
-		await writeRgba(diff, diffFile);
-		const tile = (label, file) => [
-			'(',
-			`label:${literal(label)}`,
-			file,
-			'-gravity',
-			'center',
-			'-append',
-			'-bordercolor',
+		await writeRgba(diff, scratch.diff);
+		montage({
+			tiles: [
+				tile(
+					sideLabel('previous', baseRun),
+					withoutCaption(path.join(baseDir, rel), base, captionOf(baseRun, rel)),
+					background,
+				),
+				tile(
+					sideLabel('current', afterRun),
+					withoutCaption(afterFile, after, captionOf(afterRun, rel)),
+					background,
+				),
+				tile('diff', scratch.diff, background),
+			],
+			width: after.width,
 			background,
-			'-border',
-			'12',
-			')',
-		];
-		magick([
-			'-background',
-			background,
-			'-fill',
 			foreground,
-			...bodyFont(),
-			'-pointsize',
-			// The tiles end up side by side, so they are read at the montage's width.
-			String(Math.round(pointsize(after.width * 3) * 0.62)),
-			...tile(
-				sideLabel('previous', baseRun),
-				withoutCaption(path.join(baseDir, rel), base, captionOf(baseRun, rel)),
-			),
-			...tile(
-				sideLabel('current', afterRun),
-				withoutCaption(afterFile, after, captionOf(afterRun, rel)),
-			),
-			...tile('diff', diffFile),
-			'-gravity',
-			'north',
-			'+append',
-			caption.length ? body : target,
-		]);
-		if (caption.length) {
-			stamp({ lines: caption, from: body, to: target, theme });
-		}
+			caption,
+			target,
+			theme,
+		});
 	} else {
-		await writeRgba(diff, caption.length ? body : target);
+		await writeRgba(diff, caption.length ? scratch.body : target);
 		if (caption.length) {
-			stamp({ lines: caption, from: body, to: target, theme });
+			stamp({ lines: caption, from: scratch.body, to: target, theme });
 		}
 	}
 
 	results.push([diff.changed, rel]);
 }
 
+await Promise.all(
+	Object.values(scratch).map((file) => rm(file, { force: true })),
+);
+
 results
 	.sort((a, b) => b[0] - a[0])
-	.forEach(([changed, rel]) =>
-		console.log(`${String(changed).padStart(10)}  ${rel}`),
-	);
+	.forEach(([changed, rel, note]) => {
+		const suffix = note ? `  (${note})` : '';
+		console.log(`${String(changed).padStart(10)}  ${rel}${suffix}`);
+	});
 
 console.error(`diffs in ${outDir}`);

frontend/scripts/story-shots.mjs

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { renameSync, rmSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
-import os from 'node:os';
 
 import {
+	bodyFont,
 	CONFIG_KEYS,
 	hasMagick,
+	literal,
+	magick,
+	palette,
 	settingsLine,
 	stamp,
 } from './story-shots-caption.mjs';
@@ -39,6 +43,8 @@ const { values: opts, positionals } = parseArgs({
 		clock: { type: 'string', default: FROZEN_CLOCK },
 		motion: { type: 'boolean', default: false },
 		ignore: { type: 'string', multiple: true, default: [] },
+		highlight: { type: 'string', multiple: true, default: [] },
+		crop: { type: 'string', multiple: true, default: [] },
 		flat: { type: 'boolean', default: false },
 		'no-caption': { type: 'boolean', default: false },
 		list: { type: 'boolean', default: false },
@@ -72,6 +78,10 @@ if (opts.help || (!outDir && !opts.list)) {
   --clock <iso|live>  wall clock the page reads (default ${FROZEN_CLOCK})
   --motion            keep animations and transitions running
   --ignore <selector> hide matching elements, on top of [data-shot-ignore]
+  --highlight <selector>
+                      also shoot <id>--highlight.png, every match ringed in red
+  --crop <selector>   also write one <id>--<n>.png per match under <theme>/crops,
+                      and montage them into <theme>/crops.png
   --flat              write <out>/<id>.png instead of <out>/<theme>/<id>.png
   --no-caption        do not stamp the story and the run settings on the shot
   --list              print the matched stories and exit
@@ -135,10 +145,17 @@ if (!stories.length) {
 	process.exit(1);
 }
 
-const ignoreSelectors = opts.ignore
-	.flatMap((value) => value.split(','))
-	.map((value) => value.trim())
-	.filter(Boolean);
+/** A repeatable, comma-separated flag read as one CSS selector list. */
+const selectorList = (values) =>
+	values
+		.flatMap((value) => value.split(','))
+		.map((value) => value.trim())
+		.filter(Boolean)
+		.join(', ');
+
+const ignoreSelectors = selectorList(opts.ignore);
+const highlightSelector = selectorList(opts.highlight);
+const cropSelector = selectorList(opts.crop);
 
 if (opts.clock !== 'live' && Number.isNaN(Date.parse(opts.clock))) {
 	console.error(`--clock: not a date: ${opts.clock}`);
@@ -152,13 +169,12 @@ if (opts.clock !== 'live' && Number.isNaN(Date.parse(opts.clock))) {
  * their bottom - is done by the preview itself, so a Chromatic build and a shot
  * from here see the same page.
  */
-const ignoreCss = (
-	ignore,
-) => `[data-shot-ignore], [data-chromatic='ignore']${ignore
-	.map((selector) => `, ${selector}`)
-	.join('')} {
+const ignoreCss = (ignore) => {
+	const extra = ignore ? `, ${ignore}` : '';
+	return `[data-shot-ignore], [data-chromatic='ignore']${extra} {
 	visibility: hidden !important;
 }`;
+};
 
 /**
  * Playwright is not a frontend dependency: it lives in `tests/e2e`, or globally,
@@ -248,7 +264,9 @@ const runConfig = {
 	grow: opts.grow,
 	motion: opts.motion ? 'live' : 'still',
 	settle: opts.settle,
-	ignore: ignoreSelectors.join(', '),
+	ignore: ignoreSelectors,
+	highlight: highlightSelector,
+	crop: cropSelector,
 };
 
 const captioning = !opts['no-caption'] && hasMagick();
@@ -261,6 +279,8 @@ const configLine = settingsLine(runConfig, CONFIG_KEYS);
 
 for (const theme of themes.length ? themes : [null]) {
 	const dir = opts.flat ? outDir : path.join(outDir, theme ?? 'default');
+	const cropDir = path.join(dir, 'crops');
+	const crops = [];
 	await mkdir(dir, { recursive: true });
 	if (theme) {
 		console.log(`\n[${theme}]`);
@@ -295,6 +315,9 @@ for (const theme of themes.length ? themes : [null]) {
 		// the viewport, kept only to flag the story in the log.
 		let chasing = 0;
 
+		// What the story's line in the log says beyond ok/busy.
+		const notes = [];
+
 		const url = new URL(`${base}/iframe.html`);
 		url.searchParams.set('viewMode', 'story');
 		url.searchParams.set('id', story.id);
@@ -447,47 +470,160 @@ for (const theme of themes.length ? themes : [null]) {
 				shot = next;
 			}
 
-			const file = path.join(dir, `${story.id}.png`);
-			await writeFile(file, shot);
+			/**
+			 * The band goes on the shot itself so a single screenshot says what it
+			 * is, and its height is returned so a diff can take it back off. The
+			 * temporary is written beside the shot rather than in the system temp
+			 * directory: those are often separate filesystems, and a rename across
+			 * one fails with EXDEV.
+			 */
+			const caption = (target, lines) => {
+				if (!captioning) {
+					return 0;
+				}
 
-			// The band goes on the shot itself so a single screenshot says what it
-			// is, and its height is recorded so a diff can take it back off.
-			let caption = 0;
-			if (captioning) {
 				const temporary = path.join(
-					os.tmpdir(),
-					`story-shots-caption-${process.pid}.png`,
+					path.dirname(target),
+					`.caption-${process.pid}.png`,
 				);
-				caption = stamp({
+				const rows = stamp({
 					lines: [
 						`${story.title}/${story.name}`,
 						[story.id, theme ?? 'default', stable ? '' : '(busy)']
 							.filter(Boolean)
 							.join('  '),
-						configLine,
+						...lines,
 					].filter(Boolean),
-					from: file,
+					from: target,
 					to: temporary,
 					theme: theme ?? 'dark',
 				});
-				await rename(temporary, file);
+				renameSync(temporary, target);
+				return rows;
+			};
+
+			const file = path.join(dir, `${story.id}.png`);
+			await writeFile(file, shot);
+
+			const record = (relative, caption) =>
+				shots.push({
+					file: path.posix.join(opts.flat ? '' : (theme ?? 'default'), relative),
+					id: story.id,
+					title: story.title,
+					name: story.name,
+					theme: theme ?? 'default',
+					status: stable ? 'ok' : 'busy',
+					caption,
+				});
+
+			record(`${story.id}.png`, caption(file, [configLine]));
+
+			// The crops are taken before anything is drawn over the page, so a
+			// component's own shot carries no ring and no label: the montage at the
+			// end of the theme is what names them.
+			if (cropSelector) {
+				await mkdir(cropDir, { recursive: true });
+
+				// A page that sizes itself in `vh` was shot back at `--height` with
+				// its own scrollbar, and what is below the fold there is laid out but
+				// never painted: cropping it gives a black rectangle. The crops alone
+				// are taken at the height the rounds had reached, which is where the
+				// page does paint.
+				if (chasing) {
+					await page.setViewportSize({
+						width: Number(opts.width),
+						height: chasing,
+					});
+					await page.waitForTimeout(Number(opts.settle));
+				}
+
+				const matches = page.locator(cropSelector);
+				let kept = 0;
+				for (let index = 0; index < (await matches.count()); index += 1) {
+					const element = matches.nth(index);
+					// A group whose children are all conditional renders as a 0x0 box.
+					// It has no counterpart on screen, so there is nothing to crop.
+					const box = await element.boundingBox();
+					if (!box || box.width < 1 || box.height < 1) {
+						continue;
+					}
+
+					kept += 1;
+					const relative = `${story.id}--${kept}.png`;
+					// The scroll that brings an element into view needs a frame before
+					// the crop, or the region comes back unpainted.
+					await element.scrollIntoViewIfNeeded({ timeout: 15_000 });
+					await page.waitForTimeout(250);
+					await element.screenshot({
+						path: path.join(cropDir, relative),
+						timeout: 15_000,
+					});
+					crops.push({
+						file: path.join(cropDir, relative),
+						label: `${story.title}/${story.name}  #${kept}`,
+					});
+					record(path.posix.join('crops', relative), 0);
+				}
+				notes.push(`${kept} cropped`);
+
+				if (chasing) {
+					await page.setViewportSize({
+						width: Number(opts.width),
+						height: Number(opts.height),
+					});
+					await page.waitForTimeout(Number(opts.settle));
+				}
 			}
 
-			shots.push({
-				file: path.posix.join(
-					opts.flat ? '' : (theme ?? 'default'),
-					`${story.id}.png`,
-				),
-				id: story.id,
-				title: story.title,
-				name: story.name,
-				theme: theme ?? 'default',
-				status: stable ? 'ok' : 'busy',
-				caption,
-			});
+			if (highlightSelector) {
+				const ringed = await page.evaluate(
+					([selector, padding]) => {
+						const layer = document.createElement('div');
+						// The shot is viewport-sized, so the rings are placed in viewport
+						// coordinates and survive a page that stayed scrollable.
+						layer.style.cssText =
+							'position:fixed;inset:0;pointer-events:none;z-index:2147483647';
+						let drawn = 0;
+						for (const element of document.querySelectorAll(selector)) {
+							const box = element.getBoundingClientRect();
+							if (box.width < 1 || box.height < 1) {
+								continue;
+							}
+
+							drawn += 1;
+							const ring = document.createElement('div');
+							ring.style.cssText = `position:fixed;box-sizing:border-box;border:3px solid #ff003a;border-radius:4px;left:${
+								box.left - padding
+							}px;top:${box.top - padding}px;width:${
+								box.width + padding * 2
+							}px;height:${box.height + padding * 2}px`;
+							layer.append(ring);
+						}
+						document.documentElement.append(layer);
+						window.__storyShotsHighlight = layer;
+						return drawn;
+					},
+					[highlightSelector, 6],
+				);
+
+				const highlighted = path.join(dir, `${story.id}--highlight.png`);
+				await writeFile(highlighted, await page.screenshot());
+				record(
+					`${story.id}--highlight.png`,
+					caption(highlighted, [`${ringed} highlighted`, configLine]),
+				);
+				notes.push(`${ringed} highlighted`);
+				await page.evaluate(() => {
+					window.__storyShotsHighlight?.remove();
+					delete window.__storyShotsHighlight;
+				});
+			}
+			if (chasing) {
+				notes.push(`viewport-sized content, stopped chasing ${chasing}px`);
+			}
 			console.log(
 				`  ${stable ? 'ok  ' : 'busy'} ${story.id}${
-					chasing ? ` (viewport-sized content, stopped chasing ${chasing}px)` : ''
+					notes.length ? ` (${notes.join(', ')})` : ''
 				}`,
 			);
 		} catch (error) {
@@ -497,6 +633,52 @@ for (const theme of themes.length ? themes : [null]) {
 			await context.close();
 		}
 	}
+
+	// One image of every crop the theme produced, labelled with the story it came
+	// from. A component that appears on eight pages is a survey rather than eight
+	// screenshots to open one after another.
+	if (crops.length && captioning) {
+		const sheet = path.join(dir, 'crops.png');
+		const { background, foreground } = palette(theme ?? 'dark');
+
+		// `montage -label` sizes every tile to the widest *image*, so a label
+		// longer than its crop runs under the next one. Each crop is composed with
+		// its own label first, which sizes the tile to whichever of the two is
+		// wider, and the sheet is then a montage of finished tiles.
+		const tiles = crops.map(({ file, label }, index) => {
+			const tile = path.join(cropDir, `.tile-${index}.png`);
+			magick([
+				'-background',
+				background,
+				'-fill',
+				foreground,
+				...bodyFont(),
+				'-pointsize',
+				'16',
+				file,
+				`label:${literal(label)}`,
+				'-gravity',
+				'center',
+				'-append',
+				tile,
+			]);
+			return tile;
+		});
+
+		magick([
+			'montage',
+			'-background',
+			background,
+			'-tile',
+			'2x',
+			'-geometry',
+			'+16+16',
+			...tiles,
+			sheet,
+		]);
+		tiles.forEach((tile) => rmSync(tile, { force: true }));
+		console.log(`  ${crops.length} crops -> ${sheet}`);
+	}
 }
 
 await browser.close();