@itsthecsguy/linework 0.0.0-stage → 0.1.0

package/dist/publish.js

@@ -0,0 +1,121 @@
+// `linework publish`: copy diagrams into a Google Drive folder synced by Google
+// Drive for desktop, so draw.io's Google Docs add-on can insert them and later
+// refresh them. Each file always lands at the same path, which keeps its Drive
+// file id, so "Update diagrams" in Docs picks up new versions.
+//
+// Edits can come back the other way: someone opens the diagram from Docs in
+// draw.io, which saves to the Drive copy. publish notices that the Drive copy
+// changed since it wrote it, refuses to overwrite it, and `--pull` copies it back.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+const MANIFEST = '.linework-publish.json';
+/** Google Drive for desktop folders on this machine. */
+export function driveFolders() {
+    const found = [];
+    if (process.platform === 'darwin') {
+        const cs = path.join(os.homedir(), 'Library', 'CloudStorage');
+        if (fs.existsSync(cs))
+            for (const d of fs.readdirSync(cs))
+                if (d.startsWith('GoogleDrive-')) {
+                    const my = fs.readdirSync(path.join(cs, d)).find((n) => n === 'My Drive' || n === 'Meine Ablage' || /^my drive$/i.test(n));
+                    if (my)
+                        found.push(path.join(cs, d, my));
+                }
+    }
+    else if (process.platform === 'win32') {
+        for (const letter of 'GHIJKLMNOPQRSTUVWXYZ') {
+            const p = `${letter}:\\My Drive`;
+            if (fs.existsSync(p))
+                found.push(p);
+        }
+    }
+    return found;
+}
+function projectName(cwd) {
+    try {
+        return path.basename(execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+    }
+    catch {
+        return path.basename(cwd);
+    }
+}
+function projectRoot(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return cwd;
+    }
+}
+const sha = (buf) => crypto.createHash('sha1').update(buf).digest('hex');
+/**
+ * Where publish writes. An explicit `to` is used as is. Otherwise the single
+ * Google Drive folder on this machine, under linework/<project>.
+ */
+export function publishDir(to, cwd = process.cwd()) {
+    if (to)
+        return path.resolve(cwd, to);
+    if (process.env.LINEWORK_PUBLISH_DIR)
+        return path.resolve(cwd, process.env.LINEWORK_PUBLISH_DIR);
+    const drives = driveFolders();
+    if (drives.length === 1)
+        return path.join(drives[0], 'linework', projectName(cwd));
+    if (drives.length > 1)
+        throw new Error(`found several Google Drive folders; pick one with --to:\n${drives.map((d) => '  ' + d).join('\n')}`);
+    throw new Error('no Google Drive folder found. Install Google Drive for desktop (it syncs a local folder to Drive), or pass --to <folder> to publish into any synced folder.');
+}
+export function publish(files, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const dir = publishDir(opts.to, cwd);
+    const root = projectRoot(cwd);
+    const manifestPath = path.join(dir, MANIFEST);
+    const manifest = fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : {};
+    const items = [];
+    for (const f of files) {
+        const src = path.resolve(cwd, f);
+        if (!fs.existsSync(src))
+            throw new Error(`${f} doesn't exist`);
+        if (!/\.(drawio\.svg|drawio\.png|drawio|svg)$/.test(src))
+            throw new Error(`${f}: publish takes .drawio.svg or .drawio files`);
+        // Keep the project's folder structure so two diagrams with the same name don't collide.
+        const rel = path.relative(root, src).startsWith('..') ? path.basename(src) : path.relative(root, src);
+        const dest = path.join(dir, rel);
+        const key = rel.split(path.sep).join('/');
+        const srcBuf = fs.readFileSync(src);
+        const destBuf = fs.existsSync(dest) ? fs.readFileSync(dest) : undefined;
+        // Changed in Drive since we last wrote it: someone edited it from Docs or Drive.
+        const editedInDrive = !!destBuf && manifest[key] !== undefined && sha(destBuf) !== manifest[key];
+        if (opts.pull) {
+            if (!destBuf)
+                throw new Error(`${dest} doesn't exist, so there is nothing to pull`);
+            if (sha(destBuf) !== sha(srcBuf)) {
+                fs.writeFileSync(src, destBuf);
+                items.push({ file: src, dest, action: 'pulled' });
+            }
+            else
+                items.push({ file: src, dest, action: 'unchanged' });
+            manifest[key] = sha(destBuf);
+            continue;
+        }
+        if (editedInDrive && sha(destBuf) !== sha(srcBuf) && !opts.force) {
+            items.push({ file: src, dest, action: 'conflict' });
+            continue;
+        }
+        if (destBuf && sha(destBuf) === sha(srcBuf)) {
+            manifest[key] = sha(srcBuf);
+            items.push({ file: src, dest, action: 'unchanged' });
+            continue;
+        }
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        // Overwrite in place (not delete and recreate) so Drive keeps the same file id.
+        fs.writeFileSync(dest, srcBuf);
+        manifest[key] = sha(srcBuf);
+        items.push({ file: src, dest, action: 'published' });
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    return items;
+}

package/dist/render/browser.js

@@ -0,0 +1,210 @@
+// Headless draw.io. Loads the bundled draw.io runtime into Chromium and uses
+// its own Graph code to measure, render and inspect diagrams, so what linework
+// renders matches what the draw.io editor shows.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright-core';
+import { FONT_STACK } from '../drawio/theme.js';
+import { FACES, embedFonts, fontFaceCss, fontsDir } from './fonts.js';
+const ORIGIN = 'http://aiviz.local';
+export function assetsDir() {
+    // dist/render/browser.js or src/render/browser.ts -> <pkg>/assets/drawio
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 4; i++) {
+        const candidate = path.join(dir, 'assets', 'drawio');
+        if (fs.existsSync(path.join(candidate, 'js', 'app.min.js')))
+            return candidate;
+        dir = path.dirname(dir);
+    }
+    throw new Error('linework: bundled draw.io runtime not found (assets/drawio). Reinstall linework.');
+}
+const host = () => `<!DOCTYPE html><html><head><meta charset="utf-8">
+<script src="js/export-init.js"></script>
+<link rel="stylesheet" href="mxgraph/css/common.css">
+<script src="js/app.min.js"></script>
+<script src="js/shapes-14-6-5.min.js"></script>
+<script src="js/stencils.min.js"></script>
+<script src="js/libavoid-js/libavoid.min.js"></script>
+<script src="js/libavoid-js/libavoid-routing.js"></script>
+<script src="js/diagramly/LibavoidRouting.js"></script>
+<script src="js/rough/rough.min.js"></script>
+<style>body{margin:0;background:#fff} #out{display:inline-block}
+${fontFaceCss((f) => `/aiviz-fonts/${f}`)}</style>
+</head><body><div id="out"></div><script>
+window.FONT_STACK = ${JSON.stringify(FONT_STACK)};
+function decodeInto(graph, xml) {
+  var doc = mxUtils.parseXml(xml);
+  var node = Editor.extractGraphModel(doc.documentElement, false);
+  new mxCodec(node.ownerDocument).decode(node, graph.getModel());
+  var bg = node.getAttribute('background');
+  graph.background = bg && bg != 'none' ? bg : '#ffffff';
+}
+function withGraph(xml, fn) {
+  var c = document.createElement('div');
+  c.style.cssText = 'position:absolute;left:-99999px;top:0;width:4000px;height:4000px';
+  document.body.appendChild(c);
+  var graph = new Graph(c);
+  graph.setEnabled(false);
+  try { decodeInto(graph, xml); return fn(graph); } finally { graph.destroy(); c.remove(); }
+}
+var ctx = document.createElement('canvas').getContext('2d');
+window.aiviz = {
+  measure: function (reqs) {
+    return reqs.map(function (r) {
+      if (!r[0]) return 0;
+      ctx.font = r[2] + ' ' + r[1] + 'px ' + (r[3] || window.FONT_STACK);
+      return Math.ceil(ctx.measureText(r[0]).width);
+    });
+  },
+  render: function (xml, embed) {
+    return withGraph(xml, function (graph) {
+      var svg = graph.getSvg(graph.background, 1, 16, false, null, true, null, null, null, false, false);
+      if (embed) svg.setAttribute('content', xml);
+      var out = document.getElementById('out');
+      out.innerHTML = '';
+      out.appendChild(svg.cloneNode(true));
+      return Graph.xmlDeclaration + '\\n' + (embed ? Graph.svgFileComment + '\\n' : '') + Graph.svgDoctype + '\\n' + mxUtils.getXml(svg);
+    });
+  },
+  // Route the given edges around vertices with draw.io's libavoid router (the same
+  // code as Arrange > Layout > Orthogonal routing). Returns mxGraphModel XML.
+  reroute: function (xml, edgeIds) {
+    return withGraph(xml, function (graph) {
+      var model = graph.getModel();
+      var cells = edgeIds.map(function (id) { return model.getCell(id); }).filter(Boolean);
+      if (cells.length && globalThis.Avoid) {
+        model.beginUpdate();
+        try { LibavoidRouting.routeCells(graph, globalThis.Avoid, cells, null, true); } finally { model.endUpdate(); }
+      }
+      return mxUtils.getXml(new mxCodec().encode(model));
+    });
+  },
+  // Names of stencils in a bundled set, e.g. stencilNames('aws4.xml').
+  stencilNames: function (set) {
+    var before = Object.keys(mxStencilRegistry.stencils);
+    mxStencilRegistry.loadStencilSet(STENCIL_PATH + '/' + set, null, null, false);
+    return Object.keys(mxStencilRegistry.stencils).filter(function (k) { return before.indexOf(k) < 0; });
+  },
+  hasStencil: function (name) {
+    return mxStencilRegistry.getStencil(name) != null;
+  },
+  inspect: function (xml) {
+    return withGraph(xml, function (graph) {
+      var model = graph.getModel(), out = [];
+      for (var id in model.cells) {
+        var cell = model.cells[id];
+        if (!cell || (!cell.vertex && !cell.edge)) continue;
+        var st = graph.view.getState(cell);
+        if (!st) continue;
+        var style = st.style || {};
+        var tb = st.text && st.text.boundingBox;
+        out.push({
+          id: cell.id,
+          vertex: !!cell.vertex,
+          edge: !!cell.edge,
+          parent: cell.parent ? cell.parent.id : null,
+          container: style.container == '1' || (cell.value && cell.value.getAttribute && cell.value.getAttribute('aiviz_type') == 'group'),
+          text: style.text != null || style.shape == 'text',
+          shape: style.shape || null,
+          aivizType: (cell.value && cell.value.getAttribute && cell.value.getAttribute('aiviz_type')) || null,
+          source: cell.edge && cell.source ? cell.source.id : null,
+          target: cell.edge && cell.target ? cell.target.id : null,
+          box: { x: st.x, y: st.y, w: st.width, h: st.height },
+          textBox: tb ? { x: tb.x, y: tb.y, w: tb.width, h: tb.height } : null,
+          label: graph.getLabel(cell) ? String(graph.getLabel(cell)).split(/<br\\s*\\/?>/i)[0].replace(/<[^>]+>/g, ' ').replace(/\\s+/g, ' ').trim() : '',
+          points: st.absolutePoints ? st.absolutePoints.filter(Boolean).map(function (p) { return { x: p.x, y: p.y }; }) : null,
+        });
+      }
+      return out;
+    });
+  },
+};
+window.ready = true;
+</script></body></html>`;
+const TYPES = { '.js': 'text/javascript', '.css': 'text/css', '.html': 'text/html', '.txt': 'text/plain', '.svg': 'image/svg+xml', '.png': 'image/png' };
+export class DrawioBrowser {
+    browser;
+    page;
+    constructor(browser, page) {
+        this.browser = browser;
+        this.page = page;
+    }
+    static async launch(opts = {}) {
+        const browser = await launchChromium();
+        const page = await browser.newPage({ deviceScaleFactor: opts.scale ?? 2 });
+        const dir = assetsDir();
+        const fonts = fontsDir();
+        const html = host();
+        await page.route(`${ORIGIN}/**`, async (route) => {
+            const url = new URL(route.request().url());
+            if (url.pathname === '/' || url.pathname === '/host.html')
+                return route.fulfill({ status: 200, contentType: 'text/html', body: html });
+            if (url.pathname.startsWith('/aiviz-fonts/')) {
+                const f = FACES.find((x) => `/aiviz-fonts/${x.file}` === url.pathname);
+                return f ? route.fulfill({ status: 200, contentType: 'font/woff2', body: fs.readFileSync(path.join(fonts, f.file)) }) : route.fulfill({ status: 404, body: '' });
+            }
+            const file = path.join(dir, path.normalize(url.pathname));
+            if (!file.startsWith(dir) || !fs.existsSync(file))
+                return route.fulfill({ status: 404, body: '' });
+            return route.fulfill({ status: 200, contentType: TYPES[path.extname(file)] ?? 'application/octet-stream', body: fs.readFileSync(file) });
+        });
+        // Nothing else may load: keeps rendering offline and deterministic.
+        await page.route(/^(?!http:\/\/aiviz\.local\/).*/, (route) => route.abort());
+        await page.goto(`${ORIGIN}/host.html`);
+        await page.waitForFunction(() => window.ready === true, null, { timeout: 30000 });
+        // Measuring before a font loads would size every box for the fallback font.
+        const ok = await page.evaluate((faces) => Promise.all(faces.map((f) => document.fonts.load(`${f.weight} 16px "${f.family}"`).then((r) => r.length > 0))), FACES.map(({ family, weight }) => ({ family, weight })));
+        if (ok.includes(false))
+            throw new Error('linework: bundled fonts failed to load (assets/fonts). Reinstall linework.');
+        return new DrawioBrowser(browser, page);
+    }
+    measure(reqs) {
+        return this.page.evaluate((r) => window.aiviz.measure(r), reqs);
+    }
+    /** Returns .drawio.svg text with the model embedded. */
+    async renderSvg(xml) {
+        return embedFonts(await this.page.evaluate((x) => window.aiviz.render(x, true), xml));
+    }
+    /** Renders and screenshots the diagram. Writes `file` when given; always returns the PNG bytes. */
+    async renderPng(xml, file) {
+        await this.page.evaluate((x) => window.aiviz.render(x, false), xml);
+        return this.page.locator('#out svg').screenshot({ path: file, omitBackground: false });
+    }
+    /** Reroutes the given edge cells with libavoid. Returns mxGraphModel XML. */
+    reroute(xml, edgeIds) {
+        return this.page.evaluate(([x, ids]) => window.aiviz.reroute(x, ids), [xml, edgeIds]);
+    }
+    stencilNames(set) {
+        return this.page.evaluate((s) => window.aiviz.stencilNames(s), set);
+    }
+    hasStencil(name) {
+        return this.page.evaluate((n) => window.aiviz.hasStencil(n), name);
+    }
+    inspect(xml) {
+        return this.page.evaluate((x) => window.aiviz.inspect(x), xml);
+    }
+    close() {
+        return this.browser.close();
+    }
+}
+async function launchChromium() {
+    const errors = [];
+    const attempts = [];
+    if (process.env.LINEWORK_CHROME)
+        attempts.push(() => chromium.launch({ executablePath: process.env.LINEWORK_CHROME }));
+    attempts.push(() => chromium.launch());
+    attempts.push(() => chromium.launch({ channel: 'chrome' }));
+    attempts.push(() => chromium.launch({ channel: 'msedge' }));
+    for (const a of attempts) {
+        try {
+            return await a();
+        }
+        catch (e) {
+            errors.push(e.message.split('\n')[0]);
+        }
+    }
+    throw new Error('linework needs a Chromium-based browser to lay out and render diagrams, and none was found.\n' +
+        'Fix one of these ways:\n  npx playwright install chromium\n  install Google Chrome\n  set LINEWORK_CHROME=/path/to/chrome\n' +
+        `(tried: ${errors.join(' | ')})`);
+}

package/dist/render/fonts.js

@@ -0,0 +1,66 @@
+// Bundled fonts. The headless browser measures and renders with them, and every
+// SVG gets a subset of the faces it uses (only the glyphs in its text), so a
+// diagram looks the same on GitHub, in a browser and in a doc, and text that fit
+// when linework sized the boxes still fits wherever it is shown.
+import fs from 'node:fs';
+import path from 'node:path';
+import subsetFont from 'subset-font';
+import { assetsDir } from './browser.js';
+export const FACES = [
+    { family: 'IBM Plex Sans', weight: 400, file: 'plex-sans-400.woff2' },
+    { family: 'IBM Plex Sans', weight: 600, file: 'plex-sans-600.woff2' },
+    { family: 'Kalam', weight: 400, file: 'kalam-400.woff2' },
+    { family: 'Kalam', weight: 700, file: 'kalam-700.woff2' },
+    { family: 'IBM Plex Mono', weight: 400, file: 'plex-mono-400.woff2' },
+    { family: 'IBM Plex Mono', weight: 600, file: 'plex-mono-600.woff2' },
+];
+export function fontsDir() {
+    return path.join(path.dirname(assetsDir()), 'fonts');
+}
+/** @font-face rules pointing at the font files, for pages that can fetch them. */
+export function fontFaceCss(url) {
+    return FACES.map((f) => `@font-face{font-family:"${f.family}";font-weight:${f.weight};font-style:normal;src:url(${url(f.file)}) format("woff2");}`).join('\n');
+}
+const cache = new Map();
+const read = (f) => {
+    let b = cache.get(f.file);
+    if (!b)
+        cache.set(f.file, (b = fs.readFileSync(path.join(fontsDir(), f.file))));
+    return b;
+};
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) => e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10)) : (ENT[e] ?? m));
+const STYLE_RE = /<style id="aiviz-fonts"[^>]*>[\s\S]*?<\/style>/g;
+/** Families from FACES that the SVG asks for. */
+export function familiesIn(svg) {
+    const used = new Set();
+    for (const m of svg.matchAll(/font-family(?:\s*:\s*|=")(?:&quot;|["'])?([^,;"'&<]+)/g))
+        used.add(m[1].trim());
+    return [...new Set(FACES.map((f) => f.family))].filter((f) => used.has(f));
+}
+/**
+ * Put subset copies of the bundled fonts the SVG uses into its <defs>. Replaces
+ * a previous embed, so it's safe to run on a file again after an edit.
+ */
+export async function embedFonts(svg) {
+    svg = svg.replace(STYLE_RE, '');
+    const families = familiesIn(svg);
+    if (!families.length)
+        return svg;
+    let text = '';
+    for (const m of svg.matchAll(/>([^<>]+)</g))
+        text += decode(m[1]);
+    // Blueprint's group titles use CSS text-transform, so they need the capitals too.
+    text = [...new Set(text + text.toUpperCase() + ' ')].join('');
+    const rules = [];
+    for (const f of FACES.filter((x) => families.includes(x.family))) {
+        const sub = await subsetFont(read(f), text, { targetFormat: 'woff2' });
+        rules.push(`@font-face{font-family:"${f.family}";font-weight:${f.weight};font-style:normal;src:url(data:font/woff2;base64,${sub.toString('base64')}) format("woff2");}`);
+    }
+    const style = `<style id="aiviz-fonts" type="text/css">${rules.join('')}</style>`;
+    if (/<defs\s*\/>/.test(svg))
+        return svg.replace(/<defs\s*\/>/, `<defs>${style}</defs>`);
+    if (/<defs[^>]*>/.test(svg))
+        return svg.replace(/<defs[^>]*>/, (m) => m + style);
+    return svg.replace(/<svg\b[^>]*>/, (m) => `${m}<defs>${style}</defs>`);
+}

package/dist/report.js

@@ -0,0 +1,36 @@
+export function buildLines(res, png) {
+    const s = res.check.stats;
+    const lines = [`wrote ${res.out} (${s.nodes} nodes, ${s.edges} edges, ${s.width}x${s.height}px, ${res.direction})`];
+    if (res.merge) {
+        const m = res.merge;
+        const parts = [`kept ${m.kept} positions${m.handMoved ? ` (${m.handMoved} set by hand)` : ''}`];
+        if (m.placed.length)
+            parts.push(`placed ${m.placed.join(', ')}`);
+        if (m.grown.length)
+            parts.push(`grew ${m.grown.join(', ')}`);
+        if (m.removed.length)
+            parts.push(`removed ${m.removed.join(', ')}`);
+        if (m.rerouted)
+            parts.push(`rerouted ${m.rerouted} edges`);
+        if (m.carried)
+            parts.push(`kept ${m.carried} notes/annotations`);
+        lines.push(`merged into the existing layout: ${parts.join('; ')}`);
+        if (m.keptUnknown.length)
+            lines.push(`note: kept ${m.keptUnknown.join(', ')}: added by hand, and this spec didn't come from the current file. To work from the latest version run show first; to delete them, remove them from that output.`);
+    }
+    if (res.discardedLayout)
+        lines.push('relayout: discarded the hand-arranged layout and laid out from scratch');
+    if (png)
+        lines.push(`preview ${png}`);
+    for (const w of res.warnings)
+        lines.push(`spec warning: ${w.path}: ${w.message}`);
+    return [...lines, ...checkLines(res.check)];
+}
+export function checkLines(res) {
+    const errors = res.findings.filter((f) => f.level === 'error');
+    const warnings = res.findings.filter((f) => f.level === 'warning');
+    return [
+        `check: ${errors.length} errors, ${warnings.length} warnings, ${res.stats.crossings} edge crossings`,
+        ...res.findings.map((f) => `  ${f.level}: ${f.message} [${f.rule}]`),
+    ];
+}

package/dist/spec/model.js

@@ -0,0 +1,53 @@
+// The normalized diagram model every other module works from.
+// The YAML the AI writes is parsed into this by parse.ts.
+export const DIAGRAM_TYPES = ['architecture', 'flow', 'state', 'sequence', 'er'];
+export const DIRECTIONS = ['auto', 'TB', 'LR', 'BT', 'RL'];
+export const THEMES = ['clean', 'soft', 'dark', 'sketch', 'blueprint', 'c4'];
+export const COLORS = ['blue', 'violet', 'pink', 'red', 'orange', 'amber', 'green', 'teal', 'gray'];
+// Kinds are per diagram type so the AI gets a short, relevant list.
+export const KINDS = {
+    architecture: {
+        service: { shape: 'box', color: 'violet', description: 'your own service, API or app server (default)' },
+        person: { shape: 'box', color: 'pink', description: 'a human user or role' },
+        client: { shape: 'box', color: 'blue', description: 'browser app, mobile app, CLI' },
+        function: { shape: 'box', color: 'violet', dashed: true, description: 'serverless function or job' },
+        database: { shape: 'cylinder', color: 'green', description: 'relational or document database' },
+        cache: { shape: 'box', color: 'green', description: 'Redis, Memcached, CDN cache' },
+        storage: { shape: 'cylinder', color: 'green', description: 'object or file storage, data lake' },
+        queue: { shape: 'pill', color: 'amber', description: 'queue, topic or event stream' },
+        external: { shape: 'box', color: 'gray', dashed: true, description: 'third-party system you do not own' },
+    },
+    flow: {
+        step: { shape: 'box', color: 'neutral', description: 'an action or process step (default)' },
+        decision: { shape: 'diamond', color: 'amber', description: 'a yes/no or multi-way branch; label outgoing edges' },
+        terminal: { shape: 'pill', color: 'gray', description: 'start or end of the flow' },
+        data: { shape: 'parallelogram', color: 'blue', description: 'input or output data' },
+        error: { shape: 'box', color: 'red', semantic: true, description: 'failure or rejection path' },
+    },
+    state: {
+        state: { shape: 'box', color: 'violet', description: 'a state (default)' },
+        success: { shape: 'box', color: 'green', semantic: true, description: 'a successful terminal state' },
+        error: { shape: 'box', color: 'red', semantic: true, description: 'a failure state' },
+        start: { shape: 'start', color: 'ink', description: 'initial pseudo-state; usually written as [*] in edges' },
+        end: { shape: 'end', color: 'ink', description: 'final pseudo-state; usually written as [*] in edges' },
+    },
+    sequence: {
+        service: { shape: 'box', color: 'violet', description: 'your own service or component (default)' },
+        person: { shape: 'box', color: 'pink', description: 'a human actor' },
+        client: { shape: 'box', color: 'blue', description: 'browser, mobile app, CLI' },
+        function: { shape: 'box', color: 'violet', dashed: true, description: 'serverless function or job' },
+        database: { shape: 'box', color: 'green', description: 'database or cache' },
+        queue: { shape: 'box', color: 'amber', description: 'queue, topic or event stream' },
+        external: { shape: 'box', color: 'gray', dashed: true, description: 'third-party system' },
+    },
+    er: {
+        entity: { shape: 'table', color: 'violet', description: 'a table or entity (default)' },
+        view: { shape: 'table', color: 'blue', dashed: true, description: 'a view or derived table' },
+        external: { shape: 'table', color: 'gray', dashed: true, description: 'a table owned by another system' },
+    },
+};
+export const DEFAULT_KIND = { architecture: 'service', flow: 'step', state: 'state', sequence: 'service', er: 'entity' };
+export const FRAME_OPS = ['alt', 'par', 'opt', 'loop', 'critical', 'break'];
+export function kindDef(type, kind) {
+    return KINDS[type][kind] ?? KINDS[type][DEFAULT_KIND[type]];
+}