@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/skills/cc-technical-diagrams/scripts/diagram-layout.mjs

@@ -0,0 +1,176 @@
+// @ts-check
+
+/** @typedef {{x:number,y:number,width:number,height:number}} Rect */
+/** @typedef {[number,number]} Point */
+/** @typedef {{code:string,id:string,message:string}} QualityIssue */
+/** @typedef {{lines:string[],width:number,height:number,fontSize:number,lineHeight:number}} TextLayout */
+/** @typedef {Rect & {id:string,label:string,sublabel:string,type:string,actor?:string,step?:string,shape?:"box"|"diamond"|"terminal"}} Box */
+
+/** @param {string} text @param {number} fontSize */
+function textWidth(text, fontSize) {
+  return [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)]
+    .reduce((sum, item) => sum + (/^[\x00-\x7f]+$/.test(item.segment) ? fontSize * 0.6 : fontSize), 0);
+}
+
+/** @param {string} text @param {number} maxWidth @param {number} [fontSize] @param {number} [lineHeight] @returns {TextLayout} */
+export function layoutText(text, maxWidth, fontSize = 14, lineHeight = 20) {
+  const limit = Math.max(fontSize, maxWidth);
+  /** @type {string[]} */
+  const lines = [];
+  for (const paragraph of text.split(/\r?\n/)) {
+    let line = "";
+    for (const { segment: word } of new Intl.Segmenter(undefined, { granularity: "word" }).segment(paragraph)) {
+      if (line && textWidth(word,fontSize) <= limit && textWidth(line+word,fontSize)>limit) {lines.push(line);line="";}
+      for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(word)) {
+      if (line && textWidth(line + segment, fontSize) > limit) {
+        lines.push(line);
+        line = "";
+      }
+      line += segment;
+      }
+    }
+    lines.push(line);
+  }
+  return { lines, width: Math.max(0, ...lines.map((line) => textWidth(line, fontSize))), height: lines.length * lineHeight, fontSize, lineHeight };
+}
+
+/** @param {Box} source @param {{width:boolean,height:boolean}} explicit */
+export function fitNodeText(source, explicit) {
+  const box = { ...source };
+  if (![box.width, box.height].every((v) => Number.isFinite(v) && v > 0)) throw new Error(`Invalid size for node "${box.id}".`);
+  const diamond = box.shape === "diamond" || box.type === "decision";
+  const semantic = ["agent", "model", "memory", "vectorstore", "graphdb", "tool", "document", "queue", "browser", "user", "gateway"].includes(box.type);
+  if (!explicit.width) box.width = Math.max(box.width, diamond ? 240 : 200);
+  const available = diamond ? box.width * 0.5 - 12 : (box.type === "queue" ? box.width - 64 : box.width - 32);
+  const main = layoutText(box.label, available);
+  const sub = layoutText(box.sublabel, available, 12, 16);
+  const header = ["database", "vectorstore"].includes(box.type) ? 30 : box.type === "queue" ? 20 : semantic ? 46 : box.actor ? 40 : 20;
+  const contentHeight = main.height + (box.sublabel ? sub.height + 6 : 0);
+  const needed = diamond ? (contentHeight + 24) * 2 : header + contentHeight + (["database", "vectorstore"].includes(box.type) ? 30 : 18);
+  if (!explicit.height) box.height = Math.max(box.height, needed, 72);
+  /** @type {QualityIssue[]} */
+  const issues = [];
+  if (box.height < needed || available < main.width) issues.push({ code: "node-text-overflow", id: box.id, message: `Node "${box.id}" has an explicit size too small for its complete text.` });
+  return { box, labels: [main, sub], issues };
+}
+
+/** @param {Rect} box @param {'top'|'right'|'bottom'|'left'} side @returns {Point} */
+export function boundaryPort(box, side) {
+  if (side === "top") return [box.x + box.width / 2, box.y];
+  if (side === "bottom") return [box.x + box.width / 2, box.y + box.height];
+  if (side === "left") return [box.x, box.y + box.height / 2];
+  return [box.x + box.width, box.y + box.height / 2];
+}
+
+/** Strict interior intersection; boundary contact is allowed. @param {Point} a @param {Point} b @param {Rect} r */
+export function segmentHits(a, b, r) {
+  let lo = 0, hi = 1;
+  for (const axis of [0, 1]) {
+    const start = axis === 0 ? r.x : r.y;
+    const end = start + (axis === 0 ? r.width : r.height);
+    const delta = b[axis] - a[axis];
+    if (Math.abs(delta) < 1e-8) {
+      if (a[axis] <= start + 1e-6 || a[axis] >= end - 1e-6) return false;
+    } else {
+      const t1 = (start - a[axis]) / delta, t2 = (end - a[axis]) / delta;
+      lo = Math.max(lo, Math.min(t1, t2)); hi = Math.min(hi, Math.max(t1, t2));
+    }
+  }
+  return hi - lo > 1e-6;
+}
+
+/** @param {Rect} a @param {Rect} b */
+export function overlaps(a, b) {
+  return Math.min(a.x + a.width, b.x + b.width) > Math.max(a.x, b.x) + 1e-6 && Math.min(a.y + a.height, b.y + b.height) > Math.max(a.y, b.y) + 1e-6;
+}
+
+/** @param {Point[]} points @returns {Point[]} */
+function simplify(points) {
+  return points.filter((p, i) => {
+    if (i && p[0] === points[i - 1][0] && p[1] === points[i - 1][1]) return false;
+    if (!i || i === points.length - 1) return true;
+    const prev = points[i - 1], next = points[i + 1];
+    return !((prev[0] === p[0] && next[0] === p[0]) || (prev[1] === p[1] && next[1] === p[1]));
+  });
+}
+
+/** @param {Rect & {id:string}} from @param {Rect & {id:string}} to @param {Rect[]} obstacles @param {Point[][]} occupied @param {Point[]} [waypoints] */
+export function routeConnector(from, to, obstacles, occupied, waypoints) {
+  const horizontal = Math.abs(to.x - from.x) >= Math.abs(to.y - from.y);
+  const forward = horizontal ? to.x >= from.x : to.y >= from.y;
+  const start = boundaryPort(from, horizontal ? (forward ? "right" : "left") : (forward ? "bottom" : "top"));
+  const end = boundaryPort(to, horizontal ? (forward ? "left" : "right") : (forward ? "top" : "bottom"));
+  /** @type {QualityIssue[]} */
+  const issues = [];
+  if (waypoints) {
+    const points = [start, ...waypoints, end];
+    if (points.some((p, i) => i > 0 && obstacles.some((r) => segmentHits(points[i - 1], p, r)))) issues.push({ code: "route-obstructed", id: `${from.id}-${to.id}`, message: "Explicit waypoints cross a non-endpoint node." });
+    return { points, issues };
+  }
+  if (from.id === to.id) {
+    const x = from.x + from.width + 40 + occupied.length * 4;
+    return { points: /** @type {Point[]} */ ([[from.x + from.width, from.y + from.height / 3], [x, from.y + from.height / 3], [x, from.y + from.height * 2 / 3], [from.x + from.width, from.y + from.height * 2 / 3]]), issues };
+  }
+  const padded = obstacles.map((r) => ({ x: r.x - 12, y: r.y - 12, width: r.width + 24, height: r.height + 24 }));
+  const xSet = new Set([start[0], end[0], 28]), ySet = new Set([start[1], end[1], 28]);
+  for (const r of [...padded, from, to]) { xSet.add(r.x - 16); xSet.add(r.x + r.width + 16); ySet.add(r.y - 16); ySet.add(r.y + r.height + 16); }
+  for (const route of occupied) for (const [x, y] of route) { xSet.add(x - 16); xSet.add(x + 16); ySet.add(y - 16); ySet.add(y + 16); }
+  const xs = [...xSet].filter((x) => x >= 24).sort((a, b) => a - b), ys = [...ySet].filter((y) => y >= 24).sort((a, b) => a - b);
+  if (xs.length > 128 || ys.length > 128) return { points: [start, end], issues: [{ code: "route-unresolved", id: `${from.id}-${to.id}`, message: "Routing grid exceeded its bounded search budget." }] };
+  const nx = xs.length, ny = ys.length;
+  const startId = ys.indexOf(start[1]) * nx + xs.indexOf(start[0]), endId = ys.indexOf(end[1]) * nx + xs.indexOf(end[0]);
+  /** @param {number} id @returns {Point} */
+  const point = (id) => [xs[id % nx], ys[Math.floor(id / nx)]];
+  /** @type {Array<{node:number,dir:number,cost:number,key:string}>} */
+  const pending = [{ node: startId, dir: 0, cost: 0, key: `${startId}:0` }];
+  const best = new Map([[`${startId}:0`, 0]]), previous = new Map();
+  let finish = "";
+  while (pending.length) {
+    pending.sort((a, b) => a.cost - b.cost || a.node - b.node || a.dir - b.dir);
+    const current = pending.shift();
+    if (!current || current.cost !== best.get(current.key)) continue;
+    if (current.node === endId) { finish = current.key; break; }
+    const ix = current.node % nx, iy = Math.floor(current.node / nx);
+    for (const [dx, dy] of [[-1, 0], [1, 0], [0, -1], [0, 1]]) {
+      if (ix + dx < 0 || ix + dx >= nx || iy + dy < 0 || iy + dy >= ny) continue;
+      const next = (iy + dy) * nx + ix + dx, a = point(current.node), b = point(next);
+      if ([...padded, from, to].some((r) => segmentHits(a, b, r))) continue;
+      const dir = dx ? 1 : 2;
+      let penalty = 0;
+      for (const route of occupied) for (let i = 1; i < route.length; i++) {
+        const p = route[i - 1], q = route[i];
+        if ((a[0] === b[0] && p[0] === q[0] && a[0] === p[0] && Math.min(b[1], a[1]) < Math.max(p[1], q[1]) && Math.max(b[1], a[1]) > Math.min(p[1], q[1])) || (a[1] === b[1] && p[1] === q[1] && a[1] === p[1] && Math.min(b[0], a[0]) < Math.max(p[0], q[0]) && Math.max(b[0], a[0]) > Math.min(p[0], q[0]))) penalty += 80;
+      }
+      const cost = current.cost + Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]) + (current.dir && current.dir !== dir ? 24 : 0) + penalty;
+      const key = `${next}:${dir}`;
+      if (cost < (best.get(key) ?? Infinity)) { best.set(key, cost); previous.set(key, current.key); pending.push({ node: next, dir, cost, key }); }
+    }
+  }
+  if (!finish) return { points: [start, end], issues: [{ code: "route-unresolved", id: `${from.id}-${to.id}`, message: "No obstacle-free route exists without moving explicit nodes." }] };
+  /** @type {Point[]} */
+  const route = [];
+  for (let key = finish; key; key = previous.get(key)) route.unshift(point(Number(key.split(":")[0])));
+  return { points: simplify(route), issues };
+}
+
+/** @param {Point[]} points @param {TextLayout} layout @param {Rect[]} obstacles @param {Point[][]} [routes] */
+export function placeEdgeLabel(points, layout, obstacles, routes = []) {
+  const lengths = points.slice(1).map((p, i) => Math.hypot(p[0] - points[i][0], p[1] - points[i][1]));
+  let remaining = lengths.reduce((a, b) => a + b, 0) / 2;
+  let cx = points[0][0], cy = points[0][1];
+  for (let i = 0; i < lengths.length; i++) {
+    if (remaining <= lengths[i]) {
+      const ratio = lengths[i] ? remaining / lengths[i] : 0;
+      cx = points[i][0] + (points[i + 1][0] - points[i][0]) * ratio;
+      cy = points[i][1] + (points[i + 1][1] - points[i][1]) * ratio;
+      break;
+    }
+    remaining -= lengths[i];
+  }
+  let rect = { x: cx - layout.width / 2, y: cy - layout.height - 12, width: layout.width, height: layout.height };
+  for (const offset of [12,24,36,52,72,96]) for (const direction of ["above","below","left","right"]) {
+    const candidate = direction === "above" ? {...rect,y:cy-layout.height-offset} : direction === "below" ? {...rect,y:cy+offset} : direction === "left" ? {...rect,x:cx-layout.width-offset,y:cy-layout.height/2} : {...rect,x:cx+offset,y:cy-layout.height/2};
+    if (candidate.x >= 24 && candidate.y >= 24 && !obstacles.some((r) => overlaps(candidate, r)) && !routes.some(route=>route.slice(1).some((point,index)=>segmentHits(route[index],point,{x:candidate.x-4,y:candidate.y-4,width:candidate.width+8,height:candidate.height+8})))) return { rect: candidate, issues: /** @type {QualityIssue[]} */ ([]) };
+  }
+  return { rect, issues: [{ code: "edge-label-collision", id: "edge", message: "No free label position near route midpoint." }] };
+}

package/skills/cc-technical-diagrams/scripts/export-diagram.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { analyzeManifest } from "./png-qa.mjs";
+import { withDiagramPage } from "./diagram-browser.mjs";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** @typedef {{id:string,x:number,y:number,width:number,height:number,[key:string]:unknown}} LabelRect */
+/** @typedef {{canvas:{width:number,height:number},boxes:LabelRect[],groups?:LabelRect[],labels?:LabelRect[],connectors:Array<{points:Array<[number,number]>,[key:string]:unknown}>,[key:string]:unknown}} Manifest */
+
+const SUPPORTED_FORMATS = new Set(["svg", "png", "jpg", "jpeg"]);
+const JPEG_FORMATS = new Set(["jpg", "jpeg"]);
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  const inputPath = path.resolve(requireArg(args, "input"));
+  const format = requireArg(args, "format").toLowerCase();
+  const scale = args.scale === undefined ? 2 : parseScale(args.scale);
+  const background = args.background ?? (args.theme === "dark" ? "#0f172a" : "#ffffff");
+
+  if (!SUPPORTED_FORMATS.has(format)) {
+    throw usageError(`Unsupported --format "${format}". Expected svg, png, jpg, or jpeg.`);
+  }
+  if (!fs.existsSync(inputPath)) {
+    throw usageError(`Input file does not exist: ${inputPath}`);
+  }
+
+  let svg = extractSvg(inputPath);
+  const theme = args.theme ?? "light";
+  if (theme !== "light" && theme !== "dark") throw usageError("--theme must be light or dark");
+  svg = svg.replace(/data-theme=["'][^"']*["']/, `data-theme="${theme}"`);
+  /** @type {Manifest|null} */
+  const manifest = args.manifest ? JSON.parse(fs.readFileSync(path.resolve(args.manifest), "utf8")) : null;
+  const outputPath = path.resolve(resolveOutputPath(inputPath, format, args.output));
+
+  for(const metadataPath of [args["output-manifest"],args["qa-report"]]) if(metadataPath) fs.mkdirSync(path.dirname(path.resolve(metadataPath)),{recursive:true});
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  if (format === "svg") {
+    fs.writeFileSync(outputPath, `${svg.trim()}\n`, "utf8");
+    if (manifest && args["output-manifest"]) fs.writeFileSync(path.resolve(args["output-manifest"]), JSON.stringify({...manifest,coordinateSpace:"svg",scale:1,measurement:"estimated"},null,2)+"\n");
+    if (args["qa-report"]) fs.writeFileSync(path.resolve(args["qa-report"]),JSON.stringify({status:"estimated",measurement:"estimated",theme,issues:manifest?.issues??[],visualQA:"pending"},null,2)+"\n");
+  } else {
+    const dimensions = measureSvg(svg);
+    const pageHtml = `<!doctype html><meta charset="utf-8"><style>html,body{margin:0;padding:0;background:${background};}svg.tech-diagram,body>svg{display:block;width:${dimensions.width}px;min-width:0;height:${dimensions.height}px;}</style>${svg}`;
+    const result = await withDiagramPage(pageHtml, { theme, timeoutMs: 30000 }, async (session) => {
+      await session.evaluate(`(async()=>{let last="";for(let i=0;i<8;i++){let next=Array.from(document.querySelectorAll('[data-label-id]')).map(el=>el.getBBox().width).join(',');if(next===last)return;last=next;await new Promise(r=>requestAnimationFrame(r));}throw new Error('Text layout did not stabilize');})()`);
+      const labels = await session.evaluate(`Array.from(document.querySelectorAll('[data-label-id]')).map(el=>{const r=el.getBBox();return {id:el.getAttribute('data-label-id'),x:r.x,y:r.y,width:r.width,height:r.height,fontFamily:getComputedStyle(el).fontFamily,fontSize:getComputedStyle(el).fontSize};})`);
+      const png = await session.screenshot(dimensions.width, dimensions.height, scale);
+      return { png, labels };
+    });
+    if (result.png.length < 24 || result.png.readUInt32BE(16) !== Math.ceil(dimensions.width * scale) || result.png.readUInt32BE(20) !== Math.ceil(dimensions.height * scale)) throw usageError("Browser raster export failed: unexpected image dimensions.");
+    if(manifest) {
+      const measured=/** @type {LabelRect[]} */ (result.labels);
+      const missing=(manifest.labels??[]).filter(label=>!measured.some(actual=>actual.id===label.id));
+      if(missing.length) throw usageError("Browser measurement missing manifest labels: "+missing.map(label=>label.id).join(", "));
+    }
+    if (JPEG_FORMATS.has(format)) {
+      const temp = fs.mkdtempSync(path.join(os.tmpdir(), "fec-diagram-jpeg-"));
+      try { const pngPath = path.join(temp, "image.png"); fs.writeFileSync(pngPath, result.png); convertPngToJpeg(pngPath, outputPath); } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+    } else fs.writeFileSync(outputPath, result.png);
+    if (manifest) {
+      manifest.labels = (manifest.labels ?? []).map((label) => ({ ...label, .../** @type {LabelRect[]} */ (result.labels).find((actual) => actual.id === label.id) }));
+      manifest.measurement = "browser";
+      if (args["output-manifest"]) fs.writeFileSync(path.resolve(args["output-manifest"]), JSON.stringify(scaleManifest(manifest, scale), null, 2) + "\n");
+    }
+    /** @type {Array<{code:string,message:string}>} */
+    const boundaryIssues=[];
+    if(manifest) analyzeManifest({width:Math.ceil(dimensions.width*scale),height:Math.ceil(dimensions.height*scale)},scaleManifest(manifest,scale),boundaryIssues,new Set(),false);
+    if (args["qa-report"]) fs.writeFileSync(path.resolve(args["qa-report"]), JSON.stringify({ status: boundaryIssues.length ? "partial" : "measured", issues:boundaryIssues, measurement: "browser", theme, width: dimensions.width * scale, height: dimensions.height * scale, note: "Run PNG QA and inspect the final image; browser measurement alone is not approval." }, null, 2) + "\n");
+  }
+
+  console.log(`Exported ${format.toUpperCase()} diagram: ${outputPath}`);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Record<string, string | undefined>}
+ */
+function parseArgs(argv) {
+  /** @type {Record<string, string | undefined>} */
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      throw usageError(`Unexpected positional argument "${token}".`);
+    }
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+      throw usageError(`Missing value for --${key}.`);
+    }
+    parsed[key] = value;
+    index += 1;
+  }
+  return parsed;
+}
+
+/**
+ * @param {Record<string, string | undefined>} args
+ * @param {string} key
+ */
+function requireArg(args, key) {
+  const value = args[key];
+  if (!value) throw usageError(`Missing required --${key}.`);
+  return value;
+}
+
+/**
+ * @param {string} value
+ */
+function parseScale(value) {
+  const scale = Number(value);
+  if (!Number.isFinite(scale) || scale <= 0) {
+    throw usageError("--scale must be a positive number.");
+  }
+  return scale;
+}
+
+/**
+ * @param {string} inputPath
+ * @param {string} format
+ * @param {string | undefined} output
+ */
+function resolveOutputPath(inputPath, format, output) {
+  if (output) return output;
+  const extension = JPEG_FORMATS.has(format) ? ".jpg" : `.${format}`;
+  return inputPath.replace(/\.[^.\\/]+$/, "") + extension;
+}
+
+/**
+ * @param {string} inputPath
+ */
+function extractSvg(inputPath) {
+  const content = fs.readFileSync(inputPath, "utf8");
+  if (inputPath.toLowerCase().endsWith(".svg")) {
+    if (!/<svg[\s>]/i.test(content)) {
+      throw usageError("SVG input does not contain an <svg> root.");
+    }
+    return content;
+  }
+
+  const svgStart = content.search(/<svg[\s>]/i);
+  if (svgStart === -1) {
+    throw usageError("HTML input does not contain an inline <svg> element.");
+  }
+  const afterStart = content.slice(svgStart);
+  const svgEnd = afterStart.search(/<\/svg>/i);
+  if (svgEnd === -1) {
+    throw usageError("HTML input contains an <svg> start tag without a closing </svg>.");
+  }
+  return afterStart.slice(0, svgEnd + "</svg>".length);
+}
+
+/**
+ * @param {string} svg
+ * @param {string} outputPath
+ * @param {string} format
+ * @param {number} scale
+ * @param {string} background
+ */
+/**
+ * @param {string} pngPath
+ * @param {string} outputPath
+ */
+function convertPngToJpeg(pngPath, outputPath) {
+  const converters = [
+    () => convertWithMagick(pngPath, outputPath),
+    () => convertWithFfmpeg(pngPath, outputPath),
+    () => process.platform === "win32" ? convertWithPowerShell(pngPath, outputPath) : false,
+    () => process.platform === "darwin" ? convertWithSips(pngPath, outputPath) : false,
+  ];
+
+  for (const convert of converters) {
+    try {
+      if (convert() && fs.existsSync(outputPath) && fs.statSync(outputPath).size > 0) return;
+    } catch {
+      // Try the next system converter.
+    }
+  }
+
+  throw usageError("JPG/JPEG export needs a local image converter after Chromium captures the SVG. Install ImageMagick, FFmpeg, macOS sips, or use SVG/PNG output.");
+}
+
+/**
+ * @param {string} pngPath
+ * @param {string} outputPath
+ */
+function convertWithMagick(pngPath, outputPath) {
+  for (const command of ["magick", "convert"]) {
+    const result = spawnSync(command, [pngPath, "-background", "white", "-alpha", "remove", "-quality", "95", outputPath], {
+      encoding: "utf8",
+      timeout: 15000,
+      windowsHide: true,
+    });
+    if (result.status === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} pngPath
+ * @param {string} outputPath
+ */
+function convertWithFfmpeg(pngPath, outputPath) {
+  const result = spawnSync("ffmpeg", ["-y", "-i", pngPath, "-q:v", "2", outputPath], {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true,
+  });
+  return result.status === 0;
+}
+
+/**
+ * @param {string} pngPath
+ * @param {string} outputPath
+ */
+function convertWithPowerShell(pngPath, outputPath) {
+  const script = [
+    "Add-Type -AssemblyName System.Drawing",
+    `$img = [System.Drawing.Image]::FromFile(${quotePowerShell(pngPath)})`,
+    "$bmp = New-Object System.Drawing.Bitmap $img.Width, $img.Height",
+    "$graphics = [System.Drawing.Graphics]::FromImage($bmp)",
+    "$graphics.Clear([System.Drawing.Color]::White)",
+    "$graphics.DrawImage($img, 0, 0, $img.Width, $img.Height)",
+    `$bmp.Save(${quotePowerShell(outputPath)}, [System.Drawing.Imaging.ImageFormat]::Jpeg)`,
+    "$graphics.Dispose(); $bmp.Dispose(); $img.Dispose()",
+  ].join("; ");
+  const result = spawnSync("powershell", ["-NoProfile", "-Command", script], {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true,
+  });
+  return result.status === 0;
+}
+
+/**
+ * @param {string} pngPath
+ * @param {string} outputPath
+ */
+function convertWithSips(pngPath, outputPath) {
+  fs.copyFileSync(pngPath, outputPath);
+  const result = spawnSync("sips", ["-s", "format", "jpeg", outputPath, "--out", outputPath], {
+    encoding: "utf8",
+    timeout: 15000,
+  });
+  return result.status === 0;
+}
+
+/**
+ * @param {string} value
+ */
+function quotePowerShell(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+/**
+ * @param {string} svg
+ */
+function measureSvg(svg) {
+  const openTag = svg.match(/<svg\b[^>]*>/i)?.[0] ?? "";
+  const width = numberAttr(openTag, "width");
+  const height = numberAttr(openTag, "height");
+  if (width && height) return { width, height };
+
+  const viewBox = openTag.match(/\bviewBox=(["'])(.*?)\1/i)?.[2]?.trim().split(/\s+/).map(Number);
+  if (viewBox && viewBox.length === 4 && viewBox.every(Number.isFinite)) {
+    return { width: viewBox[2], height: viewBox[3] };
+  }
+  return { width: 1280, height: 720 };
+}
+
+/**
+ * @param {string} tag
+ * @param {string} name
+ */
+function numberAttr(tag, name) {
+  const value = tag.match(new RegExp(`\\b${name}=(["'])(.*?)\\1`, "i"))?.[2];
+  if (!value) return null;
+  const number = Number.parseFloat(value);
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+/**
+ * @param {string} svg
+ * @param {number} width
+ * @param {number} height
+ * @param {number} scale
+ * @param {string} background
+ */
+function renderScreenshotHtml(svg, width, height, scale, background) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<style>
+html, body {
+  margin: 0;
+  width: ${Math.ceil(width * scale)}px;
+  height: ${Math.ceil(height * scale)}px;
+  overflow: hidden;
+  background: ${background};
+}
+svg {
+  display: block;
+  width: ${Math.ceil(width * scale)}px;
+  height: ${Math.ceil(height * scale)}px;
+}
+</style>
+</head>
+<body>${svg}</body>
+</html>
+`;
+}
+
+/**
+ * @param {string} message
+ */
+function usageError(message) {
+  return new Error(message);
+}
+
+/** @param {Manifest} manifest @param {number} scale */
+function scaleManifest(manifest, scale) {
+  /** @param {LabelRect} r */
+  const rect = (r) => ({ ...r, x: r.x * scale, y: r.y * scale, width: r.width * scale, height: r.height * scale });
+  return { ...manifest, coordinateSpace: "png", scale, canvas: { width: Math.ceil(manifest.canvas.width * scale), height: Math.ceil(manifest.canvas.height * scale) }, boxes: manifest.boxes.map(rect), groups: (manifest.groups ?? []).map(rect), labels: (manifest.labels ?? []).map(rect), connectors: manifest.connectors.map((c) => ({ ...c, points: c.points.map(([x, y]) => [x * scale, y * scale]) })) };
+}