web-corders-vrt 0.1.1

package/src/core/comparator.ts

@@ -0,0 +1,95 @@
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import type { ComparisonResult } from "../types.js";
+
+/**
+ * 2つのPNG画像をピクセル単位で比較し、差分画像を生成する。
+ * サイズが異なる場合は大きい方に合わせて白パディングで拡張する。
+ */
+export function compareImages(
+  beforeBuffer: Buffer,
+  afterBuffer: Buffer,
+  threshold: number = 0.1,
+): ComparisonResult {
+  const before = PNG.sync.read(beforeBuffer);
+  const after = PNG.sync.read(afterBuffer);
+
+  const width = Math.max(before.width, after.width);
+  const height = Math.max(before.height, after.height);
+
+  // サイズが異なる場合は正規化
+  const normalizedBefore = normalizeImage(before, width, height);
+  const normalizedAfter = normalizeImage(after, width, height);
+
+  const diff = new PNG({ width, height });
+
+  const diffCount = pixelmatch(
+    normalizedBefore.data,
+    normalizedAfter.data,
+    diff.data,
+    width,
+    height,
+    {
+      threshold: 0.1,
+      includeAA: false,
+      alpha: 0.1,
+      diffColor: [255, 0, 0],
+      diffColorAlt: [0, 200, 0],
+    },
+  );
+
+  const totalPixels = width * height;
+  const diffPercentage = (diffCount / totalPixels) * 100;
+
+  return {
+    diffCount,
+    totalPixels,
+    diffPercentage,
+    diffImage: PNG.sync.write(diff),
+    passed: diffPercentage <= threshold,
+    dimensions: {
+      width,
+      height,
+      beforeHeight: before.height,
+      afterHeight: after.height,
+    },
+  };
+}
+
+/**
+ * 画像を指定サイズに正規化する。
+ * 小さい場合は白（#ffffff）でパディングする。
+ */
+function normalizeImage(
+  png: PNG,
+  targetWidth: number,
+  targetHeight: number,
+): PNG {
+  if (png.width === targetWidth && png.height === targetHeight) {
+    return png;
+  }
+
+  const normalized = new PNG({ width: targetWidth, height: targetHeight });
+
+  // 白で埋める
+  for (let i = 0; i < normalized.data.length; i += 4) {
+    normalized.data[i] = 255; // R
+    normalized.data[i + 1] = 255; // G
+    normalized.data[i + 2] = 255; // B
+    normalized.data[i + 3] = 255; // A
+  }
+
+  // 元の画像をコピー
+  for (let y = 0; y < png.height; y++) {
+    for (let x = 0; x < png.width; x++) {
+      const srcIdx = (y * png.width + x) * 4;
+      const dstIdx = (y * targetWidth + x) * 4;
+      normalized.data[dstIdx] = png.data[srcIdx];
+      normalized.data[dstIdx + 1] = png.data[srcIdx + 1];
+      normalized.data[dstIdx + 2] = png.data[srcIdx + 2];
+      normalized.data[dstIdx + 3] = png.data[srcIdx + 3];
+    }
+  }
+
+  return normalized;
+}

package/src/core/region-detector.ts

@@ -0,0 +1,277 @@
+import { PNG } from "pngjs";
+import type {
+  VrtDiffRegion,
+  VerticalPosition,
+  HorizontalPosition,
+} from "../types.js";
+
+export interface RegionDetectorOptions {
+  /** この面積(px)未満の領域は無視する */
+  minRegionSize?: number;
+  /** この距離(px)以下の差分ピクセルを同一領域としてマージする */
+  mergingDistance?: number;
+}
+
+/**
+ * diff画像から差分領域を検出し、座標・位置ヒントを返す。
+ * Connected Component Labeling + bounding box 方式。
+ */
+export function detectDiffRegions(
+  diffImageBuffer: Buffer,
+  options: RegionDetectorOptions = {},
+): VrtDiffRegion[] {
+  const { minRegionSize = 10, mergingDistance = 50 } = options;
+
+  const png = PNG.sync.read(diffImageBuffer);
+  const { width, height, data } = png;
+
+  // 1. diff ピクセル（赤色）の座標を収集
+  const diffPixels: Array<{ x: number; y: number }> = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = (y * width + x) * 4;
+      const r = data[idx];
+      const g = data[idx + 1];
+      const b = data[idx + 2];
+      const a = data[idx + 3];
+
+      // pixelmatch の diffColor [255, 0, 0] または diffColorAlt [0, 200, 0] を検出
+      if (
+        a > 100 &&
+        ((r > 200 && g < 100 && b < 100) || (r < 100 && g > 150 && b < 100))
+      ) {
+        diffPixels.push({ x, y });
+      }
+    }
+  }
+
+  if (diffPixels.length === 0) {
+    return [];
+  }
+
+  // 2. グリッドベースのクラスタリング（高速化のため）
+  const clusters = clusterPixels(diffPixels, mergingDistance);
+
+  // 3. 各クラスタの bounding box を計算し、フィルタリング
+  const regions: VrtDiffRegion[] = clusters
+    .map((cluster, idx) => {
+      let minX = Infinity;
+      let maxX = -Infinity;
+      let minY = Infinity;
+      let maxY = -Infinity;
+      for (const p of cluster) {
+        if (p.x < minX) minX = p.x;
+        if (p.x > maxX) maxX = p.x;
+        if (p.y < minY) minY = p.y;
+        if (p.y > maxY) maxY = p.y;
+      }
+      const regionWidth = maxX - minX + 1;
+      const regionHeight = maxY - minY + 1;
+
+      return {
+        id: idx + 1,
+        boundingBox: {
+          x: minX,
+          y: minY,
+          width: regionWidth,
+          height: regionHeight,
+        },
+        diffPixelCount: cluster.length,
+        diffPercentageInRegion:
+          (cluster.length / (regionWidth * regionHeight)) * 100,
+        locationHint: estimatePosition(
+          minX,
+          minY,
+          regionWidth,
+          regionHeight,
+          width,
+          height,
+        ),
+      };
+    })
+    .filter((r) => r.diffPixelCount >= minRegionSize)
+    .sort((a, b) => b.diffPixelCount - a.diffPixelCount);
+
+  // IDを振り直す
+  return regions.map((r, i) => ({ ...r, id: i + 1 }));
+}
+
+/**
+ * ピクセルをグリッドベースでクラスタリングする。
+ * mergingDistance をセルサイズとしてグリッドに分割し、
+ * 隣接セルのピクセルを同一クラスタとしてマージする。
+ */
+function clusterPixels(
+  pixels: Array<{ x: number; y: number }>,
+  distance: number,
+): Array<Array<{ x: number; y: number }>> {
+  const cellSize = Math.max(distance, 1);
+  const grid = new Map<string, Array<{ x: number; y: number }>>();
+
+  // グリッドに割り当て
+  for (const p of pixels) {
+    const cellX = Math.floor(p.x / cellSize);
+    const cellY = Math.floor(p.y / cellSize);
+    const key = `${cellX},${cellY}`;
+    if (!grid.has(key)) {
+      grid.set(key, []);
+    }
+    grid.get(key)!.push(p);
+  }
+
+  // Union-Find でセルをクラスタリング
+  const cellKeys = Array.from(grid.keys());
+  const parent = new Map<string, string>();
+
+  function find(key: string): string {
+    if (!parent.has(key)) parent.set(key, key);
+    // 反復的にルートを探索
+    let root = key;
+    while (parent.get(root) !== root) {
+      root = parent.get(root)!;
+    }
+    // パス圧縮
+    let current = key;
+    while (current !== root) {
+      const next = parent.get(current)!;
+      parent.set(current, root);
+      current = next;
+    }
+    return root;
+  }
+
+  function union(a: string, b: string): void {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  }
+
+  // 隣接セルをマージ
+  for (const key of cellKeys) {
+    const [cx, cy] = key.split(",").map(Number);
+    for (let dx = -1; dx <= 1; dx++) {
+      for (let dy = -1; dy <= 1; dy++) {
+        if (dx === 0 && dy === 0) continue;
+        const neighborKey = `${cx + dx},${cy + dy}`;
+        if (grid.has(neighborKey)) {
+          union(key, neighborKey);
+        }
+      }
+    }
+  }
+
+  // クラスタごとにピクセルを集約
+  const clusters = new Map<string, Array<{ x: number; y: number }>>();
+  for (const key of cellKeys) {
+    const root = find(key);
+    if (!clusters.has(root)) {
+      clusters.set(root, []);
+    }
+    clusters.get(root)!.push(...grid.get(key)!);
+  }
+
+  return Array.from(clusters.values());
+}
+
+/**
+ * 差分領域の位置から、CSSの修正箇所を推定するヒントを生成する。
+ */
+function estimatePosition(
+  x: number,
+  y: number,
+  regionWidth: number,
+  regionHeight: number,
+  pageWidth: number,
+  pageHeight: number,
+): VrtDiffRegion["locationHint"] {
+  // 垂直位置の推定
+  const centerY = y + regionHeight / 2;
+  const yRatio = centerY / pageHeight;
+  let verticalPosition: VerticalPosition;
+  if (yRatio < 0.1) verticalPosition = "top";
+  else if (yRatio < 0.3) verticalPosition = "upper";
+  else if (yRatio < 0.7) verticalPosition = "middle";
+  else if (yRatio < 0.9) verticalPosition = "lower";
+  else verticalPosition = "bottom";
+
+  // 水平位置の推定
+  const centerX = x + regionWidth / 2;
+  const widthRatio = regionWidth / pageWidth;
+  let horizontalPosition: HorizontalPosition;
+  if (widthRatio > 0.8) {
+    horizontalPosition = "full-width";
+  } else if (centerX < pageWidth * 0.33) {
+    horizontalPosition = "left";
+  } else if (centerX > pageWidth * 0.67) {
+    horizontalPosition = "right";
+  } else {
+    horizontalPosition = "center";
+  }
+
+  // 要素の推定
+  const estimatedElement = guessElement(
+    verticalPosition,
+    horizontalPosition,
+    regionWidth,
+    regionHeight,
+    pageWidth,
+    y,
+  );
+
+  return {
+    verticalPosition,
+    horizontalPosition,
+    fromTopPx: y,
+    fromLeftPx: x,
+    estimatedElement,
+  };
+}
+
+/**
+ * 位置とサイズから、可能性のあるUI要素を推測する。
+ */
+function guessElement(
+  vPos: VerticalPosition,
+  hPos: HorizontalPosition,
+  width: number,
+  height: number,
+  pageWidth: number,
+  fromTop: number,
+): string {
+  // ページ最上部の全幅要素 → ヘッダー/ナビゲーション
+  if (vPos === "top" && hPos === "full-width" && fromTop < 100) {
+    return "Likely a header or navigation bar";
+  }
+
+  // ページ最下部の全幅要素 → フッター
+  if (vPos === "bottom" && hPos === "full-width") {
+    return "Likely a footer";
+  }
+
+  // 上部の大きな要素 → ヒーローセクション
+  if (vPos === "upper" && hPos === "full-width" && height > 200) {
+    return "Likely a hero section or banner";
+  }
+
+  // 小さなボタンサイズ
+  if (width < 200 && height < 60) {
+    return "Likely a button or small UI element";
+  }
+
+  // 横長の細い要素 → テキスト行
+  if (width > pageWidth * 0.5 && height < 40) {
+    return "Likely a text line or heading";
+  }
+
+  // カードサイズ
+  if (width > 200 && width < 500 && height > 100 && height < 400) {
+    return "Likely a card or content block";
+  }
+
+  // 画像サイズ
+  if (width > 100 && height > 100 && width < pageWidth * 0.8) {
+    return "Likely an image or media element";
+  }
+
+  return `UI element at ~${fromTop}px from top`;
+}

package/src/core/screenshotter.ts

@@ -0,0 +1,137 @@
+import { chromium, type Browser, type BrowserContext } from "playwright";
+import type { ScreenshotResult, ViewportType } from "../types.js";
+import {
+  DEFAULT_SP_VIEWPORT,
+  DEFAULT_PC_VIEWPORT,
+  DEFAULT_DELAY,
+  DEFAULT_CONCURRENCY,
+  SP_USER_AGENT,
+  BLOCKED_DOMAINS,
+} from "../constants.js";
+import { stabilizePage, getDateMockScript } from "./stabilizer.js";
+
+export class Screenshotter {
+  private browser: Browser | null = null;
+
+  async initialize(): Promise<void> {
+    this.browser = await chromium.launch();
+  }
+
+  /**
+   * 指定URLのスクリーンショットを取得する。
+   */
+  async capture(
+    url: string,
+    pagePath: string,
+    viewportType: ViewportType,
+    hideSelectors: string[],
+  ): Promise<ScreenshotResult> {
+    if (!this.browser) {
+      throw new Error("Browser not initialized. Call initialize() first.");
+    }
+
+    const viewport =
+      viewportType === "sp"
+        ? { ...DEFAULT_SP_VIEWPORT }
+        : { ...DEFAULT_PC_VIEWPORT };
+
+    const context: BrowserContext = await this.browser.newContext({
+      viewport,
+      deviceScaleFactor: viewportType === "sp" ? 2 : 1,
+      userAgent: viewportType === "sp" ? SP_USER_AGENT : undefined,
+    });
+
+    const page = await context.newPage();
+
+    // 日付をモック
+    await page.addInitScript(getDateMockScript());
+
+    // 広告・計測系リクエストをブロック
+    await page.route("**/*", (route) => {
+      const reqUrl = route.request().url();
+      const shouldBlock = BLOCKED_DOMAINS.some((domain) =>
+        reqUrl.includes(domain),
+      );
+      if (shouldBlock) {
+        return route.abort();
+      }
+      return route.continue();
+    });
+
+    // ページにアクセス
+    await page.goto(url, { waitUntil: "load", timeout: 60000 });
+
+    // ページの安定化
+    await stabilizePage(page, {
+      hideSelectors,
+      delay: DEFAULT_DELAY,
+    });
+
+    // スクリーンショット取得
+    const buffer = await page.screenshot({
+      fullPage: true,
+      type: "png",
+    });
+
+    // 画像サイズを取得（PNGヘッダから読む）
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+
+    await context.close();
+
+    // パスからページ名を生成
+    const pageName =
+      pagePath === "/"
+        ? "top"
+        : pagePath.replace(/^\//, "").replace(/\//g, "-");
+
+    return {
+      pagePath,
+      pageName,
+      viewportType,
+      buffer: Buffer.from(buffer),
+      width,
+      height,
+    };
+  }
+
+  /**
+   * 複数のページ・ビューポートのスクリーンショットを並行で取得する。
+   */
+  async captureAll(
+    baseUrl: string,
+    paths: string[],
+    viewports: ViewportType[],
+    hideSelectors: string[],
+  ): Promise<ScreenshotResult[]> {
+    const tasks: Array<{ url: string; path: string; viewport: ViewportType }> =
+      [];
+
+    for (const pagePath of paths) {
+      const url = new URL(pagePath, baseUrl).toString();
+      for (const viewport of viewports) {
+        tasks.push({ url, path: pagePath, viewport });
+      }
+    }
+
+    // 並行実行制御
+    const results: ScreenshotResult[] = [];
+
+    for (let i = 0; i < tasks.length; i += DEFAULT_CONCURRENCY) {
+      const batch = tasks.slice(i, i + DEFAULT_CONCURRENCY);
+      const batchResults = await Promise.all(
+        batch.map((task) =>
+          this.capture(task.url, task.path, task.viewport, hideSelectors),
+        ),
+      );
+      results.push(...batchResults);
+    }
+
+    return results;
+  }
+
+  async cleanup(): Promise<void> {
+    await this.browser?.close();
+    this.browser = null;
+  }
+}

package/src/core/stabilizer.ts

@@ -0,0 +1,59 @@
+import type { Page } from "playwright";
+import { DISABLE_ANIMATIONS_CSS } from "../constants.js";
+
+export interface StabilizeOptions {
+  disableAnimations?: boolean;
+  hideSelectors?: string[];
+  delay?: number;
+}
+
+/**
+ * ページの動的コンテンツを安定化させる。
+ * アニメーション無効化、要素の非表示、日付のモックなどを行う。
+ */
+export async function stabilizePage(
+  page: Page,
+  options: StabilizeOptions,
+): Promise<void> {
+  // アニメーション・トランジションを無効化
+  if (options.disableAnimations !== false) {
+    await page.addStyleTag({ content: DISABLE_ANIMATIONS_CSS });
+  }
+
+  // 指定要素を非表示にする（visibility: hidden でレイアウトを崩さない）
+  if (options.hideSelectors && options.hideSelectors.length > 0) {
+    const hideCSS = options.hideSelectors
+      .map((s) => `${s} { visibility: hidden !important; }`)
+      .join("\n");
+    await page.addStyleTag({ content: hideCSS });
+  }
+
+  // 追加の待機時間
+  if (options.delay && options.delay > 0) {
+    await page.waitForTimeout(options.delay);
+  }
+}
+
+/**
+ * 日付をモックして固定値にする初期化スクリプト。
+ * page.goto() の前に page.addInitScript() で使う。
+ */
+export function getDateMockScript(): string {
+  return `
+    (() => {
+      const fixedDate = new Date('2025-01-01T00:00:00Z');
+      const OrigDate = Date;
+      const MockDate = class extends OrigDate {
+        constructor(...args) {
+          if (args.length === 0) {
+            super(fixedDate.getTime());
+          } else {
+            super(...args);
+          }
+        }
+        static now() { return fixedDate.getTime(); }
+      };
+      globalThis.Date = MockDate;
+    })();
+  `;
+}