d2-to-drawio 1.0.0

package/src/index.js

@@ -0,0 +1,129 @@
+// Public library API.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, basename, relative, join, resolve as resolvePath } from 'node:path';
+import { compile, dispose, D2SyntaxError } from './compile.js';
+import { mapBoard } from './map.js';
+import { emit } from './emit.js';
+
+export { dispose, D2SyntaxError };
+
+/** Error thrown in strict mode when input uses features that degrade. */
+export class UnsupportedFeatureError extends Error {
+  constructor(warnings) {
+    super(
+      `strict mode: input uses ${warnings.length} unsupported feature(s):\n` +
+        warnings.map((w) => `  - ${w.message}`).join('\n')
+    );
+    this.name = 'UnsupportedFeatureError';
+    this.code = 'UNSUPPORTED_STRICT';
+    this.warnings = warnings;
+  }
+}
+
+function createWarnings() {
+  const seen = new Set();
+  const list = [];
+  return {
+    list,
+    add(code, message) {
+      if (seen.has(code)) return;
+      seen.add(code);
+      list.push({ code, message });
+    },
+  };
+}
+
+/** Collect a board and its nested boards (layers/scenarios/steps) as pages. */
+function collectBoards(diagram, prefix, out) {
+  out.push({ diagram, name: diagram.name || (out.length === 0 ? 'Page-1' : `page-${out.length + 1}`), prefix });
+  for (const kind of ['layers', 'scenarios', 'steps']) {
+    for (const child of diagram[kind] ?? []) {
+      collectBoards(child, prefix ? `${prefix}/${child.name}` : child.name, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Convert D2 source text to an uncompressed draw.io XML string.
+ *
+ * @param {string} d2Source
+ * @param {object} [options]
+ * @param {'dagre'|'elk'} [options.layout] layout engine (default dagre)
+ * @param {number} [options.themeID] D2 theme id (default 0)
+ * @param {boolean} [options.strict] fail on unsupported features instead of degrading
+ * @param {boolean} [options.waypoints] preserve D2 edge routes as draw.io waypoints
+ * @param {(warning: {code: string, message: string}) => void} [options.onWarning]
+ * @returns {Promise<string>}
+ */
+export async function convert(d2Source, options = {}) {
+  // Strip a UTF-8 BOM so a BOM'd file or stream still parses.
+  if (d2Source.charCodeAt(0) === 0xfeff) d2Source = d2Source.slice(1);
+  const result = await compile(d2Source, options);
+  const warnings = createWarnings();
+
+  // The root board's config echoes the effective theme (an in-file
+  // vars.d2-config can set it when the caller does not).
+  const boardOptions = {
+    ...options,
+    themeID: result.diagram?.config?.themeID ?? options.themeID ?? 0,
+  };
+
+  const boards = collectBoards(result.diagram, '', []);
+  const pages = boards.map((b, i) => {
+    const page = mapBoard(b.diagram, boardOptions, warnings);
+    if (b.prefix) page.name = b.prefix;
+    else if (!b.diagram.name) page.name = i === 0 ? 'Page-1' : `page-${i + 1}`;
+    return page;
+  });
+
+  if (options.strict && warnings.list.length > 0) {
+    throw new UnsupportedFeatureError(warnings.list);
+  }
+  if (options.onWarning) for (const w of warnings.list) options.onWarning(w);
+
+  return emit(pages);
+}
+
+/**
+ * Build a virtual filesystem map of every .d2 file under rootDir (relative
+ * paths, forward slashes) so the compiler can resolve @imports.
+ */
+export function buildImportFs(rootDir) {
+  const fsMap = {};
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+        walk(join(dir, entry.name));
+      } else if (entry.name.endsWith('.d2')) {
+        const abs = join(dir, entry.name);
+        const rel = relative(rootDir, abs).split('\\').join('/');
+        fsMap[rel] = readFileSync(abs, 'utf8');
+      }
+    }
+  };
+  walk(rootDir);
+  return fsMap;
+}
+
+/**
+ * Convert a .d2 file to draw.io XML. Sibling .d2 files (recursively under
+ * the file's directory) are made available to the compiler so relative
+ * @imports resolve.
+ *
+ * @param {string} inputPath path to the .d2 file
+ * @param {object} [options] same options as convert()
+ * @returns {Promise<string>}
+ */
+export async function convertFile(inputPath, options = {}) {
+  const abs = resolvePath(inputPath);
+  const source = readFileSync(abs, 'utf8');
+  const rootDir = dirname(abs);
+  return convert(source, {
+    ...options,
+    fsMap: buildImportFs(rootDir),
+    inputPath: basename(abs),
+  });
+}

package/src/map.js

@@ -0,0 +1,447 @@
+// Map the D2 diagram IR (d2target.Diagram) to draw.io pages of cells.
+//
+// The IR arrives flat: every shape carries a dotted id, a nesting level, and
+// ABSOLUTE coordinates. draw.io wants a parent tree with child coordinates
+// relative to the parent, so this module rebuilds the tree, converts
+// coordinates, and translates styles.
+
+import { createIdAllocator } from './ids.js';
+import { resolveColor } from './themes.js';
+import { htmlLabel, escHtml } from './emit.js';
+import { sqlTableLabel, classLabel, iconUrl } from './special.js';
+
+// D2 shape type -> draw.io style prefix. Values verified against the draw.io
+// default stylesheet where possible; visual fidelity is refined per fixture.
+const SHAPE_STYLES = {
+  rectangle: '',
+  square: '',
+  page: 'shape=note;',
+  parallelogram: 'shape=parallelogram;perimeter=parallelogramPerimeter;',
+  document: 'shape=document;',
+  cylinder: 'shape=cylinder3;boundedLbl=1;backgroundOutline=1;size=15;',
+  queue: 'shape=cylinder3;direction=north;boundedLbl=1;backgroundOutline=1;size=15;',
+  package: 'shape=folder;tabWidth=60;tabHeight=20;tabPosition=left;',
+  step: 'shape=step;perimeter=stepPerimeter;',
+  callout: 'shape=callout;',
+  stored_data: 'shape=dataStorage;',
+  person: 'shape=actor;',
+  'c4-person': 'shape=actor;',
+  diamond: 'rhombus;',
+  oval: 'ellipse;',
+  circle: 'ellipse;',
+  hexagon: 'shape=hexagon;perimeter=hexagonPerimeter2;',
+  cloud: 'shape=cloud;',
+  // Structured shapes render as one vertex with a formatted label.
+  sql_table: '',
+  class: '',
+  // Sequence containers render as a plain frame.
+  sequence_diagram: '',
+};
+
+// D2 arrowhead -> draw.io startArrow/endArrow value + fill flag.
+// The IR vocabulary was probed live: filled variants arrive as
+// "filled-diamond", explicit unfilled triangles as "unfilled-triangle".
+const ARROWHEADS = {
+  none: { arrow: 'none', fill: 0 },
+  triangle: { arrow: 'block', fill: 1 },
+  'unfilled-triangle': { arrow: 'block', fill: 0 },
+  arrow: { arrow: 'classicThin', fill: 1 },
+  diamond: { arrow: 'diamond', fill: 0 },
+  'filled-diamond': { arrow: 'diamond', fill: 1 },
+  circle: { arrow: 'oval', fill: 0 },
+  'filled-circle': { arrow: 'oval', fill: 1 },
+  box: { arrow: 'box', fill: 0 },
+  'filled-box': { arrow: 'box', fill: 1 },
+  'cf-one': { arrow: 'ERone', fill: 0 },
+  'cf-one-required': { arrow: 'ERmandOne', fill: 0 },
+  'cf-many': { arrow: 'ERzeroToMany', fill: 0 },
+  'cf-many-required': { arrow: 'ERoneToMany', fill: 0 },
+  cross: { arrow: 'cross', fill: 0 },
+};
+
+function fontStyleBits(s) {
+  let bits = 0;
+  if (s.bold) bits |= 1;
+  if (s.italic) bits |= 2;
+  if (s.underline) bits |= 4;
+  return bits;
+}
+
+/** Shared text style fragments for both vertices and edges. */
+function commonTextStyle(s, themeID, style) {
+  if (s.fontSize && s.fontSize !== 12) style.push(`fontSize=${s.fontSize}`);
+  if (s.color) style.push(`fontColor=${resolveColor(s.color, themeID)}`);
+  if (s.fontFamily === 'mono') style.push('fontFamily=Courier New');
+  const bits = fontStyleBits(s);
+  if (bits) style.push(`fontStyle=${bits}`);
+}
+
+/**
+ * Translate the IR labelPosition (e.g. INSIDE_TOP_CENTER, OUTSIDE_BOTTOM_LEFT)
+ * into draw.io align keys. The INSIDE_MIDDLE_CENTER default adds nothing.
+ */
+function labelPositionStyle(pos, style) {
+  if (!pos || pos === 'INSIDE_MIDDLE_CENTER' || pos === 'UNLOCKED') return;
+  const m = /^(INSIDE|OUTSIDE|BORDER)_(TOP|MIDDLE|BOTTOM)_(LEFT|CENTER|RIGHT)$/.exec(pos);
+  if (!m) return;
+  const [, region, vert, horiz] = m;
+  if (region === 'OUTSIDE' && vert === 'TOP') {
+    style.push('verticalLabelPosition=top', 'verticalAlign=bottom');
+  } else if (region === 'OUTSIDE' && vert === 'BOTTOM') {
+    style.push('verticalLabelPosition=bottom', 'verticalAlign=top');
+  } else if (region === 'OUTSIDE' && vert === 'MIDDLE' && horiz === 'LEFT') {
+    style.push('labelPosition=left', 'align=right');
+    return;
+  } else if (region === 'OUTSIDE' && vert === 'MIDDLE' && horiz === 'RIGHT') {
+    style.push('labelPosition=right', 'align=left');
+    return;
+  } else {
+    // INSIDE and BORDER variants approximate to inside alignment.
+    if (vert === 'TOP') style.push('verticalAlign=top');
+    if (vert === 'BOTTOM') style.push('verticalAlign=bottom');
+  }
+  if (horiz === 'LEFT') style.push('align=left');
+  if (horiz === 'RIGHT') style.push('align=right');
+}
+
+function vertexStyle(shape, themeID, warnings) {
+  const style = [];
+  const isContainer = Boolean(shape.__hasChildren);
+
+  let prefix = SHAPE_STYLES[shape.type];
+  if (prefix === undefined) {
+    warnings.add(
+      `shape-${shape.type}`,
+      `shape "${shape.type}" has no draw.io mapping; rendered as a rectangle (first: ${shape.id})`
+    );
+    prefix = '';
+  }
+  if (prefix) style.push(prefix.replace(/;$/, ''));
+  else style.push(shape.borderRadius > 0 ? 'rounded=1' : 'rounded=0');
+  if (prefix && shape.borderRadius > 0) style.push('rounded=1');
+  style.push('whiteSpace=wrap', 'html=1');
+
+  if (isContainer) {
+    style.push('container=1', 'collapsible=0', 'verticalAlign=top');
+  } else {
+    labelPositionStyle(shape.labelPosition, style);
+  }
+  const isTable = shape.type === 'sql_table' || shape.type === 'class';
+  if (isTable) {
+    // D2 table semantics invert the usual keys: fill colors the HEADER
+    // band, stroke fills the BODY, color is the header text. A single
+    // draw.io shape gets the body fill and a header-colored border; the
+    // label builder colors the header text to match.
+    style.push('align=left', 'spacingLeft=6', 'spacingRight=6', 'verticalAlign=top');
+    if (shape.stroke) style.push(`fillColor=${resolveColor(shape.stroke, themeID)}`);
+    if (shape.fill) style.push(`strokeColor=${resolveColor(shape.fill, themeID)}`);
+  } else {
+    if (shape.fill) style.push(`fillColor=${resolveColor(shape.fill, themeID)}`);
+    if (shape.stroke) style.push(`strokeColor=${resolveColor(shape.stroke, themeID)}`);
+  }
+  if (shape.strokeWidth && shape.strokeWidth !== 1) style.push(`strokeWidth=${shape.strokeWidth}`);
+  if (shape.strokeDash) {
+    style.push('dashed=1', `dashPattern=${shape.strokeDash} ${shape.strokeDash}`);
+  }
+  if (shape.opacity != null && shape.opacity < 1) {
+    style.push(`opacity=${Math.round(shape.opacity * 100)}`);
+  }
+  if (shape.shadow) style.push('shadow=1');
+  if (isTable) {
+    // Body text stays default-dark; shape.color is the header text color
+    // and is applied inside the label instead.
+    if (shape.fontSize && shape.fontSize !== 12) style.push(`fontSize=${shape.fontSize}`);
+  } else {
+    commonTextStyle(shape, themeID, style);
+  }
+
+  for (const [flag, code] of [
+    ['multiple', 'style-multiple'],
+    ['3d', 'style-3d'],
+    ['double-border', 'style-double-border'],
+    ['animated', 'style-animated'],
+    ['fillPattern', 'style-fill-pattern'],
+  ]) {
+    if (shape[flag]) {
+      warnings.add(code, `style "${flag}" has no draw.io equivalent; ignored (first: ${shape.id})`);
+    }
+  }
+  return style.join(';') + ';';
+}
+
+function textStyle(shape, themeID) {
+  const style = ['text', 'html=1', 'align=center', 'verticalAlign=middle'];
+  commonTextStyle(shape, themeID, style);
+  return style.join(';') + ';';
+}
+
+function codeStyle(shape, themeID) {
+  const style = [
+    'rounded=0',
+    'whiteSpace=wrap',
+    'html=1',
+    'align=left',
+    'verticalAlign=middle',
+    'spacingLeft=6',
+    'fontFamily=Courier New',
+  ];
+  if (shape.fill) style.push(`fillColor=${resolveColor(shape.fill, themeID)}`);
+  if (shape.stroke) style.push(`strokeColor=${resolveColor(shape.stroke, themeID)}`);
+  commonTextStyle(shape, themeID, style);
+  return style.join(';') + ';';
+}
+
+function imageStyle(shape, url) {
+  const style = [
+    'shape=image',
+    'imageAspect=0',
+    'verticalLabelPosition=bottom',
+    'verticalAlign=top',
+    'html=1',
+    `image=${url}`,
+  ];
+  return style.join(';') + ';';
+}
+
+function arrowFor(value, connId, warnings) {
+  const hit = ARROWHEADS[value];
+  if (hit) return hit;
+  warnings.add(
+    `arrowhead-${value}`,
+    `arrowhead "${value}" has no draw.io mapping; using a filled triangle (first: ${connId})`
+  );
+  return ARROWHEADS.triangle;
+}
+
+function edgeStyle(conn, themeID, options, warnings) {
+  const style = ['edgeStyle=orthogonalEdgeStyle', 'rounded=0', 'html=1'];
+  if (options.waypoints && conn.isCurve) style.push('curved=1');
+
+  const src = arrowFor(conn.srcArrow ?? 'none', conn.id, warnings);
+  const dst = arrowFor(conn.dstArrow ?? 'none', conn.id, warnings);
+  style.push(`startArrow=${src.arrow}`, `startFill=${src.fill}`);
+  style.push(`endArrow=${dst.arrow}`, `endFill=${dst.fill}`);
+
+  if (conn.stroke) {
+    const c = resolveColor(conn.stroke, themeID);
+    style.push(`strokeColor=${c}`);
+    if (!conn.color) style.push(`fontColor=${c}`);
+  }
+  if (conn.strokeWidth && conn.strokeWidth !== 1) style.push(`strokeWidth=${conn.strokeWidth}`);
+  if (conn.strokeDash) style.push('dashed=1', `dashPattern=${conn.strokeDash} ${conn.strokeDash}`);
+  if (conn.opacity != null && conn.opacity < 1) style.push(`opacity=${Math.round(conn.opacity * 100)}`);
+  if (conn.animated) {
+    warnings.add(
+      'style-animated',
+      `style "animated" has no draw.io equivalent; ignored (first: ${conn.id})`
+    );
+  }
+  commonTextStyle(conn, themeID, style);
+  return style.join(';') + ';';
+}
+
+/**
+ * Find a shape's parent id: the longest dotted prefix that names an existing
+ * shape one nesting level up. Quoted segments (ids may contain '"x.y"') are
+ * safe because a prefix cut inside quotes never matches an existing id.
+ */
+function parentIdOf(shape, byId) {
+  if (shape.level == null || shape.level <= 1) return null;
+  const id = shape.id;
+  for (let i = id.length - 1; i > 0; i--) {
+    if (id[i] !== '.') continue;
+    const candidate = id.slice(0, i);
+    const parent = byId.get(candidate);
+    if (parent && parent.level === shape.level - 1) return candidate;
+  }
+  return null;
+}
+
+/** Build the label cell value for a shape, dispatching on its type. */
+function shapeValue(shape, warnings, themeID) {
+  const headerColor = shape.fill ? resolveColor(shape.fill, themeID) : null;
+  if (shape.type === 'sql_table') {
+    warnings.add(
+      'sql-table-label',
+      `sql_table rendered as a single shape with formatted rows, not editable table cells (first: ${shape.id})`
+    );
+    return sqlTableLabel(shape, headerColor);
+  }
+  if (shape.type === 'class') {
+    warnings.add(
+      'class-label',
+      `class rendered as a single shape with formatted members, not editable rows (first: ${shape.id})`
+    );
+    return classLabel(shape, headerColor);
+  }
+  if (shape.language === 'latex' || shape.language === 'tex') {
+    // draw.io renders $$...$$ via MathJax when the page has math=1.
+    return `$$${escHtml(shape.label ?? '')}$$`;
+  }
+  if (shape.type === 'text' && shape.language === 'markdown') {
+    warnings.add(
+      'text-markdown',
+      `markdown text is rendered as plain text; formatting is lost (first: ${shape.id})`
+    );
+  }
+  return htmlLabel(shape.label ?? '');
+}
+
+/**
+ * Map one board (diagram IR) to a draw.io page.
+ *
+ * @returns {{name: string, cells: object[], background: string|null, math: boolean}}
+ */
+export function mapBoard(diagram, options, warnings) {
+  const themeID = options.themeID ?? 0;
+  const idFor = createIdAllocator();
+  const byId = new Map();
+  for (const s of diagram.shapes ?? []) byId.set(s.id, s);
+
+  // Mark containers and remember sequence-diagram subtrees: their inner
+  // edges carry positions along lifelines that anchor-based routing loses.
+  const seqPrefixes = [];
+  for (const s of byId.values()) {
+    const pid = parentIdOf(s, byId);
+    s.__parentId = pid;
+    if (pid) byId.get(pid).__hasChildren = true;
+    if (s.type === 'sequence_diagram') seqPrefixes.push(s.id + '.');
+  }
+  const inSequence = (id) => seqPrefixes.some((p) => String(id).startsWith(p));
+
+  const cells = [];
+  const emitted = new Set();
+  let pageMath = false;
+
+  // Parents first (level ascending), then z-index, then IR order.
+  const order = new Map([...byId.keys()].map((k, i) => [k, i]));
+  const shapes = [...byId.values()].sort(
+    (a, b) =>
+      (a.level ?? 1) - (b.level ?? 1) ||
+      (a.zIndex ?? 0) - (b.zIndex ?? 0) ||
+      order.get(a.id) - order.get(b.id)
+  );
+
+  for (const shape of shapes) {
+    const parentShape = shape.__parentId ? byId.get(shape.__parentId) : null;
+    const x = shape.pos.x - (parentShape ? parentShape.pos.x : 0);
+    const y = shape.pos.y - (parentShape ? parentShape.pos.y : 0);
+
+    let style;
+    let value;
+    const url = iconUrl(shape.icon);
+    if (shape.language === 'latex' || shape.language === 'tex') pageMath = true;
+    if (shape.type === 'text') {
+      value = shapeValue(shape, warnings, themeID);
+      style = textStyle(shape, themeID);
+    } else if (shape.type === 'code') {
+      value = htmlLabel(shape.label ?? '');
+      style = codeStyle(shape, themeID);
+    } else if (shape.type === 'image' && url) {
+      value = htmlLabel(shape.label ?? '');
+      style = imageStyle(shape, url);
+    } else {
+      if (url) {
+        warnings.add(
+          'icon-on-shape',
+          `icons on regular shapes are not mapped; icon dropped (first: ${shape.id})`
+        );
+      }
+      value = shapeValue(shape, warnings, themeID);
+      style = vertexStyle(shape, themeID, warnings);
+    }
+
+    if (shape.link && /^(layers|scenarios|steps|root|_)(\.|$)/.test(shape.link)) {
+      warnings.add(
+        'board-link',
+        `links to boards (${shape.link}) are kept as literal text and will not navigate in draw.io (first: ${shape.id})`
+      );
+    }
+    cells.push({
+      id: idFor(shape.id),
+      value,
+      style,
+      parent: parentShape ? idFor(parentShape.id) : '1',
+      x,
+      y,
+      w: shape.width,
+      h: shape.height,
+      tooltip: shape.tooltip || null,
+      link: shape.link || null,
+    });
+    emitted.add(shape.id);
+  }
+
+  let edgeN = 0;
+  for (const conn of diagram.connections ?? []) {
+    const route = Array.isArray(conn.route) ? conn.route : [];
+    const srcOk = emitted.has(conn.src);
+    const dstOk = emitted.has(conn.dst);
+    const sequence = inSequence(conn.src) || inSequence(conn.dst);
+
+    // Fixed-geometry edges: sequence content (messages, lifelines, and any
+    // connection with a phantom endpoint) keeps d2's computed route.
+    const fixed = (sequence || !srcOk || !dstOk) && route.length >= 2;
+    if ((!srcOk || !dstOk) && !fixed) {
+      warnings.add(
+        'edge-endpoint-missing',
+        `connection ${conn.src} -> ${conn.dst} skipped: endpoint not rendered`
+      );
+      continue;
+    }
+    if (sequence) {
+      warnings.add(
+        'sequence-fixed',
+        'sequence diagram messages and lifelines use fixed geometry; they do not re-route when shapes move'
+      );
+    }
+
+    const cell = {
+      id: `edge-${edgeN++}`,
+      value: htmlLabel(conn.label ?? ''),
+      style: edgeStyle(conn, themeID, options, warnings),
+      parent: '1',
+      edge: true,
+      tooltip: conn.tooltip || null,
+      link: conn.link || null,
+    };
+    if (fixed) {
+      cell.sourcePoint = route[0];
+      cell.targetPoint = route[route.length - 1];
+      if (route.length > 2) cell.points = route.slice(1, -1);
+      // Straight segments, not orthogonal re-routing, for fixed geometry.
+      cell.style = cell.style.replace('edgeStyle=orthogonalEdgeStyle;', 'edgeStyle=none;');
+    } else {
+      cell.source = idFor(conn.src);
+      cell.target = idFor(conn.dst);
+      if (options.waypoints && route.length > 2) {
+        cell.points = route.slice(1, -1);
+      }
+    }
+    cells.push(cell);
+
+    // Arrowhead labels ride the edge as standard draw.io edge-label
+    // children positioned near their end.
+    for (const [end, rx] of [
+      ['srcLabel', -0.75],
+      ['dstLabel', 0.75],
+    ]) {
+      const l = conn[end];
+      if (l && l.label) {
+        cells.push({
+          id: `${cell.id}-${end === 'srcLabel' ? 'src' : 'dst'}-label`,
+          value: htmlLabel(l.label),
+          style: 'edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;',
+          parent: cell.id,
+          edgeLabel: true,
+          rx,
+        });
+      }
+    }
+  }
+
+  // The board's root pseudo-shape carries the page background fill.
+  const background = diagram.root?.fill ? resolveColor(diagram.root.fill, themeID) : null;
+
+  return { name: diagram.name || 'Page-1', cells, background, math: pageMath };
+}

package/src/special.js

@@ -0,0 +1,56 @@
+// HTML label builders for D2's structured shapes (sql_table, class).
+//
+// Both render as a single draw.io vertex whose html=1 label reproduces the
+// header and rows. Rows are not individually editable cells; the feature
+// matrix documents this as partial support.
+
+import { escHtml } from './emit.js';
+
+const VISIBILITY_PREFIX = { public: '+ ', private: '- ', protected: '# ' };
+
+/** Rebuild a URL string from the Go net/url object the IR carries. */
+export function iconUrl(icon) {
+  if (!icon || typeof icon !== 'object') return null;
+  const scheme = icon.Scheme ? `${icon.Scheme}://` : '';
+  const path = icon.RawPath || icon.Path || '';
+  const query = icon.RawQuery ? `?${icon.RawQuery}` : '';
+  const fragment = icon.Fragment ? `#${icon.Fragment}` : '';
+  return `${scheme}${icon.Host ?? ''}${path}${query}${fragment}` || null;
+}
+
+function header(text, color) {
+  const inner = `<b>${escHtml(text)}</b>`;
+  return color ? `<font color="${color}">${inner}</font>` : inner;
+}
+
+/** sql_table: header + one line per column with type and constraint tags. */
+export function sqlTableLabel(shape, headerColor = null) {
+  const rows = (shape.columns ?? []).map((col) => {
+    const name = escHtml(col.name?.label ?? '');
+    const type = escHtml(col.type?.label ?? '');
+    const tags = (col.constraint ?? [])
+      .map((c) => (c === 'primary_key' ? 'PK' : c === 'foreign_key' ? 'FK' : c === 'unique' ? 'UNQ' : escHtml(c)))
+      .join(', ');
+    return `${name}: ${type}${tags ? `&nbsp;&nbsp;<i>${tags}</i>` : ''}`;
+  });
+  return `${header(shape.label ?? '', headerColor)}<hr>${rows.join('<br>')}`;
+}
+
+/** class: header + fields block + methods block, UML visibility prefixes. */
+export function classLabel(shape, headerColor = null) {
+  const fields = (shape.fields ?? []).map((f) => {
+    const vis = VISIBILITY_PREFIX[f.visibility] ?? '';
+    const line = `${vis}${escHtml(f.name)}: ${escHtml(f.type)}`;
+    return f.underline ? `<u>${line}</u>` : line;
+  });
+  const methods = (shape.methods ?? []).map((m) => {
+    const vis = VISIBILITY_PREFIX[m.visibility] ?? '';
+    const ret = m.return ? `: ${escHtml(m.return)}` : '';
+    const line = `${vis}${escHtml(m.name)}${ret}`;
+    return m.underline ? `<u>${line}</u>` : line;
+  });
+  let label = header(shape.label ?? '', headerColor);
+  label += `<hr>${fields.join('<br>')}`;
+  if (methods.length > 0) label += `<hr>${methods.join('<br>')}`;
+  return label;
+}

package/src/theme-data.js

@@ -0,0 +1,25 @@
+// D2 theme palettes, extracted from the official terrastruct/d2 theme
+// catalog (d2themescatalog) and verified against live WASM renders.
+// Codes: N1-N7 neutrals, B1-B6 base, AA2/AA4/AA5 accent A, AB4/AB5 accent B.
+export const THEMES = {
+  '0': { name: 'Neutral Default', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#0D32B2', B2: '#0D32B2', B3: '#E3E9FD', B4: '#E3E9FD', B5: '#EDF0FD', B6: '#F7F8FE', AA2: '#4A6FF3', AA4: '#EDF0FD', AA5: '#F7F8FE', AB4: '#EDF0FD', AB5: '#F7F8FE' } },
+  '1': { name: 'Neutral Grey', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#0A0F25', B2: '#676C7E', B3: '#9499AB', B4: '#CFD2DD', B5: '#DEE1EB', B6: '#EEF1F8', AA2: '#676C7E', AA4: '#CFD2DD', AA5: '#DEE1EB', AB4: '#CFD2DD', AB5: '#DEE1EB' } },
+  '3': { name: 'Flagship Terrastruct', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#000E3D', B2: '#234CDA', B3: '#6B8AFB', B4: '#A6B8F8', B5: '#D2DBFD', B6: '#E7EAFF', AA2: '#5829DC', AA4: '#B4AEF8', AA5: '#E4DBFF', AB4: '#7FDBF8', AB5: '#C3F0FF' } },
+  '4': { name: 'Cool Classics', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#000536', B2: '#0F66B7', B3: '#4393DD', B4: '#87BFF3', B5: '#BCDDFB', B6: '#E5F3FF', AA2: '#076F6F', AA4: '#77DEDE', AA5: '#C3F8F8', AB4: '#C1A2F3', AB5: '#DACEFB' } },
+  '5': { name: 'Mixed Berry Blue', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#000536', B2: '#0F66B7', B3: '#4393DD', B4: '#87BFF3', B5: '#BCDDFB', B6: '#E5F3FF', AA2: '#7639C5', AA4: '#C1A2F3', AA5: '#DACEFB', AB4: '#EA99C6', AB5: '#FFDEF1' } },
+  '6': { name: 'Grape Soda', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#170034', B2: '#7639C5', B3: '#8F70D1', B4: '#C1A2F3', B5: '#DACEFB', B6: '#F2EDFF', AA2: '#0F66B7', AA4: '#87BFF3', AA5: '#BCDDFB', AB4: '#EA99C6', AB5: '#FFDAEF' } },
+  '7': { name: 'Aubergine', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#170034', B2: '#7639C5', B3: '#8F70D1', B4: '#D0B9F5', B5: '#E7DEFF', B6: '#F4F0FF', AA2: '#0F66B7', AA4: '#87BFF3', AA5: '#BCDDFB', AB4: '#92E3E3', AB5: '#D7F5F5' } },
+  '8': { name: 'Colorblind Clear', colors: { N1: '#0A0F25', N2: '#676C7E', N3: '#9499AB', N4: '#CFD2DD', N5: '#DEE1EB', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#010E31', B2: '#173688', B3: '#5679D4', B4: '#84A1EC', B5: '#C8D6F9', B6: '#E5EDFF', AA2: '#048E63', AA4: '#A6E2D0', AA5: '#CAF2E6', AB4: '#FFDA90', AB5: '#FFF0D1' } },
+  '100': { name: 'Vanilla Nitro Cola', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#1E1303', B2: '#55452F', B3: '#9A876C', B4: '#C9B9A1', B5: '#E9DBCA', B6: '#FAF1E6', AA2: '#D35F0A', AA4: '#FABA8A', AA5: '#FFE0C7', AB4: '#84A1EC', AB5: '#D5E0FD' } },
+  '101': { name: 'Orange Creamsicle', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#311602', B2: '#D35F0A', B3: '#F18F47', B4: '#FABA8A', B5: '#FFE0C7', B6: '#FFF6EF', AA2: '#13A477', AA4: '#A6E2D0', AA5: '#CAF2E6', AB4: '#FEEC8C', AB5: '#FFF8CF' } },
+  '102': { name: 'Shirley Temple', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#31021D', B2: '#9B1A48', B3: '#D2517F', B4: '#EA99B6', B5: '#FFDAE7', B6: '#FCEDF2', AA2: '#D35F0A', AA4: '#FABA8A', AA5: '#FFE0C7', AB4: '#FFE767', AB5: '#FFF2AA' } },
+  '103': { name: 'Earth Tones', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#1E1303', B2: '#55452F', B3: '#9A876C', B4: '#C9B9A1', B5: '#E9DBCA', B6: '#FAF1E6', AA2: '#D35F0A', AA4: '#FABA8A', AA5: '#FFE0C7', AB4: '#FFE767', AB5: '#FFF2AA' } },
+  '104': { name: 'Everglade Green', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#023324', B2: '#048E63', B3: '#49BC99', B4: '#A6E2D0', B5: '#CAF2E6', B6: '#EBFDF7', AA2: '#D35F0A', AA4: '#FABA8A', AA5: '#FFE0C7', AB4: '#C9B9A1', AB5: '#E9DBCA' } },
+  '105': { name: 'Buttered Toast', colors: { N1: '#170206', N2: '#535152', N3: '#787777', N4: '#CCCACA', N5: '#DFDCDC', N6: '#ECEBEB', N7: '#FFFFFF', B1: '#312102', B2: '#DF9C18', B3: '#FDC659', B4: '#FFDA90', B5: '#FFF0D1', B6: '#FFF7E7', AA2: '#55452F', AA4: '#C9B9A1', AA5: '#E9DBCA', AB4: '#FABA8A', AB5: '#FFE0C7' } },
+  '200': { name: 'Dark Mauve', colors: { N1: '#CDD6F4', N2: '#BAC2DE', N3: '#A6ADC8', N4: '#585B70', N5: '#45475A', N6: '#313244', N7: '#1E1E2E', B1: '#CBA6f7', B2: '#CBA6f7', B3: '#6C7086', B4: '#585B70', B5: '#45475A', B6: '#313244', AA2: '#f38BA8', AA4: '#45475A', AA5: '#313244', AB4: '#45475A', AB5: '#313244' } },
+  '201': { name: 'Dark Flagship Terrastruct', colors: { N1: '#F4F6FA', N2: '#BBBEC9', N3: '#868A96', N4: '#676D7D', N5: '#3A3D49', N6: '#191C28', N7: '#000410', B1: '#F4F6FA', B2: '#6B8AFB', B3: '#3733E9', B4: '#070B67', B5: '#0B1197', B6: '#3733E9', AA2: '#8B5DEE', AA4: '#4918B1', AA5: '#7240DD', AB4: '#00607C', AB5: '#01799D' } },
+  '300': { name: 'Terminal', colors: { N1: '#000410', N2: '#0000B8', N3: '#9499AB', N4: '#CFD2DD', N5: '#C3DEF3', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#000410', B2: '#0000E4', B3: '#5AA4DC', B4: '#E7E9EE', B5: '#F5F6F9', B6: '#FFFFFF', AA2: '#008566', AA4: '#45BBA5', AA5: '#7ACCBD', AB4: '#F1C759', AB5: '#F9E088' } },
+  '301': { name: 'Terminal Grayscale', colors: { N1: '#000410', N2: '#000410', N3: '#9499AB', N4: '#FFFFFF', N5: '#FFFFFF', N6: '#EEF1F8', N7: '#FFFFFF', B1: '#000410', B2: '#000410', B3: '#FFFFFF', B4: '#E7E9EE', B5: '#F5F6F9', B6: '#FFFFFF', AA2: '#6D7284', AA4: '#F5F6F9', AA5: '#FFFFFF', AB4: '#F5F6F9', AB5: '#FFFFFF' } },
+  '302': { name: 'Origami', colors: { N1: '#170206', N2: '#6F0019', N3: '#FFFFFF', N4: '#E07088', N5: '#D2B098', N6: '#FFFFFF', N7: '#FFFFFF', B1: '#170206', B2: '#A62543', B3: '#E07088', B4: '#F3E0D2', B5: '#FAF1E6', B6: '#FFFBF8', AA2: '#0A4EA6', AA4: '#3182CD', AA5: '#68A8E4', AB4: '#E07088', AB5: '#F19CAE' } },
+  '303': { name: 'C4', colors: { N1: '#0f5eaa', N2: '#707070', N3: '#FFFFFF', N4: '#073b6f', N5: '#999999', N6: '#FFFFFF', N7: '#FFFFFF', B1: '#073b6f', B2: '#08427b', B3: '#3c7fc0', B4: '#438dd5', B5: '#8a8a8a', B6: '#999999', AA2: '#0f5eaa', AA4: '#707070', AA5: '#f5f5f5', AB4: '#e1e1e1', AB5: '#f0f0f0' } },
+};