d2-to-drawio 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moawiah Jamal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# d2-to-drawio
+
+[![npm version](https://img.shields.io/npm/v/d2-to-drawio)](https://www.npmjs.com/package/d2-to-drawio)
+[![CI](https://github.com/Moawiah188/d2-to-drawio/actions/workflows/ci.yml/badge.svg)](https://github.com/Moawiah188/d2-to-drawio/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/d2-to-drawio)](https://github.com/Moawiah188/d2-to-drawio/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/d2-to-drawio)](https://nodejs.org)
+
+Convert D2 diagrams to draw.io files: keep authoring diagrams as code in [D2](https://d2lang.com), and hand fully editable drawio / [diagrams.net](https://www.diagrams.net) files to everyone else. Shapes, containers, edges, styles, and positions all come across as native draw.io elements, not as a pasted image.
+
+```
+npx d2-to-drawio examples/basic.d2 -o basic.drawio
+```
+
+## What you get
+
+```d2
+direction: right
+
+user: Visitor { shape: person }
+app: "Web App"
+db: "Postgres" { shape: cylinder }
+
+user -> app: "browses"
+app -> db: "reads / writes"
+```
+
+```
+npx d2-to-drawio examples/basic.d2 -o basic.drawio
+```
+
+The result, opened in draw.io, every element selectable and editable:
+
+![basic example rendered in draw.io](https://raw.githubusercontent.com/Moawiah188/d2-to-drawio/main/docs/assets/basic.png)
+
+A richer example with containers, a queue, crow's foot cardinality, and tooltips ([source](https://github.com/Moawiah188/d2-to-drawio/blob/main/examples/microservices.d2)):
+
+![microservices example rendered in draw.io](https://raw.githubusercontent.com/Moawiah188/d2-to-drawio/main/docs/assets/microservices.png)
+
+Open the committed outputs directly in your browser:
+
+- [Open basic.drawio in app.diagrams.net](https://app.diagrams.net/#Uhttps%3A%2F%2Fraw.githubusercontent.com%2FMoawiah188%2Fd2-to-drawio%2Fmain%2Fexamples%2Fbasic.drawio)
+- [Open microservices.drawio in app.diagrams.net](https://app.diagrams.net/#Uhttps%3A%2F%2Fraw.githubusercontent.com%2FMoawiah188%2Fd2-to-drawio%2Fmain%2Fexamples%2Fmicroservices.drawio)
+
+<!-- PLACEHOLDER: drop a real screenshot of one of these files open in the app.diagrams.net editor (with the draw.io UI visible) here, e.g. docs/assets/editor-screenshot.png, and reference it with an absolute raw.githubusercontent.com URL. -->
+
+## Why this exists
+
+Plenty of teams standardize on draw.io and Confluence for documentation, while the engineers drawing the systems would rather write diagrams as code, version them, and review them in pull requests. Exporting D2 to SVG or PNG hands the team a static picture nobody can edit; switching the whole team to D2 rarely happens. This tool removes that one-way door: engineers keep the `.d2` source of truth, everyone else gets a native `.drawio` file they can open, edit, and paste into Confluence.
+
+## Quick start
+
+```
+npm install -g d2-to-drawio
+d2-to-drawio diagram.d2 -o diagram.drawio
+```
+
+Or without installing:
+
+```
+npx d2-to-drawio diagram.d2 -o diagram.drawio
+```
+
+Or from stdin to stdout:
+
+```
+cat diagram.d2 | d2-to-drawio > diagram.drawio
+```
+
+## CLI reference
+
+```
+Usage: d2-to-drawio [options] [input.d2]
+
+Reads from the input file, or from stdin when no file is given (or "-").
+Writes to --output, or to stdout.
+
+Options:
+  -o, --output <file>   write the .drawio XML to a file instead of stdout
+      --layout <name>   layout engine: dagre (default) or elk
+      --theme <id>      D2 theme id (default 0)
+      --waypoints       preserve D2 edge routes as fixed waypoints
+      --strict          fail when input uses features that would degrade
+  -q, --quiet           suppress warnings on stderr
+  -h, --help            show this help
+  -v, --version         print the version
+```
+
+Behavior notes:
+
+- `@imports` resolve automatically: for file input, every `.d2` under the input file's directory is available to the compiler; for stdin, imports resolve against the current directory.
+- Unsupported D2 features never crash a conversion. Each degrades to the closest visual and prints one warning line to stderr. `--strict` turns those warnings into a failing exit instead.
+- By default draw.io re-routes edges orthogonally, which keeps them fully editable. `--waypoints` pins d2's exact computed routes instead.
+- Exit codes: 0 success, 1 conversion or input error, 2 usage error.
+
+## Library API
+
+```js
+import { convert, convertFile, dispose } from 'd2-to-drawio';
+
+const xml = await convert('a -> b: hello');
+// or, resolving imports relative to the file:
+const xml2 = await convertFile('diagram.d2', { layout: 'elk' });
+
+await dispose();
+```
+
+- `convert(d2Source, options)` returns a Promise of the `.drawio` XML string.
+- `convertFile(inputPath, options)` reads the file and feeds sibling `.d2` files to the compiler so relative imports work.
+- `options`: `layout` ('dagre' | 'elk'), `themeID` (number), `strict` (boolean), `waypoints` (boolean), `onWarning` (callback receiving `{code, message}`), `fsMap`/`inputPath` (virtual filesystem for imports when using `convert`).
+- `dispose()` releases the compiler's worker thread. Call it when done, or your process will stay alive. The next `convert` after a `dispose` transparently starts a fresh engine.
+- Errors: malformed D2 rejects with `D2SyntaxError` (message carries `file:line:column`); strict-mode degradations reject with `UnsupportedFeatureError` (carrying the warning list).
+
+Output is deterministic: identical input produces byte-identical output, so generated files diff cleanly in version control.
+
+## Feature support
+
+The full, fixture-backed matrix lives in [docs/FEATURE-MATRIX.md](https://github.com/Moawiah188/d2-to-drawio/blob/main/docs/FEATURE-MATRIX.md). Summary:
+
+| Area | Support |
+|---|---|
+| Shape catalog (rectangle, square, page, parallelogram, document, cylinder, queue, package, step, callout, stored_data, person, diamond, oval, circle, hexagon, cloud, image, text) | Full |
+| Containers, any nesting depth, grid diagrams | Full |
+| Connections: `->` `<-` `<->` `--`, chains, parallel edges, self-loops | Full |
+| Arrowheads incl. crow's foot ER markers, arrowhead labels | Full |
+| Styles: fill, stroke, stroke-width, stroke-dash, opacity, shadow, fonts, bold/italic/underline | Full |
+| Themes: all 20 official palettes | Full |
+| Compiler-level features: vars, globs, classes, imports, overrides, null | Full |
+| Boards (layers, scenarios, steps) | Full, one draw.io page per board |
+| Tooltips and links | Full |
+| sql_table, class (UML) | Partial: formatted single shapes, not row-by-row cells |
+| Sequence diagrams | Partial: exact d2 geometry, but fixed (does not re-route) |
+| Markdown / LaTeX / code labels | Partial: plain text / MathJax / monospace box |
+| multiple, 3d, double-border, fill-pattern, animated, sketch | Unsupported, warned |
+
+## Limitations
+
+- The compiler dependency (`@terrastruct/d2`, the official WASM build of D2) is around 60 MB installed and takes a couple of seconds to start. One-shot CLI runs pay that startup; batch conversions should use the library API, which reuses the engine across calls.
+- sql_table and class shapes are single shapes with formatted labels. Editing individual rows as draw.io table cells is on the roadmap.
+- Sequence diagram messages and lifelines keep d2's exact geometry and will not re-route if you move the actors.
+- Links between D2 boards (`link: layers.x`) do not become page links in draw.io yet.
+- The TALA layout engine is not part of the embedded compiler; `dagre` and `elk` are available.
+
+## How it works
+
+The official D2 compiler (as a WASM build) parses the source and runs the real layout engine, producing fully positioned shapes and routed connections. This tool walks that output, rebuilds the container tree, and translates shapes, styles, and theme colors into draw.io's mxGraph cell model. It then emits deterministic, uncompressed `.drawio` XML that draw.io opens like any hand-drawn file.
+
+## Roadmap
+
+Only things actually planned:
+
+- Native draw.io table cells for sql_table and class shapes.
+- draw.io sketch style for D2 sketch mode.
+- Page links for D2 board links.
+- Icons on regular shapes (currently only `shape: image` carries an image).
+
+## Related projects
+
+As of July 2026 this is the only dedicated D2 to draw.io converter I am aware of. Related tools:
+
+- [D2](https://github.com/terrastruct/d2): the diagram language itself.
+- [draw.io / diagrams.net](https://github.com/jgraph/drawio): the editor this tool targets.
+- [@whitebite/diagram-converter](https://www.npmjs.com/package/@whitebite/diagram-converter): a universal multi-format diagram converter whose published build includes a D2 parser and drawio generator via a shared intermediate representation. A generalist; this tool goes deeper on D2 fidelity (layout preservation, themes, special shapes, degradation warnings).
+- [mmd2drawio](https://github.com/youyoubilly/mmd2drawio): the same idea for Mermaid.
+- The SVG detour: D2 can export SVG that draw.io imports as a static image. Works, but nothing is editable; that gap is the point of this project (see also [jgraph/drawio#3764](https://github.com/jgraph/drawio/issues/3764), an open request for D2 input in draw.io itself).
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Moawiah188/d2-to-drawio/blob/main/CONTRIBUTING.md). The short version: fixture first, then the mapping code, then a row in the feature matrix. Bug reports with a minimal `.d2` snippet are gold.
+
+## License
+
+[MIT](https://github.com/Moawiah188/d2-to-drawio/blob/main/LICENSE). The `@terrastruct/d2` dependency is MPL-2.0, used unmodified.

package/bin/d2-to-drawio.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// CLI for d2-to-drawio: convert D2 diagram source to draw.io XML.
+
+import { parseArgs } from 'node:util';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import {
+  convert,
+  convertFile,
+  buildImportFs,
+  dispose,
+  D2SyntaxError,
+  UnsupportedFeatureError,
+} from '../src/index.js';
+
+const HELP = `Usage: d2-to-drawio [options] [input.d2]
+
+Convert a D2 diagram (d2lang.com) to an editable draw.io / diagrams.net file.
+
+Reads from the input file, or from stdin when no file is given (or "-").
+Writes to --output, or to stdout.
+
+Options:
+  -o, --output <file>   write the .drawio XML to a file instead of stdout
+      --layout <name>   layout engine: dagre (default) or elk
+      --theme <id>      D2 theme id (default 0)
+      --waypoints       preserve D2 edge routes as fixed waypoints
+      --strict          fail when input uses features that would degrade
+  -q, --quiet           suppress warnings on stderr
+  -h, --help            show this help
+  -v, --version         print the version
+
+Examples:
+  d2-to-drawio diagram.d2 -o diagram.drawio
+  cat diagram.d2 | d2-to-drawio > diagram.drawio
+`;
+
+function version() {
+  const pkg = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+  );
+  return pkg.version;
+}
+
+function usageError(msg) {
+  process.stderr.write(`error: ${msg}\n\n${HELP}`);
+  process.exit(2);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs({
+      allowPositionals: true,
+      options: {
+        output: { type: 'string', short: 'o' },
+        layout: { type: 'string' },
+        theme: { type: 'string' },
+        waypoints: { type: 'boolean' },
+        strict: { type: 'boolean' },
+        quiet: { type: 'boolean', short: 'q' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+    });
+  } catch (err) {
+    usageError(err.message);
+  }
+  const { values, positionals } = args;
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (values.version) {
+    process.stdout.write(`${version()}\n`);
+    return 0;
+  }
+  if (positionals.length > 1) usageError('expected at most one input file');
+  if (values.layout && values.layout !== 'dagre' && values.layout !== 'elk') {
+    usageError(`unknown layout "${values.layout}" (expected dagre or elk)`);
+  }
+  let themeID;
+  if (values.theme !== undefined) {
+    themeID = Number(values.theme);
+    if (!Number.isInteger(themeID) || themeID < 0) usageError(`invalid theme id "${values.theme}"`);
+  }
+
+  // layout and themeID stay undefined unless given, so an in-file
+  // vars.d2-config block keeps control of them.
+  const convertOptions = {
+    layout: values.layout,
+    themeID,
+    strict: Boolean(values.strict),
+    waypoints: Boolean(values.waypoints),
+    onWarning: values.quiet ? undefined : (w) => process.stderr.write(`warning: ${w.message}\n`),
+  };
+
+  const inputPath = positionals[0];
+  let xml;
+  try {
+    if (!inputPath || inputPath === '-') {
+      if (process.stdin.isTTY) usageError('no input file given and stdin is a terminal');
+      const source = await readStdin();
+      // Imports in piped input resolve against the current directory.
+      xml = await convert(source, { ...convertOptions, fsMap: buildImportFs(process.cwd()) });
+    } else {
+      xml = await convertFile(inputPath, convertOptions);
+    }
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'EACCES' || err.code === 'EISDIR')) {
+      process.stderr.write(`error: cannot read "${inputPath}": ${err.message}\n`);
+      return 1;
+    }
+    if (err instanceof D2SyntaxError || err instanceof UnsupportedFeatureError) {
+      process.stderr.write(`error: ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  }
+
+  if (values.output) {
+    try {
+      writeFileSync(values.output, xml, 'utf8');
+    } catch (err) {
+      process.stderr.write(`error: cannot write "${values.output}": ${err.message}\n`);
+      return 1;
+    }
+  } else {
+    process.stdout.write(xml);
+  }
+  return 0;
+}
+
+main()
+  .then(async (code) => {
+    await dispose();
+    // The engine's worker thread would otherwise keep the process alive.
+    process.exit(code);
+  })
+  .catch(async (err) => {
+    process.stderr.write(`error: ${err && err.message ? err.message : err}\n`);
+    await dispose();
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "d2-to-drawio",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "node --test test/unit.test.mjs test/snapshot.test.mjs test/cli.test.mjs",
+    "snapshots": "node test/run-fixtures.mjs",
+    "coverage": "node --test --experimental-test-coverage test/unit.test.mjs test/snapshot.test.mjs test/cli.test.mjs"
+  },
+  "keywords": [
+    "d2",
+    "d2lang",
+    "drawio",
+    "draw.io",
+    "diagrams.net",
+    "diagram",
+    "converter",
+    "diagrams-as-code",
+    "cli",
+    "flowchart",
+    "architecture-diagram",
+    "text-to-diagram",
+    "mxgraph",
+    "export"
+  ],
+  "author": "Moawiah Jamal",
+  "license": "MIT",
+  "description": "Convert D2 diagrams to editable draw.io / diagrams.net files (.drawio XML) from the CLI or Node.js",
+  "type": "module",
+  "devDependencies": {
+    "fast-xml-parser": "^5.10.0"
+  },
+  "dependencies": {
+    "@terrastruct/d2": "^0.1.33"
+  },
+  "bin": {
+    "d2-to-drawio": "bin/d2-to-drawio.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "homepage": "https://github.com/Moawiah188/d2-to-drawio#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Moawiah188/d2-to-drawio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Moawiah188/d2-to-drawio/issues"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/compile.js

@@ -0,0 +1,97 @@
+// Wrapper around the official D2 compiler (@terrastruct/d2, WASM).
+//
+// The engine runs in a worker thread that keeps the Node event loop alive,
+// so this module manages a lazy singleton and exposes dispose() to release
+// it. Library callers must await dispose() (or exit the process) when done.
+
+import { D2 } from '@terrastruct/d2';
+
+/** Error thrown when the D2 source does not compile. */
+export class D2SyntaxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'D2SyntaxError';
+    this.code = 'D2_SYNTAX';
+  }
+}
+
+let instance = null;
+
+function getInstance() {
+  if (!instance) instance = new D2();
+  return instance;
+}
+
+/**
+ * The engine reports compile problems as a JSON array of
+ * {range, errmsg} objects serialized into the error message. Flatten that
+ * into d2's own "file:line:col: description" lines, never a stack trace.
+ */
+function formatCompileError(err) {
+  const raw = String(err && err.message ? err.message : err).trim();
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      const msgs = parsed.map((e) => e.errmsg ?? JSON.stringify(e));
+      if (msgs.length > 0) return msgs.join('\n');
+    }
+  } catch {
+    // not JSON: fall through to the raw message
+  }
+  return raw;
+}
+
+/**
+ * Compile D2 source to the positioned diagram IR.
+ *
+ * @param {string} source D2 source text
+ * @param {object} [options]
+ * @param {'dagre'|'elk'} [options.layout] layout engine (default dagre)
+ * @param {number} [options.themeID] D2 theme id (default 0)
+ * @param {Record<string, string>} [options.fsMap] virtual filesystem for imports:
+ *   relative path -> file content. Required for sources that use @imports.
+ * @param {string} [options.inputPath] entry filename inside fsMap (and the name
+ *   used in error messages). Defaults to "input.d2".
+ * @returns {Promise<object>} the CompileResponse ({ diagram, graph, ... })
+ */
+export async function compile(source, options = {}) {
+  const d2 = getInstance();
+  // Only forward explicitly-set options so an in-file `vars.d2-config`
+  // block keeps control of anything the caller leaves unset.
+  const compileOptions = {};
+  if (options.layout !== undefined) compileOptions.layout = options.layout;
+  if (options.themeID !== undefined) compileOptions.themeID = options.themeID;
+  if (options.sketch !== undefined) compileOptions.sketch = options.sketch;
+  if (options.pad !== undefined) compileOptions.pad = options.pad;
+
+  const inputPath = options.inputPath ?? 'input.d2';
+  const fs = { ...(options.fsMap ?? {}), [inputPath]: source };
+
+  try {
+    return await d2.compile({ fs, inputPath, options: compileOptions });
+  } catch (err) {
+    throw new D2SyntaxError(formatCompileError(err));
+  }
+}
+
+/**
+ * Release the engine worker so the process can exit naturally.
+ * Safe to call multiple times; compile() after dispose() re-creates it.
+ */
+export async function dispose() {
+  if (!instance) return;
+  const d2 = instance;
+  instance = null;
+  // The published API has no terminate method. The worker handle appears on
+  // the instance once init completes, so wait for readiness first: a worker
+  // still starting up would otherwise leak and keep the process alive.
+  try {
+    await d2.ready;
+  } catch {
+    // init failed: there is no worker to stop
+  }
+  const worker = d2.worker;
+  if (worker && typeof worker.terminate === 'function') {
+    await worker.terminate();
+  }
+}

package/src/emit.js

@@ -0,0 +1,128 @@
+// draw.io XML emission.
+//
+// Input is a list of pages, each holding an ordered list of cells (vertices
+// and edges). Output is an uncompressed .drawio mxfile string.
+//
+// Invariants enforced here, per the draw.io format contract:
+//   mxfile > diagram > mxGraphModel > root, root cells "0" and "1",
+//   every vertex carries mxGeometry with numeric x/y/width/height,
+//   cells with a tooltip or link are wrapped in an <object> element that
+//   carries the id and label while the inner mxCell carries neither.
+//
+// Attribute order is fixed so identical input produces byte-identical output.
+
+/** Escape text for an XML attribute value. */
+export function escAttr(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '&#10;');
+}
+
+/** Escape text destined for HTML content inside a draw.io html=1 label. */
+export function escHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Build a draw.io html=1 label from plain text: HTML-escape it and turn
+ * newlines into <br>. draw.io re-parses the cell value as HTML, so raw text
+ * must be escaped once here (and once more as an XML attribute at emit).
+ */
+export function htmlLabel(s) {
+  return escHtml(s).replace(/\r?\n/g, '<br>');
+}
+
+/** Format a coordinate: round to 2 decimals, no trailing zeros. */
+export function num(n) {
+  return String(Math.round(n * 100) / 100);
+}
+
+function vertexXml(cell) {
+  // Edge-label children use relative geometry along their parent edge.
+  if (cell.edgeLabel) {
+    return (
+      `<mxCell id="${escAttr(cell.id)}" value="${escAttr(cell.value)}" style="${escAttr(
+        cell.style
+      )}" vertex="1" connectable="0" parent="${escAttr(cell.parent)}">` +
+      `<mxGeometry x="${num(cell.rx)}" relative="1" as="geometry"/></mxCell>`
+    );
+  }
+  const geom = `<mxGeometry x="${num(cell.x)}" y="${num(cell.y)}" width="${num(cell.w)}" height="${num(cell.h)}" as="geometry"/>`;
+  const core = (id, value) =>
+    `<mxCell${id}${value} style="${escAttr(cell.style)}" vertex="1" parent="${escAttr(cell.parent)}">${geom}</mxCell>`;
+
+  if (cell.tooltip || cell.link) {
+    // Metadata wrapper: id and label move to the <object>; the inner mxCell
+    // carries neither (draw.io's own codec does the same id hoisting).
+    let attrs = ` label="${escAttr(cell.value)}"`;
+    if (cell.tooltip) attrs += ` tooltip="${escAttr(cell.tooltip)}"`;
+    if (cell.link) attrs += ` link="${escAttr(cell.link)}"`;
+    return `<object${attrs} id="${escAttr(cell.id)}">${core('', '')}</object>`;
+  }
+  return core(` id="${escAttr(cell.id)}"`, ` value="${escAttr(cell.value)}"`);
+}
+
+function edgeXml(cell) {
+  // Fixed endpoints (sourcePoint/targetPoint) carry edges that have no cell
+  // to anchor to, e.g. sequence-diagram lifelines and messages.
+  let inner = '';
+  if (cell.sourcePoint) {
+    inner += `<mxPoint x="${num(cell.sourcePoint.x)}" y="${num(cell.sourcePoint.y)}" as="sourcePoint"/>`;
+  }
+  if (cell.targetPoint) {
+    inner += `<mxPoint x="${num(cell.targetPoint.x)}" y="${num(cell.targetPoint.y)}" as="targetPoint"/>`;
+  }
+  if (cell.points && cell.points.length > 0) {
+    const pts = cell.points.map((p) => `<mxPoint x="${num(p.x)}" y="${num(p.y)}"/>`).join('');
+    inner += `<Array as="points">${pts}</Array>`;
+  }
+  const geom = inner
+    ? `<mxGeometry relative="1" as="geometry">${inner}</mxGeometry>`
+    : `<mxGeometry relative="1" as="geometry"/>`;
+
+  const endpoints =
+    (cell.source ? ` source="${escAttr(cell.source)}"` : '') +
+    (cell.target ? ` target="${escAttr(cell.target)}"` : '');
+  const core = (id, value) =>
+    `<mxCell${id}${value} style="${escAttr(cell.style)}" edge="1" parent="${escAttr(
+      cell.parent
+    )}"${endpoints}>${geom}</mxCell>`;
+
+  if (cell.tooltip || cell.link) {
+    let attrs = ` label="${escAttr(cell.value)}"`;
+    if (cell.tooltip) attrs += ` tooltip="${escAttr(cell.tooltip)}"`;
+    if (cell.link) attrs += ` link="${escAttr(cell.link)}"`;
+    return `<object${attrs} id="${escAttr(cell.id)}">${core('', '')}</object>`;
+  }
+  return core(` id="${escAttr(cell.id)}"`, ` value="${escAttr(cell.value)}"`);
+}
+
+/**
+ * Emit a complete uncompressed .drawio file.
+ *
+ * @param {Array<{name: string, cells: Array<object>, background?: string}>} pages
+ * @returns {string}
+ */
+export function emit(pages) {
+  const diagrams = pages.map((page, i) => {
+    const cells = page.cells
+      .map((c) => (c.edge ? edgeXml(c) : vertexXml(c)))
+      .join('');
+    const background =
+      page.background && page.background !== 'none'
+        ? ` background="${escAttr(page.background)}"`
+        : '';
+    const math = page.math ? '1' : '0';
+    return (
+      `<diagram id="page-${i + 1}" name="${escAttr(page.name)}">` +
+      `<mxGraphModel dx="800" dy="600" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" ` +
+      `arrows="1" fold="1" page="0" pageScale="1" math="${math}" shadow="0"${background}>` +
+      `<root><mxCell id="0"/><mxCell id="1" parent="0"/>${cells}</root>` +
+      `</mxGraphModel></diagram>`
+    );
+  });
+  return `<mxfile host="app.diagrams.net" type="device">${diagrams.join('')}</mxfile>\n`;
+}

package/src/ids.js

@@ -0,0 +1,21 @@
+// Deterministic draw.io cell id allocation.
+//
+// Ids derive from the D2 key: readable, stable across runs, deduplicated
+// with numeric suffixes. "0" and "1" are reserved for the draw.io root cells.
+
+export function createIdAllocator() {
+  const used = new Set(['0', '1']);
+  const byKey = new Map();
+
+  return function idFor(key) {
+    if (byKey.has(key)) return byKey.get(key);
+    let base = String(key).replace(/[^A-Za-z0-9_]/g, '_');
+    if (!base || /^\d+$/.test(base)) base = `n_${base}`;
+    let id = base;
+    let n = 2;
+    while (used.has(id)) id = `${base}_${n++}`;
+    used.add(id);
+    byKey.set(key, id);
+    return id;
+  };
+}