@openprd/cli 0.1.10 → 0.1.18

package/src/visual-compare.js

@@ -3,594 +3,48 @@ import path from 'node:path';
 import sharp from 'sharp';
 import { VISUAL_REVIEW_SCHEMA } from './quality-visual-review.js';
 import { compactTimestamp, timestamp } from './time.js';
-
-const DEFAULT_PANEL_WIDTH = 1180;
-const DEFAULT_QUALITY = 85;
-const DEFAULT_REFERENCE_LABEL = '效果图';
-const DEFAULT_ACTUAL_LABEL = '实现截图';
-const DEFAULT_BEFORE_LABEL = '修改前';
-const DEFAULT_AFTER_LABEL = '修改后';
-const DEFAULT_FOCUS_TITLE = '局部焦点证据板';
-const DEFAULT_PARALLEL_TITLE = '并行实验证据板';
-const DEFAULT_PARALLEL_CARD_WIDTH = 380;
-const DEFAULT_PARALLEL_COLUMNS = 3;
-const OUTPUT_FORMATS = new Set(['jpg', 'jpeg', 'png', 'webp']);
-const FOCUS_COLORS = ['#f97316', '#22c55e', '#38bdf8', '#eab308', '#fb7185', '#a78bfa'];
-const MODE_PREFIX = {
-  'reference-actual': 'visual-compare',
-  'before-after': 'visual-before-after',
-  'focus-board': 'visual-focus-board',
-  'parallel-board': 'visual-parallel-board',
-};
-const BOARD_MODE_ALIASES = new Map([
-  ['focus', 'focus-board'],
-  ['focus-board', 'focus-board'],
-  ['focus-region', 'focus-board'],
-  ['focus-region-board', 'focus-board'],
-  ['parallel', 'parallel-board'],
-  ['parallel-board', 'parallel-board'],
-  ['parallel-experiment-board', 'parallel-board'],
-  ['experiment-board', 'parallel-board'],
-]);
-
-function normalizeFormat(format, outPath) {
-  const requested = String(format || '').trim().toLowerCase();
-  if (requested) {
-    if (!OUTPUT_FORMATS.has(requested)) {
-      throw new Error(`Unsupported visual compare format: ${format}. Use jpg, png, or webp.`);
-    }
-    return requested === 'jpeg' ? 'jpg' : requested;
-  }
-
-  const ext = path.extname(String(outPath || '')).slice(1).toLowerCase();
-  if (OUTPUT_FORMATS.has(ext)) {
-    return ext === 'jpeg' ? 'jpg' : ext;
-  }
-  return 'jpg';
-}
-
-function outputExtension(format) {
-  return format === 'jpeg' ? 'jpg' : format;
-}
-
-function normalizeWorkspacePath(value) {
-  return String(value ?? '').split(path.sep).join('/');
-}
-
-function toWorkspacePath(projectRoot, filePath) {
-  const absolutePath = path.resolve(filePath);
-  const relativePath = path.relative(projectRoot, absolutePath);
-  if (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
-    return normalizeWorkspacePath(relativePath);
-  }
-  return absolutePath;
-}
-
-function resolveProjectPath(projectRoot, filePath) {
-  return path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath);
-}
-
-function defaultOutputPath(projectRoot, format, mode) {
-  const prefix = MODE_PREFIX[mode] ?? 'visual-compare';
-  return path.join(
-    projectRoot,
-    '.openprd',
-    'harness',
-    'visual-reviews',
-    `${prefix}-${compactTimestamp()}.${outputExtension(format)}`,
-  );
-}
-
-function parsePositiveInteger(value, fallback, label) {
-  if (value === null || value === undefined || value === '') {
-    return fallback;
-  }
-  const parsed = Number.parseInt(String(value), 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`${label} must be a positive integer.`);
-  }
-  return parsed;
-}
-
-function parseQuality(value) {
-  const quality = parsePositiveInteger(value, DEFAULT_QUALITY, '--quality');
-  if (quality < 1 || quality > 100) {
-    throw new Error('--quality must be between 1 and 100.');
-  }
-  return quality;
-}
-
-function metadataPathForOutput(outputPath) {
-  const ext = path.extname(outputPath);
-  return ext ? outputPath.slice(0, -ext.length) + '.json' : `${outputPath}.json`;
-}
-
-function escapeXml(value) {
-  return String(value)
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&apos;');
-}
-
-function charCount(value) {
-  return Array.from(String(value ?? '')).length;
-}
-
-function wrapText(value, maxCharsPerLine) {
-  const lines = [];
-  const normalized = String(value ?? '').trim();
-  if (!normalized) {
-    return lines;
-  }
-  for (const rawLine of normalized.split(/\r?\n/u)) {
-    const line = rawLine.trim();
-    if (!line) {
-      continue;
-    }
-    let buffer = '';
-    for (const char of Array.from(line)) {
-      if (charCount(buffer) >= maxCharsPerLine) {
-        lines.push(buffer);
-        buffer = '';
-      }
-      buffer += char;
-    }
-    if (buffer) {
-      lines.push(buffer);
-    }
-  }
-  return lines;
-}
-
-function lineSvg(lines, {
-  x = 0,
-  y = 0,
-  lineHeight = 24,
-  fontSize = 18,
-  fill = '#e5e7eb',
-  fontWeight = 500,
-} = {}) {
-  return lines.map((line, index) => (
-    `<text x="${x}" y="${y + index * lineHeight}" fill="${fill}" font-size="${fontSize}" font-weight="${fontWeight}" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${escapeXml(line)}</text>`
-  )).join('');
-}
-
-function labelSvg(label, options = {}) {
-  const text = escapeXml(label);
-  const fontSize = options.fontSize ?? 22;
-  const height = options.height ?? 46;
-  const paddingX = options.paddingX ?? 21;
-  const radius = options.radius ?? 14;
-  const bg = options.background ?? '#111827';
-  const bgOpacity = options.backgroundOpacity ?? 0.82;
-  const stroke = options.stroke ?? '#ffffff';
-  const strokeOpacity = options.strokeOpacity ?? 0.22;
-  const width = Math.max(options.minWidth ?? 126, charCount(label) * (fontSize + 4) + paddingX * 2);
-  return Buffer.from(`
-<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="${width}" height="${height}" rx="${radius}" fill="${bg}" fill-opacity="${bgOpacity}"/>
-  <rect x="0.75" y="0.75" width="${width - 1.5}" height="${height - 1.5}" rx="${Math.max(radius - 0.75, 1)}" fill="none" stroke="${stroke}" stroke-opacity="${strokeOpacity}" stroke-width="1.5"/>
-  <text x="${paddingX}" y="${Math.round(height * 0.64)}" fill="#ffffff" font-size="${fontSize}" font-weight="700" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${text}</text>
-</svg>`);
-}
-
-function titleBlockSvg(width, title, subtitle, eyebrow = null) {
-  const contentWidth = Math.max(Number(width) || 0, 1);
-  const titleLines = wrapText(title, Math.max(12, Math.floor((contentWidth - 48) / 18)));
-  const subtitleLines = wrapText(subtitle, Math.max(16, Math.floor((contentWidth - 48) / 16)));
-  const eyebrowLines = wrapText(eyebrow, Math.max(18, Math.floor((contentWidth - 48) / 18)));
-  let y = eyebrowLines.length > 0 ? 28 : 0;
-  const parts = [];
-  if (eyebrowLines.length > 0) {
-    parts.push(lineSvg(eyebrowLines, {
-      x: 0,
-      y: y,
-      lineHeight: 20,
-      fontSize: 16,
-      fill: '#93c5fd',
-      fontWeight: 700,
-    }));
-    y += eyebrowLines.length * 20 + 14;
-  }
-  parts.push(lineSvg(titleLines, {
-    x: 0,
-    y: y + 30,
-    lineHeight: 34,
-    fontSize: 30,
-    fill: '#f8fafc',
-    fontWeight: 800,
-  }));
-  y += titleLines.length * 34 + 10;
-  if (subtitleLines.length > 0) {
-    parts.push(lineSvg(subtitleLines, {
-      x: 0,
-      y: y + 24,
-      lineHeight: 24,
-      fontSize: 18,
-      fill: '#cbd5e1',
-      fontWeight: 500,
-    }));
-    y += subtitleLines.length * 24 + 6;
-  }
-  const height = Math.max(72, y + 16);
-  return {
-    height,
-    input: Buffer.from(`
-<svg width="${contentWidth}" height="${height}" viewBox="0 0 ${contentWidth} ${height}" xmlns="http://www.w3.org/2000/svg">
-  ${parts.join('')}
-</svg>`),
-  };
-}
-
-function sectionHeaderSvg(width, index, label, reason = '') {
-  const contentWidth = Math.max(Number(width) || 0, 1);
-  const titleLines = wrapText(`${index}. ${label}`, Math.max(10, Math.floor((contentWidth - 48) / 18)));
-  const reasonLines = wrapText(reason, Math.max(14, Math.floor((contentWidth - 48) / 16)));
-  const height = 32 + titleLines.length * 28 + (reasonLines.length > 0 ? 10 + reasonLines.length * 22 : 0);
-  return {
-    height,
-    input: Buffer.from(`
-<svg width="${contentWidth}" height="${height}" viewBox="0 0 ${contentWidth} ${height}" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0" y="0" width="${contentWidth}" height="${height}" rx="18" fill="#0f172a" fill-opacity="0.92"/>
-  <rect x="0.75" y="0.75" width="${contentWidth - 1.5}" height="${height - 1.5}" rx="17.25" fill="none" stroke="#475569" stroke-opacity="0.45" stroke-width="1.5"/>
-  ${lineSvg(titleLines, {
-    x: 20,
-    y: 30,
-    lineHeight: 28,
-    fontSize: 24,
-    fill: '#f8fafc',
-    fontWeight: 800,
-  })}
-  ${reasonLines.length > 0 ? lineSvg(reasonLines, {
-    x: 20,
-    y: 30 + titleLines.length * 28 + 10,
-    lineHeight: 22,
-    fontSize: 16,
-    fill: '#cbd5e1',
-    fontWeight: 500,
-  }) : ''}
-</svg>`),
-  };
-}
-
-function metricsSvg(width, metrics = [], notes = null) {
-  const contentWidth = Math.max(Number(width) || 0, 1);
-  const lines = [];
-  for (const metric of metrics) {
-    lines.push(`${metric.label}：${metric.value}`);
-  }
-  if (notes) {
-    lines.push(...wrapText(notes, Math.max(12, Math.floor((contentWidth - 24) / 16))));
-  }
-  if (lines.length === 0) {
-    return { height: 0, input: null };
-  }
-  const height = 18 + lines.length * 22;
-  return {
-    height,
-    input: Buffer.from(`
-<svg width="${contentWidth}" height="${height}" viewBox="0 0 ${contentWidth} ${height}" xmlns="http://www.w3.org/2000/svg">
-  ${lineSvg(lines, {
-    x: 0,
-    y: 20,
-    lineHeight: 22,
-    fontSize: 16,
-    fill: '#cbd5e1',
-    fontWeight: 500,
-  })}
-</svg>`),
-  };
-}
-
-async function resizePanel(inputPath, panelWidth) {
-  const source = path.resolve(inputPath);
-  const metadata = await sharp(source).metadata();
-  if (!metadata.width || !metadata.height) {
-    throw new Error(`Cannot read image dimensions: ${inputPath}`);
-  }
-  const { data, info } = await sharp(source)
-    .rotate()
-    .resize({
-      width: panelWidth,
-      fit: 'inside',
-      withoutEnlargement: true,
-    })
-    .png()
-    .toBuffer({ resolveWithObject: true });
-  return {
-    input: data,
-    width: info.width,
-    height: info.height,
-    source,
-    original: {
-      width: metadata.width,
-      height: metadata.height,
-      format: metadata.format ?? null,
-    },
-  };
-}
-
-async function extractCrop(inputPath, box, outputWidth) {
-  const source = path.resolve(inputPath);
-  const { data, info } = await sharp(source)
-    .rotate()
-    .extract({
-      left: box.x,
-      top: box.y,
-      width: box.width,
-      height: box.height,
-    })
-    .resize({
-      width: outputWidth,
-      fit: 'inside',
-      withoutEnlargement: false,
-    })
-    .png()
-    .toBuffer({ resolveWithObject: true });
-  return {
-    input: data,
-    width: info.width,
-    height: info.height,
-    source,
-    absolute: box,
-  };
-}
-
-function encodePipeline(image, format, quality) {
-  if (format === 'png') {
-    return image.png();
-  }
-  if (format === 'webp') {
-    return image.webp({ quality });
-  }
-  return image.jpeg({ quality });
-}
-
-function resolveComparisonInputs(options) {
-  const hasReferenceActual = Boolean(options.reference || options.actual);
-  const hasBeforeAfter = Boolean(options.before || options.after);
-  const hasBoard = Boolean(options.board);
-  const modeCount = [hasReferenceActual, hasBeforeAfter, hasBoard].filter(Boolean).length;
-  if (modeCount > 1) {
-    throw new Error('Use either --reference/--actual, --before/--after, or --board, not multiple modes together.');
-  }
-  if (hasBeforeAfter) {
-    if (!options.before) {
-      throw new Error('Missing --before image path.');
-    }
-    if (!options.after) {
-      throw new Error('Missing --after image path.');
-    }
-    return {
-      mode: 'before-after',
-      left: options.before,
-      right: options.after,
-      leftLabel: options.referenceLabel || DEFAULT_BEFORE_LABEL,
-      rightLabel: options.actualLabel || DEFAULT_AFTER_LABEL,
-      nextActions: [
-        '把输出图片作为视觉改动自检证据查看：左侧修改前，右侧修改后。',
-        '检查预期变化是否出现，以及未改区域是否有布局、颜色、密度或状态漂移。',
-        '没有效果图时，这张图只证明改动前后差异已自检；大界面方向性改造仍需先完成方案评审。',
-      ],
-    };
-  }
-  if (hasReferenceActual) {
-    if (!options.reference) {
-      throw new Error('Missing --reference image path.');
-    }
-    if (!options.actual) {
-      throw new Error('Missing --actual image path.');
-    }
-    return {
-      mode: 'reference-actual',
-      left: options.reference,
-      right: options.actual,
-      leftLabel: options.referenceLabel || DEFAULT_REFERENCE_LABEL,
-      rightLabel: options.actualLabel || DEFAULT_ACTUAL_LABEL,
-      nextActions: [
-        '把输出图片作为视觉评审证据查看：左侧效果图，右侧实现截图。',
-        '如果仍有明显差异，继续按效果图复刻并重新运行 visual-compare。',
-        '只有对比图确认一致后，才声明本阶段界面视觉实现完成。',
-      ],
-    };
-  }
-  if (hasBoard) {
-    return {
-      mode: 'board',
-      board: options.board,
-    };
-  }
-  throw new Error('Missing visual compare input. Use --reference/--actual, --before/--after, or --board.');
-}
-
-function normalizeBoardMode(value) {
-  const key = String(value ?? '').trim().toLowerCase();
-  return BOARD_MODE_ALIASES.get(key) ?? null;
-}
-
-async function readBoardSpec(projectRoot, boardPath) {
-  const sourcePath = resolveProjectPath(projectRoot, boardPath);
-  const payload = JSON.parse(await fs.readFile(sourcePath, 'utf8'));
-  const mode = normalizeBoardMode(payload.mode);
-  if (!mode) {
-    throw new Error(`Unsupported board mode in ${boardPath}. Use focus-board or parallel-board.`);
-  }
-  return {
-    mode,
-    sourcePath,
-    payload,
-  };
-}
-
-function normalizeImageSpec(projectRoot, value, fallbackLabel) {
-  if (!value) {
-    throw new Error('Board image spec is missing.');
-  }
-  if (typeof value === 'string') {
-    return {
-      path: resolveProjectPath(projectRoot, value),
-      label: fallbackLabel,
-    };
-  }
-  if (typeof value === 'object' && value.path) {
-    return {
-      path: resolveProjectPath(projectRoot, value.path),
-      label: value.label ? String(value.label) : fallbackLabel,
-    };
-  }
-  throw new Error('Board image spec must be a path string or an object with { path, label? }.');
-}
-
-function normalizeMetricList(metrics) {
-  if (!metrics) {
-    return [];
-  }
-  if (Array.isArray(metrics)) {
-    return metrics
-      .filter(Boolean)
-      .map((item) => {
-        if (typeof item === 'string') {
-          return { label: '说明', value: item };
-        }
-        return {
-          label: String(item.label ?? item.key ?? '指标'),
-          value: String(item.value ?? ''),
-        };
-      })
-      .filter((item) => item.value.trim());
-  }
-  if (typeof metrics === 'object') {
-    return Object.entries(metrics)
-      .filter(([, value]) => value !== null && value !== undefined && String(value).trim())
-      .map(([key, value]) => ({ label: key, value: String(value) }));
-  }
-  return [];
-}
-
-function normalizeMediaList(projectRoot, media) {
-  if (!Array.isArray(media)) {
-    return [];
-  }
-  return media
-    .filter(Boolean)
-    .map((entry, index) => {
-      if (typeof entry === 'string') {
-        return {
-          path: resolveProjectPath(projectRoot, entry),
-          label: `素材 ${index + 1}`,
-        };
-      }
-      if (!entry.path) {
-        throw new Error(`Parallel board media[${index}] is missing path.`);
-      }
-      return {
-        path: resolveProjectPath(projectRoot, entry.path),
-        label: String(entry.label ?? `素材 ${index + 1}`),
-      };
-    });
-}
-
-function parseCropDimension(box, key, alias) {
-  const primary = box[key];
-  const secondary = alias ? box[alias] : undefined;
-  const value = primary ?? secondary;
-  if (value === null || value === undefined || value === '') {
-    throw new Error(`Missing ${key} in focus region box.`);
-  }
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed)) {
-    throw new Error(`Invalid ${key} in focus region box.`);
-  }
-  return parsed;
-}
-
-function clampBox(box, original) {
-  const x = Math.max(0, Math.min(box.x, original.width - 1));
-  const y = Math.max(0, Math.min(box.y, original.height - 1));
-  const width = Math.max(1, Math.min(box.width, original.width - x));
-  const height = Math.max(1, Math.min(box.height, original.height - y));
-  return {
-    x,
-    y,
-    width,
-    height,
-  };
-}
-
-function resolveCropBox(box, original) {
-  if (!box || typeof box !== 'object') {
-    throw new Error('Focus region box must be an object.');
-  }
-  const rawUnit = String(box.unit ?? 'ratio').trim().toLowerCase();
-  const x = parseCropDimension(box, 'x', 'left');
-  const y = parseCropDimension(box, 'y', 'top');
-  const width = parseCropDimension(box, 'width', 'w');
-  const height = parseCropDimension(box, 'height', 'h');
-  let absolute;
-
-  if (rawUnit === 'ratio') {
-    absolute = {
-      x: Math.round(x * original.width),
-      y: Math.round(y * original.height),
-      width: Math.round(width * original.width),
-      height: Math.round(height * original.height),
-    };
-  } else if (rawUnit === 'percent') {
-    absolute = {
-      x: Math.round((x / 100) * original.width),
-      y: Math.round((y / 100) * original.height),
-      width: Math.round((width / 100) * original.width),
-      height: Math.round((height / 100) * original.height),
-    };
-  } else if (rawUnit === 'px' || rawUnit === 'pixel' || rawUnit === 'pixels') {
-    absolute = {
-      x: Math.round(x),
-      y: Math.round(y),
-      width: Math.round(width),
-      height: Math.round(height),
-    };
-  } else {
-    throw new Error(`Unsupported focus region unit: ${rawUnit}. Use ratio, percent, or px.`);
-  }
-
-  return {
-    unit: rawUnit === 'pixel' || rawUnit === 'pixels' ? 'px' : rawUnit,
-    requested: { x, y, width, height },
-    absolute: clampBox(absolute, original),
-  };
-}
-
-function renderedBoxFromAbsolute(box, panel) {
-  const scaleX = panel.width / panel.original.width;
-  const scaleY = panel.height / panel.original.height;
-  return {
-    x: Math.round(box.x * scaleX),
-    y: Math.round(box.y * scaleY),
-    width: Math.max(2, Math.round(box.width * scaleX)),
-    height: Math.max(2, Math.round(box.height * scaleY)),
-  };
-}
-
-function focusOverlaySvg(width, height, regions) {
-  const overlays = regions.map((region, index) => {
-    const color = region.color;
-    const box = region.box;
-    const badgeSize = 32;
-    const badgeX = Math.max(10, box.x + 10);
-    const badgeY = Math.max(10, box.y + 10);
-    return `
-      <rect x="${box.x}" y="${box.y}" width="${box.width}" height="${box.height}" rx="16" fill="none" stroke="${color}" stroke-width="4"/>
-      <rect x="${badgeX}" y="${badgeY}" width="${badgeSize}" height="${badgeSize}" rx="16" fill="${color}"/>
-      <text x="${badgeX + 10}" y="${badgeY + 22}" fill="#0f172a" font-size="18" font-weight="800" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${index + 1}</text>
-    `;
-  }).join('');
-  return Buffer.from(`
-<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
-  ${overlays}
-</svg>`);
-}
+import {
+  OPENPRD_FALLBACK_LOCALE,
+  detectPrimaryLanguage,
+  isChineseLocale,
+  isEnglishHeavyText,
+  normalizeOutputLocale,
+} from './language-policy.js';
+import {
+  ALIGNMENT_CONTAINER_TOKENS,
+  ALIGNMENT_CONTENT_SLOT_TOKENS,
+  DEFAULT_PANEL_WIDTH,
+  DEFAULT_PARALLEL_CARD_WIDTH,
+  DEFAULT_PARALLEL_COLUMNS,
+  FOCUS_COLORS,
+  defaultOutputPath,
+  encodePipeline,
+  escapeXml,
+  extractCrop,
+  focusOverlaySvg,
+  labelSvg,
+  localeFromOptions,
+  metadataPathForOutput,
+  normalizeFormat,
+  normalizeImageSpec,
+  normalizeMetricList,
+  normalizeVerificationItems,
+  parsePositiveInteger,
+  parseQuality,
+  readBoardSpec,
+  renderParallelCard,
+  renderedBoxFromAbsolute,
+  resizePanel,
+  resolveBoardLocale,
+  resolveComparisonInputs,
+  resolveCropBox,
+  sectionHeaderSvg,
+  titleBlockSvg,
+  toWorkspacePath,
+  validateBoardVisibleLanguage,
+  visualCopyForLocale,
+} from './visual-compare-core.js';
+import { renderCenteringBoard } from './visual-compare-centering.js';
 
 async function renderStandardComparison(projectRoot, comparison, options = {}) {
   const format = normalizeFormat(options.format, options.out);
@@ -626,8 +80,8 @@ async function renderStandardComparison(projectRoot, comparison, options = {}) {
   }).composite([
     { input: referencePanel.input, left: referenceLeft, top: referenceTop },
     { input: actualPanel.input, left: actualLeft, top: actualTop },
-    { input: labelSvg(comparison.leftLabel), left: referenceLeft + 16, top: referenceTop + 16 },
-    { input: labelSvg(comparison.rightLabel), left: actualLeft + 16, top: actualTop + 16 },
+    { input: labelSvg(comparison.leftLabel, { maxWidth: Math.max(32, referencePanel.width - 32) }), left: referenceLeft + 16, top: referenceTop + 16 },
+    { input: labelSvg(comparison.rightLabel, { maxWidth: Math.max(32, actualPanel.width - 32) }), left: actualLeft + 16, top: actualTop + 16 },
   ]);
 
   await fs.mkdir(path.dirname(outputPath), { recursive: true });
@@ -638,6 +92,7 @@ async function renderStandardComparison(projectRoot, comparison, options = {}) {
     schema: VISUAL_REVIEW_SCHEMA,
     generatedAt: timestamp(),
     mode: comparison.mode,
+    locale: comparison.locale,
     outputPath: toWorkspacePath(projectRoot, outputPath),
     format,
     labels: {
@@ -707,14 +162,16 @@ async function renderStandardComparison(projectRoot, comparison, options = {}) {
 }
 
 async function renderFocusBoard(projectRoot, board, options = {}) {
+  const locale = localeFromOptions(options);
+  const copy = visualCopyForLocale(locale);
   const format = normalizeFormat(options.format, options.out);
   const outputPath = options.out
     ? path.resolve(projectRoot, options.out)
     : defaultOutputPath(projectRoot, format, 'focus-board');
   const quality = parseQuality(options.quality);
   const maxPanelWidth = parsePositiveInteger(options.maxPanelWidth, DEFAULT_PANEL_WIDTH, '--max-panel-width');
-  const leftSpec = normalizeImageSpec(projectRoot, board.payload.left ?? board.payload.reference, board.payload.leftLabel ?? DEFAULT_REFERENCE_LABEL);
-  const rightSpec = normalizeImageSpec(projectRoot, board.payload.right ?? board.payload.actual, board.payload.rightLabel ?? DEFAULT_ACTUAL_LABEL);
+  const leftSpec = normalizeImageSpec(projectRoot, board.payload.left ?? board.payload.reference, board.payload.leftLabel ?? copy.referenceLabel);
+  const rightSpec = normalizeImageSpec(projectRoot, board.payload.right ?? board.payload.actual, board.payload.rightLabel ?? copy.actualLabel);
   const focusRegions = Array.isArray(board.payload.focusRegions ?? board.payload.regions) ? (board.payload.focusRegions ?? board.payload.regions) : [];
   if (focusRegions.length === 0) {
     throw new Error('Focus board requires focusRegions with at least one region.');
@@ -730,9 +187,9 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
   const contentWidth = margin * 2 + panelWidth * 2 + gap;
   const titleBlock = titleBlockSvg(
     contentWidth - margin * 2,
-    String(board.payload.title ?? DEFAULT_FOCUS_TITLE),
-    String(board.payload.summary ?? '先看整体标框，再看编号对应的局部放大；局部差异优先在这里复核。'),
-    '视觉验收 / 局部焦点',
+    String(board.payload.title ?? copy.focusTitle),
+    String(board.payload.summary ?? copy.focusSummary),
+    copy.focusEyebrow,
   );
 
   const leftOverviewX = margin + Math.round((panelWidth - leftPanel.width) / 2);
@@ -745,8 +202,8 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
     { input: titleBlock.input, left: margin, top: margin },
     { input: leftPanel.input, left: leftOverviewX, top: leftOverviewY },
     { input: rightPanel.input, left: rightOverviewX, top: rightOverviewY },
-    { input: labelSvg(leftSpec.label), left: leftOverviewX + 16, top: leftOverviewY + 16 },
-    { input: labelSvg(rightSpec.label), left: rightOverviewX + 16, top: rightOverviewY + 16 },
+    { input: labelSvg(leftSpec.label, { maxWidth: Math.max(32, leftPanel.width - 32) }), left: leftOverviewX + 16, top: leftOverviewY + 16 },
+    { input: labelSvg(rightSpec.label, { maxWidth: Math.max(32, rightPanel.width - 32) }), left: rightOverviewX + 16, top: rightOverviewY + 16 },
   ];
 
   const metadataRegions = [];
@@ -755,7 +212,7 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
   let currentTop = overviewTop + overviewHeight + sectionGap;
 
   for (const [index, region] of focusRegions.entries()) {
-    const label = String(region.label ?? region.name ?? `焦点 ${index + 1}`);
+    const label = String(region.label ?? region.name ?? copy.focusRegionLabel(index));
     const reason = String(region.reason ?? region.note ?? '').trim();
     const color = FOCUS_COLORS[index % FOCUS_COLORS.length];
     const leftResolved = resolveCropBox(region.leftBox ?? region.referenceBox ?? region.box, leftPanel.original);
@@ -776,8 +233,8 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
       { input: header.input, left: margin, top: currentTop },
       { input: leftCrop.input, left: leftCropX, top: leftCropY },
       { input: rightCrop.input, left: rightCropX, top: rightCropY },
-      { input: labelSvg(leftSpec.label, { fontSize: 18, height: 40, minWidth: 112 }), left: leftCropX + 12, top: leftCropY + 12 },
-      { input: labelSvg(rightSpec.label, { fontSize: 18, height: 40, minWidth: 112 }), left: rightCropX + 12, top: rightCropY + 12 },
+      { input: labelSvg(leftSpec.label, { fontSize: 18, height: 40, minWidth: 112, maxWidth: Math.max(32, leftCrop.width - 24) }), left: leftCropX + 12, top: leftCropY + 12 },
+      { input: labelSvg(rightSpec.label, { fontSize: 18, height: 40, minWidth: 112, maxWidth: Math.max(32, rightCrop.width - 24) }), left: rightCropX + 12, top: rightCropY + 12 },
     );
     leftOverlayRegions.push({ color, box: leftRenderedBox });
     rightOverlayRegions.push({ color, box: rightRenderedBox });
@@ -833,10 +290,11 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
     schema: VISUAL_REVIEW_SCHEMA,
     generatedAt: timestamp(),
     mode: 'focus-board',
+    locale,
     outputPath: toWorkspacePath(projectRoot, outputPath),
     format,
     boardSource: toWorkspacePath(projectRoot, board.sourcePath),
-    title: String(board.payload.title ?? DEFAULT_FOCUS_TITLE),
+    title: String(board.payload.title ?? copy.focusTitle),
     labels: {
       reference: leftSpec.label,
       actual: rightSpec.label,
@@ -881,126 +339,143 @@ async function renderFocusBoard(projectRoot, board, options = {}) {
     focusRegions: metadataRegions,
     canvas: reviewArtifact.canvas,
     reviewArtifact,
-    nextActions: [
-      '先看顶部编号框，再对照下面同编号的局部放大图复核差异。',
-      '若局部区域仍有问题，优先围绕该编号返工，并重新生成焦点证据板。',
-      '局部证据板适合补充整体对比，不建议只看整体图就结束界面验收。',
-    ],
+    nextActions: copy.focusNextActions,
   };
 }
 
-async function renderParallelCard(projectRoot, item, index, options = {}) {
-  const cardWidth = options.cardWidth;
-  const contentWidth = cardWidth - 36;
-  const title = String(item.label ?? item.title ?? `方案 ${index + 1}`);
-  const subtitle = String(item.subtitle ?? item.summary ?? '').trim();
-  const verdict = String(item.verdict ?? '').trim();
-  const mediaList = normalizeMediaList(projectRoot, item.media);
-  const metrics = normalizeMetricList(item.metrics ?? item.metricMap);
-  const notes = String(item.notes ?? item.note ?? '').trim();
-  const header = titleBlockSvg(
-    contentWidth,
-    `${index + 1}. ${title}`,
-    subtitle,
-    verdict ? `结论：${verdict}` : '并行实验',
+async function renderParallelBoard(projectRoot, board, options = {}) {
+  const locale = localeFromOptions(options);
+  const copy = visualCopyForLocale(locale);
+  const format = normalizeFormat(options.format, options.out);
+  const outputPath = options.out
+    ? path.resolve(projectRoot, options.out)
+    : defaultOutputPath(projectRoot, format, 'parallel-board');
+  const quality = parseQuality(options.quality);
+  const items = Array.isArray(board.payload.items) ? board.payload.items : [];
+  if (items.length === 0) {
+    throw new Error('Parallel board requires items with at least one experiment.');
+  }
+  const cardWidth = parsePositiveInteger(board.payload.cardWidth ?? options.maxPanelWidth, DEFAULT_PARALLEL_CARD_WIDTH, 'cardWidth');
+  const columns = Math.max(1, Math.min(parsePositiveInteger(board.payload.columns, Math.min(DEFAULT_PARALLEL_COLUMNS, items.length), 'columns'), 4));
+  const margin = 24;
+  const gap = 24;
+  const titleBlock = titleBlockSvg(
+    columns * cardWidth + (columns - 1) * gap,
+    String(board.payload.title ?? copy.parallelTitle),
+    String(board.payload.summary ?? copy.parallelSummary),
+    copy.parallelEyebrow,
   );
-  const composites = [
-    { input: header.input, left: 18, top: 18 },
-  ];
-  const renderedMedia = [];
-  let currentTop = 18 + header.height + 12;
 
-  for (const media of mediaList) {
-    const label = labelSvg(media.label, {
-      fontSize: 16,
-      height: 36,
-      minWidth: 96,
-      paddingX: 16,
-      radius: 12,
-    });
-    const mediaPanel = await resizePanel(media.path, contentWidth);
-    composites.push(
-      { input: label, left: 18, top: currentTop },
-      { input: mediaPanel.input, left: 18 + Math.round((contentWidth - mediaPanel.width) / 2), top: currentTop + 42 },
-    );
-    renderedMedia.push({
-      path: toWorkspacePath(projectRoot, media.path),
-      label: media.label,
-      original: mediaPanel.original,
-      rendered: {
-        width: mediaPanel.width,
-        height: mediaPanel.height,
-      },
-    });
-    currentTop += 42 + mediaPanel.height + 16;
+  const renderedCards = [];
+  for (const [index, item] of items.entries()) {
+    renderedCards.push(await renderParallelCard(projectRoot, item, index, { cardWidth, locale }));
   }
 
-  const metricsBlock = metricsSvg(contentWidth, metrics, notes);
-  if (metricsBlock.input) {
-    composites.push({ input: metricsBlock.input, left: 18, top: currentTop });
-    currentTop += metricsBlock.height + 12;
+  const rowHeights = [];
+  for (let index = 0; index < renderedCards.length; index += columns) {
+    rowHeights.push(Math.max(...renderedCards.slice(index, index + columns).map((card) => card.height)));
+  }
+  const canvasWidth = margin * 2 + columns * cardWidth + (columns - 1) * gap;
+  const canvasHeight = margin * 2 + titleBlock.height + 18 + rowHeights.reduce((sum, value) => sum + value, 0) + Math.max(0, rowHeights.length - 1) * gap;
+  const composites = [
+    { input: titleBlock.input, left: margin, top: margin },
+  ];
+  let currentTop = margin + titleBlock.height + 18;
+  for (let row = 0; row < rowHeights.length; row += 1) {
+    const rowCards = renderedCards.slice(row * columns, row * columns + columns);
+    for (const [column, card] of rowCards.entries()) {
+      composites.push({
+        input: card.image,
+        left: margin + column * (cardWidth + gap),
+        top: currentTop,
+      });
+    }
+    currentTop += rowHeights[row] + gap;
   }
 
-  const cardHeight = currentTop + 18;
-  const card = sharp({
+  const canvas = sharp({
     create: {
-      width: cardWidth,
-      height: cardHeight,
+      width: canvasWidth,
+      height: canvasHeight,
       channels: 3,
-      background: '#0f172a',
+      background: '#111827',
     },
-  }).composite([
-    ...composites,
-    {
-      input: Buffer.from(`
-<svg width="${cardWidth}" height="${cardHeight}" viewBox="0 0 ${cardWidth} ${cardHeight}" xmlns="http://www.w3.org/2000/svg">
-  <rect x="0.75" y="0.75" width="${cardWidth - 1.5}" height="${cardHeight - 1.5}" rx="22" fill="none" stroke="#334155" stroke-width="1.5"/>
-</svg>`),
-      left: 0,
-      top: 0,
+  }).composite(composites);
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await encodePipeline(canvas, format, quality).toFile(outputPath);
+  const metadataPath = metadataPathForOutput(outputPath);
+  const reviewArtifact = {
+    version: 1,
+    schema: VISUAL_REVIEW_SCHEMA,
+    generatedAt: timestamp(),
+    mode: 'parallel-board',
+    locale,
+    outputPath: toWorkspacePath(projectRoot, outputPath),
+    format,
+    boardSource: toWorkspacePath(projectRoot, board.sourcePath),
+    title: String(board.payload.title ?? copy.parallelTitle),
+    layout: {
+      columns,
+      cardWidth,
+      rowCount: rowHeights.length,
     },
-  ]);
+    items: renderedCards.map((card) => card.item),
+    canvas: {
+      width: canvasWidth,
+      height: canvasHeight,
+    },
+  };
+  await fs.writeFile(metadataPath, `${JSON.stringify(reviewArtifact, null, 2)}\n`, 'utf8');
 
   return {
-    image: await card.png().toBuffer(),
-    width: cardWidth,
-    height: cardHeight,
-    item: {
-      index: index + 1,
-      label: title,
-      subtitle,
-      verdict,
-      metrics,
-      notes,
-      media: renderedMedia,
-    },
+    ok: true,
+    action: 'visual-compare',
+    mode: 'parallel-board',
+    projectRoot,
+    outputPath,
+    metadataPath,
+    format,
+    quality: format === 'png' ? null : quality,
+    canvas: reviewArtifact.canvas,
+    reviewArtifact,
+    items: reviewArtifact.items,
+    nextActions: copy.parallelNextActions,
   };
 }
 
-async function renderParallelBoard(projectRoot, board, options = {}) {
+async function renderVerificationBoard(projectRoot, board, options = {}) {
+  const locale = localeFromOptions(options);
+  const copy = visualCopyForLocale(locale);
   const format = normalizeFormat(options.format, options.out);
   const outputPath = options.out
     ? path.resolve(projectRoot, options.out)
-    : defaultOutputPath(projectRoot, format, 'parallel-board');
+    : defaultOutputPath(projectRoot, format, 'verification-board');
   const quality = parseQuality(options.quality);
-  const items = Array.isArray(board.payload.items) ? board.payload.items : [];
+  const items = normalizeVerificationItems(projectRoot, board.payload, locale);
   if (items.length === 0) {
-    throw new Error('Parallel board requires items with at least one experiment.');
+    throw new Error('Verification board requires screenshots, items, or a single screenshot/path entry.');
   }
   const cardWidth = parsePositiveInteger(board.payload.cardWidth ?? options.maxPanelWidth, DEFAULT_PARALLEL_CARD_WIDTH, 'cardWidth');
   const columns = Math.max(1, Math.min(parsePositiveInteger(board.payload.columns, Math.min(DEFAULT_PARALLEL_COLUMNS, items.length), 'columns'), 4));
   const margin = 24;
   const gap = 24;
+  const route = String(board.payload.route ?? board.payload.flow ?? board.payload.method ?? '').trim();
+  const summary = String(board.payload.summary ?? copy.verificationSummary(route));
   const titleBlock = titleBlockSvg(
     columns * cardWidth + (columns - 1) * gap,
-    String(board.payload.title ?? DEFAULT_PARALLEL_TITLE),
-    String(board.payload.summary ?? '把多方向产物、局部截图、GIF 首帧和指标放到一板里，方便统一审查。'),
-    '视觉验收 / 并行实验',
+    String(board.payload.title ?? copy.verificationTitle),
+    summary,
+    copy.verificationEyebrow,
   );
 
   const renderedCards = [];
   for (const [index, item] of items.entries()) {
-    renderedCards.push(await renderParallelCard(projectRoot, item, index, { cardWidth }));
+    renderedCards.push(await renderParallelCard(projectRoot, item, index, {
+      cardWidth,
+      eyebrow: copy.verificationCardEyebrow,
+      locale,
+    }));
   }
 
   const rowHeights = [];
@@ -1041,11 +516,13 @@ async function renderParallelBoard(projectRoot, board, options = {}) {
     version: 1,
     schema: VISUAL_REVIEW_SCHEMA,
     generatedAt: timestamp(),
-    mode: 'parallel-board',
+    mode: 'verification-board',
+    locale,
     outputPath: toWorkspacePath(projectRoot, outputPath),
     format,
     boardSource: toWorkspacePath(projectRoot, board.sourcePath),
-    title: String(board.payload.title ?? DEFAULT_PARALLEL_TITLE),
+    title: String(board.payload.title ?? copy.verificationTitle),
+    route: route || null,
     layout: {
       columns,
       cardWidth,
@@ -1062,7 +539,7 @@ async function renderParallelBoard(projectRoot, board, options = {}) {
   return {
     ok: true,
     action: 'visual-compare',
-    mode: 'parallel-board',
+    mode: 'verification-board',
     projectRoot,
     outputPath,
     metadataPath,
@@ -1071,27 +548,472 @@ async function renderParallelBoard(projectRoot, board, options = {}) {
     canvas: reviewArtifact.canvas,
     reviewArtifact,
     items: reviewArtifact.items,
-    nextActions: [
-      '横向比较每个实验卡片，再结合指标和结论判断是否要保留多条方向继续迭代。',
-      '如果某个方向需要局部细看，再补一张局部焦点证据板，不要只盯整体缩略图。',
-      '并行实验证据板适合在 Agent 自验收和用户评审时一起使用，减少来回口头解释。',
-    ],
+    nextActions: copy.verificationNextActions,
   };
 }
 
+function normalizeAlignmentGroups(payload, locale = OPENPRD_FALLBACK_LOCALE) {
+  const copy = visualCopyForLocale(locale);
+  const groupEntries = normalizeAlignmentGroupEntries(payload);
+  const defaultThreshold = payload.thresholdPx ?? payload.threshold ?? 2;
+  return groupEntries.map(({ group, fallbackLevel }, index) => {
+    const threshold = group.thresholdPx ?? group.threshold ?? defaultThreshold;
+    const metrics = normalizeAlignmentMetrics(group.metrics ?? group.measurements ?? group.checks, threshold, locale);
+    const expected = String(group.expected ?? group.expectation ?? '').trim();
+    const pattern = String(group.pattern ?? group.structure ?? '').trim();
+    const level = normalizeAlignmentLevel(group.level ?? group.kind ?? group.type ?? group.scopeKind)
+      ?? fallbackLevel
+      ?? inferAlignmentLevel([group.label, group.title, group.subtitle, group.scope, pattern, expected, ...metrics.map((metric) => metric.label)].join(' '));
+    const levelLabel = alignmentLevelLabel(level, locale);
+    const notes = [
+      expected ? `${copy.alignmentExpectedPrefix}${copy.separator}${expected}` : '',
+      pattern ? `${copy.alignmentStructurePrefix}${copy.separator}${pattern}` : '',
+      String(group.notes ?? group.note ?? '').trim(),
+    ].filter(Boolean).join('\n');
+    const subtitle = [
+      levelLabel,
+      String(group.subtitle ?? group.scope ?? group.selector ?? '').trim(),
+    ].filter(Boolean).join(' / ');
+    return {
+      label: String(group.label ?? group.title ?? copy.alignmentGroupLabel(index)),
+      subtitle,
+      level,
+      levelLabel,
+      verdict: String(group.verdict ?? group.status ?? '').trim(),
+      metrics,
+      notes,
+    };
+  });
+}
+
+function normalizeAlignmentGroupEntries(payload) {
+  const entries = [];
+  const add = (groups, fallbackLevel) => {
+    if (!Array.isArray(groups)) {
+      return;
+    }
+    for (const group of groups) {
+      if (group) {
+        entries.push({ group, fallbackLevel });
+      }
+    }
+  };
+  if (Array.isArray(payload.groups)) {
+    add(payload.groups, null);
+  } else {
+    add(payload.items, null);
+  }
+  add(payload.containerGroups ?? payload.containerTracks, 'container');
+  add(payload.contentSlots ?? payload.slotGroups ?? payload.contentSlotGroups ?? payload.internalSlots, 'content-slot');
+  return entries;
+}
+
+function normalizeAlignmentLevel(value) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (['container', 'outer', 'outer-frame', 'frame', 'grid', '容器', '外框', '网格'].includes(normalized)) {
+    return 'container';
+  }
+  if (['content', 'content-slot', 'internal', 'internal-slot', 'slot', 'same-slot', '内容', '内容槽位', '内部槽位', '槽位'].includes(normalized)) {
+    return 'content-slot';
+  }
+  return null;
+}
+
+function alignmentLevelLabel(level, locale = OPENPRD_FALLBACK_LOCALE) {
+  const copy = visualCopyForLocale(locale);
+  if (level === 'container') {
+    return copy.alignmentContainerLevel;
+  }
+  if (level === 'content-slot') {
+    return copy.alignmentContentSlotLevel;
+  }
+  return '';
+}
+
+function inferAlignmentLevel(text) {
+  const normalized = String(text ?? '').toLowerCase();
+  if (ALIGNMENT_CONTENT_SLOT_TOKENS.some((token) => normalized.includes(String(token).toLowerCase()))) {
+    return 'content-slot';
+  }
+  if (ALIGNMENT_CONTAINER_TOKENS.some((token) => normalized.includes(String(token).toLowerCase()))) {
+    return 'container';
+  }
+  return 'custom';
+}
+
+function summarizeAlignmentScope(groups) {
+  return {
+    containerGroups: groups.filter((group) => group.level === 'container').map((group) => group.label),
+    contentSlotGroups: groups.filter((group) => group.level === 'content-slot').map((group) => group.label),
+  };
+}
+
+function normalizeAlignmentMetrics(metrics, threshold, locale = OPENPRD_FALLBACK_LOCALE) {
+  const copy = visualCopyForLocale(locale);
+  if (!Array.isArray(metrics)) {
+    return normalizeMetricList(metrics, locale);
+  }
+  return metrics
+    .filter(Boolean)
+    .flatMap((metric) => {
+      if (typeof metric === 'string') {
+        return [{ label: copy.metricTextLabel, value: metric }];
+      }
+      const label = String(metric.label ?? metric.name ?? metric.key ?? copy.alignmentItemLabel);
+      const values = Array.isArray(metric.values)
+        ? metric.values.map((value) => Number(value)).filter((value) => Number.isFinite(value))
+        : [];
+      const metricThreshold = metric.thresholdPx ?? metric.threshold ?? threshold;
+      const spread = metric.spreadPx ?? metric.spread ?? (
+        values.length > 0 ? Math.max(...values) - Math.min(...values) : null
+      );
+      const parts = [];
+      if (values.length > 0) {
+        parts.push(`${values.join(', ')}px`);
+      } else if (metric.value !== null && metric.value !== undefined) {
+        parts.push(String(metric.value));
+      }
+      if (spread !== null && spread !== undefined && spread !== '') {
+        const verdict = metric.verdict ?? metric.status ?? (
+          Number(spread) <= Number(metricThreshold) ? copy.passVerdict : copy.reworkVerdict
+        );
+        parts.push(`spread=${spread}px`);
+        if (metricThreshold !== null && metricThreshold !== undefined && metricThreshold !== '') {
+          parts.push(`${copy.alignmentThresholdLabel}=${metricThreshold}px`);
+        }
+        parts.push(String(verdict));
+      }
+      return [{
+        label,
+        value: parts.filter(Boolean).join(' / '),
+      }];
+    })
+    .filter((metric) => metric.value.trim());
+}
+
+function normalizeAlignmentGuides(payload, locale = OPENPRD_FALLBACK_LOCALE) {
+  const copy = visualCopyForLocale(locale);
+  const rawGuides = Array.isArray(payload.guides)
+    ? payload.guides
+    : (Array.isArray(payload.lines) ? payload.lines : []);
+  return rawGuides
+    .filter(Boolean)
+    .map((guide, index) => ({
+      ...guide,
+      label: String(guide.label ?? guide.name ?? copy.alignmentGuideLabel(index)),
+      color: String(guide.color ?? FOCUS_COLORS[index % FOCUS_COLORS.length]),
+    }));
+}
+
+function normalizeAlignmentBoxes(payload, locale = OPENPRD_FALLBACK_LOCALE) {
+  const copy = visualCopyForLocale(locale);
+  const rawBoxes = Array.isArray(payload.boxes)
+    ? payload.boxes
+    : (Array.isArray(payload.regions) ? payload.regions : []);
+  return rawBoxes
+    .filter(Boolean)
+    .map((box, index) => ({
+      ...box,
+      label: String(box.label ?? box.name ?? copy.alignmentRegionLabel(index)),
+      color: String(box.color ?? FOCUS_COLORS[index % FOCUS_COLORS.length]),
+    }));
+}
+
+function resolveGuideAxis(guide) {
+  const raw = String(guide.axis ?? guide.orientation ?? '').trim().toLowerCase();
+  if (['x', 'vertical', 'v', 'left', 'right', 'column'].includes(raw)) {
+    return 'x';
+  }
+  if (['y', 'horizontal', 'h', 'top', 'bottom', 'row', 'baseline'].includes(raw)) {
+    return 'y';
+  }
+  if (guide.x !== null && guide.x !== undefined) {
+    return 'x';
+  }
+  return 'y';
+}
+
+function resolveGuidePosition(guide, axis, original) {
+  const raw = guide.position ?? guide.value ?? (axis === 'x' ? (guide.x ?? guide.left) : (guide.y ?? guide.top));
+  if (raw === null || raw === undefined || raw === '') {
+    throw new Error(`Alignment guide "${guide.label}" is missing position.`);
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw new Error(`Alignment guide "${guide.label}" has invalid position.`);
+  }
+  const max = axis === 'x' ? original.width : original.height;
+  const unit = String(guide.unit ?? 'px').trim().toLowerCase();
+  if (unit === 'ratio') {
+    return Math.round(value * max);
+  }
+  if (unit === 'percent') {
+    return Math.round((value / 100) * max);
+  }
+  return Math.round(value);
+}
+
+function alignmentGuideOverlaySvg(panel, payload, locale = OPENPRD_FALLBACK_LOCALE) {
+  const guides = normalizeAlignmentGuides(payload, locale);
+  const boxes = normalizeAlignmentBoxes(payload, locale);
+  const guideSvg = guides.map((guide, index) => {
+    const axis = resolveGuideAxis(guide);
+    const absolute = resolveGuidePosition(guide, axis, panel.original);
+    const color = escapeXml(guide.color);
+    const label = escapeXml(guide.label);
+    if (axis === 'x') {
+      const x = Math.round(absolute * (panel.width / panel.original.width));
+      const labelY = 28 + (index % 5) * 28;
+      return `
+        <line x1="${x}" y1="0" x2="${x}" y2="${panel.height}" stroke="${color}" stroke-width="2.5" stroke-dasharray="10 8"/>
+        <rect x="${Math.min(Math.max(x + 8, 8), Math.max(8, panel.width - 160))}" y="${labelY - 20}" width="148" height="24" rx="12" fill="#0f172a" fill-opacity="0.82"/>
+        <text x="${Math.min(Math.max(x + 18, 18), Math.max(18, panel.width - 150))}" y="${labelY - 4}" fill="${color}" font-size="14" font-weight="800" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${label}: x=${absolute}</text>
+      `;
+    }
+    const y = Math.round(absolute * (panel.height / panel.original.height));
+    const labelX = 14 + (index % 3) * 164;
+    return `
+      <line x1="0" y1="${y}" x2="${panel.width}" y2="${y}" stroke="${color}" stroke-width="2.5" stroke-dasharray="10 8"/>
+      <rect x="${labelX}" y="${Math.max(8, y - 30)}" width="154" height="24" rx="12" fill="#0f172a" fill-opacity="0.82"/>
+      <text x="${labelX + 10}" y="${Math.max(24, y - 14)}" fill="${color}" font-size="14" font-weight="800" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${label}: y=${absolute}</text>
+    `;
+  }).join('');
+  const boxSvg = boxes.map((box, index) => {
+    const resolved = resolveCropBox(box.box ?? box, panel.original);
+    const rendered = renderedBoxFromAbsolute(resolved.absolute, panel);
+    const color = escapeXml(box.color);
+    const label = escapeXml(box.label);
+    const badgeY = Math.max(10, rendered.y + 10);
+    const badgeX = Math.max(10, rendered.x + 10);
+    return `
+      <rect x="${rendered.x}" y="${rendered.y}" width="${rendered.width}" height="${rendered.height}" rx="12" fill="none" stroke="${color}" stroke-width="3"/>
+      <rect x="${badgeX}" y="${badgeY}" width="${Math.max(34, 24 + label.length * 14)}" height="28" rx="14" fill="${color}" fill-opacity="0.92"/>
+      <text x="${badgeX + 10}" y="${badgeY + 19}" fill="#0f172a" font-size="14" font-weight="800" font-family="PingFang SC, Noto Sans CJK SC, Microsoft YaHei, Arial Unicode MS, sans-serif">${index + 1}. ${label}</text>
+    `;
+  }).join('');
+  return Buffer.from(`
+<svg width="${panel.width}" height="${panel.height}" viewBox="0 0 ${panel.width} ${panel.height}" xmlns="http://www.w3.org/2000/svg">
+  <rect x="0" y="0" width="${panel.width}" height="${panel.height}" fill="#020617" fill-opacity="0.08"/>
+  ${guideSvg}
+  ${boxSvg}
+</svg>`);
+}
+
+async function createAlignmentOverlayPanel(basePanel, payload, locale = OPENPRD_FALLBACK_LOCALE) {
+  const overlay = alignmentGuideOverlaySvg(basePanel, payload, locale);
+  const input = await sharp(basePanel.input)
+    .composite([{ input: overlay, left: 0, top: 0 }])
+    .png()
+    .toBuffer();
+  return {
+    ...basePanel,
+    input,
+  };
+}
+
+async function renderAlignmentBoard(projectRoot, board, options = {}) {
+  const locale = localeFromOptions(options);
+  const copy = visualCopyForLocale(locale);
+  const format = normalizeFormat(options.format, options.out);
+  const outputPath = options.out
+    ? path.resolve(projectRoot, options.out)
+    : defaultOutputPath(projectRoot, format, 'alignment-board');
+  const quality = parseQuality(options.quality);
+  const maxPanelWidth = parsePositiveInteger(options.maxPanelWidth, DEFAULT_PANEL_WIDTH, '--max-panel-width');
+  const rawScreenshot = board.payload.screenshot ?? board.payload.actual ?? board.payload.path;
+  if (!rawScreenshot && !board.payload.overlay) {
+    throw new Error('Alignment board requires screenshot, actual, path, or overlay image.');
+  }
+  const screenshotSpec = normalizeImageSpec(
+    projectRoot,
+    rawScreenshot ?? board.payload.overlay,
+    board.payload.screenshotLabel ?? copy.alignmentScreenshotLabel,
+  );
+  const overlaySpec = board.payload.overlay
+    ? normalizeImageSpec(projectRoot, board.payload.overlay, board.payload.overlayLabel ?? copy.alignmentOverlayLabel)
+    : null;
+  const screenshotPanel = await resizePanel(screenshotSpec.path, maxPanelWidth);
+  const overlayPanel = overlaySpec
+    ? await resizePanel(overlaySpec.path, maxPanelWidth)
+    : await createAlignmentOverlayPanel(screenshotPanel, board.payload, locale);
+  const panelWidth = Math.min(maxPanelWidth, Math.max(screenshotPanel.width, overlayPanel.width));
+  const overviewHeight = Math.max(screenshotPanel.height, overlayPanel.height);
+  const margin = 24;
+  const gap = 24;
+  const groups = normalizeAlignmentGroups(board.payload, locale);
+  const cardWidth = parsePositiveInteger(board.payload.cardWidth ?? options.maxPanelWidth, DEFAULT_PARALLEL_CARD_WIDTH, 'cardWidth');
+  const columns = Math.max(1, Math.min(parsePositiveInteger(board.payload.columns, Math.min(DEFAULT_PARALLEL_COLUMNS, Math.max(groups.length, 1)), 'columns'), 4));
+  const contentWidth = Math.max(margin * 2 + panelWidth * 2 + gap, margin * 2 + columns * cardWidth + (columns - 1) * gap);
+  const summary = String(board.payload.summary ?? copy.alignmentSummary);
+  const titleBlock = titleBlockSvg(
+    contentWidth - margin * 2,
+    String(board.payload.title ?? copy.alignmentTitle),
+    summary,
+    copy.alignmentEyebrow,
+  );
+  const screenshotX = margin + Math.round((panelWidth - screenshotPanel.width) / 2);
+  const overlayX = margin + panelWidth + gap + Math.round((panelWidth - overlayPanel.width) / 2);
+  const overviewTop = margin + titleBlock.height + 18;
+  const screenshotY = overviewTop + Math.round((overviewHeight - screenshotPanel.height) / 2);
+  const overlayY = overviewTop + Math.round((overviewHeight - overlayPanel.height) / 2);
+  const composites = [
+    { input: titleBlock.input, left: margin, top: margin },
+    { input: screenshotPanel.input, left: screenshotX, top: screenshotY },
+    { input: overlayPanel.input, left: overlayX, top: overlayY },
+    { input: labelSvg(screenshotSpec.label, { maxWidth: Math.max(32, screenshotPanel.width - 32) }), left: screenshotX + 16, top: screenshotY + 16 },
+    { input: labelSvg(overlaySpec?.label ?? copy.alignmentOverlayLabel, { maxWidth: Math.max(32, overlayPanel.width - 32) }), left: overlayX + 16, top: overlayY + 16 },
+  ];
+  const renderedCards = [];
+  for (const [index, group] of groups.entries()) {
+    renderedCards.push(await renderParallelCard(projectRoot, group, index, {
+      cardWidth,
+      eyebrow: copy.alignmentMeasureEyebrow,
+      locale,
+    }));
+  }
+  const rowHeights = [];
+  for (let index = 0; index < renderedCards.length; index += columns) {
+    rowHeights.push(Math.max(...renderedCards.slice(index, index + columns).map((card) => card.height)));
+  }
+  let currentTop = overviewTop + overviewHeight + 28;
+  for (let row = 0; row < rowHeights.length; row += 1) {
+    const rowCards = renderedCards.slice(row * columns, row * columns + columns);
+    for (const [column, card] of rowCards.entries()) {
+      composites.push({
+        input: card.image,
+        left: margin + column * (cardWidth + gap),
+        top: currentTop,
+      });
+    }
+    currentTop += rowHeights[row] + gap;
+  }
+  const canvasHeight = currentTop + margin - (rowHeights.length > 0 ? gap : 0);
+  const canvas = sharp({
+    create: {
+      width: contentWidth,
+      height: canvasHeight,
+      channels: 3,
+      background: '#111827',
+    },
+  }).composite(composites);
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await encodePipeline(canvas, format, quality).toFile(outputPath);
+  const metadataPath = metadataPathForOutput(outputPath);
+  const reviewArtifact = {
+    version: 1,
+    schema: VISUAL_REVIEW_SCHEMA,
+    generatedAt: timestamp(),
+    mode: 'alignment-board',
+    locale,
+    outputPath: toWorkspacePath(projectRoot, outputPath),
+    format,
+    boardSource: toWorkspacePath(projectRoot, board.sourcePath),
+    title: String(board.payload.title ?? copy.alignmentTitle),
+    alignmentScope: summarizeAlignmentScope(renderedCards.map((card) => card.item)),
+    labels: {
+      screenshot: screenshotSpec.label,
+      overlay: overlaySpec?.label ?? copy.alignmentOverlayLabel,
+    },
+    screenshot: {
+      path: toWorkspacePath(projectRoot, screenshotPanel.source),
+      original: screenshotPanel.original,
+      rendered: {
+        width: screenshotPanel.width,
+        height: screenshotPanel.height,
+      },
+    },
+    overlay: overlaySpec ? {
+      path: toWorkspacePath(projectRoot, overlayPanel.source),
+      original: overlayPanel.original,
+      rendered: {
+        width: overlayPanel.width,
+        height: overlayPanel.height,
+      },
+    } : {
+      generatedFrom: toWorkspacePath(projectRoot, screenshotPanel.source),
+      guides: normalizeAlignmentGuides(board.payload, locale),
+      boxes: normalizeAlignmentBoxes(board.payload, locale),
+    },
+    groups: renderedCards.map((card) => card.item),
+    canvas: {
+      width: contentWidth,
+      height: canvasHeight,
+    },
+  };
+  await fs.writeFile(metadataPath, `${JSON.stringify(reviewArtifact, null, 2)}\n`, 'utf8');
+
+  return {
+    ok: true,
+    action: 'visual-compare',
+    mode: 'alignment-board',
+    projectRoot,
+    outputPath,
+    metadataPath,
+    format,
+    quality: format === 'png' ? null : quality,
+    canvas: reviewArtifact.canvas,
+    reviewArtifact,
+    groups: reviewArtifact.groups,
+    nextActions: copy.alignmentNextActions,
+  };
+}
+
+const CHAT_EMBED_MODE_LABELS = {
+  'before-after': '修改前后对比',
+  'reference-actual': '效果图对比',
+  'focus-board': '局部焦点证据板',
+  'parallel-board': '并行实验证据板',
+  'verification-board': '截图实测证据板',
+  'alignment-board': '网格对齐证据板',
+  'centering-board': '内部居中证据板',
+};
+
+function attachChatEmbed(result) {
+  if (!result?.outputPath) {
+    return result;
+  }
+  const label = CHAT_EMBED_MODE_LABELS[result.mode] ?? '视觉证据板';
+  result.chatEmbed = {
+    label,
+    markdown: `![视觉证据: ${label}](${result.outputPath})`,
+    hint: '把这行 markdown 直接贴进最终回复，让证据板在对话流里可见；不要只报告文件路径。',
+  };
+  result.nextActions = [
+    ...(result.nextActions ?? []),
+    `用 ${result.chatEmbed.markdown} 把证据板嵌入对话流展示，再基于图上标注说明气质、层级与对齐结论。`,
+  ];
+  return result;
+}
+
 async function visualCompareWorkspace(projectRoot, options = {}) {
   const request = resolveComparisonInputs(options);
   if (request.mode === 'board') {
     const board = await readBoardSpec(projectRoot, request.board);
+    const locale = resolveBoardLocale(options, board.payload);
+    validateBoardVisibleLanguage(board, locale);
+    const renderOptions = { ...options, locale };
     if (board.mode === 'focus-board') {
-      return renderFocusBoard(projectRoot, board, options);
+      return attachChatEmbed(await renderFocusBoard(projectRoot, board, renderOptions));
     }
     if (board.mode === 'parallel-board') {
-      return renderParallelBoard(projectRoot, board, options);
+      return attachChatEmbed(await renderParallelBoard(projectRoot, board, renderOptions));
+    }
+    if (board.mode === 'verification-board') {
+      return attachChatEmbed(await renderVerificationBoard(projectRoot, board, renderOptions));
+    }
+    if (board.mode === 'alignment-board') {
+      return attachChatEmbed(await renderAlignmentBoard(projectRoot, board, renderOptions));
+    }
+    if (board.mode === 'centering-board') {
+      return attachChatEmbed(await renderCenteringBoard(projectRoot, board, renderOptions));
     }
     throw new Error(`Unsupported board mode: ${board.mode}`);
   }
-  return renderStandardComparison(projectRoot, request, options);
+  return attachChatEmbed(await renderStandardComparison(projectRoot, request, options));
 }
 
 export { visualCompareWorkspace };