@surlymochan/evalid 0.0.0-stage → 0.4.1

package/src/agent_team/atoms/visual/design-selection.js

@@ -0,0 +1,23 @@
+import { synthesizePhaseArtifact } from '../../common.js';
+import { readJsonFile, resolveChangePath } from '../../../core/change-artifacts.js';
+
+export async function visualDesignSelection(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  const synthesis = readJsonFile(resolveChangePath(projectRoot, changeId, 'visual_direction_synthesis.json'), {}) || {};
+  const visualDirection = synthesis.visual_direction_synthesis || {};
+  const directions = Array.isArray(visualDirection.directions) ? visualDirection.directions : [];
+  const selected = directions.find((direction) => direction.id === visualDirection.recommended_direction) || directions[0] || null;
+  return synthesizePhaseArtifact(input, context, {
+    phase: 'design_selection',
+    summary: 'A winning high-aesthetic direction and fallback candidate were selected.',
+    extraEnvelope: {
+      design_selection: {
+        status: selected ? 'selected' : 'needs_input',
+        selected_direction: selected,
+        fallback_direction: directions.find((direction) => direction.id !== selected?.id) || null,
+        selection_rule: 'Prefer reference-faithful product credibility before decorative novelty.',
+      },
+    },
+  });
+}

package/src/agent_team/atoms/visual/direction-synthesis.js

@@ -0,0 +1,124 @@
+import { synthesizePhaseArtifact } from '../../common.js';
+import { readJsonFile, resolveChangePath, writeJsonFile, writeTextFile } from '../../../core/change-artifacts.js';
+
+function buildDirection(id, label, emphasis, aestheticStandard = {}, imageReference = {}, designSystemPack = {}) {
+  const practiceSources = Array.isArray(designSystemPack.practice_sources)
+    ? designSystemPack.practice_sources.map((source) => source.id).filter(Boolean)
+    : [];
+  return {
+    id,
+    label,
+    emphasis,
+    aesthetic_dimensions: aestheticStandard.dimensions || [],
+    design_system_practices: practiceSources,
+    image_reference_brief: imageReference.enabled === false ? null : {
+      model_capability: imageReference.model_capability || 'gpt_image_v2_style_reference',
+      prompt_focus: [
+        `Create a high-aesthetic ${label.toLowerCase()} product UI reference frame.`,
+        `Emphasize ${emphasis}.`,
+        'Preserve the locked surface decomposition, hierarchy, and product credibility.',
+        `Honor the design-system pack profile: ${designSystemPack.profile || 'commercial_product_design_system_pack'}.`,
+        'Output should guide editable UI primitives, not replace implementation.',
+      ],
+    },
+  };
+}
+
+function materializeImageReferenceSet(projectRoot, changeId, imageReference = {}, directions = [], designSystemPack = {}) {
+  if (imageReference.enabled === false) return null;
+
+  const requiredOutputs = Array.isArray(imageReference.required_outputs)
+    ? imageReference.required_outputs
+    : [];
+  const references = requiredOutputs.map((output, index) => {
+    const direction = directions[index % Math.max(directions.length, 1)] || directions[0] || {};
+    const artifactPath = resolveChangePath(projectRoot, changeId, `image-references/${output.id}.md`);
+    const lines = [
+      `# ${output.id}`,
+      '',
+      `model_capability: ${imageReference.model_capability || 'gpt_image_v2_style_reference'}`,
+      `purpose: ${output.purpose || ''}`,
+      `direction: ${direction.label || 'Reference-faithful'}`,
+      `design_system_profile: ${designSystemPack.profile || 'commercial_product_design_system_pack'}`,
+      '',
+      '## Prompt',
+      '',
+      ...(direction.image_reference_brief?.prompt_focus || [
+        'Create a high-aesthetic product UI reference artifact from the frozen generation contract.',
+        'Keep the result translatable into editable Pencil and DOM primitives.',
+      ]).map((line) => `- ${line}`),
+      '',
+      '## Translation Contract',
+      '',
+      '- Use this as an aesthetic reference target, not as the shipped implementation.',
+      '- Preserve the design-system component whitelist, token policy, and required state set.',
+      '- Preserve editable UI primitives and benchmarkable DOM/canvas evidence downstream.',
+    ];
+    writeTextFile(artifactPath, lines.join('\n'));
+    return {
+      id: output.id,
+      status: 'ready',
+      kind: 'image_reference_brief',
+      model_capability: imageReference.model_capability || 'gpt_image_v2_style_reference',
+      artifact_path: `specs/changes/${changeId}/image-references/${output.id}.md`,
+      purpose: output.purpose || null,
+    };
+  });
+
+  const payload = {
+    version: 1,
+    phase: 'image_reference_generation',
+    change_id: changeId,
+    status: references.length >= 3 ? 'ready' : 'needs_refine',
+    model_capability: imageReference.model_capability || 'gpt_image_v2_style_reference',
+    references,
+    translation_contract: {
+      editable_target: 'Pencil and DOM primitives',
+      bitmap_non_goal: true,
+      benchmark_required: true,
+    },
+  };
+  writeJsonFile(resolveChangePath(projectRoot, changeId, 'image_reference_set.json'), payload);
+  return payload;
+}
+
+export async function visualDirectionSynthesis(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  const generation = readJsonFile(resolveChangePath(projectRoot, changeId, 'generation_contract.json'), {})?.generation_contract || {};
+  const designSystemPack = readJsonFile(resolveChangePath(projectRoot, changeId, 'design_system_pack.json'), {}) || {};
+  const visualConstraints = generation.visual_constraints || {};
+  const aestheticStandard = visualConstraints.aesthetic_standard || {};
+  const imageReference = visualConstraints.image_reference_generation || {};
+  const directions = [
+    buildDirection('reference-faithful', 'Reference-faithful', 'reference structure, density, and material restraint', aestheticStandard, imageReference, designSystemPack),
+    buildDirection('clarity-first', 'Clarity-first', 'information hierarchy and repeated-component rhythm', aestheticStandard, imageReference, designSystemPack),
+    buildDirection('state-polish', 'State-polish', 'interaction states, affordance contrast, and motion readiness', aestheticStandard, imageReference, designSystemPack),
+  ];
+  const imageReferenceSet = materializeImageReferenceSet(projectRoot, changeId, imageReference, directions, designSystemPack);
+  return synthesizePhaseArtifact(input, context, {
+    phase: 'visual_direction_synthesis',
+    summary: 'Multiple high-aesthetic visual directions were synthesized with image-reference prompts and product-surface constraints.',
+    extraEnvelope: {
+      visual_direction_synthesis: {
+        status: 'ready',
+        aesthetic_standard: aestheticStandard,
+        image_reference_generation: imageReference,
+        design_system_pack: {
+          status: designSystemPack.status || 'missing',
+          profile: designSystemPack.profile || null,
+          practice_sources: (designSystemPack.practice_sources || []).map((source) => source.id),
+        },
+        image_reference_set: imageReferenceSet
+          ? {
+            status: imageReferenceSet.status,
+            artifact: 'image_reference_set.json',
+            reference_count: imageReferenceSet.references.length,
+          }
+          : null,
+        directions,
+        recommended_direction: directions[0].id,
+      },
+    },
+  });
+}

package/src/agent_team/atoms/visual/dom-rect-export.js

@@ -0,0 +1,129 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+function normalizeAttributes(node = {}, panelAttr = 'data-panel') {
+  if (node.attributes && typeof node.attributes === 'object' && !Array.isArray(node.attributes)) {
+    return node.attributes;
+  }
+  if (node.attrs && typeof node.attrs === 'object' && !Array.isArray(node.attrs)) {
+    return node.attrs;
+  }
+  if (Array.isArray(node.attributes)) {
+    return Object.fromEntries(node.attributes
+      .map((entry) => Array.isArray(entry) ? entry : [entry?.name, entry?.value])
+      .filter(([name]) => typeof name === 'string'));
+  }
+  if (Array.isArray(node.attribute_list)) {
+    return Object.fromEntries(node.attribute_list
+      .map((entry) => [entry?.name, entry?.value])
+      .filter(([name]) => typeof name === 'string'));
+  }
+  if (node.dataset && typeof node.dataset === 'object' && !Array.isArray(node.dataset)) {
+    const datasetEntries = Object.entries(node.dataset).map(([key, value]) => [`data-${key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`)}`, value]);
+    return Object.fromEntries(datasetEntries);
+  }
+  return panelAttr in node ? { [panelAttr]: node[panelAttr] } : {};
+}
+
+function resolvePanelId(node = {}, panelAttr = 'data-panel') {
+  if (typeof node.panel_id === 'string' && node.panel_id.trim()) return node.panel_id.trim();
+  const attributes = normalizeAttributes(node, panelAttr);
+  if (typeof attributes[panelAttr] === 'string' && attributes[panelAttr].trim()) return attributes[panelAttr].trim();
+  if (typeof node.id === 'string' && node.id.trim()) return node.id.trim();
+  return null;
+}
+
+function normalizeRect(node = {}) {
+  if (node.boundingClientRect && typeof node.boundingClientRect === 'object') {
+    const rect = node.boundingClientRect;
+    if (Number.isFinite(rect.left) && Number.isFinite(rect.top) && Number.isFinite(rect.width) && Number.isFinite(rect.height)) {
+      return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    }
+  }
+  if (node.rect && typeof node.rect === 'object') {
+    const rect = node.rect;
+    if (Number.isFinite(rect.left) && Number.isFinite(rect.top) && Number.isFinite(rect.width) && Number.isFinite(rect.height)) {
+      return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    }
+  }
+  if (node.box && typeof node.box === 'object') {
+    const box = node.box;
+    if (Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height)) {
+      return { left: box.x, top: box.y, width: box.width, height: box.height };
+    }
+  }
+  if (Number.isFinite(node.left) && Number.isFinite(node.top) && Number.isFinite(node.width) && Number.isFinite(node.height)) {
+    return { left: node.left, top: node.top, width: node.width, height: node.height };
+  }
+  return null;
+}
+
+function pickNodes(snapshot) {
+  if (Array.isArray(snapshot)) return snapshot;
+  const collected = [];
+  if (Array.isArray(snapshot?.nodes)) collected.push(...snapshot.nodes);
+  if (Array.isArray(snapshot?.states)) {
+    for (const state of snapshot.states) {
+      if (Array.isArray(state?.nodes)) collected.push(...state.nodes);
+    }
+  }
+  if (collected.length > 0) return collected;
+  if (Array.isArray(snapshot?.dom_snapshot?.nodes)) return snapshot.dom_snapshot.nodes;
+  if (Array.isArray(snapshot?.snapshot?.nodes)) return snapshot.snapshot.nodes;
+  return [];
+}
+
+export function exportDomRectsFromSnapshot(snapshot, options = {}) {
+  const panelAttr = options.panelAttr || 'data-panel';
+  const nodes = pickNodes(snapshot);
+  const byPanelId = new Map();
+
+  for (const node of nodes) {
+    const panelId = resolvePanelId(node, panelAttr);
+    const rect = normalizeRect(node);
+    if (!panelId || !rect) continue;
+    if (!(rect.width > 0 && rect.height > 0)) continue;
+    const area = rect.width * rect.height;
+    const selector = typeof node.selector === 'string' ? node.selector : null;
+    const candidate = {
+      panel_id: panelId,
+      selector,
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height,
+      _area: area,
+    };
+    const current = byPanelId.get(panelId);
+    if (!current || candidate._area > current._area) {
+      byPanelId.set(panelId, candidate);
+    }
+  }
+
+  const domRects = Array.from(byPanelId.values())
+    .sort((left, right) => {
+      if (left.left !== right.left) return left.left - right.left;
+      if (left.top !== right.top) return left.top - right.top;
+      return left.panel_id.localeCompare(right.panel_id);
+    })
+    .map(({ _area, ...entry }) => entry);
+
+  return {
+    dom_rects: domRects,
+    panel_attr: panelAttr,
+    input_nodes: nodes.length,
+    extracted_panels: domRects.length,
+  };
+}
+
+export function exportDomRectsToFile({ inputPath, outputPath, panelAttr = 'data-panel' }) {
+  const snapshot = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const payload = exportDomRectsFromSnapshot(snapshot, { panelAttr });
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, JSON.stringify(payload, null, 2));
+  return payload;
+}
+
+export function resolveCliPath(projectRoot, maybeRelativePath) {
+  return resolve(projectRoot, maybeRelativePath);
+}

package/src/agent_team/atoms/visual/image-diff.js

@@ -0,0 +1,186 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname } from 'node:path';
+
+import { loadPlaywright } from './playwright-runtime.js';
+
+function toNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function fileToDataUrl(filePath) {
+  const extension = extname(filePath).toLowerCase();
+  const mimeType = extension === '.svg'
+    ? 'image/svg+xml'
+    : extension === '.png'
+      ? 'image/png'
+      : extension === '.jpg' || extension === '.jpeg'
+        ? 'image/jpeg'
+        : extension === '.webp'
+          ? 'image/webp'
+          : 'application/octet-stream';
+  const encoded = readFileSync(filePath).toString('base64');
+  return `data:${mimeType};base64,${encoded}`;
+}
+
+export async function computeImageDiffMetrics({
+  referencePath,
+  candidatePath,
+  pixelThreshold = 16,
+  blockRows = 12,
+  blockCols = 12,
+  heatmapOutputPath = null,
+}) {
+  if (!referencePath) throw new Error('referencePath is required for computeImageDiffMetrics');
+  if (!candidatePath) throw new Error('candidatePath is required for computeImageDiffMetrics');
+
+  const playwright = await loadPlaywright();
+  const browser = await playwright.chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage({ viewport: { width: 64, height: 64 } });
+    await page.setContent('<html><body></body></html>');
+    const metrics = await page.evaluate(async ({ referenceUrl, candidateUrl, pixelThresholdValue, blockRowsValue, blockColsValue }) => {
+      const loadImage = (src) => new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve(image);
+        image.onerror = () => reject(new Error(`Failed to load image: ${src}`));
+        image.src = src;
+      });
+
+      const [referenceImage, candidateImage] = await Promise.all([
+        loadImage(referenceUrl),
+        loadImage(candidateUrl),
+      ]);
+
+      const width = Math.max(referenceImage.naturalWidth, candidateImage.naturalWidth);
+      const height = Math.max(referenceImage.naturalHeight, candidateImage.naturalHeight);
+      const makeImageData = (image) => {
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const context = canvas.getContext('2d');
+        context.clearRect(0, 0, width, height);
+        context.drawImage(image, 0, 0);
+        return context.getImageData(0, 0, width, height).data;
+      };
+
+      const referenceData = makeImageData(referenceImage);
+      const candidateData = makeImageData(candidateImage);
+      const totalPixels = width * height;
+      const blockChanged = new Array(blockRowsValue * blockColsValue).fill(false);
+      const blockChangeCounts = new Array(blockRowsValue * blockColsValue).fill(0);
+      let changedPixels = 0;
+      let luminanceSquaredError = 0;
+
+      for (let pixelIndex = 0; pixelIndex < totalPixels; pixelIndex += 1) {
+        const base = pixelIndex * 4;
+        const redDiff = Math.abs(referenceData[base] - candidateData[base]);
+        const greenDiff = Math.abs(referenceData[base + 1] - candidateData[base + 1]);
+        const blueDiff = Math.abs(referenceData[base + 2] - candidateData[base + 2]);
+        const alphaDiff = Math.abs(referenceData[base + 3] - candidateData[base + 3]);
+        const maxChannelDiff = Math.max(redDiff, greenDiff, blueDiff, alphaDiff);
+        if (maxChannelDiff > pixelThresholdValue) {
+          changedPixels += 1;
+          const x = pixelIndex % width;
+          const y = Math.floor(pixelIndex / width);
+          const blockX = Math.min(blockColsValue - 1, Math.floor((x / Math.max(width, 1)) * blockColsValue));
+          const blockY = Math.min(blockRowsValue - 1, Math.floor((y / Math.max(height, 1)) * blockRowsValue));
+          const blockIndex = (blockY * blockColsValue) + blockX;
+          blockChanged[blockIndex] = true;
+          blockChangeCounts[blockIndex] += 1;
+        }
+
+        const referenceLuminance = (0.2126 * referenceData[base]) + (0.7152 * referenceData[base + 1]) + (0.0722 * referenceData[base + 2]);
+        const candidateLuminance = (0.2126 * candidateData[base]) + (0.7152 * candidateData[base + 1]) + (0.0722 * candidateData[base + 2]);
+        const luminanceDiff = referenceLuminance - candidateLuminance;
+        luminanceSquaredError += luminanceDiff * luminanceDiff;
+      }
+
+      const changedBlocks = blockChanged.filter(Boolean).length;
+      const pixelDiffRatio = totalPixels > 0 ? changedPixels / totalPixels : 0;
+      const layoutShiftScore = blockChanged.length > 0 ? changedBlocks / blockChanged.length : 0;
+      const rmse = totalPixels > 0 ? Math.sqrt(luminanceSquaredError / totalPixels) / 255 : 0;
+      const structuralSimilarity = Math.max(0, 1 - rmse);
+      const hotspots = blockChangeCounts
+        .map((changedCount, index) => {
+          const row = Math.floor(index / blockColsValue);
+          const col = index % blockColsValue;
+          const blockWidth = width / blockColsValue;
+          const blockHeight = height / blockRowsValue;
+          return {
+            row,
+            col,
+            changed_pixels: changedCount,
+            changed_ratio: totalPixels > 0 ? changedCount / totalPixels : 0,
+            x: Math.round(col * blockWidth),
+            y: Math.round(row * blockHeight),
+            width: Math.round(blockWidth),
+            height: Math.round(blockHeight),
+          };
+        })
+        .filter((entry) => entry.changed_pixels > 0)
+        .sort((left, right) => right.changed_pixels - left.changed_pixels)
+        .slice(0, 8);
+
+      const heatmapCanvas = document.createElement('canvas');
+      heatmapCanvas.width = width;
+      heatmapCanvas.height = height;
+      const heatmapContext = heatmapCanvas.getContext('2d');
+      heatmapContext.clearRect(0, 0, width, height);
+      heatmapContext.drawImage(candidateImage, 0, 0);
+      const maxChangedCount = Math.max(...blockChangeCounts, 0);
+      for (let row = 0; row < blockRowsValue; row += 1) {
+        for (let col = 0; col < blockColsValue; col += 1) {
+          const index = (row * blockColsValue) + col;
+          const changedCount = blockChangeCounts[index];
+          if (changedCount <= 0 || maxChangedCount <= 0) continue;
+          const intensity = changedCount / maxChangedCount;
+          const x = (col / blockColsValue) * width;
+          const y = (row / blockRowsValue) * height;
+          const blockWidth = width / blockColsValue;
+          const blockHeight = height / blockRowsValue;
+          heatmapContext.fillStyle = `rgba(255, 0, 0, ${Math.max(0.12, intensity * 0.65)})`;
+          heatmapContext.fillRect(x, y, blockWidth, blockHeight);
+          heatmapContext.strokeStyle = 'rgba(255,255,255,0.2)';
+          heatmapContext.lineWidth = 1;
+          heatmapContext.strokeRect(x, y, blockWidth, blockHeight);
+        }
+      }
+      const heatmapDataUrl = heatmapCanvas.toDataURL('image/png');
+
+      return {
+        width,
+        height,
+        changed_pixels: changedPixels,
+        total_pixels: totalPixels,
+        changed_blocks: changedBlocks,
+        total_blocks: blockChanged.length,
+        pixel_diff_ratio: pixelDiffRatio,
+        layout_shift_score: layoutShiftScore,
+        structural_similarity: structuralSimilarity,
+        hotspots,
+        heatmap_png_base64: heatmapDataUrl.replace(/^data:image\/png;base64,/, ''),
+      };
+    }, {
+      referenceUrl: fileToDataUrl(referencePath),
+      candidateUrl: fileToDataUrl(candidatePath),
+      pixelThresholdValue: toNumber(pixelThreshold, 16),
+      blockRowsValue: toNumber(blockRows, 12),
+      blockColsValue: toNumber(blockCols, 12),
+    });
+
+    const result = {
+      ...metrics,
+      heatmap_file: null,
+    };
+    if (heatmapOutputPath && typeof heatmapOutputPath === 'string') {
+      mkdirSync(dirname(heatmapOutputPath), { recursive: true });
+      writeFileSync(heatmapOutputPath, Buffer.from(metrics.heatmap_png_base64, 'base64'));
+      result.heatmap_file = heatmapOutputPath;
+    }
+    delete result.heatmap_png_base64;
+    return result;
+  } finally {
+    await browser.close();
+  }
+}

package/src/agent_team/atoms/visual/layout-competition.js

@@ -0,0 +1,8 @@
+import { synthesizePhaseArtifact } from '../../common.js';
+
+export async function visualLayoutCompetition(input = {}, context = {}) {
+  return synthesizePhaseArtifact(input, context, {
+    phase: 'layout_competition',
+    summary: 'Competing first-fold layout directions were compared and ranked.',
+  });
+}