@juangadm/pre-post 1.4.0 → 1.5.0

package/dist/moments.js

@@ -0,0 +1,170 @@
+/**
+ * Moments: short, named interactions recorded on Pre and Post and played side
+ * by side in one clip.
+ *
+ * A screenshot cannot show a menu opening or a hover state; a recording of a
+ * page sitting still shows nothing either (that is why the first GIF attempt
+ * was parked). So the unit of video is an interaction a person would do —
+ * "Open the account menu" — written as a few plain steps that target what the
+ * person sees, not CSS.
+ *
+ * Everything here is pure: parsing, validation, choosing which Moments run,
+ * and the sentences a reviewer reads. The browser side is `record.ts`.
+ */
+import fs from 'fs';
+import path from 'path';
+import { parseViewport } from './viewport.js';
+const VERBS = ['click', 'hover', 'type', 'press', 'scroll', 'wait'];
+/**
+ * Moments per run. A big PR gets video for the few changes a reviewer most
+ * needs to see move; every changed page still gets screenshots. Order is
+ * priority: the first three run, the rest are named in one line.
+ */
+export const MAX_MOMENTS = 3;
+/**
+ * Past this a clip still ships, with a nudge to split it. Not a cap: length
+ * comes only from the steps someone wrote, so nothing records for minutes on
+ * its own, and a clip a reviewer can take in on one play is the goal.
+ */
+export const LONG_CLIP_MS = 30_000;
+/** What a clip should aim for; used in the nudge. */
+const TARGET_CLIP_S = 15;
+/** A `wait` longer than this is almost certainly a mistake (ms, not s). */
+const MAX_WAIT_MS = 10_000;
+export class MomentError extends Error {
+}
+function fail(where, message) {
+    throw new MomentError(`${where}: ${message}`);
+}
+function parseStep(raw, where) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        fail(where, `expected a step like { "click": "Save" }, got ${JSON.stringify(raw)}`);
+    }
+    const keys = Object.keys(raw);
+    if (keys.length !== 1 || !VERBS.includes(keys[0])) {
+        fail(where, `a step has exactly one of ${VERBS.join(', ')} (got ${keys.join(', ') || 'nothing'})`);
+    }
+    const verb = keys[0];
+    const value = raw[verb];
+    const text = (v) => typeof v === 'string' && v.trim() ? v : null;
+    switch (verb) {
+        case 'click':
+        case 'hover': {
+            const target = text(value);
+            if (!target)
+                fail(where, `"${verb}" needs the text of what to ${verb}, e.g. { "${verb}": "Save" }`);
+            return { verb, target };
+        }
+        case 'type': {
+            if (!Array.isArray(value) || value.length !== 2 || !text(value[0]) || typeof value[1] !== 'string') {
+                fail(where, '"type" needs [field, text], e.g. { "type": ["Email", "ada@example.com"] }');
+            }
+            return { verb, target: value[0], text: value[1] };
+        }
+        case 'press': {
+            const key = text(value);
+            if (!key)
+                fail(where, '"press" needs a key, e.g. { "press": "Escape" }');
+            return { verb, key };
+        }
+        case 'scroll': {
+            if (typeof value === 'number' && Number.isFinite(value))
+                return { verb, px: value };
+            const target = text(value);
+            if (!target)
+                fail(where, '"scroll" needs the text to scroll to, or a number of pixels');
+            return { verb, target };
+        }
+        case 'wait': {
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                fail(where, '"wait" needs milliseconds, e.g. { "wait": 600 }');
+            }
+            if (value > MAX_WAIT_MS)
+                fail(where, `"wait" is in milliseconds; ${value} is over ${MAX_WAIT_MS / 1000}s`);
+            return { verb, ms: value };
+        }
+    }
+}
+/** Validate one Moment. `where` names it in errors, e.g. "Moment 2". */
+export function parseMoment(raw, where) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail(where, 'expected an object with name, route and steps');
+    const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+    if (!name)
+        fail(where, 'needs a "name" — the caption a reviewer reads, e.g. "Open the account menu"');
+    const label = `${where} ("${name}")`;
+    const route = typeof raw.route === 'string' ? raw.route.trim() : '';
+    if (!route.startsWith('/'))
+        fail(label, 'needs a "route" starting with /, e.g. "/settings"');
+    const viewport = raw.viewport === undefined ? 'desktop' : typeof raw.viewport === 'string' ? raw.viewport.trim() : '';
+    // Checked here, with the rest of the file, so a typo stops the run before
+    // any capture instead of costing one Moment after all of them were recorded.
+    try {
+        parseViewport(viewport);
+    }
+    catch {
+        fail(label, `"viewport" is desktop, tablet, mobile or WxH (got ${JSON.stringify(raw.viewport)})`);
+    }
+    if (raw.steps !== undefined && !Array.isArray(raw.steps))
+        fail(label, '"steps" is a list');
+    const steps = (raw.steps ?? []).map((s, i) => parseStep(s, `${label} step ${i + 1}`));
+    return { name, route, viewport, steps };
+}
+/** Validate a list of Moments, as found in config or a file. */
+export function parseMoments(raw, source) {
+    const list = Array.isArray(raw) ? raw
+        : raw && typeof raw === 'object' && Array.isArray(raw.moments) ? raw.moments
+            : fail(source, 'expected a list of Moments, or { "moments": [...] }');
+    return list.map((m, i) => parseMoment(m, `${source}, Moment ${i + 1}`));
+}
+/** Read a `--moments` file. */
+export function loadMomentsFile(file, cwd = process.cwd()) {
+    const full = path.resolve(cwd, file);
+    let text;
+    try {
+        text = fs.readFileSync(full, 'utf-8');
+    }
+    catch {
+        throw new MomentError(`Cannot read the Moments file ${file}.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new MomentError(`${file} is not valid JSON: ${err.message}`);
+    }
+    return parseMoments(parsed, path.basename(file));
+}
+/** The Moments that run, in priority order, and the names of the rest. */
+export function selectMoments(moments) {
+    return { run: moments.slice(0, MAX_MOMENTS), skipped: moments.slice(MAX_MOMENTS).map(m => m.name) };
+}
+/** A name as a reviewer reads it: “Open the account menu”. */
+export function quote(s) {
+    return `“${s}”`;
+}
+/** A step as a reviewer would say it: `Click “Save”`. Shown under the clip. */
+export function describeStep(step) {
+    switch (step.verb) {
+        case 'click': return `Click ${quote(step.target)}`;
+        case 'hover': return `Hover ${quote(step.target)}`;
+        case 'type': return `Type ${quote(step.text)} into ${quote(step.target)}`;
+        case 'press': return `Press ${step.key}`;
+        case 'scroll': return step.target ? `Scroll to ${quote(step.target)}` : `Scroll ${step.px >= 0 ? 'down' : 'up'} ${Math.abs(step.px)}px`;
+        case 'wait': return 'Wait';
+    }
+}
+/** One line for a clip that ran long, or null. */
+export function longClipNote(name, durationMs) {
+    if (durationMs <= LONG_CLIP_MS)
+        return null;
+    return `${quote(name)} is ${Math.round(durationMs / 1000)}s — clips under ${TARGET_CLIP_S}s get watched; consider splitting it into smaller Moments.`;
+}
+/** One line naming the Moments over the limit, or null. */
+export function skippedNote(skipped) {
+    if (!skipped.length)
+        return null;
+    return `Recorded the first ${MAX_MOMENTS} Moments; also listed, not recorded: ${skipped.map(quote).join(', ')}.`;
+}
+//# sourceMappingURL=moments.js.map

package/dist/moments.js.map

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

package/dist/record.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { AuthOptions, ViewportSize } from './types.js';
+import { Moment } from './moments.js';
+import { SideTiming } from './timeline.js';
+/** Still frames before the first step, so the viewer sees the page first. */
+export declare const LEAD_IN_MS = 500;
+/** After each step, so its result is on screen before the next one starts. */
+export declare const BREATH_MS = 400;
+/** After the last step, so the clip ends on the result. */
+export declare const TAIL_MS = 1000;
+/** A Moment with no steps records this much of the page loading, for entrance animations. */
+export declare 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 declare const FIND_TIMEOUT_MS = 3000;
+/** How long a found target's action (click, hover, typing) may take. */
+export declare const STEP_TIMEOUT_MS = 5000;
+export interface Frame {
+    t: number;
+    data: Buffer;
+}
+/** Where a pointer step acted, in viewport CSS pixels, for the click marker. */
+export interface PointerMark {
+    step: number;
+    x: number;
+    y: number;
+}
+export interface SideRecording extends SideTiming {
+    viewport: ViewportSize;
+    frames: Frame[];
+    pointers: PointerMark[];
+    /** HTTP status of the page. */
+    status?: number;
+    /** The step that could not be done, and why, in plain words. */
+    failure?: {
+        step: number;
+        message: string;
+    };
+}
+export declare class StepError extends Error {
+}
+/**
+ * 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 declare function recordSide(url: string, moment: Moment, viewport: ViewportSize, opts: {
+    auth?: AuthOptions;
+    maxWidth: number;
+}): Promise<SideRecording>;
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAQ,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,8EAA8E;AAC9E,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,2DAA2D;AAC3D,eAAO,MAAM,OAAO,OAAO,CAAC;AAC5B,6FAA6F;AAC7F,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC;;;;GAIG;AACH,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,wEAAwE;AACxE,eAAO,MAAM,eAAe,OAAO,CAAC;AAOpC,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,qBAAa,SAAU,SAAQ,KAAK;CAAG;AAwHvC;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAwD5J"}

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

@@ -35,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,EAAgC,WAAW,EAAE,mBAAmB,EAAY,MAAM,YAAY,CAAC;AAKtG,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;AAKD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CA2ItF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CA0CxD"}
+{"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

@@ -7,6 +7,7 @@ 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}\``;
@@ -56,6 +57,45 @@ export function groupChanges(outcomes) {
 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;
 /**
@@ -64,15 +104,17 @@ 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 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');
@@ -124,8 +166,11 @@ export function buildComment(result, options = {}) {
                     : '**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.', '');
     }
+    lines.push(...clips);
     for (const { lead: o, others } of groupChanges(result.outcomes)) {
         const u = images(o);
         if (others.length) {
@@ -229,6 +274,14 @@ export function buildSummary(result) {
     }
     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.