quiver-cli 1.3.1 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/command-metadata.json

@@ -1,94 +0,0 @@
-{
-  "craft": {
-    "description": "Deprecated compatibility alias for an ordinary Impeccable new-work request. It adds no behavior; natural build and redesign requests use the same flow.",
-    "argumentHint": "[feature description]"
-  },
-  "init": {
-    "description": "Sets up a project for impeccable. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles); offers DESIGN.md (visual: colors, typography, components) when code exists; pre-configures live mode; then recommends the best commands to run next. Every other command reads these files before doing work. Use once per project.",
-    "argumentHint": ""
-  },
-  "document": {
-    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
-    "argumentHint": ""
-  },
-  "extract": {
-    "description": "Pull reusable patterns, components, and design tokens into the design system. Identifies repeated patterns and consolidates them. Use when you have drift across the codebase and want to bring things back to a consistent system.",
-    "argumentHint": "[target]"
-  },
-  "live": {
-    "description": "Interactive live variant mode. Select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via HMR. Requires a running dev server. Use when you want to visually experiment with design alternatives in real time.",
-    "argumentHint": ""
-  },
-  "adapt": {
-    "description": "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility.",
-    "argumentHint": "[target] [context (mobile, tablet, print...)]"
-  },
-  "animate": {
-    "description": "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive.",
-    "argumentHint": "[target]"
-  },
-  "audit": {
-    "description": "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.",
-    "argumentHint": "[area (feature, page, component...)]"
-  },
-  "bolder": {
-    "description": "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character.",
-    "argumentHint": "[target]"
-  },
-  "clarify": {
-    "description": "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.",
-    "argumentHint": "[target]"
-  },
-  "colorize": {
-    "description": "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.",
-    "argumentHint": "[target]"
-  },
-  "critique": {
-    "description": "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.",
-    "argumentHint": "[area (feature, page, component...)]"
-  },
-  "delight": {
-    "description": "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.",
-    "argumentHint": "[target]"
-  },
-  "distill": {
-    "description": "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused.",
-    "argumentHint": "[target]"
-  },
-  "harden": {
-    "description": "Make interfaces production-ready: error handling, i18n, text overflow, edge case management, and resilience under real-world data. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues.",
-    "argumentHint": "[target]"
-  },
-  "onboard": {
-    "description": "Design onboarding flows, first-run experiences, and empty states that guide new users to value. Covers welcome screens, account setup, progressive disclosure, contextual tooltips, feature announcements, and activation moments. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment.",
-    "argumentHint": "[target]"
-  },
-  "layout": {
-    "description": "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.",
-    "argumentHint": "[target]"
-  },
-  "optimize": {
-    "description": "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience.",
-    "argumentHint": "[target]"
-  },
-  "overdrive": {
-    "description": "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.",
-    "argumentHint": "[target]"
-  },
-  "polish": {
-    "description": "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.",
-    "argumentHint": "[target]"
-  },
-  "quieter": {
-    "description": "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.",
-    "argumentHint": "[target]"
-  },
-  "shape": {
-    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
-    "argumentHint": "[feature to shape]"
-  },
-  "typeset": {
-    "description": "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.",
-    "argumentHint": "[target]"
-  }
-}

package/template/.agents/skills/design/impeccable/scripts/comp-diff.mjs

@@ -1,391 +0,0 @@
-#!/usr/bin/env node
-/**
- * comp-diff: measure a build screenshot against its approved comp and produce
- * the evidence a reviewer (human or model) needs to judge fidelity without
- * trusting anyone's memory of the image.
- *
- *   node comp-diff.mjs --comp .impeccable/mocks/approved.png --build .impeccable/review/hero-repro.png
- *   node comp-diff.mjs --comp comp.png --build desktop.png --spec .impeccable/build/spec.json --out-dir .impeccable/review/diff
- *   node comp-diff.mjs ... --json            # machine-readable report on stdout
- *   node comp-diff.mjs ... --threshold 0.75  # exit 3 when the overall score is below
- *
- * Inputs: two PNGs. The build capture may be taller than the comp (a full-page
- * screenshot); it is scaled to the comp's width and the top comp-height rows
- * are compared, because the comp is the first viewport. `--align stretch`
- * squashes the whole build onto the comp instead, for a comp that covers a
- * whole page.
- *
- * Outputs (in --out-dir, default .impeccable/review/diff):
- *   side-by-side.png   comp | build, same size, labeled, with the score
- *   heatmap.png        build with the difference painted over it (red = wrong)
- *   regions/<id>.png   paired crops per region at legible scale, scored
- *   report.json        every number below, plus per-region rows
- *
- * Scores (0..1): structure (blurred SSIM: is the composition the same?),
- * color (histogram + dominant palette: is it the same palette at the same
- * coverage?), detail (high-frequency energy ratio: did the material survive,
- * or did an illustration become a gradient?), bands (do the horizontal
- * sections line up?). `overall` weights them 0.35 / 0.25 / 0.25 / 0.15.
- *
- * Regions come from --spec (comp-spec.mjs output: normalized boxes) or, with
- * none, from the comp's own horizontal bands, so the per-region crops exist
- * either way. Every region row carries the same four scores plus `verdict`:
- * match (>= 0.8), drift (>= 0.6), missing (detail ratio < 0.35 with structure
- * < 0.6), or contradicted (everything else). The words are the finish
- * reviewer's fidelity vocabulary on purpose.
- *
- * Exit codes: 0 measured (and above threshold when one is given), 1 usage or
- * unreadable input, 3 below threshold.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { decodePng, encodePng, loadRaster } from './lib/png.mjs';
-import { crop, resize, fit, blit, createImage, fillRect, strokeRect, drawLabel } from './lib/raster.mjs';
-import { structureScore, colorScore, detailScore, diffMap, horizontalBands, bandScore, dominantColors, toGray, blurGray, ssimShifted } from './lib/image-metrics.mjs';
-
-function arg(name, fallback = null) {
-  const i = process.argv.indexOf(`--${name}`);
-  if (i === -1) return fallback;
-  const v = process.argv[i + 1];
-  return v && !v.startsWith('--') ? v : fallback;
-}
-const flag = (name) => process.argv.includes(`--${name}`);
-
-export function readPng(file) {
-  return loadRaster(file).image;
-}
-
-/**
- * Scale the build to the comp's width; take the top comp-height rows
- * (align=top), squash the whole build onto the comp (align=stretch), or scale
- * to cover and center-crop (align=cover, the way `object-fit: cover` will show
- * a plate whose aspect differs from its region).
- */
-export function alignBuild(comp, build, align = 'top') {
-  if (align === 'stretch') return resize(build, comp.width, comp.height);
-  if (align === 'cover') {
-    const s = Math.max(comp.width / build.width, comp.height / build.height);
-    const scaled = resize(build, build.width * s, build.height * s);
-    return crop(scaled, (scaled.width - comp.width) / 2, (scaled.height - comp.height) / 2, comp.width, comp.height);
-  }
-  const scaled = build.width === comp.width ? build : resize(build, comp.width, Math.round((build.height / build.width) * comp.width));
-  if (scaled.height === comp.height) return scaled;
-  if (scaled.height > comp.height) return crop(scaled, 0, 0, comp.width, comp.height);
-  // shorter than the comp: pad with white so a short page reads as missing content, not as a resize
-  const out = createImage(comp.width, comp.height, [255, 255, 255, 255]);
-  blit(out, scaled, 0, 0);
-  return out;
-}
-
-/** Weights per region kind: what a region is made of decides what losing it looks like. */
-const WEIGHTS = {
-  default: { structure: 0.35, color: 0.25, detail: 0.25, bands: 0.15 },
-  plate: { structure: 0.25, color: 0.2, detail: 0.5, bands: 0.05 },
-  image: { structure: 0.25, color: 0.2, detail: 0.5, bands: 0.05 },
-  texture: { structure: 0.15, color: 0.35, detail: 0.5, bands: 0 },
-  text: { structure: 0.5, color: 0.25, detail: 0.15, bands: 0.1 },
-  control: { structure: 0.45, color: 0.35, detail: 0.2, bands: 0 },
-};
-
-export function scorePair(a, b, kind = null) {
-  const structure = structureScore(a, b);
-  const color = colorScore(a, b);
-  const detail = detailScore(a, b);
-  const bandsA = horizontalBands(a), bandsB = horizontalBands(b);
-  const bands = bandScore(bandsA, bandsB);
-  const w = WEIGHTS[kind] || WEIGHTS.default;
-  const overall = w.structure * structure + w.color * color.score + w.detail * detail.score + w.bands * bands;
-  return {
-    overall: r4(overall),
-    structure: r4(structure),
-    color: r4(color.score),
-    colorIntersection: r4(color.intersection),
-    paletteMatch: r4(color.paletteMatch),
-    detail: r4(detail.score),
-    detailRaw: r4(detail.rawScore ?? detail.score),
-    detailAdded: r4(detail.addedFraction),
-    bands: r4(bands),
-    _detail: detail,
-    _bands: { comp: bandsA, build: bandsB },
-  };
-}
-
-/** Kinds that carry the direction: a wrong one is the wrong page, whatever the mean says. */
-export const DIRECTION_KINDS = new Set(['plate', 'image', 'text']);
-
-/** Best small global translation (build relative to comp), in pixels, by blurred-gray SSIM. */
-export function bestShift(comp, build, workWidth = 256) {
-  const h = Math.max(8, Math.round((comp.height / comp.width) * workWidth));
-  const a = blurGray(toGray(resize(comp, workWidth, h)), 2);
-  const b = blurGray(toGray(resize(build, workWidth, h)), 2);
-  const maxShift = Math.max(2, Math.round(workWidth * 0.04));
-  let best = { dx: 0, dy: 0, score: ssimShifted(a, b, 0, 0) };
-  for (const dy of [-maxShift, -maxShift / 2, 0, maxShift / 2, maxShift]) {
-    for (const dx of [-maxShift, -maxShift / 2, 0, maxShift / 2, maxShift]) {
-      const sc = ssimShifted(a, b, Math.round(dx), Math.round(dy));
-      if (sc > best.score + 0.01) best = { dx: Math.round(dx), dy: Math.round(dy), score: sc };
-    }
-  }
-  const scale = comp.width / workWidth;
-  return { dx: Math.round(best.dx * scale), dy: Math.round(best.dy * scale), score: best.score };
-}
-
-export function verdictFor(s, kind = null) {
-  const painted = kind === 'plate' || kind === 'image' || kind === 'texture';
-  // Nothing drawn where the comp drew something is missing whatever the
-  // palette says: a footer strip the build pushed below the fold read as
-  // 'drift' on ground colour alone (detail 4%, structure 92%). detailRaw is
-  // 1 when the comp region itself is calm, so a low value already means the
-  // comp had material there.
-  if (s.detailRaw != null && s.detailRaw < 0.15) return 'missing';
-  if (painted && s.detail < 0.5) return 'missing';
-  // For text, chrome, and controls "missing" means the build has nothing
-  // there, not that a thin strip sits a few pixels off: require the build's
-  // own energy to be near zero relative to the comp (rawScore, before the
-  // added-detail penalty), and drift for a mere misalignment.
-  if (!painted && s.detail < 0.35 && s.structure < 0.6) {
-    if (s.detailRaw != null && s.detailRaw < 0.2) return 'missing';
-    // low detail with structure and palette both holding is grain the build
-    // renders flatter (a spine of rotated type on textured red), not a
-    // different composition
-    if (s.structure >= 0.5 && s.color >= 0.5) return 'drift';
-    return 'contradicted';
-  }
-  if (s.detail < 0.35 && s.structure < 0.6) return 'missing';
-  // Structure is the one thing a wrong-but-busy region cannot fake: noise,
-  // a mirrored crop, a swapped column, a tile shuffle all keep color and
-  // energy and lose structure. Below the floor it is contradicted whatever
-  // the weighted mean says; painted regions with invented detail likewise.
-  if (s.structure < 0.3) return 'contradicted';
-  if (painted && (s.structure < 0.45 || s.detailAdded > 0.4)) return 'contradicted';
-  // Text is set in a substitute face at a slightly different metric almost
-  // always, and blurred SSIM reads glyph shape; a text region with its
-  // structure above the swap floor and its palette intact is drift at worst.
-  // Chasing it past that point is what burned eight to thirteen hero attempts
-  // per build in the first simulated round.
-  if (kind === 'text' && s.color >= 0.5) return s.overall >= 0.8 ? 'match' : 'drift';
-  // Chrome and controls are thin strips whose "detail" is mostly ground grain
-  // (a paper texture the build renders flatter, a scanline). When their
-  // structure and palette hold, low detail is drift, not contradiction.
-  if ((kind === 'chrome' || kind === 'control') && s.structure >= 0.5 && s.color >= 0.5) return s.overall >= 0.8 ? 'match' : 'drift';
-  if (s.overall >= 0.8) return 'match';
-  if (s.overall >= 0.6) return 'drift';
-  return 'contradicted';
-}
-
-const r4 = (v) => Math.round(v * 10000) / 10000;
-
-/** Regions from a spec (normalized boxes) or derived from the comp's bands. */
-export function resolveRegions(comp, spec) {
-  const regions = [];
-  if (spec && Array.isArray(spec.regions) && spec.regions.length) {
-    for (const r of spec.regions) {
-      const box = r.box || r;
-      if ([box.x, box.y, box.w, box.h].some((v) => typeof v !== 'number')) continue;
-      regions.push({ id: r.id || `region-${regions.length + 1}`, x: box.x, y: box.y, w: box.w, h: box.h, kind: r.kind || null });
-    }
-    if (regions.length) return regions;
-  }
-  const bands = horizontalBands(comp).filter((b) => b.strength > 0.2);
-  const cuts = [0, ...bands.map((b) => b.y), 1].filter((v, i, arr) => i === 0 || v - arr[i - 1] > 0.06);
-  if (cuts[cuts.length - 1] !== 1) cuts.push(1);
-  for (let i = 0; i + 1 < cuts.length; i++) {
-    regions.push({ id: `band-${i + 1}`, x: 0, y: cuts[i], w: 1, h: cuts[i + 1] - cuts[i], kind: 'band' });
-  }
-  if (regions.length < 2) {
-    return [
-      { id: 'top', x: 0, y: 0, w: 1, h: 0.5, kind: 'band' },
-      { id: 'bottom', x: 0, y: 0.5, w: 1, h: 0.5, kind: 'band' },
-    ];
-  }
-  return regions;
-}
-
-/** Crop a normalized region; regions thinner than 48px in either axis are grown to that so tiny strips do not swing on subpixel noise. */
-/** Bounding box of ink (pixels darker/lighter than the region's ground by a margin) within a crop, in px. */
-export function inkBox(img) {
-  const g = toGray(img);
-  // ground = median gray; ink = |v - ground| > 48
-  const sample = []; for (let i = 0; i < g.data.length; i += Math.max(1, Math.floor(g.data.length / 4000))) sample.push(g.data[i]);
-  sample.sort((p, q) => p - q); const ground = sample[Math.floor(sample.length / 2)] || 255;
-  let x0 = img.width, y0 = img.height, x1 = -1, y1 = -1;
-  for (let y = 0; y < img.height; y++) for (let x = 0; x < img.width; x++) {
-    if (Math.abs(g.data[y * img.width + x] - ground) > 48) { if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y; }
-  }
-  if (x1 < 0) return null;
-  return { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 };
-}
-
-function regionCrop(img, r) {
-  const minPx = 48;
-  let x = r.x * img.width, y = r.y * img.height, w = r.w * img.width, h = r.h * img.height;
-  if (h < minPx) { y -= (minPx - h) / 2; h = minPx; }
-  if (w < minPx) { x -= (minPx - w) / 2; w = minPx; }
-  return crop(img, x, y, w, h);
-}
-
-const HEAT_LABEL = { match: [40, 160, 80, 255], drift: [220, 160, 30, 255], missing: [200, 40, 40, 255], contradicted: [200, 40, 40, 255] };
-
-export function renderSideBySide(comp, build, label, score) {
-  const gap = 24, pad = 48;
-  const targetW = Math.min(comp.width, 1400);
-  const a = fit(comp, targetW, 100000), b = resize(build, a.width, a.height);
-  const out = createImage(a.width * 2 + gap + pad * 2, a.height + pad * 2 + 24, [24, 24, 28, 255]);
-  blit(out, a, pad, pad + 24);
-  blit(out, b, pad + a.width + gap, pad + 24);
-  drawLabel(out, 'COMP', pad, pad - 4, { scale: 2 });
-  drawLabel(out, `BUILD ${label ? label.toUpperCase() : ''}`.trim(), pad + a.width + gap, pad - 4, { scale: 2 });
-  const s = `OVERALL ${(score.overall * 100).toFixed(0)}%  STRUCT ${(score.structure * 100).toFixed(0)}%  COLOR ${(score.color * 100).toFixed(0)}%  DETAIL ${(score.detail * 100).toFixed(0)}%  BANDS ${(score.bands * 100).toFixed(0)}%`;
-  drawLabel(out, s, pad, out.height - pad + 8, { scale: 2, bg: HEAT_LABEL[verdictFor(score)] });
-  return out;
-}
-
-export function renderHeatmap(comp, build) {
-  const map = diffMap(comp, build);
-  const base = resize(build, map.width, map.height);
-  const out = { width: base.width, height: base.height, data: new Uint8Array(base.data) };
-  for (let i = 0, p = 0; i < map.data.length; i++, p += 4) {
-    const d = map.data[i];
-    if (d < 0.12) { // dim what matches so wrong stands out
-      out.data[p] = out.data[p] * 0.55 + 255 * 0.45 * 0.2; out.data[p + 1] = out.data[p + 1] * 0.55; out.data[p + 2] = out.data[p + 2] * 0.55; continue;
-    }
-    const a = Math.min(1, (d - 0.12) / 0.5);
-    out.data[p] = out.data[p] * (1 - a) + 235 * a; out.data[p + 1] = out.data[p + 1] * (1 - a) + 40 * a; out.data[p + 2] = out.data[p + 2] * (1 - a) + 40 * a;
-  }
-  const scaled = resize(out, comp.width, comp.height);
-  drawLabel(scaled, 'DIFF: RED = DIFFERS FROM COMP', 12, 12, { scale: 2 });
-  return scaled;
-}
-
-export function renderRegionPair(compCrop, buildCrop, id, score) {
-  const gap = 16, pad = 12;
-  const maxW = 700;
-  const a = fit(compCrop, maxW, 700, true), b = resize(buildCrop, a.width, a.height);
-  const out = createImage(a.width * 2 + gap + pad * 2, a.height + pad * 2 + 30, [24, 24, 28, 255]);
-  blit(out, a, pad, pad + 30);
-  blit(out, b, pad + a.width + gap, pad + 30);
-  const v = verdictFor(score);
-  drawLabel(out, `${id.toUpperCase()}  COMP`, pad, pad, { scale: 2 });
-  drawLabel(out, `BUILD  ${v.toUpperCase()} ${(score.overall * 100).toFixed(0)}%`, pad + a.width + gap, pad, { scale: 2, bg: HEAT_LABEL[v] });
-  return out;
-}
-
-export function compare({ comp, build, spec = null, align = 'top', label = '', kind = null }) {
-  let aligned = alignBuild(comp, build, align);
-  const whole = scorePair(comp, aligned, kind);
-  // Region crops are taken at fixed boxes, so a small global offset (a
-  // taller masthead, a scrollbar) would read every thin region as
-  // contradicted while the whole-image search forgives it. Find the best
-  // global translation once and shift the aligned build by it before
-  // cropping regions; the whole score above stays as measured.
-  // The side-by-side and heatmap show the build as captured; only the
-  // region crops read the shifted copy. (The shifted copy used to be what the
-  // side-by-side drew, and its padding read as a white "letterbox" on the
-  // build in every human review.)
-  const asCaptured = aligned;
-  const shift = bestShift(comp, aligned);
-  if (shift.dx || shift.dy) {
-    const shifted = createImage(aligned.width, aligned.height, [255, 255, 255, 255]);
-    blit(shifted, aligned, -shift.dx, -shift.dy);
-    aligned = shifted;
-  }
-  const regions = resolveRegions(comp, spec).map((r) => {
-    const a = regionCrop(comp, r), b = regionCrop(aligned, r);
-    const s = scorePair(a, b, r.kind);
-    return { ...r, score: strip(s), verdict: verdictFor(s, r.kind), inkBox: { comp: inkBox(a), build: inkBox(b) }, _a: a, _b: b };
-  });
-  const compPalette = dominantColors(comp), buildPalette = dominantColors(aligned);
-  return { label, align, whole: strip(whole), regions, aligned: asCaptured, alignedShifted: aligned, shift, compPalette, buildPalette, _whole: whole };
-}
-
-function strip(s) {
-  const { _detail, _bands, ...rest } = s;
-  return rest;
-}
-
-export function writeArtifacts(result, comp, outDir) {
-  fs.mkdirSync(path.join(outDir, 'regions'), { recursive: true });
-  const side = renderSideBySide(comp, result.aligned, result.label, result.whole);
-  fs.writeFileSync(path.join(outDir, 'side-by-side.png'), encodePng(side));
-  fs.writeFileSync(path.join(outDir, 'heatmap.png'), encodePng(renderHeatmap(comp, result.aligned)));
-  const regionFiles = [];
-  for (const r of result.regions) {
-    const file = path.join(outDir, 'regions', `${r.id}.png`);
-    fs.writeFileSync(file, encodePng(renderRegionPair(r._a, r._b, r.id, r.score)));
-    regionFiles.push(file);
-  }
-  return { sideBySide: path.join(outDir, 'side-by-side.png'), heatmap: path.join(outDir, 'heatmap.png'), regionFiles };
-}
-
-export function buildReport(result, files, meta) {
-  return {
-    tool: 'comp-diff',
-    version: 1,
-    createdAt: new Date().toISOString(),
-    ...meta,
-    align: result.align,
-    overall: result.whole.overall,
-    verdict: verdictFor(result.whole),
-    scores: result.whole,
-    palette: { comp: result.compPalette.map(({ hex, coverage }) => ({ hex, coverage })), build: result.buildPalette.map(({ hex, coverage }) => ({ hex, coverage })) },
-    regions: result.regions.map(({ _a, _b, ...r }) => r),
-    files,
-  };
-}
-
-function summarize(report) {
-  const lines = [];
-  lines.push(`COMP-DIFF ${report.label ? `[${report.label}] ` : ''}overall ${(report.overall * 100).toFixed(0)}% (${report.verdict}) structure ${(report.scores.structure * 100).toFixed(0)}% color ${(report.scores.color * 100).toFixed(0)}% detail ${(report.scores.detail * 100).toFixed(0)}% bands ${(report.scores.bands * 100).toFixed(0)}%`);
-  lines.push(`PALETTE comp ${report.palette.comp.slice(0, 5).map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);
-  lines.push(`PALETTE build ${report.palette.build.slice(0, 5).map((c) => `${c.hex}(${Math.round(c.coverage * 100)}%)`).join(' ')}`);
-  for (const r of report.regions) {
-    lines.push(`REGION ${r.id.padEnd(18)} ${r.verdict.padEnd(12)} ${(r.score.overall * 100).toFixed(0).padStart(3)}%  structure ${(r.score.structure * 100).toFixed(0).padStart(3)}%  color ${(r.score.color * 100).toFixed(0).padStart(3)}%  detail ${(r.score.detail * 100).toFixed(0).padStart(3)}%${r.score.detailAdded > 0.25 ? '  +invented detail' : ''}`);
-  }
-  if (report.files) {
-    lines.push(`FILES side-by-side ${report.files.sideBySide}`);
-    lines.push(`FILES heatmap ${report.files.heatmap}`);
-    lines.push(`FILES regions ${report.files.regionFiles.length} under ${path.dirname(report.files.regionFiles[0] || report.files.heatmap)}`);
-  }
-  const worst = [...report.regions].sort((a, b) => a.score.overall - b.score.overall).slice(0, 3);
-  if (worst.length) lines.push(`WORST ${worst.map((r) => `${r.id} (${r.verdict}, ${(r.score.overall * 100).toFixed(0)}%)`).join('; ')}`);
-  lines.push('OPEN the side-by-side and the worst region pairs before deciding anything; the numbers rank, the crops decide.');
-  return lines.join('\n');
-}
-
-async function main() {
-  const compPath = arg('comp'), buildPath = arg('build');
-  if (!compPath || !buildPath) {
-    console.error('usage: comp-diff.mjs --comp <png> --build <png> [--spec spec.json] [--out-dir dir] [--align top|stretch] [--label name] [--threshold 0.75] [--json]');
-    process.exit(1);
-  }
-  let comp, build;
-  try { comp = readPng(compPath); } catch (e) { console.error(`comp-diff: cannot read comp ${compPath}: ${e.message}`); process.exit(1); }
-  try { build = readPng(buildPath); } catch (e) { console.error(`comp-diff: cannot read build ${buildPath}: ${e.message}`); process.exit(1); }
-  let spec = null;
-  const specPath = arg('spec');
-  if (specPath) {
-    try { spec = JSON.parse(fs.readFileSync(specPath, 'utf8')); } catch (e) { console.error(`comp-diff: cannot read spec ${specPath}: ${e.message}`); process.exit(1); }
-  }
-  const outDir = arg('out-dir', path.join(path.dirname(buildPath), 'diff'));
-  const label = arg('label', path.basename(buildPath, '.png'));
-  const result = compare({ comp, build, spec, align: arg('align', 'top'), label });
-  const files = flag('no-files') ? null : writeArtifacts(result, comp, outDir);
-  const report = buildReport(result, files, { label, comp: compPath, build: buildPath, spec: specPath || null, compSize: `${comp.width}x${comp.height}`, buildSize: `${build.width}x${build.height}` });
-  if (files) fs.writeFileSync(path.join(outDir, 'report.json'), JSON.stringify(report, null, 2));
-  if (flag('json')) console.log(JSON.stringify(report, null, 2));
-  else console.log(summarize(report));
-  const threshold = arg('threshold') ? parseFloat(arg('threshold')) : null;
-  if (threshold != null && report.overall < threshold) {
-    if (!flag('json')) console.log(`BELOW THRESHOLD ${(threshold * 100).toFixed(0)}%: the reproduction is not done. Fix the worst regions and re-run; do not build past the hero.`);
-    process.exit(3);
-  }
-}
-
-// realpath on both sides: a skill mounted through a symlink (Cursor, a
-// worktree, an eval stage) must still run as a CLI.
-const isMain = (() => {
-  try { return !!process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); }
-  catch { return !!process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname); }
-})();
-if (isMain) main();