@itsthecsguy/linework 0.0.0-stage → 0.1.0

package/dist/drawio/write.js

@@ -0,0 +1,300 @@
+import { kindDef } from '../spec/model.js';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { ICON_PAD, ICON_SIZE, resolveIcon } from './icons.js';
+import { ER_HEAD, ER_ROW, edgeStyle, erEdgeStyle, fieldLabel, fieldStyle, groupLabel, groupStyle, nodeLabel, nodeStyle, paintFor, palette } from './theme.js';
+export { ER_HEAD, ER_ROW };
+export const FORMAT_VERSION = '1';
+export const xmlEsc = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '&#10;');
+const r = (v) => Math.round(v);
+export const autoAttr = (b) => `${r(b.x)},${r(b.y)},${r(b.w)},${r(b.h)}`;
+export function edgeCellId(edgeId) {
+    return 'e_' + edgeId.replace('->', '__').replace('#', '_');
+}
+export function diagramMeta(d, extra = {}) {
+    return {
+        aiviz_version: FORMAT_VERSION,
+        aiviz_type: d.type,
+        aiviz_direction: d.direction,
+        ...(d.theme !== 'clean' ? { aiviz_theme: d.theme } : {}),
+        ...(d.title ? { aiviz_title: d.title } : {}),
+        ...extra,
+    };
+}
+export function nodeAttrs(d, n) {
+    const shape = kindDef(d.type, n.kind).shape;
+    const label = shape === 'start' || shape === 'end' ? '' : shape === 'table' ? n.label : nodeLabel(n.label, n.tech, { theme: d.theme, type: d.type, kind: n.kind, color: n.color, highlight: n.highlight });
+    return {
+        label,
+        aiviz_kind: n.kind,
+        aiviz_label: n.label,
+        ...(n.tech ? { aiviz_tech: n.tech } : {}),
+        ...(n.icon ? { aiviz_icon: n.icon } : {}),
+        ...lookAttrs(n),
+    };
+}
+/** color/highlight as cell attributes, so `show` gives them back. */
+export function lookAttrs(l) {
+    return { ...(l.color ? { aiviz_color: l.color } : {}), ...(l.highlight ? { aiviz_highlight: '1' } : {}) };
+}
+export function lookOf(attrs) {
+    const out = {};
+    if (attrs.aiviz_color)
+        out.color = attrs.aiviz_color;
+    if (attrs.aiviz_highlight === '1')
+        out.highlight = true;
+    return out;
+}
+/** Field rows of an ER entity, as children stacked under its header. */
+export function fieldRows(d, n, width) {
+    return (n.fields ?? []).map((f, i) => ({
+        id: `${n.id}__${f.name}`,
+        parent: n.id,
+        attrs: {
+            label: fieldLabel(f.name, f.type, f.flags, d.theme),
+            aiviz_field: f.name,
+            ...(f.type ? { aiviz_ftype: f.type } : {}),
+            ...(f.flags.length ? { aiviz_flags: f.flags.join(' ') } : {}),
+        },
+        style: fieldStyle(d.theme),
+        box: { x: 0, y: ER_HEAD + i * ER_ROW, w: width, h: ER_ROW },
+    }));
+}
+/** Children a node carries: ER field rows, or a cloud icon. */
+export function nodeChildren(d, n, box) {
+    const out = fieldRows(d, n, box.w);
+    if (n.icon) {
+        const paint = paintFor(d.type, n.kind, d.theme, n);
+        const fill = /^#[0-9a-f]{6}$/i.test(paint.fill) ? paint.fill : palette(d.theme).canvas;
+        const r = resolveIcon(n.icon, { fill, ink: paint.text });
+        if (!('error' in r))
+            out.push({
+                id: `${n.id}__icon`,
+                parent: n.id,
+                attrs: { label: '', aiviz_type: 'icon' },
+                style: r.style,
+                box: { x: (ICON_PAD - ICON_SIZE) / 2 + 2, y: Math.round((box.h - ICON_SIZE) / 2), w: ICON_SIZE, h: ICON_SIZE },
+            });
+    }
+    return out;
+}
+/** Node style, with room on the left when it has an icon. */
+export function styleFor(d, n) {
+    const st = nodeStyle(d.type, n.kind, d.theme, n);
+    return n.icon ? `${st}align=left;spacingLeft=${ICON_PAD};` : st;
+}
+/** An edge label inside a filled group gets the group's fill behind it, not the canvas. */
+function labelBg(d, l, label) {
+    if (!label)
+        return undefined;
+    const cx = label.x + label.w / 2, cy = label.y + label.h / 2;
+    let best;
+    for (const g of d.groups) {
+        const b = l.groups.get(g.id);
+        if (!b || cx < b.x || cx > b.x + b.w || cy < b.y || cy > b.y + b.h)
+            continue;
+        const fill = /fillColor=([^;]+)/.exec(groupStyleFor(d, g))?.[1];
+        if (fill && fill !== 'none' && (!best || b.w * b.h < best.area))
+            best = { area: b.w * b.h, fill };
+    }
+    return best?.fill;
+}
+export function edgeStyleFor(d, e, bg) {
+    return d.type === 'er' && e.card ? erEdgeStyle(e.card, d.theme, e) : edgeStyle(e.style, d.theme, e, bg);
+}
+export function edgeAttrs(e) {
+    return { label: e.label ?? '', aiviz_edge: e.id, ...lookAttrs(e) };
+}
+/** How deep a group sits: 0 at the top, 1 inside another group, and so on. */
+export function groupDepth(d, g) {
+    let n = 0;
+    for (let p = g.parent; p && n < 20; p = d.groups.find((x) => x.id === p)?.parent)
+        n++;
+    return n;
+}
+export const groupStyleFor = (d, g) => groupStyle(d.theme, g, groupDepth(d, g));
+export function groupAttrs(g, theme = 'clean') {
+    return { label: groupLabel(g.label, theme), aiviz_type: 'group', aiviz_label: g.label, ...lookAttrs(g) };
+}
+/** Exit/entry constraints so draw.io leaves and enters nodes where ELK did. */
+export function portStyle(points, s, t) {
+    const start = points[0], end = points[points.length - 1];
+    const c01 = (v) => Math.min(1, Math.max(0, Math.round(v * 1000) / 1000));
+    return (`exitX=${c01((start.x - s.x) / s.w)};exitY=${c01((start.y - s.y) / s.h)};exitDx=0;exitDy=0;` +
+        `entryX=${c01((end.x - t.x) / t.w)};entryY=${c01((end.y - t.y) / t.h)};entryDx=0;entryDy=0;`);
+}
+export function sceneFromLayout(d, l) {
+    const parentOf = new Map();
+    for (const g of d.groups)
+        parentOf.set(g.id, g.parent);
+    for (const n of d.nodes)
+        parentOf.set(n.id, n.parent);
+    const abs = (id) => l.nodes.get(id) ?? l.groups.get(id);
+    const rel = (id) => {
+        const a = abs(id), p = parentOf.get(id);
+        if (!p)
+            return a;
+        const pb = abs(p);
+        return { ...a, x: a.x - pb.x, y: a.y - pb.y };
+    };
+    const vertices = [];
+    for (const g of d.groups) {
+        const box = rel(g.id);
+        vertices.push({ id: g.id, parent: g.parent ?? '1', attrs: { ...groupAttrs(g, d.theme), aiviz_auto: autoAttr(box) }, style: groupStyleFor(d, g), box });
+    }
+    for (const n of d.nodes) {
+        const box = rel(n.id);
+        vertices.push({ id: n.id, parent: n.parent ?? '1', attrs: { ...nodeAttrs(d, n), aiviz_auto: autoAttr(box) }, style: styleFor(d, n), box });
+        vertices.push(...nodeChildren(d, n, box));
+    }
+    const edges = d.edges.map((e) => {
+        const le = l.edges.get(e.id);
+        const base = { id: edgeCellId(e.id), parent: '1', attrs: edgeAttrs(e), style: edgeStyleFor(d, e, labelBg(d, l, le?.label)), source: e.from, target: e.to };
+        if (!le)
+            return base;
+        return {
+            ...base,
+            style: base.style + portStyle(le.points, abs(e.from), abs(e.to)),
+            points: le.points.slice(1, -1),
+            labelX: le.label && e.label ? (labelSpot(le.points, le.label) ?? labelFraction(le.points, { x: le.label.x + le.label.w / 2, y: le.label.y + le.label.h / 2 })) : undefined,
+        };
+    });
+    return { name: d.title ?? 'Diagram', background: palette(d.theme).canvas, meta: diagramMeta(d), vertices, edges, raw: [] };
+}
+const attrString = (attrs) => Object.entries(attrs)
+    .filter(([k]) => k !== 'id')
+    .map(([k, v]) => ` ${k}="${xmlEsc(v)}"`)
+    .join('');
+export function serialize(scene) {
+    // Parents before children.
+    const parentOf = new Map(scene.vertices.map((v) => [v.id, v.parent]));
+    const depth = (id) => {
+        const p = parentOf.get(id);
+        return p && p !== '1' ? 1 + depth(p) : 0;
+    };
+    // Containers first (outermost first), then everything else in its original order,
+    // which show() reads back and ELK uses as a placement hint.
+    const isParent = new Set(scene.vertices.map((v) => v.parent));
+    const containers = scene.vertices.filter((v) => isParent.has(v.id) || v.attrs.aiviz_type === 'group').sort((a, b) => depth(a.id) - depth(b.id));
+    const vertices = [...containers, ...scene.vertices.filter((v) => !containers.includes(v))];
+    const cells = [];
+    for (const v of vertices) {
+        const b = v.box;
+        cells.push(`<object id="${xmlEsc(v.id)}"${attrString({ label: '', ...v.attrs })}>` +
+            `<mxCell style="${xmlEsc(v.style)}" vertex="1" parent="${xmlEsc(v.parent)}">` +
+            `<mxGeometry x="${r(b.x)}" y="${r(b.y)}" width="${r(b.w)}" height="${r(b.h)}" as="geometry"/></mxCell></object>`);
+    }
+    cells.push(...scene.raw);
+    for (const e of scene.edges) {
+        const geom = e.geomRaw ??
+            `<mxGeometry ${e.labelX ? `x="${e.labelX.toFixed(3)}" ` : ''}relative="1" as="geometry">` +
+                (e.points?.length ? `<Array as="points">${e.points.map((p) => `<mxPoint x="${r(p.x)}" y="${r(p.y)}"/>`).join('')}</Array>` : '') +
+                `</mxGeometry>`;
+        cells.push(`<object id="${xmlEsc(e.id)}"${attrString({ label: '', ...e.attrs })}>` +
+            `<mxCell style="${xmlEsc(e.style)}" edge="1" parent="${xmlEsc(e.parent)}"` +
+            (e.source ? ` source="${xmlEsc(e.source)}"` : '') +
+            (e.target ? ` target="${xmlEsc(e.target)}"` : '') +
+            `>${geom}</mxCell></object>`);
+    }
+    return (`<mxfile host="aiviz" agent="aiviz"><diagram id="aiviz" name="${xmlEsc(scene.name)}">` +
+        `<mxGraphModel grid="1" gridSize="8" guides="1" tooltips="1" connect="1" arrows="1" page="0" background="${scene.background ?? '#FFFFFF'}" math="0" shadow="0">` +
+        `<root><object id="0"${attrString({ label: '', ...scene.meta })}><mxCell/></object><mxCell id="1" parent="0"/>${cells.join('')}</root></mxGraphModel></diagram></mxfile>`);
+}
+/** Fresh build: spec + layout -> XML. */
+export function toMxfile(d, l) {
+    return serialize(sceneFromLayout(d, l));
+}
+/**
+ * Where a label reads best: centred on the edge's longest straight run, clear of
+ * the boxes at either end and of the bends. ELK puts labels right next to the
+ * source node, which reads as a caption of that node. Returns draw.io's -1..1
+ * fraction, or undefined when no run is long enough.
+ */
+function labelSpot(pts, label) {
+    let total = 0;
+    let best;
+    for (let i = 0; i < pts.length - 1; i++) {
+        const a = pts[i], b = pts[i + 1];
+        const len = Math.hypot(b.x - a.x, b.y - a.y);
+        const vertical = Math.abs(b.x - a.x) < Math.abs(b.y - a.y);
+        const room = len - (vertical ? label.h : label.w) - 20;
+        if (room >= 0 && (!best || room > best.room))
+            best = { room, at: total + len / 2 };
+        total += len;
+    }
+    return best && total ? (best.at / total) * 2 - 1 : undefined;
+}
+// draw.io positions edge labels by fraction along the path, -1..1.
+// Project ELK's label centre onto the route and convert.
+function labelFraction(pts, c) {
+    let total = 0;
+    let best = { d: Infinity, at: 0 };
+    for (let i = 0; i < pts.length - 1; i++) {
+        const a = pts[i], b = pts[i + 1];
+        const len = Math.hypot(b.x - a.x, b.y - a.y);
+        const t = len ? Math.max(0, Math.min(1, ((c.x - a.x) * (b.x - a.x) + (c.y - a.y) * (b.y - a.y)) / (len * len))) : 0;
+        const d = Math.hypot(c.x - (a.x + t * (b.x - a.x)), c.y - (a.y + t * (b.y - a.y)));
+        if (d < best.d)
+            best = { d, at: total + t * len };
+        total += len;
+    }
+    return total ? (best.at / total) * 2 - 1 : 0;
+}
+export const routeAttr = (pts) => pts.map((p) => `${r(p.x)},${r(p.y)}`).join(' ');
+/**
+ * Record each linework edge's route as aiviz_auto, so a later merge can tell a route
+ * nobody touched (safe to reroute) from one a person adjusted (keep).
+ */
+export function stampEdgeRoutes(xml) {
+    const doc = new DOMParser().parseFromString(xml, 'text/xml');
+    const objects = doc.getElementsByTagName('object');
+    for (let i = 0; i < objects.length; i++) {
+        const o = objects[i];
+        if (!o.getAttribute('aiviz_edge'))
+            continue;
+        const geom = o.getElementsByTagName('mxGeometry')[0];
+        const pts = [];
+        const arr = geom?.getElementsByTagName('Array')[0];
+        if (arr) {
+            const ps = arr.getElementsByTagName('mxPoint');
+            for (let j = 0; j < ps.length; j++)
+                pts.push({ x: +(ps[j].getAttribute('x') ?? 0), y: +(ps[j].getAttribute('y') ?? 0) });
+        }
+        o.setAttribute('aiviz_auto', routeAttr(pts));
+    }
+    return new XMLSerializer().serializeToString(doc);
+}
+function cellById(doc, id) {
+    for (const tag of ['object', 'UserObject', 'mxCell']) {
+        const els = doc.getElementsByTagName(tag);
+        for (let i = 0; i < els.length; i++) {
+            const el = els[i];
+            if (el.getAttribute('id') !== id)
+                continue;
+            if (tag === 'mxCell')
+                return el;
+            const inner = el.getElementsByTagName('mxCell')[0];
+            if (inner)
+                return inner;
+        }
+    }
+    return undefined;
+}
+/**
+ * Copy the style and geometry of the given edges from a model the browser rerouted
+ * back into our own XML. Only those edges change; everything else stays byte-stable.
+ */
+export function patchEdges(ours, routedModel, ids) {
+    const doc = new DOMParser().parseFromString(ours, 'text/xml');
+    const routed = new DOMParser().parseFromString(routedModel, 'text/xml');
+    for (const id of ids) {
+        const src = cellById(routed, id), dst = cellById(doc, id);
+        if (!src || !dst)
+            continue;
+        dst.setAttribute('style', src.getAttribute('style') ?? '');
+        const sg = src.getElementsByTagName('mxGeometry')[0];
+        const dg = dst.getElementsByTagName('mxGeometry')[0];
+        if (sg && dg)
+            dst.replaceChild(doc.importNode(sg, true), dg);
+    }
+    return new XMLSerializer().serializeToString(doc);
+}

package/dist/edit/server.js

@@ -0,0 +1,212 @@
+// `linework edit`: open a diagram in the bundled draw.io editor, in the user's own
+// browser, and write saves back to the same file. Uses draw.io's JSON embed
+// protocol, the one the VS Code extension uses, so saved files are what
+// draw.io itself writes. Everything is served from 127.0.0.1; nothing goes online.
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { extractMxfile } from '../drawio/read.js';
+import { assetsDir } from '../render/browser.js';
+import { FACES, embedFonts, fontFaceCss, fontsDir } from '../render/fonts.js';
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript',
+    '.css': 'text/css',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.json': 'application/json',
+    '.txt': 'text/plain; charset=utf-8',
+    '.xml': 'text/xml',
+};
+const EMBED_PARAMS = 'embed=1&proto=json&spin=1&libraries=1&noSaveBtn=0&noExitBtn=0&offline=1&pwa=0&stealth=1&lang=en&dev=0';
+function hostPage(name, xml, mtime, token, format) {
+    // JSON inside a <script>: escape "<" so a label containing "</script>" can't end the tag.
+    const data = JSON.stringify({ name, xml, mtime, format }).replace(/</g, '\\u003c');
+    return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${name.replace(/[<&]/g, '')} - linework edit</title>
+<style>html,body{margin:0;height:100%;overflow:hidden;font:14px -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif}
+iframe{border:0;width:100%;height:100%} #msg{display:none;padding:48px;color:#334155}</style></head>
+<body><iframe id="f" src="/app/index.html?${EMBED_PARAMS}"></iframe><div id="msg"></div>
+<script>
+const D = ${data};
+const base = '/${token}';
+const f = document.getElementById('f');
+const send = (m) => f.contentWindow.postMessage(JSON.stringify(m), '*');
+let pending = null; // the save waiting for its export
+async function post(p, body) {
+  const r = await fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body || {}) });
+  return { ok: r.ok, body: await r.json().catch(() => ({})) };
+}
+function finish(text) {
+  f.remove();
+  const m = document.getElementById('msg');
+  m.style.display = 'block';
+  m.textContent = text;
+  post('/exit');
+}
+async function write(payload, exit) {
+  const res = await post('/save', { ...payload, mtime: D.mtime });
+  if (res.ok) {
+    D.mtime = res.body.mtime;
+    send({ action: 'status', message: 'Saved to ' + D.name, modified: false });
+    if (exit) finish('Saved ' + D.name + '. You can close this tab.');
+  } else {
+    send({ action: 'dialog', title: 'Not saved to ' + D.name, message: res.body.error || 'save failed', button: 'OK' });
+  }
+}
+window.addEventListener('message', (e) => {
+  if (e.source !== f.contentWindow || typeof e.data !== 'string') return;
+  let m; try { m = JSON.parse(e.data); } catch { return; }
+  if (m.event === 'init') send({ action: 'load', xml: D.xml, title: D.name, autosave: 0, modified: 'unsavedChanges' });
+  else if (m.event === 'save') {
+    if (D.format === 'xml') write({ xml: m.xml }, m.exit);
+    else { pending = { exit: m.exit }; send({ action: 'export', format: 'xmlsvg', xml: m.xml, spinKey: 'saving' }); }
+  } else if (m.event === 'export' && pending) {
+    const p = pending; pending = null;
+    write({ data: m.data }, p.exit);
+  } else if (m.event === 'exit') finish('Closed ' + D.name + '. You can close this tab.');
+});
+window.addEventListener('pagehide', () => navigator.sendBeacon(base + '/closed'));
+</script></body></html>`;
+}
+export async function startEditor(file, opts = {}) {
+    const abs = path.resolve(file);
+    if (!fs.existsSync(abs))
+        throw new Error(`${file} doesn't exist. Create it with linework build first.`);
+    const format = abs.endsWith('.svg') ? 'svg' : 'xml';
+    extractMxfile(fs.readFileSync(abs, 'utf8')); // fail early on files draw.io can't open
+    const assets = assetsDir();
+    if (!fs.existsSync(path.join(assets, 'index.html')))
+        throw new Error('linework: the bundled draw.io editor is missing (assets/drawio/index.html). Reinstall linework.');
+    const token = crypto.randomBytes(16).toString('hex');
+    const result = { saves: 0, conflicts: [] };
+    let resolveDone;
+    const done = new Promise((r) => (resolveDone = r));
+    let closeTimer;
+    let finished = false;
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const json = (code, body) => {
+            res.writeHead(code, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(body));
+        };
+        if (url.pathname === `/${token}/` || url.pathname === `/${token}`) {
+            clearTimeout(closeTimer); // a reload, not a close
+            const text = fs.readFileSync(abs, 'utf8');
+            res.writeHead(200, { 'content-type': TYPES['.html'], 'cache-control': 'no-store' });
+            return void res.end(hostPage(path.basename(abs), extractMxfile(text), fs.statSync(abs).mtimeMs, token, format));
+        }
+        if (req.method === 'POST' && url.pathname.startsWith(`/${token}/`)) {
+            const action = url.pathname.slice(token.length + 2);
+            let body = '';
+            req.on('data', (c) => (body += c));
+            req.on('end', async () => {
+                try {
+                    if (action === 'save') {
+                        const msg = JSON.parse(body);
+                        let content = msg.data ? decodeDataUri(msg.data) : msg.xml;
+                        // draw.io writes a fresh SVG without our fonts; put them back so the file
+                        // still renders in the diagram's typeface everywhere.
+                        if (content && msg.data)
+                            content = await embedFonts(content);
+                        if (!content)
+                            return json(400, { error: 'empty save' });
+                        let target = abs;
+                        if (fs.statSync(abs).mtimeMs !== msg.mtime) {
+                            // Someone (often an agent running linework build) changed the file while it was open.
+                            target = conflictPath(abs);
+                            result.conflicts.push(target);
+                        }
+                        fs.writeFileSync(target, content);
+                        result.saves++;
+                        if (target !== abs)
+                            return json(409, { error: `${path.basename(abs)} changed on disk after you opened it, so your version went to ${path.basename(target)} instead. Reload this page to edit the new version.` });
+                        return json(200, { mtime: fs.statSync(abs).mtimeMs });
+                    }
+                    if (action === 'exit') {
+                        json(200, {});
+                        return void finish();
+                    }
+                    if (action === 'closed') {
+                        json(200, {});
+                        closeTimer = setTimeout(finish, 3000);
+                        return;
+                    }
+                    json(404, { error: 'unknown action' });
+                }
+                catch (e) {
+                    json(500, { error: e.message });
+                }
+            });
+            return;
+        }
+        if (req.method === 'GET' && url.pathname.startsWith('/aiviz-fonts/')) {
+            const f = FACES.find((x) => `/aiviz-fonts/${x.file}` === url.pathname);
+            if (!f) {
+                res.writeHead(404);
+                return void res.end();
+            }
+            res.writeHead(200, { 'content-type': 'font/woff2' });
+            return void fs.createReadStream(path.join(fontsDir(), f.file)).pipe(res);
+        }
+        if (req.method === 'GET' && url.pathname === '/app/index.html') {
+            // The editor shows labels in the diagram's own fonts.
+            const html = fs.readFileSync(path.join(assets, 'index.html'), 'utf8').replace('</head>', `<style>${fontFaceCss((f) => `/aiviz-fonts/${f}`)}</style></head>`);
+            res.writeHead(200, { 'content-type': TYPES['.html'] });
+            return void res.end(html);
+        }
+        if (req.method === 'GET' && url.pathname.startsWith('/app/')) {
+            const rel = path.normalize(decodeURIComponent(url.pathname.slice(5)));
+            const p = path.join(assets, rel);
+            if (!p.startsWith(assets + path.sep) || !fs.existsSync(p) || !fs.statSync(p).isFile()) {
+                res.writeHead(404);
+                return void res.end();
+            }
+            res.writeHead(200, { 'content-type': TYPES[path.extname(p)] ?? 'application/octet-stream' });
+            return void fs.createReadStream(p).pipe(res);
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    function finish() {
+        if (finished)
+            return;
+        finished = true;
+        server.close();
+        server.closeAllConnections();
+        resolveDone(result);
+    }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port ?? 0, '127.0.0.1', resolve);
+    });
+    const port = server.address().port;
+    return { url: `http://127.0.0.1:${port}/${token}/`, done, close: async () => finish() };
+}
+function decodeDataUri(uri) {
+    const m = /^data:[^,]*?(;base64)?,(.*)$/s.exec(uri);
+    if (!m)
+        return uri;
+    return m[1] ? Buffer.from(m[2], 'base64').toString('utf8') : decodeURIComponent(m[2]);
+}
+function conflictPath(abs) {
+    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
+    const m = /^(.*?)((?:\.drawio)?\.(?:svg|drawio|xml))$/.exec(abs);
+    return m ? `${m[1]}.edited-${stamp}${m[2]}` : `${abs}.edited-${stamp}`;
+}
+/** Opens a URL in the user's default browser. Best effort. */
+export function openInBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]] : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/git.js

@@ -0,0 +1,46 @@
+// `linework git-setup`: make `git diff` show diagram changes as spec changes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const PATTERNS = ['*.drawio.svg diff=linework', '*.drawio diff=linework'];
+function onPath(cmd) {
+    try {
+        execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The command git should run. Prefer a stable name over this machine's paths. */
+export function cliCommand() {
+    const cli = fileURLToPath(new URL('./cli.js', import.meta.url));
+    if (onPath('linework'))
+        return 'linework';
+    if (cli.includes(`${path.sep}_npx${path.sep}`))
+        return 'npx -y @itsthecsguy/linework';
+    return `"${process.execPath}" "${cli.replace(/\.ts$/, '.js').replace(`${path.sep}src${path.sep}`, `${path.sep}dist${path.sep}`)}"`;
+}
+export function gitSetup(cwd = process.cwd()) {
+    let top;
+    try {
+        top = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim();
+    }
+    catch {
+        throw new Error('not inside a git repository');
+    }
+    const done = [];
+    const attrs = path.join(top, '.gitattributes');
+    const existing = fs.existsSync(attrs) ? fs.readFileSync(attrs, 'utf8') : '';
+    const missing = PATTERNS.filter((p) => !existing.split('\n').some((l) => l.trim() === p));
+    if (missing.length) {
+        fs.writeFileSync(attrs, existing + (existing && !existing.endsWith('\n') ? '\n' : '') + missing.join('\n') + '\n');
+        done.push(`added to .gitattributes: ${missing.join(', ')}`);
+    }
+    const cmd = `${cliCommand()} show --geometry --quiet`;
+    execFileSync('git', ['config', 'diff.linework.textconv', cmd], { cwd: top });
+    execFileSync('git', ['config', 'diff.linework.cachetextconv', 'true'], { cwd: top });
+    done.push(`set git config diff.linework.textconv to: ${cmd}  (this repo only)`);
+    return done;
+}