developer-agent-skills 1.0.0

package/skills/ui-visual-feedback-loop/scripts/compare.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const sharp = require('sharp');
+const pixelmatch = require('pixelmatch');
+const { PNG } = require('pngjs');
+
+function arg(name, fallback = undefined) {
+  const idx = process.argv.indexOf(name);
+  return idx >= 0 ? process.argv[idx + 1] : fallback;
+}
+
+async function normalizeToSameCanvas(referencePath, candidatePath) {
+  const [rMeta, cMeta] = await Promise.all([
+    sharp(referencePath).metadata(),
+    sharp(candidatePath).metadata(),
+  ]);
+
+  const width = Math.max(rMeta.width || 0, cMeta.width || 0);
+  const height = Math.max(rMeta.height || 0, cMeta.height || 0);
+
+  async function loadRGBA(file) {
+    return sharp(file)
+      .resize({ width, height, fit: 'contain', background: { r: 255, g: 255, b: 255, alpha: 1 } })
+      .png()
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+  }
+
+  const [ref, cand] = await Promise.all([loadRGBA(referencePath), loadRGBA(candidatePath)]);
+  return { width, height, ref: ref.data, cand: cand.data };
+}
+
+function channelAverage(buf, offset) {
+  let sum = 0;
+  for (let i = offset; i < buf.length; i += 4) sum += buf[i];
+  return sum / (buf.length / 4);
+}
+
+function edgeWeightedMismatch(ref, cand, width, height) {
+  let sum = 0;
+  let count = 0;
+  for (let y = 1; y < height - 1; y++) {
+    for (let x = 1; x < width - 1; x++) {
+      const i = (y * width + x) * 4;
+      const left = i - 4;
+      const right = i + 4;
+      const up = i - width * 4;
+      const down = i + width * 4;
+      const edgeRef =
+        Math.abs(ref[left] - ref[right]) +
+        Math.abs(ref[up] - ref[down]) +
+        Math.abs(ref[left + 1] - ref[right + 1]) +
+        Math.abs(ref[up + 1] - ref[down + 1]) +
+        Math.abs(ref[left + 2] - ref[right + 2]) +
+        Math.abs(ref[up + 2] - ref[down + 2]);
+      const pixDiff =
+        Math.abs(ref[i] - cand[i]) +
+        Math.abs(ref[i + 1] - cand[i + 1]) +
+        Math.abs(ref[i + 2] - cand[i + 2]);
+      if (edgeRef > 60) {
+        sum += pixDiff;
+        count++;
+      }
+    }
+  }
+  return count ? sum / count : 0;
+}
+
+(async () => {
+  const reference = arg('--reference');
+  const candidate = arg('--candidate');
+  const diffOut = arg('--diff', 'artifacts/diff.png');
+  const jsonOut = arg('--json', 'artifacts/report.json');
+
+  if (!reference || !candidate) {
+    console.error('Missing --reference or --candidate');
+    process.exit(1);
+  }
+
+  const { width, height, ref, cand } = await normalizeToSameCanvas(reference, candidate);
+
+  const refPng = new PNG({ width, height });
+  const candPng = new PNG({ width, height });
+  ref.copy(refPng.data);
+  cand.copy(candPng.data);
+
+  const diff = new PNG({ width, height });
+  const mismatchPixels = pixelmatch(refPng.data, candPng.data, diff.data, width, height, {
+    threshold: 0.12,
+    includeAA: true,
+    alpha: 0.6,
+  });
+
+  fs.mkdirSync(path.dirname(diffOut), { recursive: true });
+  fs.mkdirSync(path.dirname(jsonOut), { recursive: true });
+  fs.writeFileSync(diffOut, PNG.sync.write(diff));
+
+  const totalPixels = width * height;
+  const mismatchPercent = Number(((mismatchPixels / totalPixels) * 100).toFixed(2));
+
+  const refBrightness = (channelAverage(ref, 0) + channelAverage(ref, 1) + channelAverage(ref, 2)) / 3;
+  const candBrightness = (channelAverage(cand, 0) + channelAverage(cand, 1) + channelAverage(cand, 2)) / 3;
+  const brightnessDelta = Number((candBrightness - refBrightness).toFixed(2));
+
+  const edgeDelta = Number(edgeWeightedMismatch(ref, cand, width, height).toFixed(2));
+
+  const findings = [];
+  if (mismatchPercent > 10) findings.push({ severity: 'high', message: 'Large structural mismatch. Major layout regions likely differ or important elements are missing.' });
+  else if (mismatchPercent > 4) findings.push({ severity: 'medium', message: 'Noticeable visual mismatch. Layout, spacing, or component sizing still needs refinement.' });
+  else if (mismatchPercent > 1.5) findings.push({ severity: 'low', message: 'Only minor differences remain. Focus on spacing, typography, and small visual polish.' });
+  else findings.push({ severity: 'info', message: 'Visual mismatch is small.' });
+
+  if (brightnessDelta > 8) findings.push({ severity: 'medium', message: 'Candidate appears brighter than the reference. Inspect background, surfaces, and text contrast.' });
+  if (brightnessDelta < -8) findings.push({ severity: 'medium', message: 'Candidate appears darker than the reference. Inspect overlays, text color, and surface colors.' });
+  if (edgeDelta > 80) findings.push({ severity: 'medium', message: 'Strong edge mismatch suggests alignment, spacing, or typography differences around boundaries.' });
+
+  const report = {
+    summary: {
+      width,
+      height,
+      mismatchPixels,
+      totalPixels,
+      mismatchPercent,
+      brightnessDelta,
+      edgeDelta,
+    },
+    findings,
+    nextActions: [
+      'Check container widths, grid columns, and horizontal alignment first.',
+      'Then inspect vertical spacing, font sizes, and line-height.',
+      'Finally tune colors, border radius, shadows, and fine detail.'
+    ]
+  };
+
+  fs.writeFileSync(jsonOut, JSON.stringify(report, null, 2));
+  console.log(JSON.stringify(report, null, 2));
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/skills/ui-visual-feedback-loop/scripts/ui_loop.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REFERENCE=""
+URL="http://127.0.0.1:3000"
+START_CMD=""
+MAX_LOOPS=5
+ARTIFACTS_DIR="artifacts"
+WAIT_MS=1500
+VIEWPORT_WIDTH=""
+VIEWPORT_HEIGHT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --reference)
+      REFERENCE="$2"; shift 2 ;;
+    --url)
+      URL="$2"; shift 2 ;;
+    --start)
+      START_CMD="$2"; shift 2 ;;
+    --max-loops)
+      MAX_LOOPS="$2"; shift 2 ;;
+    --artifacts-dir)
+      ARTIFACTS_DIR="$2"; shift 2 ;;
+    --wait-ms)
+      WAIT_MS="$2"; shift 2 ;;
+    --viewport-width)
+      VIEWPORT_WIDTH="$2"; shift 2 ;;
+    --viewport-height)
+      VIEWPORT_HEIGHT="$2"; shift 2 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1 ;;
+  esac
+done
+
+if [[ -z "$REFERENCE" ]]; then
+  echo "Missing --reference path/to/reference.png" >&2
+  exit 1
+fi
+
+mkdir -p "$ARTIFACTS_DIR"
+LOG_FILE="$ARTIFACTS_DIR/iteration-log.md"
+: > "$LOG_FILE"
+
+cleanup() {
+  if [[ -n "${SERVER_PID:-}" ]]; then
+    kill "$SERVER_PID" >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
+
+if [[ -n "$START_CMD" ]]; then
+  bash -lc "$START_CMD" > "$ARTIFACTS_DIR/devserver.log" 2>&1 &
+  SERVER_PID=$!
+  echo "Started app server with PID $SERVER_PID"
+  sleep 3
+fi
+
+BEST_MISMATCH=""
+for ((i=1; i<=MAX_LOOPS; i++)); do
+  echo "# Iteration $i" >> "$LOG_FILE"
+  CAPTURE_ARGS=(node scripts/capture.js --url "$URL" --out "$ARTIFACTS_DIR/latest.png" --wait-ms "$WAIT_MS")
+  if [[ -n "$VIEWPORT_WIDTH" ]]; then
+    CAPTURE_ARGS+=(--viewport-width "$VIEWPORT_WIDTH")
+  fi
+  if [[ -n "$VIEWPORT_HEIGHT" ]]; then
+    CAPTURE_ARGS+=(--viewport-height "$VIEWPORT_HEIGHT")
+  fi
+  "${CAPTURE_ARGS[@]}"
+
+  node scripts/compare.js \
+    --reference "$REFERENCE" \
+    --candidate "$ARTIFACTS_DIR/latest.png" \
+    --diff "$ARTIFACTS_DIR/diff.png" \
+    --json "$ARTIFACTS_DIR/report.json"
+
+  MISMATCH=$(node -e 'const fs=require("fs"); const p=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); process.stdout.write(String(p.summary.mismatchPercent));' "$ARTIFACTS_DIR/report.json")
+
+  echo "- mismatchPercent: $MISMATCH" >> "$LOG_FILE"
+  echo "- report: $ARTIFACTS_DIR/report.json" >> "$LOG_FILE"
+  echo "- diff: $ARTIFACTS_DIR/diff.png" >> "$LOG_FILE"
+  echo >> "$LOG_FILE"
+
+  if [[ -z "$BEST_MISMATCH" ]]; then
+    BEST_MISMATCH="$MISMATCH"
+  fi
+
+  if node -e 'process.exit(Number(process.argv[1]) <= 1.5 ? 0 : 1)' "$MISMATCH"; then
+    echo "Visual mismatch is within threshold ($MISMATCH%). Stopping."
+    break
+  fi
+
+  echo "Iteration $i complete. Review $ARTIFACTS_DIR/report.json, apply targeted UI fixes, then rerun or let Codex continue."
+done
+
+echo "Done. Latest artifacts are in $ARTIFACTS_DIR/"