@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/skills/fec-drawio-studio/references/data-residency.md

@@ -0,0 +1,27 @@
+# Data Residency
+
+Use this checklist when a diagram contains private architecture, unreleased product details, customer data or regulated information.
+
+## Local First
+
+- A `.drawio` file written in the workspace is the safest default artifact because it can be inspected, versioned and opened locally.
+- draw.io Desktop export runs on the local machine when the CLI is installed. If the CLI is missing, keep the source file and offer a URL fallback instead of sending the diagram to a cloud converter.
+- `diagram-lint.mjs`, `diagram-url.mjs`, `layout-graph.mjs`, `png-embed-fix.mjs` and code scanners run locally. Graphviz is optional and local when installed.
+
+## URL Modes
+
+- Viewer/editor `#R` URLs and `#create=` URLs place compressed diagram content in the URL fragment.
+- URL fragments are not sent to ordinary HTTP servers as request paths, but the browser still loads application code from the chosen diagrams.net host.
+- Very large diagrams can exceed practical browser URL limits. Fall back to a local `.drawio` file when the URL becomes unwieldy.
+- On Windows, open long diagram URLs through a `.url` shortcut file or use the JSON `windowsShortcut` output from `diagram-url.mjs`; passing the URL directly through `cmd start` can lose the fragment.
+
+## External Requests
+
+- Brand CDN symbols require network access when rendered unless embedded as data URIs.
+- diagrams.net web editor/viewer loads editor code and assets from the configured host.
+- A self-hosted diagrams.net base URL can be passed with `--base-url` when the environment requires a controlled endpoint.
+- Existing draw.io MCP App or Tool servers may be useful as preview surfaces, but they are optional and governed by the user's configured host and model provider.
+
+## Handoff Rule
+
+For sensitive diagrams, deliver the local `.drawio` source plus lint results first. Add PNG/SVG/PDF or URL outputs only when the user explicitly needs them and the data boundary is acceptable.

package/skills/fec-drawio-studio/references/diagram-patterns.md

@@ -0,0 +1,41 @@
+# Diagram Patterns
+
+Use these conventions when a user asks for a named technical diagram.
+
+## Architecture
+
+- Group nodes by tier: client, edge, service, data, external.
+- Use swimlanes or grouped containers when boundaries matter.
+- Put bus or event-stream nodes near the center of publisher/subscriber rows.
+- Use cylinders for databases, rounded rectangles for services, dashed outlines for external systems.
+
+## ERD
+
+- Model tables as containers with rows for columns.
+- Mark primary keys and foreign keys in labels.
+- Use dashed relationship edges when cardinality is not fully known.
+- Prefer top-to-bottom layout for schemas with multiple relation clusters.
+
+## UML Class
+
+- Use a class box split into name, fields and methods.
+- Use hollow triangle arrows for inheritance, dashed hollow triangle for interface implementation.
+- Keep interfaces or abstract bases above concrete classes.
+
+## Sequence
+
+- Lay participants left-to-right and time top-to-bottom.
+- Keep request, response and async message styles visually distinct.
+- Add activation boxes only when they clarify nested work.
+
+## ML / Deep Learning
+
+- Show tensor shape on a second line when it matters.
+- Group encoder, decoder, embedding, attention and output stages.
+- Route skip connections around the primary flow.
+
+## Flowchart
+
+- Use ovals for start/end, rectangles for process, diamonds for decisions.
+- Label decision branches.
+- Merge branches back to a central path when possible.

package/skills/fec-drawio-studio/references/layout-and-export.md

@@ -0,0 +1,57 @@
+# Layout And Export
+
+## Auto Layout
+
+Use `layout-graph.mjs` for dependency graphs, code structure maps and diagrams with more than about 15 nodes.
+
+```bash
+node skills/fec-drawio-studio/scripts/layout-graph.mjs graph.json --output diagram.drawio --manifest layout.json
+```
+
+Input graph:
+
+```json
+{
+  "direction": "TB",
+  "nodes": [
+    { "id": "client", "label": "Web Client", "group": "Client" },
+    { "id": "api", "label": "API", "group": "Service" }
+  ],
+  "edges": [
+    { "source": "client", "target": "api", "label": "HTTPS" }
+  ]
+}
+```
+
+Graphviz `dot` is optional. If it is missing, hand-place the diagram or deliver XML plus a diagrams.net URL.
+
+## Export
+
+Preview:
+
+```bash
+drawio -x -f png --width 2000 -o diagram.png diagram.drawio
+```
+
+Final editable PNG:
+
+```bash
+drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio
+node skills/fec-drawio-studio/scripts/png-embed-fix.mjs diagram.drawio.png
+```
+
+Fallback URL:
+
+```bash
+node skills/fec-drawio-studio/scripts/diagram-url.mjs diagram.drawio --edit
+```
+
+Create/import URL for XML, Mermaid or CSV:
+
+```bash
+node skills/fec-drawio-studio/scripts/diagram-url.mjs diagram.drawio --create --type xml --json
+node skills/fec-drawio-studio/scripts/diagram-url.mjs flow.mmd --create --type mermaid
+node skills/fec-drawio-studio/scripts/diagram-url.mjs org.csv --create --type csv --lightbox
+```
+
+Use `--base-url` for a self-hosted diagrams.net endpoint. Use `--shortcut` or the JSON `windowsShortcut` field when opening the URL through Windows shell tooling.

package/skills/fec-drawio-studio/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting
+
+## draw.io CLI Missing
+
+Generate the `.drawio` file and use `diagram-url.mjs --edit` to open diagrams.net in the browser.
+
+## Graphviz Missing
+
+`layout-graph.mjs` exits with a clear Graphviz message. Keep the graph JSON and either install Graphviz or hand-place a smaller diagram.
+
+## Blank Vendor Shape
+
+Run `shape-query.mjs` and use the returned style string. A guessed `shape=mxgraph.*` often renders as a generic box.
+
+## Brand Icon Does Not Render
+
+CDN-referenced symbols require network access during render. Use `brand-symbols.mjs --embed` for a self-contained data URI when portability matters.
+
+## Embedded PNG Looks Corrupt
+
+Run `png-embed-fix.mjs` after final `drawio -e` PNG export. The command is idempotent.
+
+## Browser URL Opens Blank On Windows
+
+Use `diagram-url.mjs --json` and open the emitted `windowsShortcut` content as a `.url` file, or run `diagram-url.mjs --shortcut`. This preserves the `#R` or `#create=` fragment that carries the compressed diagram.
+
+## Mermaid Or CSV URL Fails
+
+Mermaid and CSV must use `diagram-url.mjs --create --type mermaid|csv`. The older viewer/editor `#R` mode is XML-only.

package/skills/fec-drawio-studio/references/xml-and-mermaid.md

@@ -0,0 +1,54 @@
+# XML And Mermaid
+
+Use this reference to choose the lightest editable diagram source that still meets the user's maintenance and fidelity needs.
+
+## Route Choice
+
+- Use Mermaid for common flowcharts, sequence diagrams, class diagrams, state diagrams, ERDs, timelines, mind maps and other text-first diagrams that will live in Markdown.
+- Use draw.io XML when the diagram needs exact shapes, vendor symbols, nested containers, layers, tags, metadata, custom colors or a durable `.drawio` source.
+- Use CSV only as a short import path for tabular structures such as org charts or simple relationship maps; save the resulting editable source when possible.
+- Use URL creation for preview and handoff, not as the only artifact for important diagrams.
+
+## XML Structure
+
+- Include root cells `id="0"` and `id="1"` in every diagram.
+- Give every visible vertex and edge a stable unique id.
+- Put child nodes inside their visual container by setting `parent` to the container id and using coordinates relative to that container.
+- Put edges that cross container boundaries at `parent="1"` so they are not clipped by a lane or group.
+- Every edge must contain `<mxGeometry relative="1" as="geometry"/>`; do not use self-closing edge cells.
+
+## Containers And Process Layout
+
+- Use titled swimlanes for actor, tier or bounded-context groupings.
+- Use nested swimlanes for real hierarchy such as region, VPC, availability zone and workload.
+- Use a table layout for cross-functional flows where both actor rows and phase columns matter.
+- Use plain groups only when a visual boundary is unnecessary and the group should not capture connectors.
+
+## Layers, Tags And Metadata
+
+- Use layers for major visibility sets, such as logical view, physical view, annotations or migration phases.
+- Use tags for cross-cutting filters such as critical, deprecated, external, v2 or owner names.
+- Use object metadata and placeholders when a shape represents a record with fields such as owner, status, IP, service tier or version.
+- Keep visible labels concise; put secondary facts in metadata or notes when the diagram would otherwise become hard to scan.
+
+## Labels And Dark Mode
+
+- Match diagram label language to the user's language.
+- Add `html=1` whenever labels contain HTML markup or escaped `<br>` formatting.
+- Escape XML attribute values: `&`, `<`, `>`, and `"` must be entities.
+- Prefer adaptive colors and simple palettes; specify dark-mode overrides only when automatic inversion makes labels or shapes unclear.
+
+## Mermaid Import Notes
+
+- Pick the Mermaid header deliberately: `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `timeline`, `mindmap`, `gantt`, `C4Context` and similar headers select different parsers.
+- Quote labels that include punctuation, spaces, parentheses or non-ASCII text.
+- Keep node ids simple and put display text in labels.
+- For large, highly styled or vendor-specific diagrams, move to XML before final delivery.
+
+## XML Well-Formedness
+
+- Do not include XML comments.
+- Do not leave raw ampersands or angle brackets inside attribute values.
+- Do not use duplicate ids.
+- Do not leave edges pointing to missing source or target cells.
+- Run `diagram-lint.mjs` before final handoff.

package/skills/fec-drawio-studio/scripts/brand-symbols.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs, skillDir } from "./studio-core.mjs";
+
+const MANIFEST = path.join(skillDir, "data", "brand-icons.json");
+const STYLE_PREFIX = "shape=image;html=1;imageAspect=0;aspect=fixed;verticalLabelPosition=bottom;verticalAlign=top;image=";
+const SIMPLE = new Map([
+  ["qdrant", "qdrant"], ["milvus", "milvus"], ["supabase", "supabase"], ["redis", "redis"],
+  ["postgresql", "postgresql"], ["postgres", "postgresql"], ["mongodb", "mongodb"],
+  ["elasticsearch", "elasticsearch"], ["neo4j", "neo4j"], ["kafka", "apachekafka"],
+  ["clickhouse", "clickhouse"], ["duckdb", "duckdb"], ["mysql", "mysql"], ["sqlite", "sqlite"],
+]);
+
+export function loadFamilies() {
+  const manifest = JSON.parse(fs.readFileSync(MANIFEST, "utf8"));
+  const families = new Map();
+  for (const icon of manifest.icons) {
+    const base = icon.replace(/-(color|text)$/, "");
+    if (!families.has(base)) families.set(base, new Set());
+    families.get(base).add(icon);
+  }
+  return { cdn: manifest.cdn, families };
+}
+
+export async function queryBrand(query, options = {}) {
+  const { cdn, families } = loadFamilies();
+  const hits = rankBrands(families, query).slice(0, Number(options.limit ?? 8));
+  const size = Number(options.size ?? 48);
+  const variant = options.variant ?? "color";
+  const results = [];
+  for (const brand of hits) {
+    const file = pickVariant(brand, families.get(brand), variant);
+    const url = `${cdn}${file}.svg`;
+    results.push({ brand, file, w: size, h: size, style: STYLE_PREFIX + (options.embed ? await dataUri(url) : url) });
+  }
+  if (results.length === 0) {
+    const slug = SIMPLE.get(squish(query));
+    if (slug) {
+      const url = `https://cdn.simpleicons.org/${slug}`;
+      results.push({ brand: squish(query), file: `simpleicons:${slug}`, w: size, h: size, style: STYLE_PREFIX + (options.embed ? await dataUri(url) : url) });
+    }
+  }
+  return results;
+}
+
+function rankBrands(families, query) {
+  const needle = squish(query);
+  const tokens = String(query).toLowerCase().match(/[a-z0-9]+/g) ?? [];
+  const scored = [];
+  for (const brand of families.keys()) {
+    const base = squish(brand);
+    let score = 0;
+    if (base === needle) score = 100;
+    else if (base.startsWith(needle)) score = 70;
+    else if (base.includes(needle) || needle.includes(base)) score = 45;
+    for (const token of tokens) {
+      if (base === token) score = Math.max(score, 90);
+      else if (token.length >= 3 && base.includes(token)) score = Math.max(score, 35);
+    }
+    if (score > 0) scored.push([brand, score]);
+  }
+  return scored.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([brand]) => brand);
+}
+
+function pickVariant(base, variants, preference) {
+  const order = preference === "mono" ? ["", "-color", "-text"] : preference === "text" ? ["-text", "-color", ""] : ["-color", "", "-text"];
+  for (const suffix of order) if (variants.has(base + suffix)) return base + suffix;
+  return [...variants].sort()[0];
+}
+
+function squish(value) {
+  return String(value ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+async function dataUri(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`failed to fetch ${url}: ${response.status}`);
+  const svg = Buffer.from(await response.arrayBuffer()).toString("base64");
+  return `data:image/svg+xml;base64,${svg}`;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const query = args._.join(" ");
+if (!query && !args.list) {
+  console.error("usage: node brand-symbols.mjs <brand> [--variant color|mono|text] [--embed] [--json]");
+  process.exit(2);
+}
+if (args.list) {
+  process.stdout.write([...loadFamilies().families.keys()].sort().join("\n") + "\n");
+} else {
+  const results = await queryBrand(query, args);
+  if (results.length === 0) {
+    console.error(`no brand symbol matched ${JSON.stringify(query)}`);
+    process.exit(1);
+  }
+  if (args.json) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+  else for (const item of results) process.stdout.write(`${item.brand} (${item.file}, ${item.w}x${item.h})\n  ${item.style.slice(0, 180)}${item.style.length > 180 ? "..." : ""}\n`);
+}

package/skills/fec-drawio-studio/scripts/diagram-lint.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { formatResult, parseArgs, readText } from "./studio-core.mjs";
+
+export function lintDrawio(xml) {
+  const errors = [];
+  const warnings = [];
+  if (/<!--/.test(xml) || /-->/.test(xml)) errors.push("XML comments are not allowed in draw.io diagram sources");
+  if (!/<mx(Cell|file|GraphModel)\b/.test(xml)) warnings.push("No draw.io graph markers found");
+  if (/<mxCell\b[^>]*\bedge="1"[^>]*\/>/.test(xml)) errors.push("edge mxCell must not be self-closing; add mxGeometry relative=\"1\"");
+
+  const cellRe = /<mxCell\b([^>]*?)(?:\/>|>([\s\S]*?)<\/mxCell>)/g;
+  const objectByCellIndex = objectsByCellIndex(xml);
+  const cells = [];
+  const ids = new Map();
+  for (const match of xml.matchAll(cellRe)) {
+    const objectAttrs = objectByCellIndex.get(match.index) ?? {};
+    const attrs = attrsOf(match[1]);
+    if (!attrs.id && objectAttrs.id) attrs.id = objectAttrs.id;
+    if (!attrs.value && objectAttrs.label) attrs.value = objectAttrs.label;
+    const body = match[2] ?? "";
+    const id = attrs.id;
+    if (!id) {
+      errors.push("mxCell without id");
+      continue;
+    }
+    if (ids.has(id)) errors.push(`duplicate id ${id}`);
+    ids.set(id, attrs);
+    for (const [name, value] of rawAttrsOf(match[1])) {
+      if (hasUnescapedAmpersand(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped ampersand`);
+      if (/[<>]/.test(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped angle bracket`);
+    }
+    const geom = body.match(/<mxGeometry\b([^>]*?)(?:\/>|>)/)?.[1];
+    cells.push({ id, attrs, body, geom: geom ? attrsOf(geom) : null });
+  }
+
+  if (cells.length > 0) {
+    if (!ids.has("0")) errors.push("missing root cell id 0");
+    if (!ids.has("1")) errors.push("missing default layer cell id 1");
+  }
+
+  for (const cell of cells) {
+    const { attrs, id, geom } = cell;
+    if ((attrs.vertex === "1" || attrs.edge === "1") && (id === "0" || id === "1")) {
+      errors.push(`reserved id used by graph cell ${id}`);
+    }
+    if (attrs.parent && !ids.has(attrs.parent)) errors.push(`cell ${id} parent ${attrs.parent} does not exist`);
+    for (const end of ["source", "target"]) {
+      if (attrs[end] && !ids.has(attrs[end])) errors.push(`edge ${id} ${end} ${attrs[end]} does not exist`);
+    }
+    if (attrs.edge === "1" && !geom) errors.push(`edge ${id} is missing mxGeometry`);
+    if (attrs.edge === "1" && (!attrs.source || !attrs.target)) warnings.push(`edge ${id} has no source or target`);
+    if (attrs.vertex === "1") {
+      if (looksLikeHtml(attrs.value) && !styleHas(attrs.style, "html", "1")) warnings.push(`cell ${id} label contains HTML but style does not include html=1`);
+      if (!geom) errors.push(`vertex ${id} is missing mxGeometry`);
+      else {
+        const rect = rectOf(geom);
+        if (!Number.isFinite(rect.w) || !Number.isFinite(rect.h)) errors.push(`vertex ${id} has invalid size`);
+        else if (rect.w <= 0 || rect.h <= 0) warnings.push(`vertex ${id} has non-positive size`);
+        if (rect.x < 0 || rect.y < 0) warnings.push(`vertex ${id} has negative position`);
+      }
+    }
+  }
+
+  const leafVertices = cells
+    .filter((cell) => cell.attrs.vertex === "1" && cell.geom)
+    .filter((cell) => !cells.some((candidate) => candidate.attrs.parent === cell.id))
+    .map((cell) => ({ id: cell.id, parent: cell.attrs.parent ?? "1", rect: rectOf(cell.geom) }))
+    .filter((item) => Number.isFinite(item.rect.w) && Number.isFinite(item.rect.h));
+  for (let i = 0; i < leafVertices.length; i += 1) {
+    for (let j = i + 1; j < leafVertices.length; j += 1) {
+      if (leafVertices[i].parent === leafVertices[j].parent && overlaps(leafVertices[i].rect, leafVertices[j].rect)) {
+        warnings.push(`vertices ${leafVertices[i].id} and ${leafVertices[j].id} overlap`);
+      }
+    }
+  }
+  if (cells.filter((cell) => cell.attrs.vertex === "1").length === 0) warnings.push("diagram has no vertex cells");
+  return { title: "Diagram Lint", errors, warnings, ok: errors.length === 0 };
+}
+
+function objectsByCellIndex(xml) {
+  const out = new Map();
+  const objectRe = /<object\b([^>]*)>([\s\S]*?)<\/object>/g;
+  for (const match of xml.matchAll(objectRe)) {
+    const inner = match[2] ?? "";
+    const cellOffset = inner.search(/<mxCell\b/);
+    if (cellOffset < 0) continue;
+    const index = match.index + match[0].indexOf("<mxCell");
+    out.set(index, attrsOf(match[1]));
+  }
+  return out;
+}
+
+function attrsOf(raw) {
+  const attrs = {};
+  for (const match of raw.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)="([^"]*)"/g)) attrs[match[1]] = decode(match[2]);
+  return attrs;
+}
+
+function rawAttrsOf(raw) {
+  return [...raw.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)="([^"]*)"/g)].map((match) => [match[1], match[2]]);
+}
+
+function decode(value) {
+  return value.replaceAll("&quot;", '"').replaceAll("&gt;", ">").replaceAll("&lt;", "<").replaceAll("&amp;", "&");
+}
+
+function hasUnescapedAmpersand(value) {
+  return /&(?!amp;|lt;|gt;|quot;|apos;|#[0-9]+;|#x[0-9a-fA-F]+;)/.test(value);
+}
+
+function looksLikeHtml(value = "") {
+  return /<\/?[A-Za-z][^>]*>/.test(value);
+}
+
+function styleHas(style = "", key, expected) {
+  return style.split(";").some((part) => {
+    const [partKey, value] = part.split("=", 2);
+    return partKey === key && value === expected;
+  });
+}
+
+function rectOf(geom) {
+  return {
+    x: Number(geom.x ?? 0),
+    y: Number(geom.y ?? 0),
+    w: Number(geom.width),
+    h: Number(geom.height),
+  };
+}
+
+function overlaps(a, b) {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const input = args._[0];
+if (!input) {
+  console.error("usage: node diagram-lint.mjs <file.drawio> [--format markdown|json] [--strict]");
+  process.exit(2);
+}
+const result = lintDrawio(readText(input));
+process.stdout.write(formatResult(result, args.format ?? (args.json ? "json" : "markdown")));
+if (!result.ok || (args.strict && result.warnings.length > 0)) process.exit(1);

package/skills/fec-drawio-studio/scripts/diagram-url.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import zlib from "node:zlib";
+import { parseArgs, readText } from "./studio-core.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+const input = args._[0];
+if (!input) {
+  console.error(
+    "usage: node diagram-url.mjs <diagram-file> [--edit|--create] [--type xml|mermaid|csv] [--lightbox] [--dark true|false|auto] [--base-url URL] [--json|--shortcut]",
+  );
+  process.exit(2);
+}
+
+export function encodeDiagramXml(xml) {
+  const encoded = encodeURIComponent(xml);
+  return zlib.deflateRawSync(Buffer.from(encoded, "utf8")).toString("base64");
+}
+
+export function viewerUrl(xml, options = {}) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://viewer.diagrams.net/");
+  return `${baseUrl}?highlight=0000ff&edit=_blank#R${encodeDiagramXml(xml)}`;
+}
+
+export function editorUrl(xml, options = {}) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://app.diagrams.net/");
+  return `${baseUrl}?offline=1#R${encodeDiagramXml(xml)}`;
+}
+
+export function createUrl(content, options = {}) {
+  const type = normalizeType(options.type);
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://app.diagrams.net/");
+  const params = new URLSearchParams();
+  if (options.lightbox) {
+    params.set("lightbox", "1");
+    params.set("edit", "_blank");
+  } else {
+    params.set("grid", "0");
+    params.set("pv", "0");
+    params.set("edit", "_blank");
+  }
+  params.set("border", String(options.border ?? 10));
+  const dark = normalizeDark(options.dark);
+  if (dark === true) params.set("dark", "1");
+
+  const payload = encodeURIComponent(
+    JSON.stringify({
+      type,
+      compressed: true,
+      data: encodeDiagramXml(content),
+    }),
+  );
+  const query = params.toString();
+  return `${baseUrl}${query ? `?${query}` : ""}#create=${payload}`;
+}
+
+export function internetShortcut(url) {
+  return `[InternetShortcut]\r\nURL=${url}\r\n`;
+}
+
+function normalizeType(value = "xml") {
+  if (["xml", "mermaid", "csv"].includes(value)) return value;
+  throw new Error(`Unsupported diagram type "${value}". Expected xml, mermaid, or csv.`);
+}
+
+function normalizeDark(value = "auto") {
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  if (value === "auto" || value === undefined) return "auto";
+  throw new Error(`Unsupported dark mode "${value}". Expected true, false, or auto.`);
+}
+
+function normalizeBaseUrl(value) {
+  return String(value).replace(/[?#].*$/, "").replace(/\/?$/, "/");
+}
+
+try {
+  const content = readText(input);
+  const type = normalizeType(args.type ?? "xml");
+  if (type !== "xml" && !args.create) {
+    throw new Error("Mermaid and CSV inputs require --create because viewer/editor #R URLs only load XML.");
+  }
+  const options = {
+    baseUrl: args.baseUrl,
+    border: args.border,
+    dark: args.dark,
+    lightbox: Boolean(args.lightbox),
+    type,
+  };
+  const mode = args.create ? "create" : args.edit ? "edit" : "view";
+  const url = args.create ? createUrl(content, options) : args.edit ? editorUrl(content, options) : viewerUrl(content, options);
+  const shortcut = internetShortcut(url);
+  if (args.shortcut) {
+    process.stdout.write(shortcut);
+  } else if (args.json) {
+    process.stdout.write(`${JSON.stringify({ url, mode, type, windowsShortcut: shortcut }, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${url}\n`);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/skills/fec-drawio-studio/scripts/layout-graph.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { parseArgs, printOrWrite, readText, snap, writeText, xmlEscape } from "./studio-core.mjs";
+
+const DEFAULT_W = 140;
+const DEFAULT_H = 64;
+const NODE_STYLE = "rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;";
+const EDGE_STYLE = "edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;";
+const PALETTE = [
+  ["#dae8fc", "#6c8ebf"], ["#d5e8d4", "#82b366"], ["#ffe6cc", "#d79b00"],
+  ["#e1d5e7", "#9673a6"], ["#fff2cc", "#d6b656"], ["#f8cecc", "#b85450"],
+];
+
+export function buildDot(graph) {
+  const direction = String(graph.direction ?? "TB").toUpperCase() === "LR" ? "LR" : "TB";
+  const lines = [`digraph G { rankdir=${direction}; splines=ortho; node [shape=box fixedsize=true];`];
+  for (const node of graph.nodes) {
+    lines.push(`"${escapeDot(node.id)}" [width=${Number(node.width ?? DEFAULT_W) / 72} height=${Number(node.height ?? DEFAULT_H) / 72}];`);
+  }
+  for (const edge of graph.edges ?? []) lines.push(`"${escapeDot(edge.source)}" -> "${escapeDot(edge.target)}";`);
+  lines.push("}");
+  return lines.join("\n");
+}
+
+export function runDot(dot) {
+  const proc = spawnSync("dot", ["-Tplain"], { input: dot, encoding: "utf8" });
+  if (proc.error?.code === "ENOENT") throw new Error("Graphviz `dot` not found on PATH");
+  if (proc.status !== 0) throw new Error(`Graphviz failed: ${proc.stderr.trim()}`);
+  const pos = new Map();
+  let height = 0;
+  for (const line of proc.stdout.split(/\r?\n/)) {
+    const parts = splitPlain(line);
+    if (parts[0] === "graph") height = Number(parts[3]);
+    if (parts[0] === "node") pos.set(parts[1], { x: Number(parts[2]), y: Number(parts[3]) });
+  }
+  return { height, pos };
+}
+
+export function graphToDrawio(graph, layout) {
+  const groups = [...new Set((graph.nodes ?? []).map((node) => node.group).filter(Boolean))];
+  const groupColor = (group) => PALETTE[Math.max(0, groups.indexOf(group)) % PALETTE.length];
+  const cells = [];
+  const manifest = { nodes: {}, edges: graph.edges ?? [] };
+  for (const node of graph.nodes ?? []) {
+    const p = layout.pos.get(node.id);
+    if (!p) continue;
+    const w = Number(node.width ?? DEFAULT_W);
+    const h = Number(node.height ?? DEFAULT_H);
+    const x = snap(p.x * 72 - w / 2 + 40);
+    const y = snap((layout.height - p.y) * 72 - h / 2 + 40);
+    const style = node.style ?? (node.group ? tintStyle(groupColor(node.group)) : NODE_STYLE);
+    manifest.nodes[node.id] = { x, y, width: w, height: h, group: node.group ?? null };
+    cells.push(`        <mxCell id="${xmlEscape(node.id)}" value="${xmlEscape(node.label ?? node.id)}" style="${xmlEscape(style)}" vertex="1" parent="1">
+          <mxGeometry x="${x}" y="${y}" width="${w}" height="${h}" as="geometry"/>
+        </mxCell>`);
+  }
+  let edgeIndex = 0;
+  for (const edge of graph.edges ?? []) {
+    cells.push(`        <mxCell id="edge_${edgeIndex++}" value="${xmlEscape(edge.label ?? "")}" style="${EDGE_STYLE}" edge="1" parent="1" source="${xmlEscape(edge.source)}" target="${xmlEscape(edge.target)}">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>`);
+  }
+  return {
+    manifest,
+    xml: `<mxfile host="drawio">
+  <diagram name="Page-1">
+    <mxGraphModel grid="1" gridSize="10" page="1" pageWidth="1100" pageHeight="850">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+${cells.join("\n")}
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
+`,
+  };
+}
+
+function tintStyle([fill, stroke]) {
+  return `rounded=1;whiteSpace=wrap;html=1;fillColor=${fill};strokeColor=${stroke};`;
+}
+
+function escapeDot(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+function splitPlain(line) {
+  return line.match(/"[^"]*"|\S+/g)?.map((part) => part.replace(/^"|"$/g, "")) ?? [];
+}
+
+const args = parseArgs(process.argv.slice(2));
+const input = args._[0];
+if (!input) {
+  console.error("usage: node layout-graph.mjs graph.json --output diagram.drawio [--manifest layout.json]");
+  process.exit(2);
+}
+try {
+  const graph = JSON.parse(readText(input));
+  const rendered = graphToDrawio(graph, runDot(buildDot(graph)));
+  printOrWrite(rendered.xml, args.output);
+  if (args.manifest) writeText(args.manifest, `${JSON.stringify(rendered.manifest, null, 2)}\n`);
+  if (!args.output) process.stderr.write(`rendered ${graph.nodes.length} nodes\n`);
+} catch (error) {
+  console.error(`error: ${error.message}`);
+  process.exit(1);
+}