@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/skills/fec-image-generation/references/html-technical-diagrams.md

@@ -0,0 +1,236 @@
+# HTML Technical Diagrams
+
+Use this route when a technical diagram should be easy to open in a browser, share as one file, switch dark/light themes, and export from the browser after visual QA.
+
+This route complements, but does not replace, other diagram sources:
+
+| Need | Prefer |
+| ---- | ------ |
+| Small markdown-maintained diagram | Mermaid, Graphviz, or SVG |
+| Editable source for future manual changes | `fec-drawio-studio` and `.drawio` |
+| Browser-ready themed technical diagram | HTML technical diagram route |
+| Raster-first visual, poster, concept art, or image edit | Image generation or editing route |
+
+## Supported Diagram Intents
+
+- `architecture`: system topology, system blueprints, deployment topology, cloud regions, trust boundaries, clients, gateways, services, data stores, event buses, auth flows, agent runtime maps, memory or recall overview diagrams, before/after architecture comparisons, and infrastructure overview diagrams.
+- `workflow`: ownership lanes, process maps, approval gates, automation runs, exception paths, cyclical loops, runbooks, CI/CD, incident response, tool calls, and request lifecycles.
+- `sequence`: participants over time, API call chains, cache fallback, auth checks, async traces, and return messages.
+- `dataflow`: sources, ingest, processing, storage, consumers, PII boundaries, governance, analytics, and lineage.
+- `lifecycle`: object states, terminal states, retries, waits, cancellation, timeout, deployment or order status transitions.
+
+Use the `architecture` mode for browser-ready overview diagrams with explicit coordinates. Use `fec-drawio-studio` instead when the priority is `.drawio` source, official vendor icons, diagrams.net manual editing, or complex auto-layout.
+
+## Themed Semantic Diagrams
+
+Use `visual.style` when the same JSON source needs a clearer delivery tone without changing its model: `default`, `terminal`, `blueprint`, `minimal`, `glass`, `warm`, `openai`, or `editorial-dark`.
+
+For agent, memory, and AI workflow maps, prefer architecture nodes with semantic `type` values:
+
+- Actors and entry points: `user`, `browser`, `gateway`.
+- Intelligence and orchestration: `agent`, `model`, `tool`.
+- Memory and knowledge: `memory`, `vectorstore`, `graphdb`, `document`.
+- Runtime movement: `queue`, `messagebus`, `backend`, `external`.
+
+Use connection `flow` values when arrows need meaning beyond visual direction:
+
+- `control`: orchestration, policy, trigger, or command.
+- `data`: request payloads, documents, embeddings, facts, or responses.
+- `read`: retrieval from memory or stores.
+- `write`: persistence, indexing, notes, or memory updates.
+- `async`: evented or queued work.
+- `feedback`: loops, retries, refinement, or reasoning cycles.
+
+When two or more flow types are present, the renderer emits a flow legend automatically. Keep arrow labels short and use `waypoints` to route around dense groups, title labels, and node interiors.
+
+## System Blueprint Workflow
+
+Use the architecture route for presentation-ready system blueprints, deployment topology, integration maps, agent runtime views, memory or recall maps, and before/after architecture comparisons. First extract a compact system model, then draw:
+
+- Entry surfaces: browsers, mobile clients, CLIs, webhooks, schedulers, or agent/session entry points.
+- Application layer: gateways, frontend apps, backend services, workers, orchestration, runtime hosts, and tool adapters.
+- Data layer: databases, object stores, caches, vector stores, queues, event buses, logs, and analytics stores.
+- External dependencies: identity providers, AI models, payment/email services, SaaS APIs, cloud services, design tools, or runtime connectors.
+- Identity and trust boundaries: auth, permissions, PII zones, tenant boundaries, private networks, secret stores, and policy checks.
+- Key flows: request/control flow, data flow, event flow, deployment flow, recall/memory flow, or before/after migration flow.
+
+Keep the first blueprint readable:
+
+- Show 4-10 primary nodes and collapse low-value files, classes, or endpoints into grouped nodes.
+- Use 1-3 group boundaries for layers, trust zones, runtime environments, or ownership domains.
+- Include a short title and subtitle that work when the file is shared outside the original conversation.
+- Use a legend or up to three summary cards for runtime, data, trust, risks, inputs, or outcomes.
+- Prefer semantic color roles over decorative styling, and split into multiple diagrams when connectors or labels become dense.
+
+For README or stakeholder handoff, keep the JSON IR and HTML as the editable source, then export SVG/PNG/JPG artifacts:
+
+```bash
+node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format svg
+node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format png --scale 2
+```
+
+Raster export uses an existing Chromium-family browser when available. If the environment cannot rasterize SVG, deliver the generated HTML/SVG and state that PNG/JPG export needs a local browser.
+
+## JSON IR
+
+All modes require:
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Release Workflow",
+    "subtitle": "PR to production"
+  }
+}
+```
+
+Mode-specific minimum fields:
+
+- `architecture`: `nodes`, `connections`; optional `groups`, `legend`, and `summary`.
+- `workflow`: `lanes`, `nodes`, `edges`; optional `summary`.
+- `sequence`: `participants`, `messages`.
+- `dataflow`: `stages`, `nodes`, `flows`.
+- `lifecycle`: `lanes`, `states`, `transitions`.
+
+IDs must start with a letter and use only letters, numbers, `_`, and `-`. Keep labels short enough to read inside nodes; put long explanation in surrounding prose instead of the diagram.
+
+## Process Workflow IR
+
+Workflow mode is for ordered processes where ownership, decisions, branches, and loop-backs matter more than exact infrastructure topology. Use lanes for actors or systems, nodes for steps, and edges for outcomes. Nodes still support explicit `col` placement so authors can control reading order without relying on a hidden auto-layout engine.
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Procurement Approval",
+    "subtitle": "Request to payment"
+  },
+  "lanes": [
+    { "id": "requester", "label": "Requester" },
+    { "id": "system", "label": "System" },
+    { "id": "manager", "label": "Manager" }
+  ],
+  "nodes": [
+    { "id": "start", "lane": "requester", "col": 0, "type": "start", "label": "Submit Request", "actor": "Employee" },
+    { "id": "classify", "lane": "system", "col": 1, "type": "active", "label": "Classify Spend", "actor": "Policy Engine", "sublabel": "auto rules" },
+    { "id": "review", "lane": "manager", "col": 2, "type": "decision", "label": "Approved?", "step": "A" },
+    { "id": "pay", "lane": "system", "col": 3, "type": "success", "label": "Issue Payment" },
+    { "id": "reject", "lane": "requester", "col": 3, "type": "failure", "label": "Return Request" }
+  ],
+  "edges": [
+    { "from": "start", "to": "classify", "label": "intake", "variant": "emphasis" },
+    { "from": "classify", "to": "review", "label": "policy result" },
+    { "from": "review", "to": "pay", "label": "yes", "variant": "emphasis" },
+    { "from": "review", "to": "reject", "label": "no", "variant": "return", "waypoints": [[650, 396], [520, 396]] }
+  ],
+  "summary": [
+    { "title": "Inputs", "type": "active", "items": ["Purchase request", "Policy threshold"] },
+    { "title": "Outcomes", "type": "success", "items": ["Payment issued", "Requester notified"] }
+  ]
+}
+```
+
+Workflow node fields:
+
+- `type`: use `start`, `active`, `waiting`, `decision`, `success`, `failure`, or `external` for process semantics.
+- `actor`: optional short owner or system label above the node.
+- `step`: optional displayed step marker. If omitted, workflow nodes receive sequential markers automatically.
+- `sublabel`, `width`, `height`, and `yOffset`: optional readability adjustments for dense lanes.
+
+Workflow edge fields:
+
+- `variant`: use `emphasis` for happy paths, `return` or `dashed` for loop-backs and rework, and `security` only for trust or policy checks.
+- `waypoints`: optional `[x, y]` points for exception paths, cross-row links, or loops that should avoid labels and nodes.
+
+Use `summary` for compact process metadata such as prerequisites, inputs/outputs, or tools. Keep long explanations outside the SVG so labels remain readable.
+
+## Architecture IR
+
+Architecture mode uses explicit coordinates because system diagrams often need intentional placement, boundaries, and trust zones:
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "SaaS Architecture",
+    "subtitle": "Browser-ready infrastructure overview"
+  },
+  "visual": {
+    "style": "blueprint"
+  },
+  "groups": [
+    { "id": "cloud", "label": "Cloud region", "type": "cloud", "x": 170, "y": 50, "width": 620, "height": 280 }
+  ],
+  "nodes": [
+    { "id": "web", "label": "Web App", "type": "frontend", "x": 48, "y": 160, "sublabel": "React" },
+    { "id": "api", "label": "API Gateway", "type": "cloud", "x": 230, "y": 160, "group": "cloud" },
+    { "id": "svc", "label": "App Service", "type": "backend", "x": 420, "y": 160, "group": "cloud" },
+    { "id": "db", "label": "PostgreSQL", "type": "database", "x": 620, "y": 160, "group": "cloud" }
+  ],
+  "connections": [
+    { "from": "web", "to": "api", "label": "HTTPS", "variant": "emphasis" },
+    { "from": "api", "to": "svc", "label": "REST" },
+    { "from": "svc", "to": "db", "label": "SQL" }
+  ],
+  "summary": [
+    { "title": "Runtime", "type": "backend", "items": ["API and worker services", "Managed relational data"] }
+  ]
+}
+```
+
+Supported node and group types include `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`, `agent`, `model`, `memory`, `vectorstore`, `graphdb`, `tool`, `document`, `queue`, `browser`, `user`, and `gateway`. Connections support the standard variants `default`, `emphasis`, `security`, `dashed`, and `return`; architecture connections may also include `flow`. Add `waypoints` as `[[x, y], ...]` when a connection needs to route around boundaries or labels.
+
+Architecture output includes an automatic legend unless `legend` is set to `false`. A custom legend can be supplied as `{ "label": "...", "type": "..." }` items. `summary` renders up to three cards below the SVG and is not included in the layout manifest, so PNG QA focuses on the diagram itself.
+
+## Architecture Layout Rules
+
+- Draw groups as broad boundaries around components, not as decorative panels.
+- Keep legends below or outside all boundaries; increase the coordinates and view area rather than squeezing content.
+- Use `messagebus` nodes for event buses and place them in the gap between services.
+- Use `security` connections for auth, token, policy, or trust-boundary flows.
+- Prefer `waypoints` over dense crossing lines when gateways fan out to several services.
+- Split the diagram when the overview needs more than one dense cluster or when label readability depends on shrinking text.
+
+## Render Command
+
+```bash
+node skills/fec-image-generation/scripts/tech-diagram-render.mjs \
+  --input diagram.json \
+  --output diagram.html \
+  --type architecture \
+  --manifest diagram.layout.json
+```
+
+The generated HTML is self-contained and includes:
+
+- Inline SVG.
+- CSS-variable dark/light theme.
+- Browser controls for theme toggle, SVG download, and print/PDF.
+- Optional layout manifest for PNG QA.
+
+## QA and Repair
+
+After exporting a PNG from the browser, run:
+
+```bash
+node skills/fec-image-generation/scripts/png-qa.mjs \
+  --png diagram.png \
+  --manifest diagram.layout.json \
+  --format markdown
+```
+
+Repair the source JSON or rendering dimensions rather than editing pixels:
+
+- Overlap: split dense lanes or add rows/lanes/stages.
+- Truncated label: shorten labels, add `sublabel`, or widen nodes.
+- Connector through label: reduce edge labels or separate nearby nodes.
+- Dense flow: split into overview and detail diagrams.
+- Edge clipping: increase output space or simplify the path.
+
+## Delivery Notes
+
+Deliver the `.html` source together with any exported SVG/PNG/JPG requested by the user. Report the route used, source file, exported file, QA result, and any naming or domain assumptions that still need human confirmation.

package/skills/fec-image-generation/references/png-qa-autofix.md

@@ -0,0 +1,30 @@
+# PNG QA And Autofix
+
+## Loop
+
+1. Export PNG from the editable source or image workflow.
+2. Inspect the PNG visually.
+3. Run `png-qa.mjs` with a manifest when available.
+4. Convert each issue into source, prompt, or layout changes.
+5. Repeat for 2 rounds by default, up to 5 when the user asks for more repair attempts.
+
+## Issue mapping
+
+| Issue | Repair |
+| ----- | ------ |
+| `blank-image` | Check export target, renderer errors, hidden layers, transparent fill, or failed image generation. |
+| `edge-clipping` | Add canvas padding, expand SVG viewBox, reduce subject scale, or export a larger frame. |
+| `box-overlap` | Increase spacing, reflow to grid/layers, split clusters, or shorten labels. |
+| `box-out-of-bounds` | Move the node inside canvas or increase canvas dimensions. |
+| `label-overflow` | Wrap text, widen the box, reduce copy, or increase font/container size together. |
+| `connector-through-label` | Add waypoints around boxes, move labels, or use orthogonal routing. |
+| `connector-stacking` | Offset parallel connectors or replace repeated lines with a labeled grouped path. |
+| `manifest-canvas-mismatch` | Regenerate the manifest from final export dimensions. |
+
+## Manifest quality
+
+The helper can only reason about overlaps and connectors when the manifest coordinates match the exported PNG. If the manifest is stale, repair the manifest first, then rerun QA.
+
+## Reporting
+
+Report the number of QA rounds and the final issue list. If issues remain because the source renderer cannot expose layout coordinates, say which checks were image-only and which require manual visual review.

package/skills/fec-image-generation/scripts/export-diagram.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+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 ?? "#0f172a";
+
+  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}`);
+  }
+
+  const svg = extractSvg(inputPath);
+  const outputPath = path.resolve(resolveOutputPath(inputPath, format, args.output));
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  if (format === "svg") {
+    fs.writeFileSync(outputPath, `${svg.trim()}\n`, "utf8");
+  } else {
+    exportRaster(svg, outputPath, format, scale, background);
+  }
+
+  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
+ */
+function exportRaster(svg, outputPath, format, scale, background) {
+  const browser = findBrowser();
+  if (!browser) {
+    throw usageError(
+      "PNG/JPG export requires a local Chromium browser (Chrome, Edge, Chromium, Brave, or Vivaldi) because Node.js has no built-in SVG rasterizer. Export SVG instead, or install a Chromium browser and rerun this command.",
+    );
+  }
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-diagram-export-"));
+  const htmlPath = path.join(tempDir, "diagram.html");
+  const screenshotPath = path.join(tempDir, "diagram.png");
+  const { width, height } = measureSvg(svg);
+  const viewportWidth = Math.ceil(width * scale);
+  const viewportHeight = Math.ceil(height * scale);
+
+  try {
+    fs.writeFileSync(htmlPath, renderScreenshotHtml(svg, width, height, scale, background), "utf8");
+
+    const result = spawnSync(browser, [
+      "--headless=new",
+      "--disable-gpu",
+      "--hide-scrollbars",
+      `--window-size=${viewportWidth},${viewportHeight}`,
+      `--screenshot=${screenshotPath}`,
+      pathToFileURL(htmlPath).href,
+    ], {
+      encoding: "utf8",
+      timeout: 30000,
+      windowsHide: true,
+    });
+
+    if (result.status !== 0 || !fs.existsSync(screenshotPath)) {
+      throw usageError(`Browser raster export failed: ${result.stderr || result.stdout || `exit code ${result.status}`}`.trim());
+    }
+
+    if (JPEG_FORMATS.has(format)) {
+      convertPngToJpeg(screenshotPath, outputPath);
+    } else {
+      fs.copyFileSync(screenshotPath, outputPath);
+    }
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * @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;
+}
+
+function findBrowser() {
+  const envBrowser = process.env.CHROME_PATH || process.env.EDGE_PATH || process.env.BROWSER;
+  const candidates = [
+    envBrowser,
+    process.platform === "win32" ? "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" : undefined,
+    process.platform === "win32" ? "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe" : undefined,
+    process.platform === "win32" ? "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe" : undefined,
+    process.platform === "win32" ? "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe" : undefined,
+    process.platform === "darwin" ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" : undefined,
+    process.platform === "darwin" ? "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" : undefined,
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "microsoft-edge",
+    "msedge",
+    "brave-browser",
+    "vivaldi",
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    if (path.isAbsolute(candidate) && fs.existsSync(candidate)) return candidate;
+    if (!path.isAbsolute(candidate)) {
+      const result = spawnSync(candidate, ["--version"], { encoding: "utf8", timeout: 5000, windowsHide: true });
+      if (result.status === 0) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * @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);
+}