π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
fix(guides): stop reporting discarded edits as changes in the summary
Luis Ortizc73f113c8e99
diff --git a/src/core/guides/__tests__/snapshot-diff.test.ts b/src/core/guides/__tests__/snapshot-diff.test.tsindex 847b8ff..110d3dc 100644--- a/src/core/guides/__tests__/snapshot-diff.test.ts+++ b/src/core/guides/__tests__/snapshot-diff.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from 'vitest';import type { Annotation, ScreenshotEdits } from '@/core/screenshot/types';import { diffSnapshots, type SnapshotLike } from '../snapshot-diff';-import type { Snapshot } from '../types';+import type { ScreenshotBounds, Snapshot } from '../types';type StepInput = SnapshotLike['steps'][number];type ShotInput = SnapshotLike['screenshots'][number];@@ -10,8 +10,13 @@ function step(id: string, description = `${id} description`, screenshotId?: strireturn { id, description, ...(screenshotId ? { screenshotId } : {}), ...(url ? { url } : {}) };}-function shot(id: string, stepId: string, edits?: ScreenshotEdits): ShotInput & { stepId: string } {- return edits ? { id, stepId, edits } : { id, stepId };+function shot(+ id: string,+ stepId: string,+ edits?: ScreenshotEdits,+ captured?: { bounds?: ScreenshotBounds; pixelRatio?: number },+): ShotInput & { stepId: string } {+ return { id, stepId, ...(edits ? { edits } : {}), ...captured };}function like(steps: StepInput[], overrides: Partial<SnapshotLike> = {}): SnapshotLike {@@ -370,15 +375,142 @@ describe('diffSnapshots', () => {expect(diffSnapshots(a, b)).toEqual(empty);});- it('reports a replacement that also clears the edits on the new row', () => {+ it('does not report the edits left behind on the row a replacement replaced', () => {const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { alt: 'one' })] });const b = like([step('s1', 'Same', 'sc2')], {screenshots: [shot('sc1', 's1', { alt: 'one' }), shot('sc2', 's1', { alt: 'two' })],});+ expect(diffSnapshots(a, b)).toEqual({ ...empty, replaced: 1 });+ });++ it('reports only the replacement when a pristine screenshot is replaced', () => {+ const a = like([step('s1', 'Same', 'old')], {+ screenshots: [shot('old', 's1', undefined, { bounds: { x: 2, y: 3, width: 4, height: 5 }, pixelRatio: 2 })],+ });+ const b = like([step('s1', 'Same', 'new')], {+ screenshots: [+ shot('old', 's1', undefined, { bounds: { x: 2, y: 3, width: 4, height: 5 }, pixelRatio: 2 }),+ shot('new', 's1', { target: null }),+ ],+ });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, replaced: 1 });+ });++ it('reports only the replacement when a fully edited screenshot is replaced', () => {+ const edited: ScreenshotEdits = {+ viewport: { x: 1, y: 2, width: 30, height: 40 },+ target: { x: 0, y: 0, width: 5, height: 5, border: 'dashed', color: '#4F46E5' },+ annotations: [box, redact],+ alt: 'hello',+ };+ const carried: ScreenshotEdits = { ...edited, target: null };+ delete carried.viewport;+ delete carried.alt;++ const a = like([step('s1', 'Same', 'old')], { screenshots: [shot('old', 's1', edited)] });+ const b = like([step('s1', 'Same', 'new')], {+ screenshots: [shot('old', 's1', edited), shot('new', 's1', carried)],+ });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, replaced: 1 });+ });++ it('suppresses the derived causes per step, not per diff', () => {+ const a = like([step('r1', 'Same', 'old'), step('c1', 'Same', 'kept')], {+ screenshots: [+ shot('old', 'r1', { alt: 'gone' }),+ shot('kept', 'c1', { viewport: { x: 0, y: 0, width: 9, height: 9 } }),+ ],+ });+ const b = like([step('r1', 'Same', 'new'), step('c1', 'Same', 'kept')], {+ screenshots: [+ shot('new', 'r1', { target: null }),+ shot('kept', 'c1', { viewport: { x: 3, y: 0, width: 6, height: 9 } }),+ ],+ });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, replaced: 1, cropped: 1 });+ });++ it('lets a step other than the replaced one set the alt flag', () => {+ const a = like([step('r1', 'Same', 'old'), step('t1', 'Same', 'text')], {+ screenshots: [shot('old', 'r1', { alt: 'gone' }), shot('text', 't1', { alt: 'before' })],+ });+ const b = like([step('r1', 'Same', 'new'), step('t1', 'Same', 'text')], {+ screenshots: [shot('new', 'r1', { target: null }), shot('text', 't1', { alt: 'after' })],+ });+expect(diffSnapshots(a, b)).toEqual({ ...empty, replaced: 1, altEdited: true });});+ it('reports nothing for an annotation editor visit that materialised the derived target', () => {+ const captured = { bounds: { x: 2, y: 3, width: 4, height: 5 }, pixelRatio: 2 };+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', undefined, captured)] });+ const b = like([step('s1', 'Same', 'sc1')], {+ screenshots: [+ shot(+ 'sc1',+ 's1',+ {+ annotations: [],+ target: { x: 4, y: 6, width: 8, height: 10, border: 'dashed', color: '#4F46E5' },+ },+ captured,+ ),+ ],+ });++ expect(diffSnapshots(a, b)).toEqual(empty);+ });++ it('reports nothing when an absent target and an explicit null both resolve to no target', () => {+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1')] });+ const b = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { target: null })] });++ expect(diffSnapshots(a, b)).toEqual(empty);+ });++ it('still reports a target the user actually moved away from the derived box', () => {+ const captured = { bounds: { x: 2, y: 3, width: 4, height: 5 }, pixelRatio: 2 };+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', undefined, captured)] });+ const b = like([step('s1', 'Same', 'sc1')], {+ screenshots: [+ shot(+ 'sc1',+ 's1',+ { target: { x: 40, y: 6, width: 8, height: 10, border: 'dashed', color: '#4F46E5' } },+ captured,+ ),+ ],+ });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, annotated: 1 });+ });++ it('still reports a target the user switched off', () => {+ const captured = { bounds: { x: 2, y: 3, width: 4, height: 5 }, pixelRatio: 2 };+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', undefined, captured)] });+ const b = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { target: null }, captured)] });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, annotated: 1 });+ });++ it('treats an empty alt string as no alt text', () => {+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1')] });+ const b = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { alt: '' })] });++ expect(diffSnapshots(a, b)).toEqual(empty);+ });++ it('reports clearing an alt text that was really there', () => {+ const a = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { alt: 'described' })] });+ const b = like([step('s1', 'Same', 'sc1')], { screenshots: [shot('sc1', 's1', { alt: '' })] });++ expect(diffSnapshots(a, b)).toEqual({ ...empty, altEdited: true });+ });+it('ignores screenshots belonging to steps present on only one side', () => {const a = like([step('s1', 'Same'), step('s2', 'Gone', 'sc1')], { screenshots: [shot('sc1', 's2')] });const b = like([step('s1', 'Same'), step('s3', 'New', 'sc2')], { screenshots: [shot('sc2', 's3')] });diff --git a/src/core/guides/snapshot-diff.ts b/src/core/guides/snapshot-diff.tsindex 3bcf1fe..a25e851 100644--- a/src/core/guides/snapshot-diff.ts+++ b/src/core/guides/snapshot-diff.ts@@ -1,4 +1,6 @@+import { resolveTarget } from '@/core/screenshot/geometry';import type { Annotation, ScreenshotEdits } from '@/core/screenshot/types';+import type { ScreenshotBounds } from './types';interface DiffStep {id: string;@@ -10,6 +12,8 @@ interface DiffStep {interface DiffScreenshot {id: string;edits?: ScreenshotEdits;+ bounds?: ScreenshotBounds;+ pixelRatio?: number;}export interface SnapshotLike {@@ -44,9 +48,13 @@ function stableStringify(value: unknown): string {return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(',')}}`;}-function editsFor(snapshot: SnapshotLike, screenshotId: string | undefined): ScreenshotEdits {- if (!screenshotId) return {};- return snapshot.screenshots.find((row) => row.id === screenshotId)?.edits ?? {};+function rowFor(snapshot: SnapshotLike, screenshotId: string | undefined): DiffScreenshot {+ if (!screenshotId) return { id: '' };+ return snapshot.screenshots.find((row) => row.id === screenshotId) ?? { id: screenshotId };+}++function altOf(edits: ScreenshotEdits): string {+ return edits.alt ?? '';}function redactions(edits: ScreenshotEdits): Annotation[] {@@ -87,16 +95,24 @@ export function diffSnapshots(from: SnapshotLike, to: SnapshotLike): SnapshotDifif (before.description !== step.description) edited++;if (before.url !== step.url) urls++;- if (before.screenshotId !== step.screenshotId) replaced++;+ if (before.screenshotId !== step.screenshotId) {+ replaced++;+ continue;+ }- const beforeEdits = editsFor(from, before.screenshotId);- const afterEdits = editsFor(to, step.screenshotId);+ const beforeRow = rowFor(from, before.screenshotId);+ const afterRow = rowFor(to, step.screenshotId);+ const beforeEdits = beforeRow.edits ?? {};+ const afterEdits = afterRow.edits ?? {};if (differs(beforeEdits.viewport, afterEdits.viewport)) cropped++;- if (differs(drawings(beforeEdits), drawings(afterEdits)) || differs(beforeEdits.target, afterEdits.target))+ if (+ differs(drawings(beforeEdits), drawings(afterEdits)) ||+ differs(resolveTarget(beforeRow), resolveTarget(afterRow))+ )annotated++;if (differs(redactions(beforeEdits), redactions(afterEdits))) blurred++;- if (differs(beforeEdits.alt, afterEdits.alt)) altEdited = true;+ if (altOf(beforeEdits) !== altOf(afterEdits)) altEdited = true;}return {diff --git a/src/core/screenshot/geometry.ts b/src/core/screenshot/geometry.tsindex ad81caf..ee2b517 100644--- a/src/core/screenshot/geometry.ts+++ b/src/core/screenshot/geometry.ts@@ -194,7 +194,9 @@ export function resizeAnnotation(a: Annotation, handle: Handle, dx: number, dy:};}-export function resolveTarget(screenshot: Screenshot): ClickTarget | null {+export type TargetSource = Pick<Screenshot, 'edits' | 'bounds' | 'pixelRatio'>;++export function resolveTarget(screenshot: TargetSource): ClickTarget | null {const explicit = screenshot.edits?.target;if (explicit !== undefined) return explicit;diff --git a/src/ui/fullview/components/__tests__/version-history-panel.test.tsx b/src/ui/fullview/components/__tests__/version-history-panel.test.tsxindex ecec1bf..3a0e369 100644--- a/src/ui/fullview/components/__tests__/version-history-panel.test.tsx+++ b/src/ui/fullview/components/__tests__/version-history-panel.test.tsx@@ -139,9 +139,10 @@ describe('VersionHistoryPanel change summary', () => {});it('uses the plural key for every counted cause above one', async () => {+ const ids = ['e1', 'e2', 'u1', 'u2', 'rp1', 'rp2', 'cr1', 'cr2', 'an1', 'an2', 'bl1', 'bl2'];const snapshot = older({title: 'Before',- stepIds: ['x1', 'x2', 'e1', 'e2', 'u1', 'u2', 'p1', 'p2'],+ stepIds: ['x1', 'x2', ...ids],steps: [step('x1', 'Gone one'),step('x2', 'Gone two'),@@ -149,17 +150,29 @@ describe('VersionHistoryPanel change summary', () => {step('e2', 'Old e2'),step('u1', 'Same', undefined, 'https://a.test/one'),step('u2', 'Same', undefined, 'https://a.test/two'),- step('p1', 'Same', 'p1a'),- step('p2', 'Same', 'p2a'),+ step('rp1', 'Same', 'rp1a'),+ step('rp2', 'Same', 'rp2a'),+ step('cr1', 'Same', 'cr1s'),+ step('cr2', 'Same', 'cr2s'),+ step('an1', 'Same', 'an1s'),+ step('an2', 'Same', 'an2s'),+ step('bl1', 'Same', 'bl1s'),+ step('bl2', 'Same', 'bl2s'),],screenshots: [- shot('p1a', 'p1', { viewport: viewportA, annotations: [box, redact], alt: 'before' }),- shot('p2a', 'p2', { viewport: viewportA, annotations: [box, redact], alt: 'before' }),+ shot('rp1a', 'rp1'),+ shot('rp2a', 'rp2'),+ shot('cr1s', 'cr1', { viewport: viewportA, alt: 'before' }),+ shot('cr2s', 'cr2', { viewport: viewportA }),+ shot('an1s', 'an1', { annotations: [box] }),+ shot('an2s', 'an2', { annotations: [box] }),+ shot('bl1s', 'bl1', { annotations: [redact] }),+ shot('bl2s', 'bl2', { annotations: [redact] }),],});const live: SnapshotLike = {title: 'After',- stepIds: ['y1', 'y2', 'e2', 'e1', 'u1', 'u2', 'p1', 'p2'],+ stepIds: ['y1', 'y2', 'e2', 'e1', ...ids.slice(2)],steps: [step('y1', 'New one'),step('y2', 'New two'),@@ -167,12 +180,24 @@ describe('VersionHistoryPanel change summary', () => {step('e1', 'New e1'),step('u1', 'Same', undefined, 'https://b.test/one'),step('u2', 'Same', undefined, 'https://b.test/two'),- step('p1', 'Same', 'p1b'),- step('p2', 'Same', 'p2b'),+ step('rp1', 'Same', 'rp1b'),+ step('rp2', 'Same', 'rp2b'),+ step('cr1', 'Same', 'cr1s'),+ step('cr2', 'Same', 'cr2s'),+ step('an1', 'Same', 'an1s'),+ step('an2', 'Same', 'an2s'),+ step('bl1', 'Same', 'bl1s'),+ step('bl2', 'Same', 'bl2s'),],screenshots: [- shot('p1b', 'p1', { viewport: viewportB, annotations: [otherBox, otherRedact], alt: 'after' }),- shot('p2b', 'p2', { viewport: viewportB, annotations: [otherBox, otherRedact], alt: 'after' }),+ shot('rp1b', 'rp1'),+ shot('rp2b', 'rp2'),+ shot('cr1s', 'cr1', { viewport: viewportB, alt: 'after' }),+ shot('cr2s', 'cr2', { viewport: viewportB }),+ shot('an1s', 'an1', { annotations: [otherBox] }),+ shot('an2s', 'an2', { annotations: [otherBox] }),+ shot('bl1s', 'bl1', { annotations: [otherRedact] }),+ shot('bl2s', 'bl2', { annotations: [otherRedact] }),],};