Compare commits

..
35 changed files with 1172 additions and 79 deletions

No files matched your search

+17
View File
@@ -159,6 +159,23 @@ invisible on a device.
A pixel mismatch that rounds to 0.00% is noise and counts as "same". Diff regions inside the status-bar band are excluded from the verdict and reported as `ignoredStatusBarRegions`; the Viewer marks that band in Compare.
Each changed region also records whether its content only moved. CI searches for the shift (up to 20 screenshot
pixels vertically and 4 horizontally, whole pixels and then sixths of one) that best lines Before up with After inside
the region; near-ties go to the smallest move, and a second fit nearly as good two or more pixels away (repeating
content) or a best fit at the edge of the search leaves the region unmeasured. When the shift explains most of the
region's difference (a quarter for a move of half a pixel or less, where text re-rasterizes rather than moves; 60%
above that) and, aligned by it, no more than two pixels still differ by over 140 in any channel, the region gets
`shift: { x, y }` in screenshot pixels (right and down positive). New text, another colour or a caret is not a move.
Every region the comparison found is measured, not only the eight it publishes, and `allRegionsMoved: true` says all
of them moved. Moves are measured while the comparison's time budget lasts.
The Viewer draws moved areas dashed, at each side's own position, labelled with how far they moved to a tenth
("↑4.1pt"); areas whose moves are within a third of each other merge into one outline, never around a changed area.
When every region moved, What changed says how far per direction in place of the generic visual finding, and adds
"Nothing on this screen changed content" when no other finding remains. A switch there turns the labels off. iOS
screenshots are one pixel per point, so labels read in points; Android's are labelled in screenshot pixels, since the
report does not know the screen's density.
## 7. Local CI test
`test/ci/run.mjs` runs the production pipeline against an app folder in this repository (`test/ci/apps/wallet`) and a scenario (`test/ci/scenarios/<app>/<name>/`: `scenario.json`, `overlay/`, `expected.json`, optional `setup.yaml`). The [local CI test harness README](test/ci/README.md) covers prerequisites, scenarios, expectations, the matrix runner and how to revisit a result. In outline:
+4
View File
@@ -179,6 +179,10 @@ imported source changed), `app-wide` (only app-wide inputs such as dependencies,
| Not compared | No comparison was performed, including for a screen whose source changed. Not counted as a change: Explore reports what the captures show, not what the code might do. Earlier versions listed these as Source-affected |
A difference that rounds to 0.00% of pixels is rendering noise and counts as no difference.
A changed region whose content only moved (a layout that grew by a device pixel, a sheet that is taller) carries
`shift`, how far it moved in screenshot pixels, and `allRegionsMoved: true` says every region CI found moved (it
publishes the largest eight); the Viewer labels each outline with its move. A shift does not change the verdict: a
moved screen is still Modified.
Accessibility only is how readers present a `modified` verdict whose visual verdict is `unchanged`; the contract has no
separate status for it, so reports from earlier versions show it too. The accessibility tree can include content outside
the screenshot (rows below the fold, elements under a sheet), so such a change may still be visible on a device.
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.4",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.4",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.19.1",
"version": "0.19.4",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
+10
View File
@@ -172,8 +172,18 @@ export type PublicVisualVerdict = {
rect: { x: number; y: number; width: number; height: number };
normalizedRect: { x: number; y: number; width: number; height: number };
differentPixels: number; shareOfDiffPercentage: number; dominantChange: string; location: string;
/**
* Set when the region's content is the same in both screenshots, only moved: how far, in screenshot pixels
* (right and down are positive). Absent when the content itself changed.
*/
shift?: { x: number; y: number };
}>;
tool: string;
/**
* Every region the comparison found (not only the published ones) only moved: nothing on the screen changed
* content. Absent when any region changed, or moves were not measured.
*/
allRegionsMoved?: true;
/** Diff regions inside the iOS status-bar band that were excluded from the verdict. */
ignoredStatusBarRegions?: number;
/** Diff regions that lay entirely inside the home-indicator band and were left out of the verdict. */
+11 -1
View File
@@ -75,13 +75,23 @@ function assertReviewFields(surface: Surface, enforceComparisonEvidence: boolean
}
}
/** A region's move between the screenshots: finite, and small enough to be layout drift rather than another screen. */
function validShift(shift: unknown): boolean {
if (!shift || typeof shift !== "object") return false;
const { x, y } = shift as { x?: unknown; y?: unknown };
return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y) && Math.abs(x) <= 64 && Math.abs(y) <= 64;
}
function assertVisualVerdict(visual: PublicVisualVerdict, enforceComparisonEvidence: boolean, paired: boolean): void {
if (!visual || typeof visual !== "object" || !VISUAL_VERDICTS.has(visual.verdict)
|| typeof visual.reason !== "string" || (enforceComparisonEvidence && visual.reason === "diff-failed") || typeof visual.tool !== "string"
|| typeof visual.threshold !== "number" || !Number.isFinite(visual.threshold)
|| (visual.mismatchPercentage !== undefined
&& (typeof visual.mismatchPercentage !== "number" || !Number.isFinite(visual.mismatchPercentage) || visual.mismatchPercentage < 0))
|| (visual.regions !== undefined && (!Array.isArray(visual.regions) || visual.regions.length > 64))
|| (visual.regions !== undefined && (!Array.isArray(visual.regions) || visual.regions.length > 64
|| visual.regions.some(region => region?.shift !== undefined && !validShift(region.shift))))
|| (visual.allRegionsMoved !== undefined && (visual.allRegionsMoved !== true || !visual.regions?.length
|| visual.regions.some(region => region.shift === undefined)))
|| !paired) {
throw new Error("Public visual verdict is inconsistent");
}
+28
View File
@@ -27,6 +27,7 @@ import {
} from "./visual-evidence.js";
import { AGENT_DEVICE_VERSION } from "../shared/agent-device-version.js";
import { STATUS_BAR_BAND_PERCENT } from "../shared/png-evidence.js";
import { measureRegionShifts } from "./region-shift.js";
export const DEFAULT_VISUAL_THRESHOLD = 0.1;
export const DEFAULT_EVIDENCE_TIME_BUDGET_MS = 10 * 60_000;
@@ -141,6 +142,29 @@ function visualVerdict(assessment: VisualEvidenceAssessment, threshold: number):
};
}
/**
* The published regions with how far their content moved, where a move explains it: a layout that shifted by a
* device pixel reads as moved, not as changed. Every region the comparison found is measured, not only the ones
* published, so `allRegionsMoved` can say nothing else on the screen changed. A measurement that fails leaves the
* regions as they were.
*/
async function withRegionShifts(basePath: string, headPath: string, all: readonly VisualDiffRegion[], published: NonNullable<PublicVisualVerdict["regions"]>):
Promise<Pick<PublicVisualVerdict, "regions" | "allRegionsMoved">> {
try {
const shifts = await measureRegionShifts(basePath, headPath, all.map(region => region.rect));
const shiftOf = new Map(all.map((region, index) => [region.rect, shifts[index]] as const));
return {
regions: published.map(region => {
const shift = shiftOf.get(region.rect);
return shift ? { ...region, shift } : region;
}),
...(all.length > 0 && shifts.every(Boolean) ? { allRegionsMoved: true as const } : {}),
};
} catch {
return { regions: published };
}
}
/** Remove status-bar-only diff regions from a measurement and recompute its verdict inputs. */
export function ignoreStatusBar(measurement: ScreenshotDiffMeasurement, bandPercent: number = STATUS_BAR_BAND_PERCENT): { measurement: ScreenshotDiffMeasurement; ignored: number } {
const bands = ignoreSystemBands(measurement, { top: bandPercent, bottom: 0 });
@@ -463,6 +487,10 @@ export async function assessPublicEvidence(options: {
representative: measurement,
});
visual = visualVerdict(assessment, threshold);
// Measuring moves is extra: once the comparison budget is spent, regions go out unmeasured.
if (visual.verdict === "modified" && visual.regions?.length && now() <= deadline) {
Object.assign(visual, await withRegionShifts(basePath, headPath, measurement.regions, visual.regions));
}
if (ignoredTop > 0) visual.ignoredStatusBarRegions = ignoredTop;
if (ignoredBottom > 0) visual.ignoredHomeIndicatorRegions = ignoredBottom;
visualCounts.compared += 1;
+150
View File
@@ -0,0 +1,150 @@
import { createRequire } from "node:module";
import { readFile } from "node:fs/promises";
import type { DecodedFrame } from "../shared/png-evidence.js";
/** How far a region's content moved from Before to After, in screenshot pixels (right and down are positive). */
export type RegionShift = { x: number; y: number };
type Rect = { x: number; y: number; width: number; height: number };
/**
* The farthest a region is searched for, in screenshot pixels: layout drift, not a different screen. Drift adds up
* down a long screen (a device pixel per text element above), so the vertical reach is the larger.
*/
const MAX_SHIFT_X = 4;
const MAX_SHIFT_Y = 20;
/** How close to the edge of the search a best fit may land and still count: the real one may lie beyond it. */
const EDGE = 1.5;
/**
* The share of a region's difference one shift must explain for the region to have moved rather than changed.
* A move of half a pixel or less re-rasterizes text rather than shifting it, so a pure shift explains only a
* quarter to a half of it; content that changed (new text, a caret) explains under a quarter at that size, and
* anything larger has to be explained mostly by the shift. Measured on euxy's SDK 58 upgrade (brentvatne/euxy#161).
*/
const MIN_EXPLAINED = 0.6;
const MIN_EXPLAINED_SUBPIXEL = 0.25;
const SUBPIXEL = 0.5;
/** A smaller shift is rendering noise, not a move. */
const MIN_SHIFT = 0.25;
/** Sixths of a pixel in the refining search: a third of a 1x pixel is one device pixel on a 3x screen. */
const STEPS_PER_PIXEL = 6;
/** Fits this close to the best are ties, which go to the smallest move (content that is the same all along one axis). */
const TIE = 1.005;
/** Another fit this close at a vertical offset two or more pixels away makes the move ambiguous (repeating content). */
const AMBIGUOUS = 1.05;
/**
* After aligning by the move, content is the same only where every channel is within this: re-rasterized text
* differs by at most about 125 (brentvatne/euxy#161), new content by about 200. A few pixels over it are noise; more are a change.
*/
const CHANGED_CHANNEL = 140;
const CHANGED_PIXELS = 3;
type Image = { width: number; height: number; frame: DecodedFrame; luminance: Float32Array };
type Fit = { sx: number; sy: number; error: number };
function image(frame: DecodedFrame): Image {
const luminance = new Float32Array(frame.width * frame.height);
for (let index = 0; index < luminance.length; index += 1) {
const offset = index * 4;
luminance[index] = 0.299 * frame.data[offset]! + 0.587 * frame.data[offset + 1]! + 0.114 * frame.data[offset + 2]!;
}
return { width: frame.width, height: frame.height, frame, luminance };
}
/** Bilinear sample of one plane: `channel` 0–2 of the frame, or luminance when undefined. */
function at(source: Image, x: number, y: number, channel?: number): number {
const cx = Math.min(source.width - 1, Math.max(0, x));
const cy = Math.min(source.height - 1, Math.max(0, y));
const x0 = Math.floor(cx), y0 = Math.floor(cy);
const x1 = Math.min(source.width - 1, x0 + 1), y1 = Math.min(source.height - 1, y0 + 1);
const fx = cx - x0, fy = cy - y0;
const value = channel === undefined
? (px: number, py: number) => source.luminance[py * source.width + px]!
: (px: number, py: number) => source.frame.data[(py * source.width + px) * 4 + channel]!;
return value(x0, y0) * (1 - fx) * (1 - fy) + value(x1, y0) * fx * (1 - fy) + value(x0, y1) * (1 - fx) * fy + value(x1, y1) * fx * fy;
}
/** How badly After's region matches Before shifted by (sx, sy). */
function mismatch(base: Image, head: Image, rect: Rect, sx: number, sy: number): number {
let error = 0;
for (let y = rect.y; y < rect.y + rect.height; y += 1) {
for (let x = rect.x; x < rect.x + rect.width; x += 1) {
error += Math.abs(at(base, x - sx, y - sy) - head.luminance[y * head.width + x]!);
}
}
return error;
}
/** The best of some fits, with near-ties going to the smallest move. */
function bestOf(fits: readonly Fit[]): Fit {
const least = Math.min(...fits.map(fit => fit.error));
return fits.filter(fit => fit.error <= least * TIE + 1e-6)
.sort((a, b) => Math.hypot(a.sx, a.sy) - Math.hypot(b.sx, b.sy))[0]!;
}
/** Whether, aligned by the move, some of the region still differs strongly in any channel: content that changed. */
function changedAfterMove(base: Image, head: Image, rect: Rect, sx: number, sy: number): boolean {
let strong = 0;
for (let y = rect.y; y < rect.y + rect.height; y += 1) {
for (let x = rect.x; x < rect.x + rect.width; x += 1) {
for (let channel = 0; channel < 3; channel += 1) {
if (Math.abs(at(base, x - sx, y - sy, channel) - head.frame.data[(y * head.width + x) * 4 + channel]!) > CHANGED_CHANNEL) {
strong += 1;
if (strong >= CHANGED_PIXELS) return true;
break;
}
}
}
}
return false;
}
/**
* The shift that explains one region's difference, if one does: the region's content is the same in both
* screenshots, only moved. A region whose content changed (new text, another colour) has no shift, and neither has
* one whose content repeats so that several shifts fit.
*/
function regionShift(base: Image, head: Image, region: Rect): RegionShift | undefined {
const x = Math.max(0, Math.floor(region.x)), y = Math.max(0, Math.floor(region.y));
const rect = { x, y, width: Math.min(head.width - x, Math.ceil(region.width)), height: Math.min(head.height - y, Math.ceil(region.height)) };
if (rect.width <= 0 || rect.height <= 0) return undefined;
const unshifted = mismatch(base, head, rect, 0, 0);
if (unshifted === 0) return undefined;
// Whole pixels first, every pixel counting: sampling every other row aliases on thin shapes (text, hairlines).
const whole: Fit[] = [];
for (let sy = -MAX_SHIFT_Y; sy <= MAX_SHIFT_Y; sy += 1) {
for (let sx = -MAX_SHIFT_X; sx <= MAX_SHIFT_X; sx += 1) whole.push({ sx, sy, error: mismatch(base, head, rect, sx, sy) });
}
const coarse = bestOf(whole);
if (whole.some(fit => Math.abs(fit.sy - coarse.sy) >= 2 && fit.error <= coarse.error * AMBIGUOUS + 1e-6)) return undefined;
// Then sixths of a pixel around it, from whole-number steps so a move up and a move down round alike.
const fine: Fit[] = [];
for (let iy = -STEPS_PER_PIXEL; iy <= STEPS_PER_PIXEL; iy += 1) {
for (let ix = -STEPS_PER_PIXEL; ix <= STEPS_PER_PIXEL; ix += 1) {
const sx = coarse.sx + ix / STEPS_PER_PIXEL, sy = coarse.sy + iy / STEPS_PER_PIXEL;
fine.push({ sx, sy, error: ix === 0 && iy === 0 ? coarse.error : mismatch(base, head, rect, sx, sy) });
}
}
const best = bestOf(fine);
if (Math.abs(best.sx) > MAX_SHIFT_X - EDGE || Math.abs(best.sy) > MAX_SHIFT_Y - EDGE) return undefined;
const distance = Math.hypot(best.sx, best.sy);
const needed = distance <= SUBPIXEL + 1e-6 ? MIN_EXPLAINED_SUBPIXEL : MIN_EXPLAINED;
if (distance < MIN_SHIFT - 1e-6 || 1 - best.error / unshifted < needed) return undefined;
if (changedAfterMove(base, head, rect, best.sx, best.sy)) return undefined;
const round = (value: number) => Math.round(value * 100) / 100 || 0;
return { x: round(best.sx), y: round(best.sy) };
}
/** Each region's shift between two screenshots of the same size; undefined where a region's content changed. */
export function regionShifts(baseFrame: DecodedFrame, headFrame: DecodedFrame, regions: readonly Rect[]): Array<RegionShift | undefined> {
if (baseFrame.width !== headFrame.width || baseFrame.height !== headFrame.height) return regions.map(() => undefined);
const base = image(baseFrame), head = image(headFrame);
return regions.map(region => regionShift(base, head, region));
}
/** Reads both PNG screenshots and measures each region's shift. */
export async function measureRegionShifts(basePath: string, headPath: string, regions: readonly Rect[]): Promise<Array<RegionShift | undefined>> {
const { PNG } = createRequire(import.meta.url.replace(/\?.*$/, ""))("pngjs") as
{ PNG: { sync: { read(bytes: Buffer, options: { checkCRC: boolean }): DecodedFrame } } };
const [base, head] = await Promise.all([readFile(basePath), readFile(headPath)]);
return regionShifts(PNG.sync.read(base, { checkCRC: false }), PNG.sync.read(head, { checkCRC: false }), regions);
}
+7 -4
View File
@@ -406,10 +406,13 @@ test("the Screens tree folds by row, by keyboard, and all at once, and remembers
await tree.getByRole("button", { name: "Expand all" }).click();
await expect.poll(() => rows.count()).toBe(expandedRows);
// Section headings name the folder, with the path beneath.
const onboarding = page.getByRole("region", { name: "Onboarding" });
await expect(onboarding.getByRole("heading", { level: 2 })).toHaveText("Onboarding");
await expect(onboarding.locator(".screens-section-head .path")).toHaveText("app/onboarding");
// The tree names the folders, so the page beside it is one grid without section headings, in the tree's order.
await expect(page.locator(".screens-page .screens-section-head")).toHaveCount(0);
await expect(page.locator(".screens-page .screens-grid")).toHaveCount(1);
const treeOrder = await tree.locator(".screens-tree-row[data-screen-id]").evaluateAll(rows => rows.map(row => row.dataset.screenId));
const gridOrder = await page.locator(".screens-page .screens-cell").evaluateAll(cells => cells.map(cell => cell.dataset.screenId));
assert.ok(gridOrder.length > 1);
assert.deepEqual(gridOrder, treeOrder);
assert.deepEqual(errors, []);
});
+96 -2
View File
@@ -1309,7 +1309,100 @@ for (const canvas of ["map", "screens"] as const) {
});
}
test("reuses the Map screenshot card visual in Screens, with the route at the card's left edge", async ({ page }) => {
test("← and → step through the Screens cards in page order, with focus, and leave the tree's arrows alone", async ({ page }) => {
await serveWorkspace(page);
await page.goto("/screens");
const grid = page.getByRole("main", { name: "Screens" });
await grid.getByRole("button", { name: /^All/ }).click();
const cells = grid.locator(".screens-grid .screens-cell");
const ids = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
expect(ids.length).toBeGreaterThan(2);
const card = (id: string) => grid.locator(`.screens-cell[data-screen-id="${id}"] .screen-screenshot-card`);
const target = (id: string) => grid.locator(`.screens-cell[data-screen-id="${id}"] .screen-screenshot-target`);
// With nothing selected, → starts at the first card.
await expect(grid.locator(".screen-screenshot-card.selected")).toHaveCount(0);
await page.keyboard.press("ArrowRight");
await expect(card(ids[0]!)).toHaveClass(/selected/);
await expect(target(ids[0]!)).toBeFocused();
await page.keyboard.press("ArrowRight");
await expect(card(ids[1]!)).toHaveClass(/selected/);
await expect(target(ids[1]!)).toBeFocused();
await page.keyboard.press("ArrowRight");
await expect(card(ids[2]!)).toHaveClass(/selected/);
await page.keyboard.press("ArrowLeft");
await expect(card(ids[1]!)).toHaveClass(/selected/);
await expect(card(ids[2]!)).not.toHaveClass(/selected/);
// ↓ and ↑ move a row, to the card in the same column.
const tops = await cells.evaluateAll(elements => elements.map(element => Math.round(element.getBoundingClientRect().top)));
const columns = tops.filter(top => top === tops[0]).length;
if (ids.length > 1 + columns) {
await page.keyboard.press("ArrowDown");
await expect(card(ids[1 + columns]!)).toHaveClass(/selected/);
await expect(target(ids[1 + columns]!)).toBeFocused();
await page.keyboard.press("ArrowUp");
await expect(card(ids[1]!)).toHaveClass(/selected/);
}
// Held, → keeps stepping, as in Compare, and stops on release.
const selectedAt = async () => ids.indexOf((await grid.locator(".screens-cell:has(.screen-screenshot-card.selected)").getAttribute("data-screen-id"))!);
const from = await selectedAt();
await page.keyboard.down("ArrowRight");
await expect.poll(selectedAt, { timeout: 4000 }).toBeGreaterThanOrEqual(Math.min(ids.length - 1, from + 3));
await page.keyboard.up("ArrowRight");
const released = await selectedAt();
await page.waitForTimeout(500);
expect(await selectedAt()).toBe(released);
// Return opens the pick in the Inspector, from the card or from anywhere on the page.
const inspector = page.getByRole("complementary", { name: "Inspector panel" });
await expect(inspector).toBeHidden();
await page.keyboard.press("Enter");
await expect(inspector).toBeVisible();
await page.keyboard.press("Escape");
await expect(inspector).toBeHidden();
await page.evaluate(() => (document.activeElement as HTMLElement | null)?.blur());
await page.keyboard.press("Enter");
await expect(inspector).toBeVisible();
await page.keyboard.press("Escape");
await expect(inspector).toBeHidden();
// In the tree, ← and → fold and unfold rows; they do not step the cards.
const picked = await selectedAt();
const row = grid.locator(".screens-tree-row").first();
await row.focus();
await page.keyboard.press("ArrowLeft");
await expect(card(ids[picked]!)).toHaveClass(/selected/);
});
test("→ steps the Screens cards right after Screens is opened from the toolbar, and from a pick that Changed hides", async ({ page }) => {
await serveWorkspace(page);
await page.goto("/map");
await page.getByRole("group", { name: "Canvas view" }).getByRole("button", { name: "Screens", exact: true }).click();
const grid = page.getByRole("main", { name: "Screens" });
const cells = grid.locator(".screens-grid .screens-cell");
await expect(cells.first()).toBeVisible();
// Focus is still on the toolbar's Screens button.
await page.keyboard.press("ArrowRight");
await expect(cells.first().locator(".screen-screenshot-card")).toHaveClass(/selected/);
// Pick a screen that Changed hides, then show Changed: → goes to the next changed card after it in the tree.
await grid.getByRole("button", { name: /^All/ }).click();
const all = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
await grid.getByRole("button", { name: /^Changed/ }).click();
const changed = await cells.evaluateAll(elements => elements.map(element => element.getAttribute("data-screen-id")!));
const hidden = all.find((id, position) => !changed.includes(id) && all.slice(position + 1).some(next => changed.includes(next)));
test.skip(!hidden, "the fixture has no unchanged screen before a changed one");
await grid.getByRole("button", { name: /^All/ }).click();
await grid.locator(`.screens-cell[data-screen-id="${hidden}"] .screen-screenshot-target`).click();
await grid.getByRole("button", { name: /^Changed/ }).click();
const expected = all.slice(all.indexOf(hidden!) + 1).find(id => changed.includes(id))!;
await page.keyboard.press("ArrowRight");
await expect(grid.locator(`.screens-cell[data-screen-id="${expected}"] .screen-screenshot-card`)).toHaveClass(/selected/);
});
test("reuses the Map screenshot card in Screens, with the route under the screenshot at the card's left edge", async ({ page }) => {
await serveWorkspace(page);
await page.goto("/screens");
@@ -1337,8 +1430,9 @@ test("reuses the Map screenshot card visual in Screens, with the route at the ca
};
});
expect(layout.flexDirection).toBe("column");
// The card is the Map's, so the heading still comes first in the markup; Screens shows it as the card's footer.
expect(layout.headingBeforeImage).toBe(true);
expect(layout.headingTop).toBeLessThan(layout.imageTop);
expect(layout.headingTop).toBeGreaterThan(layout.imageTop);
expect(layout.titleLeftDelta).toBeLessThan(1);
}
@@ -253,3 +253,36 @@ test("quarantine: a report-level contract failure still throws", () => {
assert.throws(() => quarantineReviewContract(provenance), /disagree with their build provenance/);
});
test('a visual region may carry the shift its content moved by, and a malformed one is rejected', async () => {
const { assertPublicReview } = await import('../../dist/contracts/review-validation.js');
const valid = JSON.parse(JSON.stringify(reviewWithRegion({ x: 0, y: -4.17 })));
assert.doesNotThrow(() => assertPublicReview(valid));
for (const shift of [{ x: 0 }, { x: 0, y: Number.NaN }, { x: 0, y: 500 }, 'up']) {
assert.throws(() => assertPublicReview(reviewWithRegion(shift)), /visual verdict is inconsistent/, JSON.stringify(shift));
}
});
function reviewWithRegion(shift) {
const input = review();
input.surfaces[0].review = { status: "modified", description: "Updated visual styling in the main content area." };
input.surfaces[0].visual = { verdict: "modified", reason: "repeated-cross-build-delta", mismatchPercentage: 1, threshold: 0.1, tool: "agent-device",
regions: [{ rect: { x: 0, y: 0, width: 1, height: 1 }, normalizedRect: { x: 0, y: 0, width: 100, height: 100 },
differentPixels: 1, shareOfDiffPercentage: 100, dominantChange: "mixed", location: "center", shift }] };
return input;
}
test('allRegionsMoved is only true, and only where every published region carries its shift', async () => {
const { assertPublicReview } = await import('../../dist/contracts/review-validation.js');
const moved = reviewWithRegion({ x: 0, y: 1 });
moved.surfaces[0].visual.allRegionsMoved = true;
assert.doesNotThrow(() => assertPublicReview(moved));
for (const [label, mutate] of [['false', visual => { visual.allRegionsMoved = false; }],
['a region without a shift', visual => { delete visual.regions[0].shift; }],
['no regions', visual => { delete visual.regions; }]]) {
const input = reviewWithRegion({ x: 0, y: 1 });
input.surfaces[0].visual.allRegionsMoved = true;
mutate(input.surfaces[0].visual);
assert.throws(() => assertPublicReview(input), /visual verdict is inconsistent/, label);
}
});
+103
View File
@@ -0,0 +1,103 @@
import assert from "node:assert/strict";
import test from "node:test";
import { Buffer } from "node:buffer";
import { regionShifts } from "../../dist/review/region-shift.js";
/** A 120×160 frame of a light background with dark text-like bars, drawn `offsetY` pixels lower (fractions blend rows). */
function frame(offsetY, { barColor = 40, extraBar = false } = {}) {
const width = 120, height = 160;
const data = Buffer.alloc(width * height * 4, 240);
const bars = [[10, 20, 80, 6], [10, 34, 60, 4], [10, 60, 90, 8], ...(extraBar ? [[10, 90, 70, 6]] : [])];
for (let y = 0; y < height; y += 1) {
for (let x = 0; x < width; x += 1) {
// Coverage of the pixel row [y, y+1) by each bar after the vertical offset, for sub-pixel moves.
let coverage = 0;
for (const [bx, by, bw, bh] of bars) {
if (x < bx || x >= bx + bw) continue;
const top = by + offsetY, bottom = top + bh;
coverage += Math.max(0, Math.min(y + 1, bottom) - Math.max(y, top));
}
const value = Math.round(240 - Math.min(1, coverage) * (240 - barColor));
data.fill(value, (y * width + x) * 4, (y * width + x) * 4 + 3);
data[(y * width + x) * 4 + 3] = 255;
}
}
return { width, height, data };
}
const region = { x: 0, y: 10, width: 110, height: 70 };
test("a region whose content only moved reports how far, to a sixth of a pixel", () => {
assert.deepEqual(regionShifts(frame(0), frame(2), [region]), [{ x: 0, y: 2 }]);
assert.deepEqual(regionShifts(frame(0), frame(-4), [region]), [{ x: 0, y: -4 }]);
const [third] = regionShifts(frame(0), frame(1 / 3), [region]);
assert.ok(third && Math.abs(third.y - 1 / 3) < 0.1 && third.x === 0, JSON.stringify(third));
});
test("a region whose content changed, or that did not change, has no shift", () => {
assert.deepEqual(regionShifts(frame(0), frame(0, { barColor: 200 }), [region]), [undefined], "another colour is a change, not a move");
assert.deepEqual(regionShifts(frame(0), frame(0, { extraBar: true }), [{ x: 0, y: 80, width: 110, height: 30 }]), [undefined], "new content is a change");
assert.deepEqual(regionShifts(frame(0), frame(0), [region]), [undefined], "identical pixels have nothing to explain");
});
test("screenshots of different sizes are not measured", () => {
const small = { ...frame(0), width: 60, data: Buffer.alloc(60 * 160 * 4, 240) };
assert.deepEqual(regionShifts(small, frame(2), [region]), [undefined]);
});
test("a third of a pixel counts as a move even when re-rasterized text explains only part of it, but changed content does not", () => {
// A third of a pixel down, then every bar a shade darker: the shift explains roughly a third of the difference,
// as re-rasterized text does on a 3x screen.
const shifted = frame(1 / 3), base = frame(0);
const noisy = { ...shifted, data: Buffer.from(shifted.data.map((value, index) => (index % 4 === 3 || value === 240 ? value : Math.max(0, value - 14)))) };
const [move] = regionShifts(base, noisy, [region]);
assert.ok(move && Math.abs(move.y - 1 / 3) < 0.1, JSON.stringify(move));
});
test("a best fit at the edge of the search is not a move: repeating content lines up with itself a pitch away", () => {
// Bars repeating every 12 pixels; After is the same pattern 12 pixels lower, which also matches unshifted rows.
const stripes = offset => {
const width = 60, height = 120, data = Buffer.alloc(width * height * 4, 240);
for (let y = 0; y < height; y += 1) if (((y - offset) % 12 + 12) % 12 < 4) for (let x = 0; x < width; x += 1) data.fill(30, (y * width + x) * 4, (y * width + x) * 4 + 3);
for (let i = 3; i < data.length; i += 4) data[i] = 255;
return { width, height, data };
};
// Moved down 5 also fits as up 7: two fits that good are ambiguous, so the region is not a move rather than a wrong one.
assert.deepEqual(regionShifts(stripes(0), stripes(5), [{ x: 0, y: 20, width: 60, height: 60 }]), [undefined]);
});
/** A frame painted by `paint(x, y)` (dark where true) on a light background, optionally in colour. */
function painted(width, height, paint, colour = [30, 30, 30]) {
const data = Buffer.alloc(width * height * 4, 240);
for (let y = 0; y < height; y += 1) for (let x = 0; x < width; x += 1) {
const offset = (y * width + x) * 4;
if (paint(x, y)) { data[offset] = colour[0]; data[offset + 1] = colour[1]; data[offset + 2] = colour[2]; }
data[offset + 3] = 255;
}
return { width, height, data };
}
test("content that is the same all along one axis is measured along the other: full-width bars and hairlines", () => {
const bar = offset => painted(80, 100, (x, y) => y >= 40 + offset && y < 46 + offset);
assert.deepEqual(regionShifts(bar(0), bar(2), [{ x: 0, y: 30, width: 80, height: 30 }]), [{ x: 0, y: 2 }]);
const hairline = offset => painted(80, 100, (x, y) => y === 50 + offset);
assert.deepEqual(regionShifts(hairline(0), hairline(1), [{ x: 0, y: 44, width: 80, height: 12 }]), [{ x: 0, y: 1 }]);
assert.deepEqual(regionShifts(hairline(0), hairline(-3), [{ x: 0, y: 40, width: 80, height: 16 }]), [{ x: 0, y: -3 }]);
});
test("a region that moved and also changed is not a move: the leftover after aligning it gives the change away", () => {
// Three bars moved down 2px, plus a new short bar inside the region, as a digit that changed in a row that moved.
const bars = (offset, extra) => painted(120, 160, (x, y) => (x >= 10 && x < 90 && ((y >= 20 + offset && y < 26 + offset)
|| (y >= 34 + offset && y < 38 + offset) || (y >= 60 + offset && y < 68 + offset))) || (extra && x >= 95 && x < 105 && y >= 45 && y < 48));
assert.deepEqual(regionShifts(bars(0, false), bars(2, false), [region]), [{ x: 0, y: 2 }]);
assert.deepEqual(regionShifts(bars(0, false), bars(2, true), [region]), [undefined]);
// Another colour of the same brightness, moved: luminance alone would call it moved.
const red = painted(120, 160, (x, y) => x >= 10 && x < 90 && y >= 20 && y < 40, [200, 40, 40]);
const green = painted(120, 160, (x, y) => x >= 10 && x < 90 && y >= 22 && y < 42, [40, 112, 40]);
assert.deepEqual(regionShifts(red, green, [region]), [undefined]);
});
test("a half-pixel move up and down is judged alike", () => {
const up = regionShifts(frame(0), frame(-0.5), [region])[0], down = regionShifts(frame(0), frame(0.5), [region])[0];
assert.deepEqual([up?.y, down?.y], [-0.5, 0.5]);
});
+15 -1
View File
@@ -3,7 +3,7 @@ import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { indexMap } = await tsImport("../../viewer/src/utils/model.ts", import.meta.url);
const { screenTree } = await tsImport("../../viewer/src/utils/screen-tree.ts", import.meta.url);
const { screenTree, treeScreenOrder } = await tsImport("../../viewer/src/utils/screen-tree.ts", import.meta.url);
const at = (second) => `2026-10-13T00:00:${String(second).padStart(2, "0")}.000Z`;
function screen(id, title, depth, extra = {}) {
@@ -49,6 +49,20 @@ test("with route files, sections follow the app directory and the tabs lead", ()
assert.deepEqual(folders, ["(tabs)/"]);
});
test("the screens' order is the tree's, depth first: a nested folder's screens come right after their parent's", () => {
// The folders are found as settings, feed, settings/security: sections keep that order, while the tree nests
// security under settings. The Screens grid and its arrow keys follow the tree, as the sidebar reads.
const screens = [screen("profile", "A profile", 1), screen("feed", "B feed", 1), screen("security", "C security", 1), screen("loose", "D loose", 1)];
const routeFiles = new Map([
["profile", "app/settings/profile.tsx"],
["feed", "app/feed/index.tsx"],
["security", "app/settings/security/index.tsx"],
]);
const tree = screenTree(screens, indexMap(map({ screens })), routeFiles);
assert.deepEqual(tree.sections.flatMap(section => section.screenIds), ["profile", "feed", "security", "loose"]);
assert.deepEqual(treeScreenOrder(tree), ["profile", "security", "feed", "loose"]);
});
test("a black-box exploration groups by the tab each screen was opened from", () => {
const screens = [
screen("seq", "Sequencer", 0),
+17 -1
View File
@@ -15,6 +15,21 @@ test("hints print modifiers in Apple's ⌥⇧⌘ order and as Ctrl+Alt+Shift els
assert.equal(formatShortcut(SHORTCUTS.camera.fit, true), "⇧1");
assert.equal(formatShortcut({ code: "KeyT", key: "T", mod: true, alt: true }, false), "Ctrl+Alt+T");
assert.equal(formatShortcut(SHORTCUTS.edit.redo, false), "Ctrl+Shift+Z");
// The Control key itself prints as ⌃ on a Mac, where ⌘ would be a different key.
assert.equal(formatShortcut(SHORTCUTS.canvasByNumber.screens, true), "⌃2");
assert.equal(formatShortcut(SHORTCUTS.canvasByNumber.screens, false), "Ctrl+2");
});
test("Ctrl+1, Ctrl+2 and Ctrl+3 reach Map, Screens and Compare with Control alone, never ⌘ (the browser's tab keys)", () => {
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true }), SHORTCUTS.canvasByNumber.map), true);
assert.equal(matchesShortcut(key("Digit2", { ctrlKey: true }), SHORTCUTS.canvasByNumber.screens), true);
assert.equal(matchesShortcut(key("Digit3", { ctrlKey: true }), SHORTCUTS.canvasByNumber.compare), true);
assert.equal(matchesShortcut(key("Digit1", { metaKey: true }), SHORTCUTS.canvasByNumber.map), false);
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true, metaKey: true }), SHORTCUTS.canvasByNumber.map), false);
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true, shiftKey: true }), SHORTCUTS.canvasByNumber.map), false);
// Compare's 1, 2, 3 (Split, Swipe, Flip) stay plain digits.
assert.equal(matchesShortcut(key("Digit1", { ctrlKey: true }), SHORTCUTS.compare.split), false);
assert.equal(matchesShortcut(key("Digit1"), SHORTCUTS.canvasByNumber.map), false);
});
test("a chord matches only its own modifiers, on either ⌘ or Ctrl", () => {
@@ -35,7 +50,8 @@ test("no two shortcuts share a chord", () => {
const seen = new Map();
for (const [group, entries] of Object.entries(SHORTCUTS)) {
for (const [name, shortcut] of Object.entries(entries)) {
const chord = `${shortcut.code}:${Boolean(shortcut.mod)}:${Boolean(shortcut.alt)}:${Boolean(shortcut.shift)}`;
// Off Apple keyboards ⌘ is Ctrl, so a Control chord clashes with the same ⌘ chord.
const chord = `${shortcut.code}:${Boolean(shortcut.mod || shortcut.ctrl)}:${Boolean(shortcut.alt)}:${Boolean(shortcut.shift)}`;
const clash = seen.get(chord);
assert.ok(!clash, `${group}.${name} repeats ${clash}`);
seen.set(chord, `${group}.${name}`);
+47
View File
@@ -0,0 +1,47 @@
import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { groupVisualRegions, formatMove, layoutShiftSummary } = await tsImport("../../viewer/src/utils/visual-diff.ts", import.meta.url);
const move = (y, x = 0, unit = "pt") => ({ x: x / 4, y: y / 8, amount: { x, y }, unit });
const region = (y, height, shift, x = 10, width = 60) => ({ x, y, width, height, share: 10, ...(shift === undefined ? {} : { move: shift }) });
test("areas that moved by the same amount read as one, across a gap that keeps changed areas apart", () => {
// A sheet's title, button and footer moved up about 4pt (measured 3.8–4.3 across its parts), 5% of the height apart.
const sheet = groupVisualRegions([region(60, 5, move(-4)), region(70, 5, move(-4.33)), region(80, 3, move(-3.83)), region(86, 3, move(-4.17))]);
assert.equal(sheet.length, 1);
assert.equal(formatMove(sheet[0]), "↑4.1pt", "one number: the parts' average, to a tenth");
// The same areas with changed content stay apart, as before.
assert.equal(groupVisualRegions([region(60, 5), region(70, 5), region(80, 3)]).length, 3);
// A moved area and a changed one that touch are not merged, and up and down did not move together.
assert.equal(groupVisualRegions([region(60, 5, move(-4)), region(65, 5)]).length, 2);
assert.equal(groupVisualRegions([region(30, 5, move(1)), region(36, 5, move(-1))]).length, 2);
});
test("rows that drifted by different amounts keep their own outlines and numbers", () => {
// List rows a device pixel and more apart: 1, 1.5 and 2pt, as the rows behind euxy's sheet.
const rows = groupVisualRegions([region(40, 5, move(1)), region(46, 5, move(1.5)), region(52, 5, move(2))]);
assert.deepEqual(rows.map(row => formatMove(row)), ["↓1pt", "↓1.5pt", "↓2pt"]);
// Two-thirds of a point apart is a different move too, as on euxy's channel-surf sheet (1.3 and 2pt).
assert.equal(groupVisualRegions([region(40, 5, move(1.33)), region(46, 5, move(2))]).length, 2);
});
test("a moved outline never grows around a changed area", () => {
const changes = groupVisualRegions([region(10, 4, move(1)), region(15, 4), region(20, 4, move(1))]);
assert.deepEqual(changes.map(change => `${change.move ? "moved" : "changed"} ${change.y}`), ["moved 10", "changed 15", "moved 20"]);
});
test("labels are one number, never empty or zero", () => {
assert.equal(formatMove({ move: move(1, 2, "px") }), "→2 ↓1px", "a sideways move is named too, in Android's screenshot pixels");
assert.equal(formatMove({ move: move(1.33) }), "↓1.3pt");
// Two nudges a third of a pixel apart, one sideways and one down, average under a quarter on both axes.
assert.equal(formatMove({ move: move(0.17, 0.16) }), "↓0.2pt");
});
test("What changed summarizes a screen whose every area moved, per direction, and nothing when any content changed", () => {
const moved = groupVisualRegions([region(20, 5, move(1)), region(40, 5, move(2)), region(70, 5, move(-4.17))]);
assert.deepEqual(layoutShiftSummary(moved), ["2 areas moved down 1–2pt.", "1 area moved up 4.2pt."]);
assert.equal(layoutShiftSummary([...moved, ...groupVisualRegions([region(90, 3)])]), undefined);
assert.equal(layoutShiftSummary([]), undefined);
});
+5 -1
View File
@@ -46,6 +46,7 @@ import {
type ThemePreference,
} from "./utils/navigation";
import {
CANVAS_NUMBER_KEYS,
matchesShortcut,
modalOpen,
SHORTCUTS,
@@ -142,7 +143,10 @@ const LEGACY_COLLAPSED_STORAGE_KEY = "expo-explore:panel-collapsed";
const RIGHT_COLLAPSED_STORAGE_KEY = "expo-explore:right-panel-collapsed";
// The shell's keyboard map, paired with what each key selects. Read as lists so a key and the
// thing it reaches stay one entry.
const CANVAS_KEYS = Object.entries(SHORTCUTS.canvas) as [CanvasView, Shortcut][];
const CANVAS_KEYS = [
...Object.entries(SHORTCUTS.canvas),
...(CANVAS_NUMBER_KEYS ? Object.entries(SHORTCUTS.canvasByNumber) : []),
] as [CanvasView, Shortcut][];
/** Before data loads there is no comparison to assume. A workspace reparses the URL on arrival. */
const EMPTY_ROUTE_CONTEXT: RouteContext = {
@@ -5,6 +5,10 @@ import { StatusGlyph } from "../shared/status-icon";
import { Tooltip } from "../shared/tooltip";
import { DIFF_LABELS, type DiffStatus } from "../../utils/build-diff";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { setMeasurementsShown, useMeasurementsShown } from "../../utils/measurements-setting";
/** A screen whose every changed area only moved: how far, per direction, and whether no other finding remains. */
export type LayoutShift = { lines: string[]; nothingElse: boolean };
import type { ComparePicker } from "./compare-section";
/**
@@ -92,11 +96,29 @@ export function CompareSteps(props: {
* findings as bullets, then what changed for assistive technology under its own heading, then the
* notes about the comparison under a hairline.
*/
export function WhatChangedContent(props: { facts: string[]; assistive?: string[]; accessibilityOnly?: boolean | undefined; notes: string[] }) {
export function WhatChangedContent(props: {
facts: string[];
assistive?: string[];
accessibilityOnly?: boolean | undefined;
/** Set when every changed area only moved: a line per direction (layoutShiftSummary), and whether nothing else changed. */
layoutShift?: LayoutShift | undefined;
/** Some outlined area moved, so its outline can be labelled with how far. */
measurable?: boolean | undefined;
notes: string[];
}) {
const assistive = props.assistive ?? [];
const assistiveTitle = useId();
const measurements = useMeasurementsShown();
return (
<div className="what-changed-content" role="region" aria-label="What changed on this screen">
{props.layoutShift ? (
<div className="what-changed-shift">
<p>{props.layoutShift.nothingElse ? "Layout shifted. Nothing on this screen changed content." : "Layout shifted."}</p>
<ul className="what-changed-content-list">
{props.layoutShift.lines.map((line) => <li key={line}>{line}</li>)}
</ul>
</div>
) : null}
{props.facts.length > 0 ? (
<ul className="what-changed-content-list">
{props.facts.map((fact) => <li key={fact}>{fact}</li>)}
@@ -123,6 +145,16 @@ export function WhatChangedContent(props: { facts: string[]; assistive?: string[
{props.notes.map((note) => <p key={note}>{note}</p>)}
</div>
) : null}
{props.measurable ? (
<label className="what-changed-measurements">
<span className="what-changed-measurements-text">
<span>Show measurements</span>
<small>How far each outlined area moved</small>
</span>
<input type="checkbox" role="switch" className="what-changed-switch" checked={measurements}
onChange={(event) => setMeasurementsShown(event.target.checked)} />
</label>
) : null}
</div>
);
}
@@ -136,13 +168,15 @@ export function WhatChangedPopover(props: {
facts: string[];
assistive?: string[];
accessibilityOnly?: boolean | undefined;
layoutShift?: LayoutShift | undefined;
measurable?: boolean | undefined;
notes: string[];
open: boolean;
onOpenChange: (open: boolean) => void;
}) {
const ref = useRef<HTMLDivElement>(null);
const { open, onOpenChange } = props;
const empty = props.facts.length === 0 && !props.assistive?.length && props.notes.length === 0;
const empty = props.facts.length === 0 && !props.assistive?.length && !props.layoutShift && props.notes.length === 0;
useEffect(() => {
if (!open) return;
const onPointerDown = (event: PointerEvent) => {
@@ -173,10 +207,10 @@ export function WhatChangedPopover(props: {
{open ? (
<div className="compare-what-changed-popover" role="dialog" aria-modal="false" aria-label="What changed">
{/* A screen that changed only for assistive technology has nothing else to title. */}
{props.facts.length > 0 || props.notes.length > 0
{props.facts.length > 0 || props.notes.length > 0 || props.layoutShift
? <strong className="compare-what-changed-popover-title">What changed</strong> : null}
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
accessibilityOnly={props.accessibilityOnly} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
</div>
) : null}
</div>
@@ -203,6 +203,51 @@
.what-changed-assistive-title > .status-glyph-dot { width: 8px; height: 8px; border-radius: 2px; background: var(--diff); }
.what-changed-assistive-context { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
.what-changed-assistive + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
/* A screen whose changed areas only moved: the verdict, then how far, per direction. */
.what-changed-shift { display: flex; flex-direction: column; gap: 8px; }
.what-changed-shift > p { margin: 0; color: var(--text); font-size: 13px; line-height: 18px; }
/* Show measurements: a row with a switch, under a hairline, like the hand-off's scope switch. */
.what-changed-measurements {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
padding-top: 12px;
border-top: 1px solid var(--panel-line);
cursor: pointer;
}
.what-changed-measurements-text { display: flex; min-width: 0; flex-direction: column; gap: 2px; font-size: 13px; font-weight: 500; line-height: 18px; }
.what-changed-measurements-text > small { color: var(--secondary); font-size: 12px; font-weight: 400; line-height: 16px; }
.what-changed-switch {
position: relative;
width: 36px;
height: 22px;
flex: none;
margin: 0;
border-radius: 11px;
background: var(--border);
cursor: pointer;
appearance: none;
transition: background 160ms ease;
}
.what-changed-switch::after {
position: absolute;
top: 2px;
left: 2px;
width: 18px;
height: 18px;
border-radius: 9px;
background: #fff;
box-shadow: 0 1px 2px rgb(0 0 0 / 0.25);
content: "";
transition: transform 160ms ease;
}
.what-changed-switch:checked { background: var(--text); }
.what-changed-switch:checked::after { transform: translateX(14px); }
.what-changed-switch:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
@media (prefers-reduced-motion: reduce) {
.what-changed-switch, .what-changed-switch::after { transition: none; }
}
.what-changed-content-list + .what-changed-content-notes { padding-top: 12px; border-top: 1px solid var(--panel-line); }
.what-changed-content-notes > p { margin: 0; color: var(--secondary); font-size: 12px; line-height: 17px; }
@@ -4,7 +4,7 @@ import type { ChangesMenuData } from "../panels/changes-menu";
import { diffLabel, ACCESSIBILITY_ONLY_HIGHLIGHT, type BuildDiff, type ScreenDiff } from "../../utils/build-diff";
import type { MapIndex } from "../../utils/model";
import type { ChangedScreen } from "../../utils/changed-screens";
import { groupVisualRegions, type VisualChange } from "../../utils/visual-diff";
import { groupVisualRegions, layoutShiftSummary, type VisualChange } from "../../utils/visual-diff";
import { formatShortcut, matchesShortcut, SHORTCUTS, shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { optionalStorage } from "../../utils/embedded-report";
@@ -51,11 +51,14 @@ export function compareModeOptions() {
// Highlight changes (the outlines) is one remembered choice, on unless turned off, shared by
// every view that draws them: Compare, the Inspector's review and its header button, and the O key.
const outlinesListeners = new Set<() => void>();
/** The choice made this visit, so the button works where storage is denied (a private window). */
let outlinesChosen: boolean | undefined;
function storedOutlines(): boolean {
return optionalStorage.getItem(OUTLINES_STORAGE_KEY) !== "false";
return outlinesChosen ?? optionalStorage.getItem(OUTLINES_STORAGE_KEY) !== "false";
}
/** Sets the outlines choice everywhere at once and remembers it. */
/** Sets the outlines choice everywhere at once and remembers it where it can. */
export function setOutlinesShown(shown: boolean) {
outlinesChosen = shown;
optionalStorage.setItem(OUTLINES_STORAGE_KEY, String(shown));
for (const listener of outlinesListeners) listener();
}
@@ -101,9 +104,22 @@ export function useCompareController(options: CompareControllerOptions) {
);
// Only what CI found on this screen. The generic summary ("Shared app source changed.") is
// not a finding about this screen, so it leaves the list empty and the button disabled.
// Every changed area only moved, CI's own count included (it publishes the largest regions only): say how far,
// in place of its generic pixel finding ("Updated visual styling in the main content area").
const shiftLines = useMemo(
() => (screenDiff?.visual?.allRegionsMoved ? layoutShiftSummary(areas) : undefined),
[areas, screenDiff?.visual?.allRegionsMoved],
);
const measurable = areas.some((area) => area.move);
const facts = useMemo(
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"),
[screenDiff],
() => presentedChanges(screenDiff).filter((change) => change.id !== "legacy-summary"
&& !(shiftLines && change.fact?.templateId === "visual.main-content-changed")),
[screenDiff, shiftLines],
);
// "Nothing on this screen changed content" only when no other finding says otherwise.
const layoutShift = useMemo(
() => (shiftLines ? { lines: shiftLines, nothingElse: facts.length === 0 } : undefined),
[shiftLines, facts.length],
);
// What changed for assistive technology is listed under its own heading.
const split = useMemo(() => splitForAssistiveTechnology(facts, screenDiff), [facts, screenDiff]);
@@ -241,7 +257,7 @@ export function useCompareController(options: CompareControllerOptions) {
const chosenMode: CompareMode = phone ? phoneMode : desktopMode;
const modesDisabled = !comparable;
return {
screen, screenDiff, route, position, previous, next, comparable, areas, facts, split,
screen, screenDiff, route, position, previous, next, comparable, areas, facts, split, layoutShift, measurable,
mode, chosenMode, modesDisabled, chooseMode, modeOptions, outlines, shownOutlines, statusBarIgnored, homeIndicatorIgnored, toggleOutlines,
activeArea, setActiveArea, stepArea, flipSide, flip, swipePosition, setSwipePosition,
aspect, setAspect, factsOpen, setFactsOpen,
@@ -355,7 +371,7 @@ export function CompareSection(props: CompareSectionProps) {
</button>
</Tooltip>
<WhatChangedPopover facts={factCopies} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} open={factsOpen} onOpenChange={setFactsOpen} />
</div>
</header>
@@ -490,7 +506,7 @@ export function CompareStage(props: StageProps) {
))}
</figcaption>
<div className="compare-frame-wrap">
<button type="button" className="compare-frame compare-flip-frame"
<button type="button" className="compare-frame compare-flip-frame" data-side={showing}
aria-label={`Show ${showing === "after" ? "Before" : "After"}`} onClick={props.onFlip}>
<CompareImage src={showing === "after" ? after : before} alt={`${props.title}, ${showing}`}
placeholder="No screenshot" onAspect={props.onAspect} />
@@ -1,7 +1,7 @@
import { useEffect } from "react";
import { createPortal } from "react-dom";
import { X } from "lucide-react";
import { formatShortcut, SHORTCUTS, type Shortcut } from "../../utils/shortcuts";
import { CANVAS_NUMBER_KEYS, formatShortcut, SHORTCUTS, type Shortcut } from "../../utils/shortcuts";
import type { CanvasView } from "../../utils/navigation";
import { useModalDialog } from "../../hooks/use-modal-dialog";
@@ -63,6 +63,9 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
label: context.hasChanges ? "Map, Screens, Compare" : "Map, Screens",
keys: sections.map((section) => SHORTCUTS.canvas[section]),
},
...(CANVAS_NUMBER_KEYS
? [{ label: "The same, by their place in the toolbar", keys: sections.map((section) => SHORTCUTS.canvasByNumber[section]) }]
: []),
{ label: "Search screens", keys: [SHORTCUTS.app.search] },
...(context.handoff ? [{ label: "Hand off to AI", keys: [SHORTCUTS.app.handoff] }] : []),
...(context.hasChanges ? [{ label: "Changed screens menu", keys: [SHORTCUTS.app.changes] }] : []),
@@ -83,9 +86,17 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
],
};
const screensGroup: Group = {
title: "Screens",
rows: [
{ label: "Move through the screens", keys: ["←", "→", "↑", "↓"] },
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
],
};
const here: Group[] = context.canvas === "compare"
? [reviewGroup(context)]
: [...(context.review ? [reviewGroup(context)] : []), ...(context.canvas === "map" ? [mapGroup] : []), CAMERA];
: [...(context.review ? [reviewGroup(context)] : []), ...(context.canvas === "map" ? [mapGroup] : []),
...(context.canvas === "screens" ? [screensGroup] : []), CAMERA];
return [here, [goTo, view]];
}
@@ -2,7 +2,7 @@ import { type CSSProperties, type ReactNode } from "react";
import { ChevronDown } from "lucide-react";
import { ToggleGroup } from "../shared/toggle-group";
import { ChangeOutlines, HomeIndicatorBand, StatusBarBand } from "../panels/visual-diff";
import { WhatChangedContent } from "./compare-header";
import { WhatChangedContent, type LayoutShift } from "./compare-header";
import {
CompareStage,
compareModeOptions,
@@ -46,11 +46,13 @@ function WhatChangedAccordion(props: {
facts: string[];
assistive?: string[];
accessibilityOnly?: boolean | undefined;
layoutShift?: LayoutShift | undefined;
measurable?: boolean | undefined;
notes: string[];
open: boolean;
onOpenChange?: (open: boolean) => void;
}) {
const count = props.facts.length + (props.assistive?.length ?? 0);
const count = props.facts.length + (props.assistive?.length ?? 0) + (props.layoutShift?.lines.length ?? 0);
const empty = !props.onOpenChange || (count === 0 && props.notes.length === 0);
const open = props.open && !empty;
return (
@@ -72,7 +74,7 @@ function WhatChangedAccordion(props: {
{open ? (
<div className="what-changed-accordion-content" id="what-changed-accordion-content">
<WhatChangedContent facts={props.facts} {...(props.assistive ? { assistive: props.assistive } : {})}
accessibilityOnly={props.accessibilityOnly} notes={props.notes} />
accessibilityOnly={props.accessibilityOnly} layoutShift={props.layoutShift} measurable={props.measurable} notes={props.notes} />
</div>
) : null}
</section>
@@ -145,7 +147,8 @@ export function SidebarReview(props: CompareControllerOptions) {
/>
</div>
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes}
<WhatChangedAccordion facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes}
open={compare.factsOpen} onOpenChange={compare.setFactsOpen} />
</section>
);
+1 -1
View File
@@ -349,7 +349,7 @@ function ScreenDiffSection(props: {
: { ...current, [screenshot]: aspectRatio }
));
};
// CI compares the two images pixel for pixel, so the same areas are outlined on both sides.
// The same areas are outlined on both sides; an area that only moved sits where its content is on each.
const outlines = visualChanges.length > 0 ? <ChangeOutlines changes={visualChanges} /> : null;
return (
@@ -19,6 +19,35 @@
box-shadow: 0 0 0 3px color-mix(in srgb, var(--modified) 35%, transparent);
}
.visual-change-outlines.has-active .visual-change-outline:not(.active) { opacity: 0.35; }
/* An area that only moved: dashed and quiet, in the slate of a measurement rather than the orange of a change. */
.visual-change-outline.moved {
border: 1.5px dashed var(--moved);
background: transparent;
}
.visual-change-outline.moved.active {
background: color-mix(in srgb, var(--moved) 14%, transparent);
box-shadow: 0 0 0 3px color-mix(in srgb, var(--moved) 30%, transparent);
}
/* How far it moved, riding the outline's top right corner. */
.visual-change-measure {
position: absolute;
top: 0;
right: 0;
padding: 0 5px;
border-radius: 5px;
color: #fff;
background: var(--moved);
font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
font-size: 10px;
font-weight: 600;
line-height: 15px;
white-space: nowrap;
transform: translate(4px, -60%);
}
:root[data-theme="dark"] .visual-change-measure { color: #0b0c0e; }
/* The Before side draws moved areas where their content was (see ChangeOutlines): Compare's sides and the
Inspector's side-by-side pair. */
.compare-side[data-side="before"], .compare-flip-frame[data-side="before"], [data-diff-side="before"] { --outline-before: 1; }
/* The status-bar band CI does not compare: blurred out, explained by its tooltip on hover. */
.visual-status-bar-band {
+15 -9
View File
@@ -1,36 +1,42 @@
import { useRef, useState, type CSSProperties, type KeyboardEvent, type PointerEvent } from "react";
import { ChevronsLeftRight } from "lucide-react";
import { outlineRect, type VisualChange } from "../../utils/visual-diff";
import { formatMove, outlineRect, type VisualChange } from "../../utils/visual-diff";
import { useMeasurementsShown } from "../../utils/measurements-setting";
import { HOME_INDICATOR_BAND_PERCENT_BY_PLATFORM, STATUS_BAR_BAND_PERCENT } from "../../../../src/contracts/capture";
import { ScreenshotImage } from "../shared/screenshot-image";
import "./visual-diff.css";
/**
* Outlines over a screenshot, one per changed area. The same rectangles go on Before and After:
* CI compares the two images pixel for pixel, so an area has one position, not one per side.
* The parent must be positioned.
* Outlines over a screenshot, one per changed area. An area whose content changed has one position, the same
* on Before and After. An area that only moved is dashed and drawn where its content is on each side, labelled
* with how far it moved while measurements are shown. The parent must be positioned.
*/
export function ChangeOutlines(props: {
changes: readonly VisualChange[];
activeIndex?: number | undefined;
}) {
const measurements = useMeasurementsShown();
return (
<span
className={`visual-change-outlines${props.activeIndex !== undefined ? " has-active" : ""}`}
aria-hidden="true">
{props.changes.map((change, index) => {
const rect = outlineRect(change);
// A moved area sits where its content is on each side: the Before side (--outline-before: 1) draws it
// back by the move, so the outline jumps by the amount on its label when the sides flip.
const back = (offset: number, move: number | undefined) => (move ? `calc(${offset}% - var(--outline-before, 0) * ${move}%)` : `${offset}%`);
return (
<span
key={index}
className={`visual-change-outline${props.activeIndex === index ? " active" : ""}`}
className={`visual-change-outline${change.move ? " moved" : ""}${props.activeIndex === index ? " active" : ""}`}
style={{
left: `${rect.x}%`,
top: `${rect.y}%`,
left: back(rect.x, change.move?.x),
top: back(rect.y, change.move?.y),
width: `${rect.width}%`,
height: `${rect.height}%`,
}}
/>
}}>
{change.move && measurements ? <span className="visual-change-measure">{formatMove(change)}</span> : null}
</span>
);
})}
</span>
@@ -75,7 +75,7 @@ export function PhoneCompare(props: CompareControllerOptions & {
<ScanSearch aria-hidden="true" />
</button>
<button type="button" className="phone-icon-button" aria-label="What changed" aria-haspopup="dialog"
disabled={compare.facts.length === 0 && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
disabled={compare.facts.length === 0 && !compare.layoutShift && notes.length === 0} onClick={() => compare.setFactsOpen(true)}>
<List aria-hidden="true" />
</button>
{props.headerAction}
@@ -122,7 +122,8 @@ export function PhoneCompare(props: CompareControllerOptions & {
</div>
<PhoneSheet title="What changed" open={compare.factsOpen} onClose={() => compare.setFactsOpen(false)}>
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly} notes={notes} />
<WhatChangedContent facts={facts} assistive={assistive} accessibilityOnly={screenDiff.accessibilityOnly}
layoutShift={compare.layoutShift} measurable={compare.measurable} notes={notes} />
</PhoneSheet>
</section>
);
+85
View File
@@ -184,6 +184,91 @@ button.screens-tree-row:hover { color: var(--text); background: var(--panel-hove
.screens-cell-via { overflow: hidden; color: var(--tertiary); font-size: 11px; text-overflow: ellipsis; white-space: nowrap; }
.screens-cell-elsewhere { color: var(--modified); font-size: 11px; font-weight: 600; }
/* ── Desktop grid ── */
/* One evenly spaced grid. Each screen is a card: the screenshot in a grey well and the route under it, with the
status as the tree's dot before it, the way file browsers show documents. Nothing is framed in the status colour,
so the page reads as a list of screens rather than a canvas of them. */
.screens-page:not(.phone) .screens-sections { display: block; padding-top: 0; }
.screens-page:not(.phone) .screens-grid { gap: 12px; }
/* Wide enough for a 28-character route after the dot, in the footer's 10.5px mono with room to spare: Linux's
fonts set it at about 183px. Five cards fit beside the tree at 1440px. */
.screens-page:not(.phone) .screens-cell { width: 216px; }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card {
overflow: hidden;
gap: 0;
border: 1px solid var(--border-subtle);
border-radius: 12px;
background: var(--surface);
transition: border-color 120ms ease, box-shadow 120ms ease;
}
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.screen-screenshot-target:hover) { border-color: color-mix(in srgb, var(--accent) 55%, var(--border-subtle)); }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent); }
/* The status is laid out against the card, not the screenshot, so it can sit in the footer. */
.screens-page:not(.phone) .screens-cell :is(.screen-screenshot-slot, .diff-frame) { position: static; }
.screens-page:not(.phone) .screens-cell .screen-screenshot-slot { order: 1; height: 236px; flex: none; padding: 12px 0; background: var(--element); }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected .screen-screenshot-slot { background: var(--accent-soft); }
.screens-page:not(.phone) .screens-cell .screen-node-image img,
.screens-page:not(.phone) .screens-cell .screen-node-image > .image-placeholder,
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-frame .screen-node-image img,
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-frame .screen-node-image > .image-placeholder {
border-color: transparent;
border-radius: 8px;
box-shadow: 0 1px 3px rgb(0 0 0 / 0.14);
}
/* The image box hugs the screenshot, so its corners and shadow are the screenshot's and no box shows around it. */
/* The screenshot fits the well both ways at its own proportions (styles.css's max-width and max-height), so a
landscape capture is framed as itself, not letterboxed inside a portrait-sized box. */
.screens-page:not(.phone) .screens-cell .screen-node-image img { width: auto; height: auto; background: transparent; }
/* No screenshot: the well has a size here, so the placeholder fits it the way styles.css fits it to a Map slot,
at the screenshot's proportions, rather than by the cell's width as a phone's cell does (phone.css). */
.screens-page:not(.phone) .screens-cell .screen-node-image:has(> .image-placeholder) { container-type: size; }
.screens-page:not(.phone) .screens-cell .screen-node-image > .image-placeholder {
width: min(
100cqw - 2 * var(--frame-border),
(100cqh - 2 * var(--frame-border)) * var(--screenshot-width) / var(--screenshot-height),
var(--screenshot-width) * 1px
);
height: min(
100cqh - 2 * var(--frame-border),
(100cqw - 2 * var(--frame-border)) * var(--screenshot-height) / var(--screenshot-width),
var(--screenshot-height) * 1px
);
aspect-ratio: auto;
}
/* A selected card's button is pressed, and a focused pressed button brightens (styles.css). Here that would wash out
the screenshot and, as a filter, become the box the status is placed in, lifting it into the well. Keyboard focus
rings the card instead. */
.screens-page:not(.phone) .screens-cell .screen-screenshot-target:focus-visible { filter: none; outline: 0; }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.screen-screenshot-target:focus-visible) {
box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 42%, transparent);
}
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected:has(.screen-screenshot-target:focus-visible) {
box-shadow: 0 0 0 1px var(--accent), 0 0 0 4px color-mix(in srgb, var(--accent) 32%, transparent);
}
.screens-page:not(.phone) .screens-cell .screen-node-heading { order: 2; min-height: 0; padding: 10px 6px 10px 8px; }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card:has(.diff-label) .screen-node-heading { padding-left: 20px; }
.screens-page:not(.phone) .screens-cell .screen-node-title { font-size: 10.5px; line-height: 14px; }
.screens-page:not(.phone) .screens-cell .screen-screenshot-card.selected .screen-node-title { color: var(--accent-strong); font-weight: 600; }
/* The status is the tree's dot before the route, in the status colour (a square for accessibility only); the word
stays in the label's accessible name. */
.screens-page:not(.phone) .screens-cell .screen-screenshot-card .diff-label {
top: auto;
bottom: 13.5px;
left: 8px;
width: 7px;
height: 7px;
overflow: hidden;
padding: 0;
border-radius: 50%;
color: transparent;
background: var(--diff);
box-shadow: none;
font-size: 0;
transform: none;
}
.screens-page:not(.phone) .screens-cell .diff-accessibility-only .diff-label { border-radius: 2px; }
.screens-page:not(.phone) .screens-cell :is(.screens-cell-via, .screens-cell-elsewhere) { padding-inline: 2px; }
/* ── Phone ── */
/* The space under the top bar is a block, not padding: both engines inset a sticky child's rest
position by the scroll container's padding, which pushed the section bar a bar's height too low. */
+142 -18
View File
@@ -5,9 +5,11 @@ import { primaryScreenshotForScreen, screenshotSize } from "../../utils/screen-i
import { diffClass, type BuildDiff, type DiffStatus } from "../../utils/build-diff";
import { focusStatusOf, isCapturedChange } from "../../utils/changed-screens";
import { displayPathForScreen, screenLabel } from "../../utils/screen-path";
import { screenTree, treeIndex, treeNodeKey, type ScreenTree, type ScreenTreeNode } from "../../utils/screen-tree";
import { screenTree, treeIndex, treeNodeKey, treeScreenOrder, type ScreenTree, type ScreenTreeNode } from "../../utils/screen-tree";
import type { Appearance } from "../../utils/appearance";
import type { FocusRequest, FocusStatus } from "../../utils/navigation";
import { shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
import { PhoneSheet } from "../phone/phone-chrome";
@@ -75,6 +77,26 @@ function cardId(id: string): string {
return `screens-card-${id.replace(/[^A-Za-z0-9_-]/g, "_")}`;
}
/**
* The card in the row above or below a screen's, nearest it across: read from where the cards sit, so it follows the
* grid however many columns the page has room for. A short last row still takes ↓ from the row above it.
*/
function cardInNextRow(from: string, ids: readonly string[], down: boolean): string | undefined {
const box = (id: string) => document.getElementById(cardId(id))?.getBoundingClientRect();
const here = box(from);
if (!here) return undefined;
const centre = (rect: DOMRect) => rect.left + rect.width / 2;
const rows = ids.flatMap(id => {
const rect = box(id);
return rect && (down ? rect.top >= here.bottom - 1 : rect.bottom <= here.top + 1) ? [{ id, rect }] : [];
});
if (!rows.length) return undefined;
const nearestTop = down ? Math.min(...rows.map(row => row.rect.top)) : Math.max(...rows.map(row => row.rect.top));
const row = rows.filter(candidate => Math.abs(candidate.rect.top - nearestTop) < 1);
return row.reduce((best, candidate) =>
Math.abs(centre(candidate.rect) - centre(here)) < Math.abs(centre(best.rect) - centre(here)) ? candidate : best).id;
}
function sectionAnchor(id: string): string {
return `screens-section-${id.replace(/[^A-Za-z0-9_-]/g, "_")}`;
}
@@ -168,6 +190,7 @@ function TreeRows(props: {
<button type="button" style={style}
className={`screens-tree-row${node.tab ? " tab" : ""}${props.visible.has(screen.id) ? "" : " filtered"}`}
aria-current={props.selectedScreenId === screen.id ? "true" : undefined}
data-screen-id={screen.id}
aria-expanded={key ? open : undefined}
data-tree-key={key}
onClick={() => props.onSelect(screen.id)}>
@@ -202,8 +225,8 @@ function Legend(props: { others: Appearance[] }) {
}
/**
* Screens as a page that scrolls: a section per route folder (or per tab, when there are no route
* files), with the tree of them beside it on desktop and behind a Tree button on a phone.
* Screens as a page that scrolls. On desktop, one grid of every screen in the order of the tree beside it; on a
* phone, a section per route folder (or per tab, when there are no route files), with the tree behind a Tree button.
*/
export function ScreensView(props: ScreensViewProps) {
const tree: ScreenTree = useMemo(
@@ -222,6 +245,9 @@ export function ScreensView(props: ScreensViewProps) {
const sections = tree.sections
.map(section => ({ ...section, screenIds: section.screenIds.filter(id => shown.has(id)) }))
.filter(section => section.screenIds.length > 0);
// The desktop grid reads in the tree's order, not the sections' (screen-tree.ts).
const treeOrder = useMemo(() => treeScreenOrder(tree), [tree]);
const order = props.phone ? sections.flatMap(section => section.screenIds) : treeOrder.filter(id => shown.has(id));
const others = [...new Set([...(props.changedElsewhere?.values() ?? [])].flat())];
// Folding. All keeps the reader's folds and remembers them per report. Changed folds separately, starting
@@ -321,12 +347,118 @@ export function ScreensView(props: ScreensViewProps) {
requestAnimationFrame(() => document.getElementById(cardId(id))?.scrollIntoView({ block: "center", behavior: "smooth" }));
};
// On desktop the arrow keys move through the cards: ← and → in their order on the page (`order`), as the arrows step
// through screens in Compare, and ↑ and ↓ to the card above or below, by where the cards sit, so they follow the grid
// at any width. A step picks the screen as the tree does, leaving the Inspector as it is, and focus follows it; with
// nothing picked, → and ↓ start at the first card, and a pick that Changed hides steps from where it sits in the tree.
// The tree's rows keep their arrow keys, and so do the Inspector's controls. Phones are left as they were.
// Held, an arrow keeps stepping as Compare's do (key-hold.ts). Return opens the picked screen in the Inspector, as a
// click on its card does; on the card itself the button already does.
const orderRef = useRef(order);
orderRef.current = order;
const treeOrderRef = useRef(treeOrder);
treeOrderRef.current = treeOrder;
const selectedRef = useRef(selected);
selectedRef.current = selected;
const pickRef = useRef(props.onPickScreen ?? props.onSelectScreen);
pickRef.current = props.onPickScreen ?? props.onSelectScreen;
const openRef = useRef(props.onSelectScreen);
openRef.current = props.onSelectScreen;
useEffect(() => {
if (props.phone) return;
/** The card an arrow moves to from `from` (the pick, or the last card a hold stepped to). */
const next = (code: string, from: string | undefined): string | undefined => {
const ids = orderRef.current;
const vertical = code === "ArrowUp" || code === "ArrowDown";
const forward = code === "ArrowRight" || code === "ArrowDown";
if (from && ids.includes(from)) return vertical ? cardInNextRow(from, ids, forward) : ids[ids.indexOf(from) + (forward ? 1 : -1)];
if (from && treeOrderRef.current.includes(from)) {
// Picked, but hidden by Changed: the nearest shown card past it in the tree's order.
const shownIds = new Set(ids);
const all = treeOrderRef.current;
const at = all.indexOf(from);
return (forward ? all.slice(at + 1) : all.slice(0, at).reverse()).find(candidate => shownIds.has(candidate));
}
return forward ? ids[0] : ids[ids.length - 1];
};
const go = (id: string) => {
pickRef.current(id);
requestAnimationFrame(() => document.getElementById(cardId(id))?.querySelector<HTMLElement>(".screen-screenshot-target")?.focus({ preventScroll: true }));
};
let hold: { code: string; at: string; timer: ReturnType<typeof setTimeout> } | undefined;
const endHold = () => {
if (hold) clearTimeout(hold.timer);
hold = undefined;
};
const beginHold = (code: string, at: string) => {
endHold();
let step = 1;
const tick = () => {
const id = hold && next(code, hold.at);
if (!hold || !id) { endHold(); return; }
go(id);
hold = { code, at: id, timer: setTimeout(tick, holdIntervalMs(step)) };
step += 1;
};
hold = { code, at, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
};
const onKeyDown = (event: globalThis.KeyboardEvent) => {
const arrow = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.code);
if (!arrow && event.key !== "Enter") return;
// The browser's own repeat of a held arrow would scroll the page under the hold.
if (event.repeat && hold?.code === event.code) { event.preventDefault(); return; }
if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.defaultPrevented || !shortcutsLive(event)) return;
const target = event.target instanceof Element ? event.target : null;
if (!arrow) {
// Return on a button or a link presses it; elsewhere on the page it opens the pick.
const selectedId = selectedRef.current;
if (target?.closest("button, a, [role=\"button\"]") || !target?.closest("body") || !selectedId || !orderRef.current.includes(selectedId)) return;
if (target !== document.body && !target.closest(".screens-page")) return;
event.preventDefault();
openRef.current(selectedId);
return;
}
// The page, or the bottom toolbar that Screens was just opened from; its buttons have no arrow keys of their own.
const onPage = !target || target === document.body || target.closest(".screens-page, .canvas-toolbar") !== null;
if (!onPage || target?.closest(".screens-tree-list")) return;
const id = next(event.code, selectedRef.current);
if (!id) return;
event.preventDefault();
go(id);
beginHold(event.code, id);
};
const onKeyUp = (event: globalThis.KeyboardEvent) => {
if (hold && event.code === hold.code) endHold();
};
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", endHold);
return () => {
endHold();
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", endHold);
};
}, [props.phone]);
// The Inspector floats over the right edge; the page keeps its content clear of it.
const { visibleFrame } = useCanvasVisibleFrame();
const style = !props.phone && visibleFrame
? ({ "--screens-right-inset": `calc(100% - ${visibleFrame.x + visibleFrame.width}px)` } as CSSProperties)
: undefined;
const cell = (id: string) => {
const screen = props.index.screens.get(id);
return screen ? (
<ScreenCell key={id} screen={screen} index={props.index} diff={props.diff}
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
via={tree.via.get(id)}
selected={props.selectedScreenId === id}
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
onSelect={() => props.onSelectScreen(id)} />
) : null;
};
const treeRows = (
<ul className="screens-tree-list" onKeyDown={onTreeKey}>
<TreeRows nodes={tree.tree} depth={0} index={props.index} diff={props.diff} elsewhere={props.changedElsewhere}
@@ -378,28 +510,20 @@ export function ScreensView(props: ScreensViewProps) {
</aside>
)}
<div className="screens-sections">
{sections.map(section => (
{props.phone ? sections.map(section => (
<section key={section.id} id={sectionAnchor(section.id)} className="screens-section" aria-label={section.name ?? section.title}>
<header className="screens-section-head">
<h2>{section.name ?? section.title}</h2>
{section.path ? <span className="path">{breakAfterSlashes(section.title)}</span>
: section.subtitle ? <span>{section.subtitle}</span> : null}
</header>
<div className="screens-grid">
{section.screenIds.map(id => {
const screen = props.index.screens.get(id);
return screen ? (
<ScreenCell key={id} screen={screen} index={props.index} diff={props.diff}
elsewhere={isChanged(props.diff, id) ? undefined : props.changedElsewhere?.get(id)}
via={tree.via.get(id)}
selected={props.selectedScreenId === id}
dimmed={Boolean(props.focus?.length) && !props.focus!.some((state) => state === focusStatusOf(props.diff?.screens.get(id)))}
onSelect={() => props.onSelectScreen(id)} />
) : null;
})}
</div>
<div className="screens-grid">{section.screenIds.map(cell)}</div>
</section>
))}
)) : (
// On desktop the tree beside the page already shows the folders, so every screen sits in one evenly
// spaced grid in the tree's order, without headings between them.
<div className="screens-grid">{order.map(cell)}</div>
)}
</div>
</div>
+19 -4
View File
@@ -10,6 +10,7 @@ import type {
import {
captureNotes,
visualDiff,
type RegionMove,
type ReviewerChangeCategory,
type ReviewRuntimeEvidence,
type ViewerReviewProjection,
@@ -54,6 +55,19 @@ function comparisonStatus(surface: Surface): BuildComparisonEntry["status"] {
return comparisonReview(surface)?.status ?? "not-compared";
}
/**
* A region's move in percent of the image, from its pixel shift and the image size its rect implies. iOS
* screenshots are one pixel per point; Android's are in the screenshot's own pixels, since the report does not
* know the screen's density.
*/
function regionMove(region: NonNullable<NonNullable<Surface["visual"]>["regions"]>[number], platform: "ios" | "android" | undefined): RegionMove | undefined {
const { shift, rect, normalizedRect } = region;
if (!shift || !(normalizedRect.width > 0) || !(normalizedRect.height > 0)) return undefined;
const imageWidth = (rect.width * 100) / normalizedRect.width;
const imageHeight = (rect.height * 100) / normalizedRect.height;
return { x: (shift.x * 100) / imageWidth, y: (shift.y * 100) / imageHeight, amount: { x: shift.x, y: shift.y }, unit: platform === "android" ? "px" : "pt" };
}
/** The side's route exists and was planned, but its capture ended without a screenshot. */
function captureUnavailable(surface: Surface, side: Side): boolean {
const outcome = side === "base" ? surface.baseOutcome : surface.headOutcome;
@@ -572,10 +586,11 @@ export function publicReviewProjection(review: PublicReview): ViewerReviewProjec
...(surface.visual?.mismatchPercentage !== undefined ? { mismatchPercentage: surface.visual.mismatchPercentage } : {}),
...(surface.visual?.ignoredStatusBarRegions ? { ignoredStatusBarRegions: surface.visual.ignoredStatusBarRegions } : {}),
...(surface.visual?.ignoredHomeIndicatorRegions ? { ignoredHomeIndicatorRegions: surface.visual.ignoredHomeIndicatorRegions } : {}),
regions: (surface.visual?.regions ?? []).map((region) => ({
...region.normalizedRect,
share: region.shareOfDiffPercentage,
})),
...(surface.visual?.allRegionsMoved ? { allRegionsMoved: true } : {}),
regions: (surface.visual?.regions ?? []).map((region) => {
const move = regionMove(region, review.runtime.platform);
return { ...region.normalizedRect, share: region.shareOfDiffPercentage, ...(move ? { move } : {}) };
}),
})
: undefined;
// A side that exists in its revision but has no screenshot says why, in the report's words.
+3
View File
@@ -67,6 +67,8 @@
/* Accessibility only is blue, as in the PR comment (🟦), deeper than the accent a screen variant uses. */
--accessibility: #2f6feb;
--accessibility-soft: #e8f0fe;
/* A measurement: slate, quieter than any change colour. */
--moved: #5b6b85;
--graph-dot: #d9d9e0;
--graph-line: #8b8d98;
--graph-line-soft: #c5c7ce;
@@ -186,6 +188,7 @@
--modified-soft: #331e0b;
--accessibility: #8fa8ff;
--accessibility-soft: #17224a;
--moved: #9fb0cc;
--graph-dot: #212225;
--graph-line: #696e77;
--graph-line-soft: #3f4349;
+2 -2
View File
@@ -4,8 +4,8 @@
* or a spinner accelerates. The browser's own key repeat is ignored (its rate is a fixed OS setting),
* so the hold is timed here and ends on key up, blur, or the end of the list.
*/
export const HOLD_INITIAL_DELAY_MS = 400;
export const HOLD_FIRST_INTERVAL_MS = 300;
export const HOLD_INITIAL_DELAY_MS = 250;
export const HOLD_FIRST_INTERVAL_MS = 200;
export const HOLD_FLOOR_INTERVAL_MS = 70;
const HOLD_DECAY = 0.8;
+30
View File
@@ -0,0 +1,30 @@
import { useSyncExternalStore } from "react";
import { optionalStorage } from "./embedded-report";
const MEASUREMENTS_STORAGE_KEY = "expo-explore:compare-measurements";
const listeners = new Set<() => void>();
/** The choice made this visit: storage can be denied (a private window), and the switch must still work. */
let chosen: boolean | undefined;
function stored(): boolean {
return chosen ?? optionalStorage.getItem(MEASUREMENTS_STORAGE_KEY) !== "false";
}
/** Shows or hides how far each moved area moved, everywhere at once, and remembers the choice where it can. */
export function setMeasurementsShown(shown: boolean) {
chosen = shown;
optionalStorage.setItem(MEASUREMENTS_STORAGE_KEY, String(shown));
for (const listener of listeners) listener();
}
/** Whether outlines label how far each moved area moved: on until a reader turns it off in What changed. */
export function useMeasurementsShown(): boolean {
return useSyncExternalStore(
(onChange) => {
listeners.add(onChange);
return () => listeners.delete(onChange);
},
stored,
() => true,
);
}
+22 -1
View File
@@ -67,6 +67,12 @@ export type ReviewRuntimeEvidenceComparison = {
current?: ReviewRuntimeEvidence;
};
/**
* How far an area's content moved from Before to After when it is otherwise the same: in percent of the image
* (to place the Before outline) and in the screenshot's own units (to label it). Right and down are positive.
*/
export type RegionMove = { x: number; y: number; amount: { x: number; y: number }; unit: "pt" | "px" };
/** One area of the screenshot that differs, in percent of the image width and height (0–100). */
export type VisualDiffRegion = {
x: number;
@@ -75,12 +81,16 @@ export type VisualDiffRegion = {
height: number;
/** This region's share of all differing pixels, in percent. */
share: number;
/** Set when the area only moved; absent when its content changed. */
move?: RegionMove;
};
/** The CI pixel comparison of the before and after screenshots. */
export type ReviewVisualDiff = {
mismatchPercentage?: number;
regions: VisualDiffRegion[];
/** Every region CI found only moved, including ones the report leaves out: nothing on the screen changed content. */
allRegionsMoved?: true;
/** Diff regions inside the status-bar band that CI left out of the verdict. */
ignoredStatusBarRegions?: number;
/** Diff regions inside the home-indicator band (iOS, bottom) that CI left out of the verdict. */
@@ -260,7 +270,17 @@ function visualDiffRegion(value: unknown): VisualDiffRegion | undefined {
const [x, y, width, height, share] = ["x", "y", "width", "height", "share"].map((key) => percent(candidate?.[key]));
if (x === undefined || y === undefined || width === undefined || height === undefined || share === undefined) return undefined;
if (width <= 0 || height <= 0 || x + width > 100.01 || y + height > 100.01) return undefined;
return { x, y, width, height, share };
const move = regionMove(candidate?.move);
return { x, y, width, height, share, ...(move ? { move } : {}) };
}
function regionMove(value: unknown): RegionMove | undefined {
const candidate = record(value);
const amount = record(candidate?.amount);
const finite = (entry: unknown): entry is number => typeof entry === "number" && Number.isFinite(entry) && Math.abs(entry) <= 100;
if (!candidate || !amount || !finite(candidate.x) || !finite(candidate.y) || !finite(amount.x) || !finite(amount.y)
|| (candidate.unit !== "pt" && candidate.unit !== "px")) return undefined;
return { x: candidate.x, y: candidate.y, amount: { x: amount.x, y: amount.y }, unit: candidate.unit };
}
export function visualDiff(value: unknown): ReviewVisualDiff | undefined {
@@ -276,6 +296,7 @@ export function visualDiff(value: unknown): ReviewVisualDiff | undefined {
const ignoredHomeIndicatorRegions = count(candidate.ignoredHomeIndicatorRegions);
return {
regions,
...(candidate.allRegionsMoved === true && regions.length > 0 && regions.every((region) => region.move) ? { allRegionsMoved: true as const } : {}),
...(mismatchPercentage !== undefined ? { mismatchPercentage } : {}),
...(ignoredStatusBarRegions !== undefined ? { ignoredStatusBarRegions } : {}),
...(ignoredHomeIndicatorRegions !== undefined ? { ignoredHomeIndicatorRegions } : {}),
+16
View File
@@ -228,6 +228,22 @@ export type ScreenTreeIndex = {
parents: Map<string, string>;
};
/**
* Every screen in the order the tree lists it: depth first, so a subfolder's screens follow its parent folder's own,
* where sections list folders in the order they were found. A screen the tree leaves out comes last.
*/
export function treeScreenOrder(tree: ScreenTree): string[] {
const ids: string[] = [];
const walk = (nodes: readonly ScreenTreeNode[]) => {
for (const node of nodes) {
if (node.kind === "screen") ids.push(node.screenId);
walk(node.children);
}
};
walk(tree.tree);
return [...new Set([...ids, ...tree.sections.flatMap(section => section.screenIds)])];
}
export function treeIndex(tree: readonly ScreenTreeNode[]): ScreenTreeIndex {
const index: ScreenTreeIndex = { keys: [], screensUnder: new Map(), ancestors: new Map(), parents: new Map() };
const walk = (nodes: readonly ScreenTreeNode[], above: string[]): string[] => nodes.flatMap((node) => {
+23 -3
View File
@@ -7,6 +7,8 @@ export type Shortcut = {
code: string;
/** ⌘ on Apple keyboards, Ctrl everywhere else. */
mod?: boolean;
/** The Control key itself on every keyboard, for chords whose ⌘ form the browser keeps (⌘1–⌘9 switch tabs). */
ctrl?: boolean;
/** ⌥ on Apple keyboards, Alt everywhere else. */
alt?: boolean;
shift?: boolean;
@@ -17,6 +19,12 @@ export type Shortcut = {
const APPLE = typeof navigator !== "undefined"
&& /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent);
/**
* Whether Ctrl+1–3 reach the page. On Apple keyboards ⌃ is free (the browser's tab keys are ⌘1–9); elsewhere the
* browser keeps Ctrl+1–8 for its tabs, so those keys are neither handled nor printed there.
*/
export const CANVAS_NUMBER_KEYS = APPLE;
function mod(code: string, key: string): Shortcut {
return { code, key, mod: true };
}
@@ -25,6 +33,10 @@ function modShift(code: string, key: string): Shortcut {
return { code, key, mod: true, shift: true };
}
function ctrl(code: string, key: string): Shortcut {
return { code, key, ctrl: true };
}
function shift(code: string, key: string): Shortcut {
return { code, key, shift: true };
}
@@ -68,6 +80,12 @@ export const SHORTCUTS = {
screens: plain("KeyS", "S"),
compare: plain("KeyC", "C"),
},
/** The canvases by their place in the toolbar, as tabs are numbered elsewhere. Apple keyboards only (CANVAS_NUMBER_KEYS). */
canvasByNumber: {
map: ctrl("Digit1", "1"),
screens: ctrl("Digit2", "2"),
compare: ctrl("Digit3", "3"),
},
/** Compare only. The arrows walk changed screens; J and K walk the changed areas of one. */
compare: {
previousScreen: plain("ArrowLeft", "←"),
@@ -92,10 +110,10 @@ export const SHORTCUTS = {
/** The hint, in the idiom of the keyboard reading it: Apple's ⌥⇧⌘ order, or Ctrl+Alt+Shift. */
export function formatShortcut(shortcut: Shortcut, apple = APPLE): string {
if (apple) {
return `${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${shortcut.mod ? "⌘" : ""}${shortcut.key}`;
return `${shortcut.ctrl ? "⌃" : ""}${shortcut.alt ? "⌥" : ""}${shortcut.shift ? "⇧" : ""}${shortcut.mod ? "⌘" : ""}${shortcut.key}`;
}
const parts: string[] = [];
if (shortcut.mod) parts.push("Ctrl");
if (shortcut.mod || shortcut.ctrl) parts.push("Ctrl");
if (shortcut.alt) parts.push("Alt");
if (shortcut.shift) parts.push("Shift");
parts.push(shortcut.key);
@@ -104,7 +122,9 @@ export function formatShortcut(shortcut: Shortcut, apple = APPLE): string {
export function matchesShortcut(event: KeyboardEvent, shortcut: Shortcut): boolean {
if (event.code !== shortcut.code) return false;
if ((event.metaKey || event.ctrlKey) !== Boolean(shortcut.mod)) return false;
if (shortcut.ctrl) {
if (!event.ctrlKey || event.metaKey) return false;
} else if ((event.metaKey || event.ctrlKey) !== Boolean(shortcut.mod)) return false;
if (event.shiftKey !== Boolean(shortcut.shift)) return false;
return event.altKey === Boolean(shortcut.alt);
}
+109 -8
View File
@@ -1,4 +1,4 @@
import type { VisualDiffRegion } from "./review-model";
import type { RegionMove, VisualDiffRegion } from "./review-model";
/** A rectangle in percent of the image width and height (0–100). */
export type PercentRect = { x: number; y: number; width: number; height: number };
@@ -8,18 +8,69 @@ export type VisualChange = PercentRect & {
/** This change's share of all differing pixels, in percent. */
share: number;
regionCount: number;
/** Set when every region in it only moved, by the same amount: their average, which places and labels the outline. */
move?: RegionMove;
/** The least and most its regions moved, in the screenshot's units, which keeps a merged outline to one amount. */
moveRange?: { x: [number, number]; y: [number, number] };
};
/**
* Areas moved by the same amount when their moves are within this of each other, in the screenshot's units. Parts of
* one rigid sheet measure up to a third apart (re-rasterized text), so a third is the same move; rows that drifted by
* half a point or more (1, 1.5, 2pt down a list) keep their own outlines.
*/
const SAME_MOVE = 0.34;
/**
* The most the regions in one outline may differ, together. Measuring a move from re-rasterized text is good to
* about this: a sheet that moved 4.17pt as a whole measures 3.8–4.3pt across its parts (brentvatne/euxy#161).
*/
const MAX_MOVE_SPREAD = 0.5;
function sameMove(a: VisualChange, b: VisualChange): boolean {
if (!a.move || !b.move) return !a.move && !b.move;
const first = rangeOf(a), second = rangeOf(b);
const same = (axis: "x" | "y") => {
const low = Math.min(first[axis][0], second[axis][0]), high = Math.max(first[axis][1], second[axis][1]);
// One direction only: content that moved up and content that moved down did not move together.
return Math.abs(a.move!.amount[axis] - b.move!.amount[axis]) <= SAME_MOVE + 1e-6
&& high - low <= MAX_MOVE_SPREAD + 1e-6 && (low >= -0.25 || high <= 0.25);
};
return same("x") && same("y");
}
function overlaps(a: PercentRect, b: PercentRect): boolean {
return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
}
/** Two moves as one, weighted by each change's share of the difference. */
function mergedMove(a: VisualChange, b: VisualChange): RegionMove | undefined {
if (!a.move || !b.move) return undefined;
const total = a.share + b.share || 1;
const mix = (first: number, second: number) => (first * a.share + second * b.share) / total;
return { x: mix(a.move.x, b.move.x), y: mix(a.move.y, b.move.y), unit: a.move.unit,
amount: { x: mix(a.move.amount.x, b.move.amount.x), y: mix(a.move.amount.y, b.move.amount.y) } };
}
/** Regions closer than this, in percent of the image height, read as one change. */
const VERTICAL_GAP = 1.5;
/** Regions closer than this, in percent of the image width, read as one change. */
const HORIZONTAL_GAP = 3;
function near(a: PercentRect, b: PercentRect): boolean {
return a.x <= b.x + b.width + HORIZONTAL_GAP
&& b.x <= a.x + a.width + HORIZONTAL_GAP
&& a.y <= b.y + b.height + VERTICAL_GAP
&& b.y <= a.y + a.height + VERTICAL_GAP;
/**
* Areas that moved by the same amount moved together (a sheet, a card and the rows under it), so they read as one
* across a wider gap: the content between them moved too, it just has no edges for CI to see.
*/
const MOVED_VERTICAL_GAP = 8;
const MOVED_HORIZONTAL_GAP = 10;
function near(a: VisualChange, b: VisualChange): boolean {
const moved = Boolean(a.move && b.move);
const horizontal = moved ? MOVED_HORIZONTAL_GAP : HORIZONTAL_GAP;
const vertical = moved ? MOVED_VERTICAL_GAP : VERTICAL_GAP;
return a.x <= b.x + b.width + horizontal
&& b.x <= a.x + a.width + horizontal
&& a.y <= b.y + b.height + vertical
&& b.y <= a.y + a.height + vertical;
}
function union(a: VisualChange, b: VisualChange): VisualChange {
@@ -32,9 +83,19 @@ function union(a: VisualChange, b: VisualChange): VisualChange {
height: Math.max(a.y + a.height, b.y + b.height) - y,
share: a.share + b.share,
regionCount: a.regionCount + b.regionCount,
...(mergedMove(a, b) ? { move: mergedMove(a, b)!, moveRange: {
x: [Math.min(rangeOf(a).x[0], rangeOf(b).x[0]), Math.max(rangeOf(a).x[1], rangeOf(b).x[1])],
y: [Math.min(rangeOf(a).y[0], rangeOf(b).y[0]), Math.max(rangeOf(a).y[1], rangeOf(b).y[1])],
} } : {}),
};
}
/** A change's move range: its own, or its single move's amount. */
function rangeOf(change: VisualChange): { x: [number, number]; y: [number, number] } {
const amount = change.move?.amount ?? { x: 0, y: 0 };
return change.moveRange ?? { x: [amount.x, amount.x], y: [amount.y, amount.y] };
}
/**
* CI reports many small regions for one visible change (a card that grew reports its text rows,
* its badge and its border). Merge regions that touch or nearly touch until none do, then order
@@ -50,9 +111,13 @@ export function groupVisualRegions(regions: readonly VisualDiffRegion[]): Visual
merged = false;
outer: for (let i = 0; i < changes.length; i += 1) {
for (let j = i + 1; j < changes.length; j += 1) {
if (!near(changes[i]!, changes[j]!)) continue;
// A moved area and a changed one stay apart, as do areas that moved by different amounts.
if (!near(changes[i]!, changes[j]!) || !sameMove(changes[i]!, changes[j]!)) continue;
const combined = union(changes[i]!, changes[j]!);
// Nor does one moved outline grow around a changed area: that content did not move, it changed.
if (combined.move && changes.some((change, index) => index !== i && index !== j && !change.move && overlaps(combined, change))) continue;
const next = changes.filter((_, index) => index !== i && index !== j);
next.push(union(changes[i]!, changes[j]!));
next.push(combined);
changes = next;
merged = true;
break outer;
@@ -64,6 +129,42 @@ export function groupVisualRegions(regions: readonly VisualDiffRegion[]): Visual
return changes.sort((a, b) => a.y - b.y || a.x - b.x);
}
/** "1.3" for 1.33, "4" for 4.04: a move to a tenth, about as fine as measuring it from pixels gets. */
function amount(value: number): string {
return (Math.round(Math.abs(value) * 10) / 10).toString();
}
/** A change's move as its outline labels it: "↑4.1pt", "↓1.3pt", "→2 ↓1pt". A part under a quarter is left out. */
export function formatMove(change: Pick<VisualChange, "move">): string {
const move = change.move;
if (!move) return "";
const { x, y } = move.amount;
const horizontal = `${x < 0 ? "←" : "→"}${amount(x)}`, vertical = `${y < 0 ? "↑" : "↓"}${amount(y)}`;
const parts = [...(Math.abs(x) >= 0.25 ? [horizontal] : []), ...(Math.abs(y) >= 0.25 ? [vertical] : [])];
// Merged diagonal nudges can average under a quarter on both axes; the larger still says which way.
return `${parts.length ? parts.join(" ") : Math.abs(y) >= Math.abs(x) ? vertical : horizontal}${move.unit}`;
}
/**
* How far the areas of a screen whose every changed area only moved went, a line per direction: "2 areas moved up
* 4pt", "3 areas moved down 1–2pt". Undefined when any area's content changed.
*/
export function layoutShiftSummary(changes: readonly VisualChange[]): string[] | undefined {
if (changes.length === 0 || changes.some((change) => !change.move)) return undefined;
const groups = new Map<string, number[]>();
for (const change of changes) {
const { x, y } = change.move!.amount;
const vertical = Math.abs(y) >= Math.abs(x);
const direction = vertical ? (y < 0 ? "up" : "down") : (x < 0 ? "left" : "right");
groups.set(direction, [...(groups.get(direction) ?? []), Math.abs(vertical ? y : x)]);
}
const unit = changes[0]!.move!.unit;
return [...groups].map(([direction, amounts]) => {
const low = amount(Math.min(...amounts)), high = amount(Math.max(...amounts));
return `${amounts.length === 1 ? "1 area" : `${amounts.length} areas`} moved ${direction} ${low === high ? low : `${low}–${high}`}${unit}.`;
});
}
/** Room around a change's outline, in percent of the image width and height, so it frames text. */
const OUTLINE_PAD_X = 1.5;
const OUTLINE_PAD_Y = 0.7;