From 661711c4a423104afdfecd3b2174090e35ec6356 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 9 Jun 2026 19:37:30 +0200 Subject: [PATCH 1/2] refactor(types): documentary NormalizedRect/NormalizedPoint aliases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add NormalizedRect/NormalizedPoint aliases of Rect/Point (utils/snapshot.ts) to convey coordinate space at the two normalized-percentage sites that were typed as absolute Rect: ScreenshotDiffRegion.normalizedRect and the OCR block normalizedRect (+ the OCR center-distance path). Documentary only — the aliases are structurally Rect/Point, so this is intent-conveying, not enforced. Full nominal branding was scoped out as disproportionate: the normalized surface is 2 fields with no current cross-space mixing, and rectCenter/ squaredDistance are intentionally space-agnostic. --- src/utils/screenshot-diff-ocr.ts | 12 ++++++------ src/utils/screenshot-diff-regions.ts | 4 ++-- src/utils/snapshot.ts | 11 +++++++++++ 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/src/utils/screenshot-diff-ocr.ts b/src/utils/screenshot-diff-ocr.ts index 729f3b557..f538db45a 100644 --- a/src/utils/screenshot-diff-ocr.ts +++ b/src/utils/screenshot-diff-ocr.ts @@ -1,4 +1,4 @@ -import type { Rect } from './snapshot.ts'; +import type { NormalizedPoint, NormalizedRect, Rect } from './snapshot.ts'; import { runCmd, whichCmd } from './exec.ts'; export type MovementRange = { min: number; max: number }; @@ -8,7 +8,7 @@ export type ScreenshotOcrBlock = { text: string; confidence: number; rect: Rect; - normalizedRect: Rect; + normalizedRect: NormalizedRect; }; export type ScreenshotOcrTextMatch = { @@ -240,10 +240,10 @@ function findBestCurrentMatch( if (usedCurrent.has(index)) continue; const currentBlock = currentBlocks[index]!; if (normalizeTextForMatching(currentBlock.text) !== normalizedText) continue; - const distance = squaredDistance( - rectCenter(baselineBlock.normalizedRect), - rectCenter(currentBlock.normalizedRect), - ); + // Centers are in normalized [0..100] space; compare like-for-like. + const baselineCenter: NormalizedPoint = rectCenter(baselineBlock.normalizedRect); + const currentCenter: NormalizedPoint = rectCenter(currentBlock.normalizedRect); + const distance = squaredDistance(baselineCenter, currentCenter); if (distance >= bestDistance) continue; bestIndex = index; bestDistance = distance; diff --git a/src/utils/screenshot-diff-regions.ts b/src/utils/screenshot-diff-regions.ts index 9986dcf6c..4854ca809 100644 --- a/src/utils/screenshot-diff-regions.ts +++ b/src/utils/screenshot-diff-regions.ts @@ -1,5 +1,5 @@ import type { PNG } from './png.ts'; -import type { Rect } from './snapshot.ts'; +import type { NormalizedRect, Rect } from './snapshot.ts'; import { findConnectedMaskComponents } from './screenshot-diff-components.ts'; import { splitLargeDiffRegions } from './screenshot-diff-region-split.ts'; import type { MutableDiffRegion } from './screenshot-diff-region-types.ts'; @@ -15,7 +15,7 @@ type ScreenshotDiffColor = { export type ScreenshotDiffRegion = { index: number; rect: Rect; - normalizedRect: Rect; + normalizedRect: NormalizedRect; differentPixels: number; shareOfDiffPercentage: number; densityPercentage: number; diff --git a/src/utils/snapshot.ts b/src/utils/snapshot.ts index 5155d8938..d7b063978 100644 --- a/src/utils/snapshot.ts +++ b/src/utils/snapshot.ts @@ -10,6 +10,17 @@ export type Point = { y: number; }; +/** + * A rect whose coordinates are normalized percentages [0..100] of the viewport + * (as used by screenshot-diff regions/OCR), NOT absolute pixels. Documentary + * alias of {@link Rect} — it conveys coordinate space to readers but is not + * enforced by the type system (still structurally a Rect). + */ +export type NormalizedRect = Rect; + +/** A point in normalized [0..100] viewport space. Documentary alias of {@link Point}. */ +export type NormalizedPoint = Point; + export type SnapshotOptions = { interactiveOnly?: boolean; compact?: boolean; From be15d55c5753e753ae3f80a8e9aff4ea84a58f70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Wed, 10 Jun 2026 00:31:03 +0200 Subject: [PATCH 2/2] address review: relocate NormalizedRect/Point to screenshot-geometry + fix doc - Move the documentary aliases out of the general snapshot.ts into screenshot-geometry.ts (the screenshot-diff geometry module), where their only consumers live (better collocation). - Correct the doc: coords are normalized to the screenshot IMAGE's dimensions, not 'viewport'. --- src/utils/screenshot-diff-ocr.ts | 10 ++++++++-- src/utils/screenshot-diff-regions.ts | 3 ++- src/utils/screenshot-geometry.ts | 14 +++++++++++++- src/utils/snapshot.ts | 11 ----------- 4 files changed, 23 insertions(+), 15 deletions(-) diff --git a/src/utils/screenshot-diff-ocr.ts b/src/utils/screenshot-diff-ocr.ts index f538db45a..8554eda01 100644 --- a/src/utils/screenshot-diff-ocr.ts +++ b/src/utils/screenshot-diff-ocr.ts @@ -1,8 +1,14 @@ -import type { NormalizedPoint, NormalizedRect, Rect } from './snapshot.ts'; +import type { Rect } from './snapshot.ts'; import { runCmd, whichCmd } from './exec.ts'; export type MovementRange = { min: number; max: number }; -import { rectCenter, squaredDistance, unionRects } from './screenshot-geometry.ts'; +import { + rectCenter, + squaredDistance, + unionRects, + type NormalizedPoint, + type NormalizedRect, +} from './screenshot-geometry.ts'; export type ScreenshotOcrBlock = { text: string; diff --git a/src/utils/screenshot-diff-regions.ts b/src/utils/screenshot-diff-regions.ts index 4854ca809..6c82fb283 100644 --- a/src/utils/screenshot-diff-regions.ts +++ b/src/utils/screenshot-diff-regions.ts @@ -1,5 +1,6 @@ import type { PNG } from './png.ts'; -import type { NormalizedRect, Rect } from './snapshot.ts'; +import type { Rect } from './snapshot.ts'; +import type { NormalizedRect } from './screenshot-geometry.ts'; import { findConnectedMaskComponents } from './screenshot-diff-components.ts'; import { splitLargeDiffRegions } from './screenshot-diff-region-split.ts'; import type { MutableDiffRegion } from './screenshot-diff-region-types.ts'; diff --git a/src/utils/screenshot-geometry.ts b/src/utils/screenshot-geometry.ts index 3baad93d7..e0ec13e96 100644 --- a/src/utils/screenshot-geometry.ts +++ b/src/utils/screenshot-geometry.ts @@ -1,7 +1,19 @@ -import type { Rect } from './snapshot.ts'; +import type { Point, Rect } from './snapshot.ts'; export type ImageDimensions = { width: number; height: number }; +/** + * A rect whose coordinates are normalized percentages [0..100] of the screenshot + * image's dimensions (as produced by the screenshot-diff regions/OCR code), NOT + * absolute pixels. Documentary alias of {@link Rect} — it conveys coordinate + * space to readers but is not enforced by the type system (still structurally a + * Rect). + */ +export type NormalizedRect = Rect; + +/** A point in normalized [0..100] screenshot-image space. Documentary alias of {@link Point}. */ +export type NormalizedPoint = Point; + export function unionRects(rects: Rect[]): Rect { let minX = Number.POSITIVE_INFINITY; let minY = Number.POSITIVE_INFINITY; diff --git a/src/utils/snapshot.ts b/src/utils/snapshot.ts index d7b063978..5155d8938 100644 --- a/src/utils/snapshot.ts +++ b/src/utils/snapshot.ts @@ -10,17 +10,6 @@ export type Point = { y: number; }; -/** - * A rect whose coordinates are normalized percentages [0..100] of the viewport - * (as used by screenshot-diff regions/OCR), NOT absolute pixels. Documentary - * alias of {@link Rect} — it conveys coordinate space to readers but is not - * enforced by the type system (still structurally a Rect). - */ -export type NormalizedRect = Rect; - -/** A point in normalized [0..100] viewport space. Documentary alias of {@link Point}. */ -export type NormalizedPoint = Point; - export type SnapshotOptions = { interactiveOnly?: boolean; compact?: boolean;