@juangadm/pre-post 1.3.0 → 1.5.0

package/dist/record.js

@@ -0,0 +1,223 @@
+/**
+ * Record one side of a Moment: load the page, then play its steps while the
+ * browser streams frames.
+ *
+ * Frames come from CDP `Page.startScreencast`, which sends a frame only when
+ * pixels change — about every 17 ms during a transition, nothing while the
+ * page sits still (measured; docs/internal/video-spike.md). Playwright's own
+ * `recordVideo` was the alternative: fixed at 25 fps and recording from the
+ * moment the context opens, load and all.
+ *
+ * Every step's start time is marked, so `timeline.ts` can line the two sides
+ * up step by step. A step that fails ends the recording at the moment it
+ * began: the seconds spent looking for a button that is not there are not
+ * something a reviewer should watch.
+ */
+import { gotoChecked, hideDevIndicator, settlePage, withMotionPage } from './browser.js';
+/** Still frames before the first step, so the viewer sees the page first. */
+export const LEAD_IN_MS = 500;
+/** After each step, so its result is on screen before the next one starts. */
+export const BREATH_MS = 400;
+/** After the last step, so the clip ends on the result. */
+export const TAIL_MS = 1000;
+/** A Moment with no steps records this much of the page loading, for entrance animations. */
+export const LOAD_ONLY_MS = 3000;
+/**
+ * How long a step looks for its target. Short, because a missing target is
+ * the normal case on Pre for a new feature, and every second spent looking is
+ * a second the whole run waits.
+ */
+export const FIND_TIMEOUT_MS = 3000;
+/** How long a found target's action (click, hover, typing) may take. */
+export const STEP_TIMEOUT_MS = 5000;
+/** A smooth scroll's travel time. */
+const SCROLL_MS = 700;
+/** Typed one key at a time, slow enough to read. */
+const TYPE_DELAY_MS = 45;
+const SETTLE_MS = 8000;
+export class StepError extends Error {
+}
+const ROLES = ['button', 'link', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'tab', 'option', 'checkbox', 'radio', 'switch', 'textbox', 'searchbox', 'combobox'];
+/**
+ * Candidate locators for a target, most specific first.
+ *
+ * Steps name what a person sees ("Save", "Email"), so the accessible name of
+ * something interactive is tried first, then a field's label or placeholder,
+ * then exact visible text, then the same things loosely. `css=` skips all of
+ * it for the rare case plain words cannot say.
+ */
+function candidates(page, target) {
+    if (target.startsWith('css='))
+        return [page.locator(target.slice(4))];
+    const byRole = (exact) => ROLES.map(role => page.getByRole(role, { name: target, exact })).reduce((a, b) => a.or(b));
+    return [
+        byRole(true),
+        page.getByLabel(target, { exact: true }).or(page.getByPlaceholder(target, { exact: true })),
+        page.getByText(target, { exact: true }),
+        byRole(false).or(page.getByLabel(target)).or(page.getByPlaceholder(target)).or(page.getByText(target)),
+    ];
+}
+/**
+ * The visible element a step means, waiting for it to appear — a menu item
+ * exists only once the menu is open, and the step before just opened it.
+ */
+async function resolveTarget(page, target) {
+    const deadline = Date.now() + FIND_TIMEOUT_MS;
+    const tiers = candidates(page, target).map(l => l.filter({ visible: true }));
+    for (;;) {
+        // All tiers at once, most specific match wins: one round trip per poll,
+        // not four, while the page is being recorded.
+        const counts = await Promise.all(tiers.map(t => t.count().catch(() => 0)));
+        const hit = counts.findIndex(n => n > 0);
+        if (hit !== -1)
+            return tiers[hit].first();
+        if (Date.now() >= deadline)
+            throw new StepError(`Couldn't find “${target}”`);
+        await page.waitForTimeout(100);
+    }
+}
+async function pointAt(locator, step, pointers) {
+    const box = await locator.boundingBox().catch(() => null);
+    if (box)
+        pointers.push({ step, x: box.x + box.width / 2, y: box.y + box.height / 2 });
+}
+async function act(what, fn) {
+    try {
+        await fn();
+    }
+    catch {
+        throw new StepError(`Couldn't ${what}`);
+    }
+}
+async function runStep(page, step, index, pointers) {
+    if (step.verb === 'wait')
+        return page.waitForTimeout(step.ms);
+    if (step.verb === 'press')
+        return act(`press ${step.key}`, () => page.keyboard.press(step.key));
+    if (step.verb === 'scroll' && !step.target) {
+        // Smooth on purpose: a jump cut reads as a different page. Explicit
+        // `behavior: 'smooth'` wins over the init script's scroll-behavior rule.
+        await page.evaluate(px => window.scrollBy({ top: px, behavior: 'smooth' }), step.px);
+        return page.waitForTimeout(SCROLL_MS);
+    }
+    const target = step.target;
+    const el = await resolveTarget(page, target);
+    const quoted = `“${target}”`;
+    switch (step.verb) {
+        case 'scroll':
+            await act(`scroll to ${quoted}`, () => el.evaluate(node => node.scrollIntoView({ behavior: 'smooth', block: 'center' })));
+            return page.waitForTimeout(SCROLL_MS);
+        case 'click':
+            await pointAt(el, index, pointers);
+            return act(`click ${quoted}`, () => el.click({ timeout: STEP_TIMEOUT_MS }));
+        case 'hover':
+            await pointAt(el, index, pointers);
+            return act(`hover ${quoted}`, () => el.hover({ timeout: STEP_TIMEOUT_MS }));
+        case 'type':
+            await pointAt(el, index, pointers);
+            return act(`type into ${quoted}`, async () => {
+                await el.click({ timeout: STEP_TIMEOUT_MS });
+                await el.pressSequentially(step.text, { delay: TYPE_DELAY_MS, timeout: STEP_TIMEOUT_MS + step.text.length * TYPE_DELAY_MS });
+            });
+    }
+}
+/**
+ * The screencast's own frame clock, in ms, when it agrees with ours. Its
+ * timestamp is seconds since the epoch; if a browser ever sends something
+ * else, the arrival time is close enough.
+ */
+function frameTime(seconds) {
+    const now = Date.now();
+    const t = typeof seconds === 'number' ? seconds * 1000 : NaN;
+    return Number.isFinite(t) && Math.abs(t - now) < 5000 ? t : now;
+}
+/**
+ * Stream frames into `frames` until the returned stop is called. Frames are
+ * sent at `maxWidth`, the width they will be drawn at, not the page's: a
+ * desktop page is shown in an 800px pane, and shipping and holding the full
+ * size would be most of the memory a recording uses.
+ */
+async function startScreencast(cdp, viewport, maxWidth, frames) {
+    let open = true;
+    cdp.on('Page.screencastFrame', f => {
+        if (open)
+            frames.push({ t: frameTime(f.metadata.timestamp), data: Buffer.from(f.data, 'base64') });
+        // The browser sends the next frame only once this one is acknowledged.
+        cdp.send('Page.screencastFrameAck', { sessionId: f.sessionId }).catch(() => undefined);
+    });
+    const scale = Math.min(1, maxWidth / viewport.width);
+    await cdp.send('Page.startScreencast', {
+        format: 'jpeg', quality: 85, everyNthFrame: 1,
+        maxWidth: Math.round(viewport.width * scale), maxHeight: Math.round(viewport.height * scale),
+    });
+    return async () => {
+        open = false;
+        await cdp.send('Page.stopScreencast').catch(() => undefined);
+    };
+}
+/**
+ * Record `moment` on `url`. Throws NavigationError / HttpStatusError when the
+ * page cannot be loaded; returns a recording with `failure` set when a step
+ * cannot be done. A page that answers 4xx/5xx comes back with its status and
+ * no frames, for the caller to phrase.
+ */
+export async function recordSide(url, moment, viewport, opts) {
+    const { auth, maxWidth } = opts;
+    return withMotionPage(viewport, auth, async (page, ctx) => {
+        const frames = [];
+        const pointers = [];
+        const marks = [];
+        const cdp = await ctx.newCDPSession(page);
+        const loadOnly = moment.steps.length === 0;
+        // A load-only Moment is about the load, so recording starts before the
+        // navigation: an entrance animation can run while the document is still
+        // parsing. Any other starts on a settled page, because how fast each side
+        // loaded is not the change.
+        let start = Date.now();
+        let stop = loadOnly ? await startScreencast(cdp, viewport, maxWidth, frames) : null;
+        const { status } = await gotoChecked(page, url).catch(async (err) => { await stop?.(); throw err; });
+        if (status !== undefined && status >= 400) {
+            await stop?.();
+            const now = Date.now();
+            return { viewport, frames: [], pointers, marks, start: now, end: now, status };
+        }
+        if (!stop) {
+            await settlePage(page, SETTLE_MS);
+            await hideDevIndicator(page);
+            // The screencast sends nothing until something paints, and a settled
+            // page paints nothing. Seed the stream with what is on screen now.
+            start = Date.now();
+            const first = await page.screenshot({ type: 'jpeg', quality: 85, timeout: 10_000 }).catch(() => null);
+            if (first)
+                frames.push({ t: start, data: first });
+            stop = await startScreencast(cdp, viewport, maxWidth, frames);
+        }
+        let failure;
+        await page.waitForTimeout(loadOnly ? LOAD_ONLY_MS : LEAD_IN_MS);
+        for (let i = 0; i < moment.steps.length; i++) {
+            const began = Date.now();
+            try {
+                await runStep(page, moment.steps[i], i, pointers);
+            }
+            catch (err) {
+                failure = { step: i, message: err instanceof StepError ? err.message : `Step ${i + 1} failed`, at: began };
+                break;
+            }
+            marks.push(began);
+            if (moment.steps[i].verb !== 'wait')
+                await page.waitForTimeout(BREATH_MS);
+        }
+        if (!failure && !loadOnly)
+            await page.waitForTimeout(TAIL_MS);
+        await stop();
+        const end = failure?.at ?? Date.now();
+        // Nothing after `end` is ever shown — for a failed step, that is every
+        // frame of the search — so it is not carried into the compositor.
+        const shown = frames.filter(f => f.t <= end).sort((a, b) => a.t - b.t);
+        return {
+            viewport, frames: shown, pointers, marks, start, end, status,
+            failure: failure && { step: failure.step, message: failure.message },
+        };
+    });
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"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"}

package/dist/report.d.ts

@@ -2,8 +2,27 @@
  * Output formatting: the PR comment (for humans) and the terminal summary
  * (for the developer or the agent that invoked the CLI).
  */
-import { PrRunResult } from './types.js';
+import { PrRunResult, RouteCaptureOutcome } from './types.js';
 export declare const STICKY_MARKER = "<!-- pre-post:visual-changes -->";
+/** One change to show, and the other routes that show exactly the same change. */
+export interface ChangeGroup {
+    lead: RouteCaptureOutcome;
+    others: RouteCaptureOutcome[];
+}
+/**
+ * Collapse routes that show the same change into one entry.
+ *
+ * A nav edit touches every page, and the report used to repeat it: six
+ * sections, 24 images, one change. Routes whose change has the same
+ * fingerprint, at the same viewport, are one entry led by the first of them.
+ * So are routes whose only change is the same move: the sentence ("Content
+ * shifted down 8px. Nothing else changed.") is the whole report, and eight
+ * pages of it was twelve full-page images saying one thing. A move with
+ * something else on top, or a change with no fingerprint, stands alone.
+ */
+export declare function groupChanges(outcomes: RouteCaptureOutcome[]): ChangeGroup[];
+/** A reviewer's name for a side: its label, else the host a deployment answers on. */
+export declare function sideLabel(url: string, label: string | undefined, localName: string): string;
 export interface CommentOptions {
     version?: string;
     headSha?: string | null;
@@ -16,6 +35,15 @@ export interface CommentOptions {
      */
     filesDir?: string;
 }
+/**
+ * The clips, above the screenshots: they show what screenshots cannot, and a
+ * reviewer who presses play once has seen the change.
+ *
+ * An attachment URL on its own line is what GitHub turns into a player. A
+ * clip on the assets branch cannot play there, so its last frame links to it,
+ * with the one thing that would make it play.
+ */
+export declare function momentLines(result: Pick<PrRunResult, 'moments' | 'momentsSkipped' | 'momentsHint'>, local?: (f?: string) => string | undefined): string[];
 /**
  * Markdown body for the sticky PR comment.
  */

package/dist/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAe,WAAW,EAAuB,MAAM,YAAY,CAAC;AAI3E,eAAO,MAAM,aAAa,qCAAqC,CAAC;AAgBhE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAqGtF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAsCxD"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAgC,WAAW,EAAE,mBAAmB,EAAY,MAAM,YAAY,CAAC;AAMtG,eAAO,MAAM,aAAa,qCAAqC,CAAC;AAgBhE,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,WAAW,EAAE,CAmB3E;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,gBAAgB,GAAG,aAAa,CAAC,EAAE,KAAK,GAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAkB,GAAG,MAAM,EAAE,CAwBjK;AAKD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAiJtF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAiDxD"}

package/dist/report.js

@@ -3,8 +3,11 @@
  * (for the developer or the agent that invoked the CLI).
  */
 import path from 'path';
-import { describeShift } from './run.js';
+import { isBrokenVerdict, sideName } from './types.js';
+import { describePageError, describeShift } from './run.js';
 import { hostOf, isLocalUrl } from './url.js';
+import { capNotice } from './routes.js';
+import { MAX_MOMENTS, quote, skippedNote } from './moments.js';
 export const STICKY_MARKER = '<!-- pre-post:visual-changes -->';
 function code(s) {
     return `\`${s}\``;
@@ -18,6 +21,81 @@ function groupByRoute(outcomes) {
         map.set(o.route, [...(map.get(o.route) ?? []), o]);
     return map;
 }
+/**
+ * Collapse routes that show the same change into one entry.
+ *
+ * A nav edit touches every page, and the report used to repeat it: six
+ * sections, 24 images, one change. Routes whose change has the same
+ * fingerprint, at the same viewport, are one entry led by the first of them.
+ * So are routes whose only change is the same move: the sentence ("Content
+ * shifted down 8px. Nothing else changed.") is the whole report, and eight
+ * pages of it was twelve full-page images saying one thing. A move with
+ * something else on top, or a change with no fingerprint, stands alone.
+ */
+export function groupChanges(outcomes) {
+    const groups = [];
+    const byKey = new Map();
+    // Filtered here, not by callers: `pr` groups to choose what to upload and
+    // the report groups to render, and both must pick the same lead.
+    for (const o of outcomes.filter(o => o.status === 'changed' && (o.urls || o.files))) {
+        const key = o.shift
+            ? (o.shift.otherChange ? null : `${o.viewport}:move:${Math.round(o.shift.px)}`)
+            : o.fingerprint ? `${o.viewport}:${o.fingerprint}` : null;
+        const existing = key ? byKey.get(key) : undefined;
+        if (existing) {
+            existing.others.push(o);
+            continue;
+        }
+        const group = { lead: o, others: [] };
+        groups.push(group);
+        if (key)
+            byKey.set(key, group);
+    }
+    return groups;
+}
+/** A reviewer's name for a side: its label, else the host a deployment answers on. */
+export function sideLabel(url, label, localName) {
+    return label ?? (isLocalUrl(url) ? localName : hostOf(url));
+}
+/**
+ * The clips, above the screenshots: they show what screenshots cannot, and a
+ * reviewer who presses play once has seen the change.
+ *
+ * An attachment URL on its own line is what GitHub turns into a player. A
+ * clip on the assets branch cannot play there, so its last frame links to it,
+ * with the one thing that would make it play.
+ */
+export function momentLines(result, local = f => f) {
+    const lines = [];
+    const recorded = (result.moments ?? []).filter(m => m.status === 'recorded');
+    const failed = (result.moments ?? []).filter(m => m.status === 'error');
+    for (const m of recorded) {
+        const seconds = m.durationMs ? ` · ${(m.durationMs / 1000).toFixed(1)}s` : '';
+        lines.push(`### ▶ ${m.name} — ${viewportLabel(m.viewport)}`, '', `${code(m.route)}${seconds}${m.preNote ? ` · ${m.preNote}` : ''}`, '');
+        const video = m.videoUrl ?? local(m.file);
+        const poster = m.posterUrl ?? local(m.poster);
+        if (m.inline && m.videoUrl)
+            lines.push(m.videoUrl, '');
+        else if (video && poster)
+            lines.push(`[![${m.name} — open the video](${poster})](${video})`, '');
+        else if (video)
+            lines.push(`[Open the video](${video})`, '');
+        if (m.note)
+            lines.push(`<sub>${m.note}</sub>`, '');
+    }
+    if (recorded.some(m => !m.inline) && result.momentsHint)
+        lines.push(`<sub>${result.momentsHint}</sub>`, '');
+    if (failed.length) {
+        lines.push('**Could not record:**');
+        for (const m of failed)
+            lines.push(`- ${quote(m.name)}: ${m.error}`);
+        lines.push('');
+    }
+    if (result.momentsSkipped?.length) {
+        lines.push(`**Also listed, not recorded (over the ${MAX_MOMENTS}-Moment limit):** ${result.momentsSkipped.map(quote).join(', ')}`, '');
+    }
+    return lines;
+}
 /** A run shorter than this says how long it took in the PR description. */
 const FAST_RUN_MS = 30_000;
 /**
@@ -26,70 +104,100 @@ const FAST_RUN_MS = 30_000;
 export function buildComment(result, options = {}) {
     const lines = [STICKY_MARKER, '## Visual changes', ''];
     /** Published URLs when there are any, else the local files. */
+    const dir = options.filesDir;
+    const local = (f) => f && dir && path.isAbsolute(f) ? path.relative(dir, f).split(path.sep).join('/') : f;
     const images = (o) => {
         if (o.urls)
             return o.urls;
-        const dir = options.filesDir;
         if (!dir || !o.files)
             return o.files ?? {};
-        const local = (f) => f && (path.isAbsolute(f) ? path.relative(dir, f).split(path.sep).join('/') : f);
         return Object.fromEntries(Object.entries(o.files).map(([k, f]) => [k, local(f)]));
     };
-    const routes = groupByRoute(result.outcomes);
+    const clips = momentLines(result, local);
+    const hasClips = (result.moments ?? []).some(m => m.status === 'recorded');
     const changed = result.outcomes.filter(o => o.status === 'changed');
     const unchanged = result.outcomes.filter(o => o.status === 'unchanged');
     const errors = result.outcomes.filter(o => o.status === 'error');
+    // Only the baseline can be broken here: a broken Post is a verdict, above.
+    const notCompared = result.outcomes.filter(o => o.status === 'broken');
     // A page that only one side has is still something a reviewer must see, so it
     // counts as a change for "did anything happen" — but it is shown as one
     // screenshot, never as a Pre/Post pair, because there is no pair.
     const oneSided = result.outcomes.filter(o => (o.status === 'added' || o.status === 'removed') && (o.urls || o.files));
     // Both sides can now be a deployment, so name the actual hosts rather than
     // assuming Post is the reader's own checkout.
-    const postLabel = isLocalUrl(result.afterBase) ? 'this branch (local)' : hostOf(result.afterBase);
+    // Named for the reviewer. A local side is served on a throwaway port, so its
+    // URL named nothing and changed on every run; the label says what it is.
+    const preLabel = sideLabel(result.beforeBase, result.beforeLabel, 'a local server');
+    const postLabel = sideLabel(result.afterBase, result.afterLabel, 'this branch');
     const sha = options.headSha ? ` @ ${code(options.headSha.slice(0, 7))}` : '';
     // Only a quick run earns a mention: the number is there to show the tool is
     // cheap to run, and a slow one would say the opposite.
     const took = result.durationMs > 0 && result.durationMs < FAST_RUN_MS ? ` in ${Math.max(1, Math.round(result.durationMs / 1000))}s` : '';
-    lines.push(`**Pre** = ${hostOf(result.beforeBase)} · **Post** = ${postLabel}${sha} · <a href="https://github.com/juangadm/pre-post">pre-post</a>${took}`, '');
+    // No sides means nothing was served — a run that stopped before the dev
+    // servers because no page could be captured. Naming empty sides says nothing.
+    if (result.beforeBase || result.afterBase) {
+        lines.push(`**Pre** = ${preLabel} · **Post** = ${postLabel}${sha} · <a href="https://github.com/juangadm/pre-post">pre-post</a>${took}`, '');
+    }
+    // A side that renders an error page is the whole story. One sentence and
+    // where it happened; no screenshots, because a picture of an error panel in a
+    // Pre/Post table reads as a design, and that is how it used to ship.
+    if (isBrokenVerdict(result.verdict)) {
+        lines.push(`**${result.verdict.hint}**`, '');
+        for (const o of result.outcomes.filter(o => o.broken)) {
+            lines.push(`- ${code(o.route)} ${viewportLabel(o.viewport)}: ${describePageError(o.broken.error)}`);
+        }
+        lines.push('');
+        return lines.join('\n');
+    }
     // "No visual changes" is a claim about what the two sides looked like, so it
     // may only be made about routes that were actually compared. A run where
     // every capture failed compared nothing, and printing it there — directly
     // above a list of six "Could not capture" lines, which is how it shipped —
     // reports a clean diff for a run that produced no diff at all.
     if (changed.length + unchanged.length + oneSided.length === 0) {
-        lines.push(errors.length
-            ? `**Nothing was compared** — ${errors.length === 1 ? 'the only capture' : `all ${errors.length} captures`} failed. See below.`
-            : '**Nothing was compared** — no route produced a screenshot.', '');
+        const failed = errors.length + notCompared.length;
+        lines.push(failed
+            ? `**Nothing was compared** — ${failed === 1 ? 'the only capture' : `all ${failed} captures`} failed. See below.`
+            : result.outcomes.length > 0
+                ? '**Nothing was compared** — no route produced a screenshot.'
+                : result.skippedDynamic.length
+                    ? '**Nothing was compared yet** — the only pages this branch affects need a sample URL. See below.'
+                    : '**No pages affected** — nothing this branch changed renders on a page.', '');
     }
     else if (changed.length === 0 && oneSided.length === 0) {
-        lines.push('No visual changes.', '');
+        // A clip can show a change no still frame does (a transition, a hover), so
+        // with clips the claim is only about the screenshots.
+        lines.push(hasClips ? 'No visual changes in the screenshots.' : 'No visual changes.', '');
     }
-    for (const [route, outcomes] of routes) {
-        const changedHere = outcomes.filter(o => o.status === 'changed' && (o.urls || o.files));
-        if (changedHere.length === 0)
-            continue;
-        for (const o of changedHere) {
-            const u = images(o);
-            lines.push(`### ${code(route)} — ${viewportLabel(o.viewport)}`, '');
-            // A move repaints everything below it, so the percentage says nothing a
-            // reviewer can use. Say how far it moved instead, and whether the branch
-            // changed anything else.
-            if (o.shift) {
-                lines.push(o.shift.otherChange
-                    ? `Content ${describeShift(o.shift.px)}. The pair below is aligned on that move, so it shows what changed besides it.`
-                    : `Content ${describeShift(o.shift.px)}. Nothing else changed.`, '');
-            }
-            const cropped = Boolean(u.cropBefore && u.cropAfter);
-            const pre = u.cropBefore ?? u.before;
-            const post = u.cropAfter ?? u.after;
-            lines.push('| Pre | Post |', '|:---:|:---:|', `| ![Pre](${pre}) | ![Post](${post}) |`, '');
-            // Without a crop the pair above is already the full page; repeating it
-            // under a fold gives a reviewer two more identical images to scroll past.
-            if (cropped) {
-                lines.push('<details>', `<summary>Full page</summary>`, '');
-                lines.push('| Pre (full) | Post (full) |', '|:---:|:---:|', `| ![Pre full](${u.before}) | ![Post full](${u.after}) |`, '');
-                lines.push('</details>', '');
-            }
+    lines.push(...clips);
+    for (const { lead: o, others } of groupChanges(result.outcomes)) {
+        const u = images(o);
+        if (others.length) {
+            const all = [o, ...others].map(r => code(r.route)).join(', ');
+            lines.push(`### Same change on ${others.length + 1} pages — ${viewportLabel(o.viewport)}`, '', `${all}. Shown on ${code(o.route)}:`, '');
+        }
+        else {
+            lines.push(`### ${code(o.route)} — ${viewportLabel(o.viewport)}`, '');
+        }
+        // A move repaints everything below it, so the percentage says nothing a
+        // reviewer can use. Say how far it moved instead, and whether the branch
+        // changed anything else.
+        if (o.shift) {
+            lines.push(o.shift.otherChange
+                ? `Content ${describeShift(o.shift.px)}. The pair below is aligned on that move, so it shows what changed besides it.`
+                : `Content ${describeShift(o.shift.px)}. Nothing else changed.`, '');
+        }
+        const cropped = Boolean(u.cropBefore && u.cropAfter);
+        const pre = u.cropBefore ?? u.before;
+        const post = u.cropAfter ?? u.after;
+        lines.push('| Pre | Post |', '|:---:|:---:|', `| ![Pre](${pre}) | ![Post](${post}) |`, '');
+        // Without a crop the pair above is already the full page; repeating it
+        // under a fold gives a reviewer two more identical images to scroll past.
+        if (cropped) {
+            lines.push('<details>', `<summary>Full page</summary>`, '');
+            lines.push('| Pre (full) | Post (full) |', '|:---:|:---:|', `| ![Pre full](${u.before}) | ![Post full](${u.after}) |`, '');
+            lines.push('</details>', '');
         }
     }
     for (const o of oneSided) {
@@ -101,7 +209,7 @@ export function buildComment(result, options = {}) {
         const side = o.status === 'added' ? 'Post' : 'Pre';
         lines.push(`### ${code(o.route)} — ${viewportLabel(o.viewport)} · ${what}`, '');
         lines.push(o.status === 'added'
-            ? `This route has no baseline — ${hostOf(result.beforeBase)} returns 404 for it — so there is no "before" to show and no percentage to quote. ${side} only:`
+            ? `This route has no baseline — ${preLabel} returns 404 for it — so there is no "before" to show and no percentage to quote. ${side} only:`
             : `This route is gone on this branch, so there is no "after". ${side} only:`, '');
         lines.push(`![${side}](${image})`, '');
     }
@@ -116,9 +224,20 @@ export function buildComment(result, options = {}) {
             lines.push(`- ${code(o.route)} ${o.viewport}: ${o.error}`);
         lines.push('');
     }
+    if (notCompared.length) {
+        lines.push('**Not compared** (the baseline shows an error on these pages, not caused by this branch):');
+        for (const o of notCompared)
+            lines.push(`- ${code(o.route)} ${o.viewport}: ${describePageError(o.broken.error)}`);
+        lines.push('');
+    }
     if (result.skippedDynamic.length) {
         lines.push(`**Needs a sample URL:** ${result.skippedDynamic.map(code).join(', ')} — add them under ${code('"samples"')} in ${code('.pre-post.json')}.`, '');
     }
+    // A route list that silently stops at the cap reads as "these are all the
+    // pages this branch touches". Name the rest.
+    if (result.omitted) {
+        lines.push(`**Also affected, not captured (over the ${result.omitted.cap}-page limit):** ${result.omitted.routes.map(code).join(', ')}`, '');
+    }
     return lines.join('\n');
 }
 /**
@@ -137,11 +256,14 @@ export function buildSummary(result) {
         o.route,
         o.viewport,
         o.status === 'error' ? 'error'
-            : o.status === 'changed' ? 'changed'
-                : o.status === 'added' ? 'new page'
-                    : o.status === 'removed' ? 'removed'
-                        : 'no change',
-        o.status === 'error' ? (o.error ?? '') : (o.note || ''),
+            : o.status === 'broken' ? 'broken'
+                : o.status === 'changed' ? 'changed'
+                    : o.status === 'added' ? 'new page'
+                        : o.status === 'removed' ? 'removed'
+                            : 'no change',
+        o.status === 'error' ? (o.error ?? '')
+            : o.broken ? `${sideName(o.broken.side)}: ${describePageError(o.broken.error)}`
+                : (o.note || ''),
     ]);
     const widths = [0, 1, 2].map(i => Math.max(...rows.map(r => r[i].length), 0));
     for (const r of rows) {
@@ -150,6 +272,16 @@ export function buildSummary(result) {
     if (result.skippedDynamic.length) {
         lines.push(`  needs sample URL: ${result.skippedDynamic.join(', ')} (add to .pre-post.json "samples")`);
     }
+    if (result.omitted)
+        lines.push(`  ${capNotice(result.omitted.routes, result.omitted.cap)}`);
+    for (const m of result.moments ?? []) {
+        lines.push(m.status === 'recorded'
+            ? `  ▶ ${quote(m.name)}  ${m.viewport}  ${(m.durationMs / 1000).toFixed(1)}s${m.inline ? '  inline in PR' : ''}${m.preNote ? `  (${m.preNote})` : ''}`
+            : `  ▶ ${quote(m.name)}  not recorded: ${m.error}`);
+    }
+    const skipped = skippedNote(result.momentsSkipped ?? []);
+    if (skipped)
+        lines.push(`  ${skipped}`);
     // Named for what actually happened. The images normally go in the PR
     // description and only fall back to a comment, so "Comment:" sent a reader
     // looking for a comment that a run with zero comments had never created.