hauntview 0.0.0-stage → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +358 -2
  3. package/VERSION +1 -0
  4. package/dist/cli.js +8184 -0
  5. package/package.json +120 -4
  6. package/scripts/postinstall.mjs +47 -0
  7. package/src/core/browser-launch.ts +60 -0
  8. package/src/core/browser-pool.ts +267 -0
  9. package/src/core/concurrency-resolver.ts +154 -0
  10. package/src/core/finding-classifier.ts +346 -0
  11. package/src/core/index.ts +8 -0
  12. package/src/core/profile-manager.ts +499 -0
  13. package/src/core/report-store.ts +117 -0
  14. package/src/core/screenshot-manager.ts +312 -0
  15. package/src/core/system-capability.ts +161 -0
  16. package/src/core/visual-diff.ts +230 -0
  17. package/src/engine.ts +473 -0
  18. package/src/profiles/accessibility-cognitive.ts +261 -0
  19. package/src/profiles/accessibility-keyboard.ts +225 -0
  20. package/src/profiles/accessibility-screenreader.ts +243 -0
  21. package/src/profiles/accessibility-visual.ts +257 -0
  22. package/src/profiles/broken-links.ts +261 -0
  23. package/src/profiles/browser-edge.ts +192 -0
  24. package/src/profiles/browser-firefox.ts +254 -0
  25. package/src/profiles/browser-legacy.ts +213 -0
  26. package/src/profiles/console-errors.ts +192 -0
  27. package/src/profiles/desktop-4k.ts +273 -0
  28. package/src/profiles/desktop.ts +192 -0
  29. package/src/profiles/font-failure.ts +148 -0
  30. package/src/profiles/form-resilience.ts +285 -0
  31. package/src/profiles/i18n-cjk.ts +218 -0
  32. package/src/profiles/i18n-mixed.ts +255 -0
  33. package/src/profiles/i18n-rtl.ts +236 -0
  34. package/src/profiles/image-failure.ts +178 -0
  35. package/src/profiles/index.ts +42 -0
  36. package/src/profiles/js-disabled.ts +179 -0
  37. package/src/profiles/mobile.ts +175 -0
  38. package/src/profiles/network-resilience.ts +208 -0
  39. package/src/profiles/offline.ts +165 -0
  40. package/src/profiles/performance.ts +244 -0
  41. package/src/profiles/reduced-motion.ts +144 -0
  42. package/src/profiles/security-hygiene.ts +206 -0
  43. package/src/profiles/tablet.ts +176 -0
  44. package/src/reports/factory.ts +56 -0
  45. package/src/reports/html-generator.ts +1105 -0
  46. package/src/reports/index.ts +9 -0
  47. package/src/reports/markdown-generator.ts +349 -0
  48. package/src/reports/types.ts +34 -0
  49. package/src/reports/zip-generator.ts +85 -0
  50. package/src/types/contracts.ts +238 -0
  51. package/src/types/finding-utils.ts +121 -0
  52. package/src/types/index.ts +8 -0
  53. package/src/types/profiles.ts +175 -0
  54. package/src/types/results.ts +135 -0
  55. package/src/version.ts +5 -0
@@ -0,0 +1,312 @@
1
+ /**
2
+ * ScreenshotManager - Handles screenshot capture, storage, and comparison
3
+ * Manages screenshot metadata, hashing, and deduplication
4
+ */
5
+
6
+ import * as fs from 'fs/promises';
7
+ import * as path from 'path';
8
+ import * as crypto from 'crypto';
9
+ import { Page } from 'playwright';
10
+ import { PNG } from 'pngjs';
11
+ import { ScreenshotMetadata, Viewport } from '../types';
12
+
13
+ interface StoredScreenshot {
14
+ metadata: ScreenshotMetadata;
15
+ buffer: Buffer;
16
+ hash: string;
17
+ }
18
+
19
+ export class ScreenshotManager {
20
+ private screenshotDir: string;
21
+ private screenshots: Map<string, StoredScreenshot> = new Map();
22
+ private hashIndex: Map<string, string[]> = new Map(); // hash -> filenames
23
+
24
+ constructor(screenshotDir: string = '.hauntview/screenshots') {
25
+ this.screenshotDir = screenshotDir;
26
+ }
27
+
28
+ /**
29
+ * Initialize screenshot directory
30
+ */
31
+ async initialize(): Promise<void> {
32
+ try {
33
+ await fs.mkdir(this.screenshotDir, { recursive: true });
34
+ } catch (error) {
35
+ throw new Error(`Failed to initialize screenshot directory: ${error}`);
36
+ }
37
+ }
38
+
39
+ /**
40
+ * Capture screenshot from page
41
+ */
42
+ async captureScreenshot(
43
+ page: Page,
44
+ profileId: string,
45
+ url: string,
46
+ viewport: Viewport,
47
+ options?: { fullPage?: boolean }
48
+ ): Promise<ScreenshotMetadata> {
49
+ try {
50
+ const buffer = await page.screenshot({
51
+ fullPage: options?.fullPage ?? true,
52
+ });
53
+
54
+ const metadata = this.generateMetadata(profileId, url, viewport, buffer);
55
+ await this.storeScreenshot(metadata, buffer);
56
+
57
+ return metadata;
58
+ } catch (error) {
59
+ throw new Error(`Failed to capture screenshot: ${error}`);
60
+ }
61
+ }
62
+
63
+ /**
64
+ * Store screenshot on disk
65
+ */
66
+ async storeScreenshot(metadata: ScreenshotMetadata, buffer: Buffer): Promise<void> {
67
+ const filePath = path.join(this.screenshotDir, metadata.fileName);
68
+
69
+ try {
70
+ // Ensure subdirectory exists
71
+ await fs.mkdir(path.dirname(filePath), { recursive: true });
72
+
73
+ // Write screenshot
74
+ await fs.writeFile(filePath, buffer);
75
+
76
+ // Store in memory index
77
+ this.screenshots.set(metadata.fileName, {
78
+ metadata,
79
+ buffer,
80
+ hash: metadata.hash,
81
+ });
82
+
83
+ // Update hash index for deduplication
84
+ if (!this.hashIndex.has(metadata.hash)) {
85
+ this.hashIndex.set(metadata.hash, []);
86
+ }
87
+ this.hashIndex.get(metadata.hash)!.push(metadata.fileName);
88
+ } catch (error) {
89
+ throw new Error(`Failed to store screenshot: ${error}`);
90
+ }
91
+ }
92
+
93
+ /**
94
+ * Retrieve screenshot by filename
95
+ */
96
+ async getScreenshot(fileName: string): Promise<ScreenshotMetadata | null> {
97
+ const stored = this.screenshots.get(fileName);
98
+ if (stored) {
99
+ return stored.metadata;
100
+ }
101
+
102
+ // Try to load from disk
103
+ const filePath = path.join(this.screenshotDir, fileName);
104
+ try {
105
+ const buffer = await fs.readFile(filePath);
106
+ const hash = this.hashBuffer(buffer);
107
+
108
+ const metadata: ScreenshotMetadata = {
109
+ profileId: fileName.split('/')[0],
110
+ timestamp: parseInt(fileName.match(/\d+/)?.[0] || String(Date.now())),
111
+ url: '',
112
+ viewport: { width: 1280, height: 720, isMobile: false, hasTouch: false },
113
+ fileName,
114
+ hash,
115
+ };
116
+
117
+ this.screenshots.set(fileName, {
118
+ metadata,
119
+ buffer,
120
+ hash,
121
+ });
122
+
123
+ return metadata;
124
+ } catch {
125
+ return null;
126
+ }
127
+ }
128
+
129
+ /**
130
+ * Find duplicate screenshots by hash
131
+ */
132
+ async findDuplicates(fileName: string): Promise<string[]> {
133
+ const screenshot = this.screenshots.get(fileName);
134
+ if (!screenshot) {
135
+ return [];
136
+ }
137
+
138
+ const duplicates = this.hashIndex.get(screenshot.hash) || [];
139
+ return duplicates.filter((f) => f !== fileName);
140
+ }
141
+
142
+ /**
143
+ * Compare two screenshots using pixelmatch and pngjs
144
+ */
145
+ async compareScreenshots(
146
+ fileName1: string,
147
+ fileName2: string
148
+ ): Promise<{ pixelDifference: number; percentageDifference: number; diffBuffer?: Buffer }> {
149
+ const screenshot1 =
150
+ this.screenshots.get(fileName1) || (await this.loadStoredScreenshot(fileName1));
151
+ const screenshot2 =
152
+ this.screenshots.get(fileName2) || (await this.loadStoredScreenshot(fileName2));
153
+
154
+ if (!screenshot1 || !screenshot2) {
155
+ throw new Error('One or both screenshots not found');
156
+ }
157
+
158
+ // Simple comparison: if hashes match, identical
159
+ if (screenshot1.hash === screenshot2.hash) {
160
+ return { pixelDifference: 0, percentageDifference: 0 };
161
+ }
162
+
163
+ try {
164
+ const img1 = PNG.sync.read(screenshot1.buffer);
165
+ const img2 = PNG.sync.read(screenshot2.buffer);
166
+
167
+ const width = Math.max(img1.width, img2.width);
168
+ const height = Math.max(img1.height, img2.height);
169
+
170
+ // Normalize dimensions if they differ
171
+ const canvas1 = new PNG({ width, height });
172
+ const canvas2 = new PNG({ width, height });
173
+ PNG.bitblt(img1, canvas1, 0, 0, img1.width, img1.height, 0, 0);
174
+ PNG.bitblt(img2, canvas2, 0, 0, img2.width, img2.height, 0, 0);
175
+
176
+ const pixelmatchModule = await import('pixelmatch');
177
+ const pixelmatch = pixelmatchModule.default || pixelmatchModule;
178
+
179
+ const diff = new PNG({ width, height });
180
+ const pixelDifference = pixelmatch(canvas1.data, canvas2.data, diff.data, width, height, {
181
+ threshold: 0.1,
182
+ });
183
+
184
+ const totalPixels = width * height;
185
+ const percentageDifference = totalPixels > 0 ? pixelDifference / totalPixels : 0;
186
+ const diffBuffer = PNG.sync.write(diff);
187
+
188
+ return {
189
+ pixelDifference,
190
+ percentageDifference,
191
+ diffBuffer,
192
+ };
193
+ } catch {
194
+ // Fallback for non-PNG or decoding issue
195
+ return { pixelDifference: -1, percentageDifference: 1 };
196
+ }
197
+ }
198
+
199
+ private async loadStoredScreenshot(fileName: string): Promise<StoredScreenshot | null> {
200
+ const filePath = path.join(this.screenshotDir, fileName);
201
+ try {
202
+ const buffer = await fs.readFile(filePath);
203
+ const hash = this.hashBuffer(buffer);
204
+ const metadata: ScreenshotMetadata = {
205
+ profileId: fileName.split('/')[0] || 'default',
206
+ timestamp: Date.now(),
207
+ url: '',
208
+ viewport: { width: 1280, height: 720, isMobile: false, hasTouch: false },
209
+ fileName,
210
+ hash,
211
+ };
212
+ const stored = { metadata, buffer, hash };
213
+ this.screenshots.set(fileName, stored);
214
+ return stored;
215
+ } catch {
216
+ return null;
217
+ }
218
+ }
219
+
220
+ /**
221
+ * Clean up screenshots older than specified time
222
+ */
223
+ async cleanup(maxAgeMs: number = 7 * 24 * 60 * 60 * 1000): Promise<number> {
224
+ let removedCount = 0;
225
+ const now = Date.now();
226
+
227
+ try {
228
+ const files = await fs.readdir(this.screenshotDir, { recursive: true });
229
+
230
+ for (const file of files) {
231
+ const filePath = path.join(this.screenshotDir, String(file));
232
+ const stat = await fs.stat(filePath);
233
+
234
+ if (now - stat.mtimeMs > maxAgeMs) {
235
+ await fs.unlink(filePath);
236
+ this.screenshots.delete(String(file));
237
+ removedCount++;
238
+ }
239
+ }
240
+ } catch (error) {
241
+ throw new Error(`Failed to cleanup screenshots: ${error}`);
242
+ }
243
+
244
+ return removedCount;
245
+ }
246
+
247
+ /**
248
+ * Get all screenshots for a profile
249
+ */
250
+ async getProfileScreenshots(profileId: string): Promise<ScreenshotMetadata[]> {
251
+ const screenshots: ScreenshotMetadata[] = [];
252
+
253
+ for (const stored of this.screenshots.values()) {
254
+ if (stored.metadata.profileId === profileId) {
255
+ screenshots.push(stored.metadata);
256
+ }
257
+ }
258
+
259
+ return screenshots.sort((a, b) => a.timestamp - b.timestamp);
260
+ }
261
+
262
+ /**
263
+ * Generate metadata for screenshot
264
+ */
265
+ private generateMetadata(
266
+ profileId: string,
267
+ url: string,
268
+ viewport: Viewport,
269
+ buffer: Buffer
270
+ ): ScreenshotMetadata {
271
+ const timestamp = Date.now();
272
+ const hash = this.hashBuffer(buffer);
273
+ const fileName = `${profileId}/${timestamp}-${hash.substring(0, 8)}.png`;
274
+
275
+ return {
276
+ profileId,
277
+ timestamp,
278
+ url,
279
+ viewport,
280
+ fileName,
281
+ hash,
282
+ };
283
+ }
284
+
285
+ /**
286
+ * Calculate hash of buffer
287
+ */
288
+ private hashBuffer(buffer: Buffer): string {
289
+ return crypto.createHash('sha256').update(buffer).digest('hex');
290
+ }
291
+
292
+ /**
293
+ * Get screenshot statistics
294
+ */
295
+ getStats(): {
296
+ totalScreenshots: number;
297
+ uniqueScreenshots: number;
298
+ totalSize: number;
299
+ } {
300
+ let totalSize = 0;
301
+
302
+ for (const stored of this.screenshots.values()) {
303
+ totalSize += stored.buffer.length;
304
+ }
305
+
306
+ return {
307
+ totalScreenshots: this.screenshots.size,
308
+ uniqueScreenshots: this.hashIndex.size,
309
+ totalSize,
310
+ };
311
+ }
312
+ }
@@ -0,0 +1,161 @@
1
+ /**
2
+ * src/core/system-capability.ts
3
+ *
4
+ * System hardware capability detection, heuristic concurrency recommendations,
5
+ * validation, and runtime clamping.
6
+ */
7
+
8
+ import * as os from 'os';
9
+
10
+ export interface SystemSpecs {
11
+ logicalCores: number;
12
+ cpuModel: string;
13
+ totalMemoryBytes: number;
14
+ freeMemoryBytes: number;
15
+ }
16
+
17
+ export interface ConcurrencyRecommendation {
18
+ cpuBound: number;
19
+ ramBound: number;
20
+ recommendedMax: number;
21
+ defaultSuggested: number;
22
+ isConstrained: boolean;
23
+ constraintReason?: string;
24
+ specs: SystemSpecs;
25
+ }
26
+
27
+ export interface ConcurrencyValidationResult {
28
+ valid: boolean;
29
+ clampedValue: number;
30
+ warning?: string;
31
+ errorMessage?: string;
32
+ }
33
+
34
+ /**
35
+ * Reads live machine specs using Node's os module
36
+ */
37
+ export function getLiveSystemSpecs(): SystemSpecs {
38
+ let logicalCores = 1;
39
+ try {
40
+ if (typeof os.availableParallelism === 'function') {
41
+ logicalCores = os.availableParallelism();
42
+ } else {
43
+ logicalCores = os.cpus().length || 1;
44
+ }
45
+ } catch {
46
+ logicalCores = 1;
47
+ }
48
+
49
+ let cpuModel = 'Generic CPU';
50
+ try {
51
+ const cpus = os.cpus();
52
+ if (cpus && cpus.length > 0 && cpus[0].model) {
53
+ cpuModel = cpus[0].model.trim();
54
+ }
55
+ } catch {
56
+ // Fallback to generic CPU
57
+ }
58
+
59
+ return {
60
+ logicalCores,
61
+ cpuModel,
62
+ totalMemoryBytes: os.totalmem(),
63
+ freeMemoryBytes: os.freemem(),
64
+ };
65
+ }
66
+
67
+ /**
68
+ * Computes hardware-aware concurrency limits using conservative heuristics:
69
+ * - CPU bound: roughly half logical cores (min 1) to account for hyperthreading and browser overhead
70
+ * - RAM bound: ~2 GB per concurrent browser execution
71
+ * - Constrained: < 4 GB RAM or < 2 cores caps concurrency at 1
72
+ */
73
+ export function evaluateSystemCapability(customSpecs?: SystemSpecs): ConcurrencyRecommendation {
74
+ const specs = customSpecs ?? getLiveSystemSpecs();
75
+ const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
76
+
77
+ const cpuBound = Math.max(1, Math.floor(specs.logicalCores / 2));
78
+ const ramBound = Math.max(1, Math.floor(totalMemoryGb / 2));
79
+
80
+ const isConstrained = specs.logicalCores < 2 || totalMemoryGb < 3.5;
81
+
82
+ let recommendedMax: number;
83
+ let constraintReason: string | undefined;
84
+
85
+ if (isConstrained) {
86
+ recommendedMax = 1;
87
+ constraintReason = `Your system has limited hardware resources (${specs.logicalCores} cores, ${totalMemoryGb.toFixed(1)} GB RAM). Concurrency is not recommended and is capped at 1.`;
88
+ } else {
89
+ recommendedMax = Math.max(1, Math.min(cpuBound, ramBound));
90
+ }
91
+
92
+ const defaultSuggested = Math.min(2, recommendedMax);
93
+
94
+ return {
95
+ cpuBound,
96
+ ramBound,
97
+ recommendedMax,
98
+ defaultSuggested,
99
+ isConstrained,
100
+ constraintReason,
101
+ specs,
102
+ };
103
+ }
104
+
105
+ /**
106
+ * Validates a user-requested concurrency amount against machine recommendations.
107
+ * Rejects values that exceed recommendedMax with an informative explanation.
108
+ */
109
+ export function validateConcurrencyAmount(
110
+ requested: number,
111
+ recommendation: ConcurrencyRecommendation
112
+ ): ConcurrencyValidationResult {
113
+ const { recommendedMax, specs } = recommendation;
114
+ const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
115
+
116
+ if (requested < 1) {
117
+ return {
118
+ valid: false,
119
+ clampedValue: 1,
120
+ errorMessage: 'Concurrency amount must be at least 1.',
121
+ };
122
+ }
123
+
124
+ if (requested > recommendedMax) {
125
+ const errorMessage = `Your ${specs.cpuModel} (${specs.logicalCores} cores/threads, ${totalMemoryGb.toFixed(1)} GB RAM) supports at most ${recommendedMax} concurrent rites; ${requested} would likely freeze the machine.`;
126
+ return {
127
+ valid: false,
128
+ clampedValue: recommendedMax,
129
+ errorMessage,
130
+ };
131
+ }
132
+
133
+ return {
134
+ valid: true,
135
+ clampedValue: requested,
136
+ };
137
+ }
138
+
139
+ /**
140
+ * Runtime clamping for config values loaded from disk or env vars
141
+ */
142
+ export function clampConcurrencyAmount(
143
+ requested: number,
144
+ recommendation: ConcurrencyRecommendation
145
+ ): { effectiveAmount: number; wasClamped: boolean; warning?: string } {
146
+ const { recommendedMax, specs } = recommendation;
147
+ if (requested > recommendedMax) {
148
+ const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
149
+ const warning = `[haunt] Configured concurrency amount (${requested}) exceeds machine recommended limit (${recommendedMax}) for ${specs.cpuModel} (${totalMemoryGb.toFixed(1)} GB RAM). Clamping to ${recommendedMax}.`;
150
+ return {
151
+ effectiveAmount: recommendedMax,
152
+ wasClamped: true,
153
+ warning,
154
+ };
155
+ }
156
+
157
+ return {
158
+ effectiveAmount: Math.max(1, requested),
159
+ wasClamped: false,
160
+ };
161
+ }
@@ -0,0 +1,230 @@
1
+ /**
2
+ * visual-diff.ts — Ectoplasm diff engine
3
+ *
4
+ * Compares two PNG screenshots using pixelmatch and clusters changed pixels
5
+ * into bounding-box regions (the "ectoplasm overlay").
6
+ *
7
+ * changedRatio is a pure fact about pixels — it is NOT a finding by itself.
8
+ * Callers must attach a mechanism (overflow, failed request, etc.) before
9
+ * raising a Finding.
10
+ */
11
+
12
+ import fs from 'fs';
13
+ import path from 'path';
14
+ import { PNG } from 'pngjs';
15
+ import pixelmatch from 'pixelmatch';
16
+
17
+ export interface Rect {
18
+ x: number;
19
+ y: number;
20
+ width: number;
21
+ height: number;
22
+ }
23
+
24
+ export interface DiffResult {
25
+ /** Fraction of pixels that changed, 0..1 */
26
+ changedRatio: number;
27
+ /** Absolute path where the ectoplasm PNG was written */
28
+ ectoplasmPath: string;
29
+ /** Up to 20 change regions, sorted by area descending */
30
+ changeRegions: Rect[];
31
+ /** Masked regions that were blanked before diffing */
32
+ maskedRegions: Rect[];
33
+ }
34
+
35
+ /** Maximum PNG height (px) before cropping */
36
+ const MAX_HEIGHT = 12_000;
37
+
38
+ /**
39
+ * Compute a pixel diff between two PNGs and write an ectoplasm overlay.
40
+ *
41
+ * @param baselinePath - Path to the baseline (living page) PNG
42
+ * @param apparitionPath - Path to the apparition (condition run) PNG
43
+ * @param outputPath - Path where the ectoplasm diff PNG will be written
44
+ * @param maskedRegions - Optional areas to blank in both images before diffing
45
+ */
46
+ export async function computeDiff(
47
+ baselinePath: string,
48
+ apparitionPath: string,
49
+ outputPath: string,
50
+ maskedRegions: Rect[] = []
51
+ ): Promise<DiffResult> {
52
+ // Read both PNGs synchronously
53
+ const baselineBuffer = fs.readFileSync(baselinePath);
54
+ const apparitionBuffer = fs.readFileSync(apparitionPath);
55
+
56
+ const baselinePng = PNG.sync.read(baselineBuffer);
57
+ const apparitionPng = PNG.sync.read(apparitionBuffer);
58
+
59
+ // Normalise to the same canvas size (union of both dims), then cap height
60
+ const rawWidth = Math.max(baselinePng.width, apparitionPng.width);
61
+ const rawHeight = Math.min(Math.max(baselinePng.height, apparitionPng.height), MAX_HEIGHT);
62
+
63
+ // Create canvases of the normalised size (zero-initialised = transparent/black)
64
+ const canvasA = new PNG({ width: rawWidth, height: rawHeight });
65
+ const canvasB = new PNG({ width: rawWidth, height: rawHeight });
66
+
67
+ // Blit source images into canvases (cropping to MAX_HEIGHT implicitly)
68
+ const blitHeight = (src: PNG) => Math.min(src.height, rawHeight);
69
+ PNG.bitblt(baselinePng, canvasA, 0, 0, baselinePng.width, blitHeight(baselinePng), 0, 0);
70
+ PNG.bitblt(apparitionPng, canvasB, 0, 0, apparitionPng.width, blitHeight(apparitionPng), 0, 0);
71
+
72
+ // Apply masked regions: set identical pixels in both canvases so they never diff
73
+ for (const region of maskedRegions) {
74
+ applyMask(canvasA, region);
75
+ applyMask(canvasB, region);
76
+ }
77
+
78
+ const diffPng = new PNG({ width: rawWidth, height: rawHeight });
79
+
80
+ const changedPixels = pixelmatch(canvasA.data, canvasB.data, diffPng.data, rawWidth, rawHeight, {
81
+ threshold: 0.1,
82
+ includeAA: false,
83
+ });
84
+
85
+ const totalPixels = rawWidth * rawHeight;
86
+ const changedRatio = totalPixels > 0 ? changedPixels / totalPixels : 0;
87
+
88
+ // Write ectoplasm PNG, creating parent directory as needed
89
+ const outputDir = path.dirname(outputPath);
90
+ fs.mkdirSync(outputDir, { recursive: true });
91
+ const diffBuffer = PNG.sync.write(diffPng);
92
+ fs.writeFileSync(outputPath, diffBuffer);
93
+
94
+ // Build a boolean mask of which pixels actually changed.
95
+ // We compare the two source canvases directly rather than interpreting
96
+ // pixelmatch's coloured output (which tints even unchanged pixels gray).
97
+ const changedMask = buildChangedMask(canvasA, canvasB, rawWidth, rawHeight, 0.1);
98
+
99
+ // Cluster changed pixels into bounding-box regions via BFS flood fill
100
+ const changeRegions = clusterChangedRegions(changedMask, rawWidth, rawHeight);
101
+
102
+ return {
103
+ changedRatio,
104
+ ectoplasmPath: outputPath,
105
+ changeRegions,
106
+ maskedRegions,
107
+ };
108
+ }
109
+
110
+ // ---------------------------------------------------------------------------
111
+ // Helpers
112
+ // ---------------------------------------------------------------------------
113
+
114
+ /**
115
+ * Zero out a rectangular region in a PNG (RGBA → 0,0,0,0) so it produces
116
+ * no diff signal against the other canvas which receives the same treatment.
117
+ */
118
+ function applyMask(png: PNG, region: Rect): void {
119
+ const x2 = Math.min(region.x + region.width, png.width);
120
+ const y2 = Math.min(region.y + region.height, png.height);
121
+
122
+ for (let y = Math.max(0, region.y); y < y2; y++) {
123
+ for (let x = Math.max(0, region.x); x < x2; x++) {
124
+ const idx = (y * png.width + x) * 4;
125
+ png.data[idx] = 0;
126
+ png.data[idx + 1] = 0;
127
+ png.data[idx + 2] = 0;
128
+ png.data[idx + 3] = 0;
129
+ }
130
+ }
131
+ }
132
+
133
+ /**
134
+ * Build a boolean mask (Uint8Array, 1 = changed) by directly comparing the
135
+ * two source canvases. This avoids interpreting pixelmatch's coloured diff
136
+ * output, which tints even unchanged pixels with a faint gray so they are
137
+ * visible against a white background — those tinted pixels are NOT real diffs.
138
+ *
139
+ * A pixel is considered changed when the per-channel delta for any channel
140
+ * exceeds the pixelmatch threshold (0..255 scale) or alpha differs.
141
+ */
142
+ function buildChangedMask(
143
+ canvasA: PNG,
144
+ canvasB: PNG,
145
+ width: number,
146
+ height: number,
147
+ threshold: number // 0..1 as used by pixelmatch
148
+ ): Uint8Array {
149
+ const mask = new Uint8Array(width * height);
150
+ const thresholdByte = threshold * 255;
151
+
152
+ for (let i = 0; i < width * height; i++) {
153
+ const p = i * 4;
154
+ const dr = Math.abs(canvasA.data[p] - canvasB.data[p]);
155
+ const dg = Math.abs(canvasA.data[p + 1] - canvasB.data[p + 1]);
156
+ const db = Math.abs(canvasA.data[p + 2] - canvasB.data[p + 2]);
157
+ const da = Math.abs(canvasA.data[p + 3] - canvasB.data[p + 3]);
158
+ if (dr > thresholdByte || dg > thresholdByte || db > thresholdByte || da > thresholdByte) {
159
+ mask[i] = 1;
160
+ }
161
+ }
162
+ return mask;
163
+ }
164
+
165
+ /**
166
+ * Cluster changed pixels (mask[i] === 1) into bounding-box regions via BFS
167
+ * flood fill. Returns up to 20 regions, sorted by area descending.
168
+ */
169
+ function clusterChangedRegions(changedMask: Uint8Array, width: number, height: number): Rect[] {
170
+ const visited = new Uint8Array(width * height);
171
+ const regions: Rect[] = [];
172
+
173
+ for (let startY = 0; startY < height; startY++) {
174
+ for (let startX = 0; startX < width; startX++) {
175
+ const idx = startY * width + startX;
176
+ if (visited[idx] || !changedMask[idx]) {
177
+ visited[idx] = 1;
178
+ continue;
179
+ }
180
+
181
+ // BFS over the connected component
182
+ const queue: number[] = [idx];
183
+ visited[idx] = 1;
184
+
185
+ let minX = startX;
186
+ let maxX = startX;
187
+ let minY = startY;
188
+ let maxY = startY;
189
+
190
+ let head = 0;
191
+ while (head < queue.length) {
192
+ const cur = queue[head++];
193
+ const cy = Math.floor(cur / width);
194
+ const cx = cur % width;
195
+
196
+ if (cx < minX) minX = cx;
197
+ if (cx > maxX) maxX = cx;
198
+ if (cy < minY) minY = cy;
199
+ if (cy > maxY) maxY = cy;
200
+
201
+ // 4-connected neighbours
202
+ const neighbours = [
203
+ cy > 0 ? cur - width : -1,
204
+ cy < height - 1 ? cur + width : -1,
205
+ cx > 0 ? cur - 1 : -1,
206
+ cx < width - 1 ? cur + 1 : -1,
207
+ ];
208
+
209
+ for (const nb of neighbours) {
210
+ if (nb < 0 || visited[nb]) continue;
211
+ if (changedMask[nb]) {
212
+ visited[nb] = 1;
213
+ queue.push(nb);
214
+ }
215
+ }
216
+ }
217
+
218
+ regions.push({
219
+ x: minX,
220
+ y: minY,
221
+ width: maxX - minX + 1,
222
+ height: maxY - minY + 1,
223
+ });
224
+ }
225
+ }
226
+
227
+ // Sort by area descending, keep at most 20
228
+ regions.sort((a, b) => b.width * b.height - a.width * a.height);
229
+ return regions.slice(0, 20);
230
+ }