@bovinphang/frontend-craft 2.8.0 → 2.9.0

package/skills/fec-image-generation/references/diagram-workflows.md

@@ -7,10 +7,10 @@
 | ER diagram | Mermaid ER, DBML, Graphviz, SVG | Cardinality labels, table names, key fields, crossing relations. |
 | UML class | Mermaid class, PlantUML, Graphviz | Inheritance direction, method/property wrapping, package grouping. |
 | Sequence | Mermaid sequence, PlantUML | Lifeline order, activation spans, async/return arrows, message text. |
-| Technical architecture | HTML `architecture` IR, Mermaid flowchart, C4/Structurizr, SVG/HTML, draw.io | Layer grouping, trust boundaries, data flow direction, legends. |
+| Technical architecture | draw.io, Mermaid/C4, HTML `architecture` IR, SVG/HTML | Layer grouping, trust boundaries, data flow direction, legends. |
 | Agent / memory architecture | HTML `architecture` IR with semantic node types and flow arrows, SVG/HTML, draw.io | Read/write path separation, tool-call loops, memory tiers, retrieval labels, flow legend. |
 | ML / deep learning | SVG/HTML/canvas | Tensor shapes, layer order, branch joins, repeated blocks, annotations. |
-| Flowchart / process workflow | HTML `workflow` IR, Mermaid flowchart, SVG, draw.io | Decision labels, terminal states, loop-back readability, connector spacing, exception path clarity. |
+| Flowchart / process workflow | Mermaid flowchart, HTML `workflow` IR, SVG, draw.io | Decision labels, terminal states, loop-back readability, connector spacing, exception path clarity. |
 | Live session sketch | Interactive local browser server | Incremental reveal, session isolation, readable labels after manual dragging, export handoff. |
 
 ## Interactive live diagrams
@@ -50,7 +50,7 @@ Coordinates are PNG pixel coordinates after export. Boxes should cover visible l
 ## Diagram repair playbook
 
 - **Overlapping nodes:** increase rank/column spacing, split clusters, or move low-priority annotations into a legend.
-- **Truncated labels:** widen the node, add manual line breaks, reduce label length, or increase export scale.
+- **Truncated labels:** widen the node, add manual line breaks, preserve the full text, and adjust source layout.
 - **Connector through labels:** add waypoints, route orthogonally around boxes, or move labels above the segment.
 - **Connector stacking:** separate parallel edges with different waypoints or bundle them with a shared labeled bus.
 - **Edge clipping:** increase outer padding or export viewBox/canvas size.
@@ -72,3 +72,10 @@ Use HTML `workflow` IR when the user wants a browser-ready process map, approval
 ## Export guidance
 
 Prefer exporting at 2x scale for raster PNGs, then downsample only if text remains crisp. Keep the editable source committed or attached wherever future diagram changes are expected.
+
+
+## Quality delivery contract
+
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse fec-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+
+The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

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

@@ -226,7 +226,7 @@ node skills/fec-image-generation/scripts/png-qa.mjs \
 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.
+- Truncated label: wrap complete labels, preserve text, 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.
@@ -234,3 +234,10 @@ Repair the source JSON or rendering dimensions rather than editing pixels:
 ## 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.
+
+
+## Quality delivery contract
+
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse fec-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+
+The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

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

@@ -14,9 +14,9 @@
 | ----- | ------ |
 | `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-overlap` | Increase spacing, reflow to grid/layers, split clusters, or wrap complete 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. |
+| `label-overflow` | Wrap text, widen the box, preserve complete copy, and 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. |
@@ -28,3 +28,10 @@ The helper can only reason about overlaps and connectors when the manifest coord
 ## 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.
+
+
+## Quality delivery contract
+
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse fec-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+
+The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

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

@@ -0,0 +1,90 @@
+// @ts-check
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export function findBrowser() {
+  const candidates = [process.env.FEC_BROWSER_PATH,
+    "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Google/Chrome/Application/chrome.exe",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "google-chrome", "chromium", "chromium-browser", "msedge", "brave-browser", "vivaldi"];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (path.isAbsolute(candidate) ? fs.existsSync(candidate) : spawnSync(candidate, ["--version"], { timeout: 5000, windowsHide: true, stdio: "ignore" }).status === 0) return candidate;
+  }
+  return null;
+}
+
+/** @typedef {{evaluate:(expression:string)=>Promise<unknown>,screenshot:(width:number,height:number,scale?:number)=>Promise<Buffer>}} DiagramSession */
+
+/** @template T @param {string} html @param {{theme:'light'|'dark',timeoutMs:number}} options @param {(session:DiagramSession)=>Promise<T>} action @returns {Promise<T>} */
+export async function withDiagramPage(html, options, action) {
+  const browser = findBrowser();
+  if (!browser) throw new Error("PNG/JPG export requires a local Chromium browser. Export SVG instead, or install a Chromium browser and rerun this command.");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-diagram-browser-"));
+  const page = path.join(dir, "diagram.html"), profile = path.join(dir, "profile");
+  fs.writeFileSync(page, html);
+  const child = spawn(browser, ["--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check", "--hide-scrollbars", "--remote-debugging-port=0", "--remote-allow-origins=http://localhost", `--user-data-dir=${profile}`, pathToFileURL(page).href], { windowsHide: true, stdio: "ignore" });
+  let childError = "";
+  child.on("error", (error) => { childError = error.message; });
+  /** @type {WebSocket | undefined} */
+  let socket;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  try {
+    const work = async () => {
+    const deadline = Date.now() + Math.min(5000, options.timeoutMs);
+    const portFile = path.join(profile, "DevToolsActivePort");
+    while (!fs.existsSync(portFile) && Date.now() < deadline && (child.exitCode === null || child.exitCode === 0) && !childError) await new Promise((resolve) => setTimeout(resolve, 50));
+    if (!fs.existsSync(portFile)) throw new Error(`Browser raster export failed: browser did not start a debugging session${childError ? ` (${childError})` : ""}.`);
+    const port = Number(fs.readFileSync(portFile, "utf8").split("\n")[0]);
+    const pages = await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(Math.min(5000, options.timeoutMs)) })).json();
+    const target = pages.find(/** @param {{type:string}} p */ (p) => p.type === "page");
+    if (!target?.webSocketDebuggerUrl) throw new Error("Browser did not create a diagram page.");
+    socket = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => { socket?.addEventListener("open", resolve, { once: true }); socket?.addEventListener("error", reject, { once: true }); });
+    /** @type {Map<number,{resolve:(value:Record<string,unknown>)=>void,reject:(reason:Error)=>void}>} */
+    const pending = new Map();
+    socket.addEventListener("close", () => { for (const entry of pending.values()) entry.reject(new Error("Browser session closed before export completed.")); pending.clear(); });
+    let serial = 0;
+    socket.addEventListener("message", (event) => {
+      const message = JSON.parse(String(event.data));
+      const entry = pending.get(message.id);
+      if (!entry) return;
+      pending.delete(message.id);
+      if (message.error) entry.reject(new Error(message.error.message)); else entry.resolve(message.result ?? {});
+    });
+    /** @param {string} method @param {Record<string,unknown>} [params] @returns {Promise<Record<string,unknown>>} */
+    const call = (method, params = {}) => new Promise((resolve, reject) => { const id = ++serial; pending.set(id, { resolve, reject }); socket?.send(JSON.stringify({ id, method, params })); });
+    /** @param {string} expression */
+    const evaluate = async (expression) => {
+      const result = await call("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+      if (result.exceptionDetails) throw new Error(`Diagram evaluation failed: ${JSON.stringify(result.exceptionDetails)}`);
+      return /** @type {{value?:unknown}} */ (result.result).value;
+    };
+    /** @type {DiagramSession} */
+    const session = { evaluate, screenshot: async (width, height, scale = 1) => {
+      await call("Emulation.setDeviceMetricsOverride", { width: Math.ceil(width), height: Math.ceil(height), deviceScaleFactor: scale, mobile: false });
+      const result = await call("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, clip: { x: 0, y: 0, width, height, scale: 1 } });
+      return Buffer.from(String(result.data), "base64");
+    } };
+    await evaluate(`(async()=>{if(document.readyState!=="complete")await new Promise(r=>window.addEventListener("load",r,{once:true}));await document.fonts.ready;await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));})()`);
+    return await action(session);
+    };
+    return await Promise.race([work(), new Promise(/** @param {(reason:Error)=>void} reject */ (_, reject) => { timer = setTimeout(() => reject(new Error("Browser export timed out.")), options.timeoutMs); })]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ id: 999999, method: "Browser.close" }));
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    socket?.close();
+    child.kill();
+    // The Chromium profile is owned by this invocation only. Windows may release locks after exit.
+    await new Promise((resolve) => setTimeout(resolve, 120));
+    try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* A locked temporary profile can be removed by OS cleanup. */ }
+  }
+}

package/skills/fec-image-generation/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/fec-image-generation/scripts/export-diagram.mjs

@@ -1,11 +1,14 @@
 #!/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";
-import { pathToFileURL } from "node:url";
+/** @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"]);
@@ -15,7 +18,7 @@ try {
   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";
+  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.`);
@@ -24,14 +27,48 @@ try {
     throw usageError(`Input file does not exist: ${inputPath}`);
   }
 
-  const svg = extractSvg(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 {
-    exportRaster(svg, outputPath, format, scale, background);
+    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}`);
@@ -126,51 +163,6 @@ function extractSvg(inputPath) {
  * @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
@@ -259,37 +251,6 @@ function convertWithSips(pngPath, outputPath) {
   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
  */
@@ -362,3 +323,10 @@ svg {
 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]) })) };
+}

package/skills/fec-image-generation/scripts/mermaid-render.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// @ts-check
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+// Use installed tools only. Never invoke npx or a shell that could download packages.
+try {
+  /** @type {Record<string,string>} */
+  const args = {};
+  for (let i = 2; i < process.argv.length; i += 2) {
+    const key = process.argv[i];
+    if (!key.startsWith("--") || !process.argv[i + 1]) throw new Error("Expected --input source.mmd --output image.svg [--cli path] [--theme default|dark|neutral|forest] [--timeout 30000] [--report file.json]");
+    if (!["input", "output", "cli", "theme", "timeout", "report", "format"].includes(key.slice(2))) throw new Error(`Unknown argument: ${key}`);
+    args[key.slice(2)] = process.argv[i + 1];
+  }
+  if (!args.input || !args.output) throw new Error("--input and --output are required.");
+  const input = path.resolve(args.input), output = path.resolve(args.output);
+  if (!fs.existsSync(input)) throw new Error(`Input does not exist: ${input}`);
+  if (!/\.(svg|png|pdf)$/i.test(output)) throw new Error("Output must end in .svg, .png or .pdf.");
+  const theme = args.theme === "light" ? "default" : args.theme ?? "default";
+  if (args.format && !["json","markdown"].includes(args.format)) throw new Error("--format must be json or markdown");
+  if (!["default", "dark", "neutral", "forest"].includes(theme)) throw new Error("Unsupported Mermaid theme.");
+  const timeout = Number(args.timeout ?? 30000);
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 300000) throw new Error("--timeout must be between 100 and 300000 milliseconds.");
+  /** @type {string[]} */
+  const candidates = args.cli ? [path.resolve(args.cli)] : (process.env.PATH ?? "").split(path.delimiter).flatMap((dir) => [path.join(dir, "mmdc"), path.join(dir, "mmdc.cmd")]);
+  let cli = candidates.find((candidate) => fs.existsSync(candidate));
+  if (cli?.endsWith(".cmd")) {
+    // npm Windows shims are shell scripts. Execute their installed JS entry directly.
+    const entry = path.join(path.dirname(cli), "node_modules", "@mermaid-js", "mermaid-cli", "src", "cli.js");
+    cli = fs.existsSync(entry) ? entry : undefined;
+  }
+  if (!cli) throw new Error("Mermaid CLI unavailable. Use the JSON/HTML renderer or provide an installed mmdc JS entry with --cli. No packages were installed.");
+  const js = /\.[cm]?js$/i.test(cli);
+  const command = js ? process.execPath : cli;
+  const prefix = js ? [cli] : [];
+  const version = spawnSync(command, [...prefix, "--version"], { encoding: "utf8", timeout, windowsHide: true });
+  if (version.error || version.status !== 0) throw new Error(`Mermaid CLI unavailable: ${version.error?.message ?? version.stderr}`);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-mermaid-"));
+  try {
+    const artifact = path.join(dir, `diagram${path.extname(output)}`);
+    const result = spawnSync(command, [...prefix, "-i", input, "-o", artifact, "-t", theme], { encoding: "utf8", timeout, windowsHide: true });
+    if (result.error || result.status !== 0) throw new Error(`Mermaid render failed: ${result.error?.message ?? result.stderr}`);
+    if (!fs.existsSync(artifact) || fs.statSync(artifact).size === 0) throw new Error("Mermaid render failed: no fresh artifact produced.");
+    const bytes = fs.readFileSync(artifact);
+    if (output.endsWith(".svg") && !bytes.toString("utf8").includes("<svg")) throw new Error("Mermaid render failed: invalid SVG.");
+    if (output.endsWith(".png") && bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") throw new Error("Mermaid render failed: invalid PNG.");
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.copyFileSync(artifact, output);
+    if (args.report) {
+      fs.mkdirSync(path.dirname(path.resolve(args.report)), { recursive: true });
+      fs.writeFileSync(args.report, JSON.stringify({ ok:true,engine:"mermaid",format:path.extname(output).slice(1),verified:false,route: "mermaid", version: version.stdout.trim(), input, output, theme, status: "rendered", visualQA: "pending" }, null, 2) + "\n");
+    }
+    const report = {ok:true,engine:"mermaid",version:version.stdout.trim(),input,output,format:path.extname(output).slice(1),verified:false,reason:"Final image visual QA is pending."};
+    console.log(args.format === "json" ? JSON.stringify(report) : `Rendered Mermaid diagram: ${output}\nVisual QA: pending`);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}