@itsthecsguy/linework 0.1.4 → 0.2.0

package/dist/commands.js

@@ -0,0 +1,346 @@
+// Every command, written against an output sink so the same code runs in the
+// CLI process and in the background process that keeps Chromium warm.
+import fs from 'node:fs';
+import path from 'node:path';
+export const USAGE = `linework: AI-written, hand-editable diagrams (YAML spec -> .drawio.svg)
+
+Usage:
+  linework build <spec.yaml|-> -o <out.drawio.svg> [--png preview.png] [--relayout]
+      Lay out and write the diagram, then lint it. "-" reads the spec from stdin.
+      If the file exists and someone edited it by hand, the spec is merged in:
+      existing positions stay, new nodes are placed next to their neighbours.
+      --relayout throws the existing layout away (hand edits included).
+  linework set <file.drawio.svg> <id.field=value | theme=..|title=..|direction=..>...
+  linework add <file.drawio.svg> <"id: { label: .., in: .. }" | "a -> b: label" | "group id: { label: .. }">...
+  linework rm  <file.drawio.svg> <id | "a -> b">...
+      Change a diagram in place, one command per change, no spec file. Everything
+      already in the diagram keeps its position, hand edits included.
+        linework set d.drawio.svg api.label="Checkout API v2" api.highlight=true
+        linework add d.drawio.svg "fraud: { label: Fraud check, in: vpc }" "api -> fraud: score"
+        linework rm  d.drawio.svg cache "api -> stripe"
+  linework show <file.drawio.svg> [--geometry]
+      Print the spec of an existing diagram (including hand edits) as YAML.
+      --geometry appends node positions as comments.
+  linework render <file.drawio.svg> -o <out.png|out.svg> [--scale 2]
+      Render a preview image.
+  linework check <file.drawio.svg>
+      Lint layout: overlaps, edges through nodes, labels that don't fit.
+  linework tidy <file.drawio.svg>
+      Reroute edges that check flags as broken (e.g. after moving nodes by hand).
+      Nothing else in the file changes.
+  linework edit <file.drawio.svg> [--no-open] [--port N]
+      Open the diagram in draw.io (bundled, offline) in your browser. Saving in
+      the editor writes the file. Stops when you exit the editor or close the tab.
+  linework import <file.mmd|doc.md|-> [--block N] [-o out.drawio.svg] [--png p.png]
+      Convert a Mermaid diagram (flowchart, state, sequence, ER) to an linework spec.
+      Prints the spec, or builds it straight away with -o.
+  linework icons <aws|gcp|k8s|azure> [filter]
+      List icon names, for "icon: aws.lambda" on architecture nodes.
+  linework publish <file.drawio.svg...> [--to DIR] [--pull] [--force]
+      Copy diagrams into your Google Drive folder (Google Drive for desktop) so
+      draw.io's Google Docs add-on can insert them and refresh them later.
+      --pull copies back a diagram someone edited from Docs or Drive.
+  linework skill [install <dir>]
+      Print where the bundled agent skill is, or copy it to <dir>/linework
+      (e.g. .claude/skills, ~/.agents/skills).
+  linework mcp [--root DIR]
+      Run as an MCP server over stdio, for chat apps and agents without a shell.
+      Relative paths resolve against --root (default: the current folder).
+  linework git-setup
+      Make git diff show .drawio.svg changes as spec changes (this repo only).
+  linework kinds [architecture|flow|state]
+      List node kinds for each diagram type.
+  linework schema
+      Print the spec's JSON Schema.
+
+  linework daemon [status|stop]
+      Builds after the first reuse a background process that keeps the browser
+      running, and take about a fifth of the time. It exits after 5 idle minutes.
+      Turn it off with LINEWORK_NO_DAEMON=1 or --no-daemon.
+
+  linework install-browser
+      Download the headless Chromium build that matches this version. Needed only
+      when no Chrome or Edge is installed, or to run inside an agent's sandbox.
+`;
+export const processIO = {
+    out: (t) => void process.stdout.write(t),
+    err: (t) => void process.stderr.write(t),
+    stdin: () => fs.readFileSync(0, 'utf8'),
+    get code() {
+        return Number(process.exitCode ?? 0);
+    },
+    set code(c) {
+        process.exitCode = c;
+    },
+};
+/** A usage error: print the message and exit with this code. */
+export class Exit extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Print an error the way the CLI does and return the exit code for it. */
+export function report(e, io = processIO) {
+    if (e instanceof Exit) {
+        io.err(e.message + '\n');
+        return e.code;
+    }
+    if (e?.constructor?.name === 'PatchError') {
+        io.err(`error: ${e.message}\n`);
+        return 2;
+    }
+    if (e?.name === 'SpecError') {
+        io.err('spec error:\n');
+        for (const i of e.issues)
+            io.err(`  ${i.path ? i.path + ': ' : ''}${i.message}\n`);
+        return 1;
+    }
+    io.err(`error: ${e?.message ?? e}\n`);
+    return 1;
+}
+/** Commands that draw, and so need Chromium. */
+export function needsBrowser(cmd, values) {
+    return ['build', 'set', 'add', 'rm', 'render', 'check', 'tidy', 'icons'].includes(cmd) || (cmd === 'import' && !!values.out);
+}
+/** A small spec with a group, labels and a cycle: enough to exercise ELK's main paths. */
+const WARM_SPEC = 'type: architecture\ngroups: { g: G }\nnodes:\n  a: { in: g }\n  b: { in: g }\n  c: {}\nedges:\n  - a -> b: x\n  - b -> c: y\n  - c -> a\n';
+export async function warmUp() {
+    const [{ parseSpecText }, { layout }] = await Promise.all([import('./spec/parse.js'), import('./layout/layout.js')]);
+    await layout(parseSpecText(WARM_SPEC).diagram);
+}
+export const OPTIONS = {
+    out: { type: 'string', short: 'o' },
+    png: { type: 'string' },
+    force: { type: 'boolean', default: false },
+    relayout: { type: 'boolean', default: false },
+    geometry: { type: 'boolean', default: false },
+    quiet: { type: 'boolean', short: 'q', default: false },
+    block: { type: 'string' },
+    scale: { type: 'string' },
+    'no-open': { type: 'boolean', default: false },
+    port: { type: 'string' },
+    'no-daemon': { type: 'boolean', default: false },
+    root: { type: 'string' },
+    to: { type: 'string' },
+    pull: { type: 'boolean', default: false },
+    help: { type: 'boolean', short: 'h' },
+};
+export async function run(cmd, values, positionals, launching, io = processIO) {
+    const console = { log: (m = '') => io.out(m + '\n'), error: (m = '') => io.err(m + '\n') };
+    const fail = (msg) => {
+        throw new Exit(msg, 2);
+    };
+    const printCheck = async (res) => {
+        const { checkLines } = await import('./report.js');
+        for (const line of checkLines(res))
+            console.log(line);
+    };
+    const browser = async () => {
+        // ELK compiles its code on first use. Laying out a tiny graph while Chromium
+        // is still starting takes that cost off the real layout.
+        if (launching && !io.warm && ['build', 'import', 'set', 'add', 'rm'].includes(cmd))
+            await warmUp();
+        return launching;
+    };
+    const { buildLines } = await import('./report.js');
+    switch (cmd) {
+        case 'build': {
+            const src = positionals[0];
+            if (!src || !values.out)
+                fail('usage: linework build <spec.yaml|-> -o <out.drawio.svg>');
+            const text = src === '-' ? io.stdin() : fs.readFileSync(src, 'utf8');
+            const { build } = await import('./api.js');
+            // Spec errors first: they shouldn't wait on, or hide behind, a browser problem.
+            (await import('./spec/parse.js')).parseSpecText(text);
+            const res = await build(text, { out: values.out, png: values.png, force: values.force, relayout: values.relayout, browser: await browser() });
+            for (const line of buildLines(res, values.png))
+                console.log(line);
+            return;
+        }
+        case 'set':
+        case 'add':
+        case 'rm': {
+            const [file, ...args] = positionals;
+            if (!file || !args.length)
+                fail(`usage: linework ${cmd} <file.drawio.svg> ${cmd === 'set' ? 'id.field=value...' : cmd === 'add' ? '"id: { label: .. }" | "a -> b: label"...' : 'id | "a -> b"...'}`);
+            const { patchFile, patchSpec } = await import('./patch.js');
+            const { show } = await import('./api.js');
+            // Bad arguments first: they shouldn't wait on, or hide behind, a browser problem.
+            (await import('./spec/parse.js')).parseSpecText(patchSpec(show(file).yaml, [{ op: cmd, args }]));
+            const res = await patchFile(file, [{ op: cmd, args }], { png: values.png, browser: await browser() });
+            for (const line of buildLines(res, values.png))
+                console.log(line);
+            return;
+        }
+        case 'show': {
+            const file = positionals[0] ?? fail('usage: linework show <file.drawio.svg>');
+            const { show } = await import('./api.js');
+            const res = show(file, { geometry: values.geometry });
+            io.out(res.yaml);
+            if (values.quiet)
+                return;
+            for (const n of res.notes)
+                console.error(`note: ${n}`);
+            if (res.edits.length) {
+                const moved = res.edits.filter((e) => e.what !== 'added').length;
+                const added = res.edits.filter((e) => e.what === 'added').length;
+                console.error(`note: edited by hand since the last build (${moved} moved/resized, ${added} added). build keeps those positions and merges your changes in.`);
+            }
+            return;
+        }
+        case 'render': {
+            const file = positionals[0];
+            if (!file || !values.out)
+                fail('usage: linework render <file.drawio.svg> -o <out.png>');
+            const { render } = await import('./api.js');
+            await render(file, values.out, await browser());
+            console.log(`wrote ${values.out}`);
+            return;
+        }
+        case 'check': {
+            const file = positionals[0] ?? fail('usage: linework check <file.drawio.svg>');
+            const { checkFile } = await import('./api.js');
+            const res = await checkFile(file, await browser());
+            await printCheck(res);
+            if (res.findings.some((f) => f.level === 'error'))
+                io.code = 1;
+            return;
+        }
+        case 'tidy': {
+            const file = positionals[0] ?? fail('usage: linework tidy <file.drawio.svg>');
+            const { tidy } = await import('./api.js');
+            const res = await tidy(file, await browser());
+            const did = [res.fixed ? `rerouted ${res.fixed} edge${res.fixed === 1 ? '' : 's'}` : '', res.labels ? `moved ${res.labels} label${res.labels === 1 ? '' : 's'}` : ''].filter(Boolean);
+            console.log(did.length ? `${did.join(', ')} in ${file}` : 'nothing to fix');
+            await printCheck(res.check);
+            return;
+        }
+        case 'edit': {
+            const file = positionals[0] ?? fail('usage: linework edit <file.drawio.svg>');
+            const { startEditor, openInBrowser } = await import('./edit/server.js');
+            const session = await startEditor(file, { port: values.port ? Number(values.port) : undefined });
+            const opened = !values['no-open'] && openInBrowser(session.url);
+            console.log(`${opened ? 'opened' : 'open'} ${session.url}`);
+            console.log(`editing ${file}. Save in the editor (Ctrl/Cmd+S) to write the file. Exit the editor, close the tab or press Ctrl+C to stop.`);
+            process.once('SIGINT', () => void session.close());
+            const res = await session.done;
+            console.log(res.saves ? `saved ${file} ${res.saves - res.conflicts.length} time(s)` : 'closed without saving');
+            for (const c of res.conflicts)
+                console.log(`note: ${file} changed on disk while it was open, so one save went to ${c}`);
+            return;
+        }
+        case 'import': {
+            const src = positionals[0] ?? fail('usage: linework import <file.mmd|doc.md|-> [-o out.drawio.svg]');
+            const { importMermaid, mermaidBlocks } = await import('./import/mermaid.js');
+            const { toYaml } = await import('./drawio/show.js');
+            let text = src === '-' ? io.stdin() : fs.readFileSync(src, 'utf8');
+            if (/\.(md|markdown|mdx)$/i.test(src)) {
+                const blocks = mermaidBlocks(text);
+                if (!blocks.length)
+                    fail(`${src} has no \`\`\`mermaid blocks`);
+                const n = values.block ? Number(values.block) : blocks.length === 1 ? 1 : 0;
+                if (!n || !blocks[n - 1]) {
+                    const first = blocks.map((b, i) => `  ${i + 1}: ${b.split('\n')[0]}`).join('\n');
+                    fail(`${src} has ${blocks.length} mermaid blocks; pick one with --block N:\n${first}`);
+                }
+                text = blocks[n - 1];
+            }
+            const res = importMermaid(text);
+            for (const w of res.warnings)
+                console.error(`import: ${w}`);
+            const yaml = toYaml(res.diagram, 'imported from Mermaid');
+            if (!values.out)
+                return void io.out(yaml);
+            const { build } = await import('./api.js');
+            const built = await build(yaml, { out: values.out, png: values.png, relayout: values.relayout, force: values.force, browser: await browser() });
+            console.log(`wrote ${built.out} (${built.check.stats.nodes} nodes, ${built.check.stats.edges} edges, ${built.direction})`);
+            await printCheck(built.check);
+            return;
+        }
+        case 'icons': {
+            const provider = positionals[0];
+            if (!provider || !['aws', 'gcp', 'k8s', 'azure'].includes(provider))
+                fail('usage: linework icons <aws|gcp|k8s|azure> [filter]');
+            const { listIcons } = await import('./api.js');
+            const names = await listIcons(provider, positionals[1], await browser());
+            console.log(names.map((n) => `${provider}.${n}`).join('\n') || 'no matches');
+            return;
+        }
+        case 'publish': {
+            if (!positionals.length)
+                fail('usage: linework publish <file.drawio.svg...> [--to DIR]');
+            const { publish } = await import('./publish.js');
+            const items = publish(positionals, { to: values.to, pull: values.pull, force: values.force });
+            for (const i of items) {
+                if (i.action === 'published')
+                    console.log(`published ${path.relative(process.cwd(), i.file)} -> ${i.dest}`);
+                else if (i.action === 'unchanged')
+                    console.log(`unchanged ${i.dest}`);
+                else if (i.action === 'pulled')
+                    console.log(`pulled ${i.dest} -> ${path.relative(process.cwd(), i.file)}`);
+                else
+                    console.log(`skipped ${path.relative(process.cwd(), i.file)}: the Drive copy was edited after the last publish. Run with --pull to take that version, or --force to overwrite it.`);
+            }
+            if (items.some((i) => i.action === 'published') && !values.pull) {
+                console.log('\nNot in the doc yet? In Google Docs: Extensions > draw.io > Insert diagrams, then pick the file.');
+                console.log('Already in the doc? After Drive syncs: Extensions > draw.io > Update diagrams.');
+            }
+            if (items.some((i) => i.action === 'conflict'))
+                io.code = 1;
+            return;
+        }
+        case 'skill': {
+            const { fileURLToPath } = await import('node:url');
+            const src = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'linework');
+            if (positionals[0] !== 'install')
+                return void console.log(src);
+            const dir = positionals[1] ?? fail('usage: linework skill install <skills-dir>   e.g. .claude/skills');
+            const dest = path.join(dir.replace(/^~(?=$|\/)/, process.env.HOME ?? '~'), 'linework');
+            fs.mkdirSync(dest, { recursive: true });
+            fs.cpSync(src, dest, { recursive: true });
+            console.log(`installed the linework skill to ${dest}`);
+            return;
+        }
+        case 'mcp': {
+            const { runStdio } = await import('./mcp/server.js');
+            await runStdio({ root: path.resolve(values.root ?? process.env.LINEWORK_ROOT ?? process.cwd()) });
+            return;
+        }
+        case 'git-setup': {
+            const { gitSetup } = await import('./git.js');
+            for (const line of gitSetup())
+                console.log(line);
+            return;
+        }
+        case 'kinds': {
+            const { KINDS, DIAGRAM_TYPES } = await import('./spec/model.js');
+            const types = (positionals.length ? positionals : DIAGRAM_TYPES);
+            for (const t of types) {
+                if (!KINDS[t])
+                    fail(`unknown type ${t}`);
+                console.log(`${t}:`);
+                for (const [k, d] of Object.entries(KINDS[t]))
+                    console.log(`  ${k.padEnd(10)} ${d.description}`);
+            }
+            return;
+        }
+        case 'schema': {
+            const { jsonSchema } = await import('./spec/parse.js');
+            console.log(JSON.stringify(jsonSchema(), null, 2));
+            return;
+        }
+        case 'install-browser': {
+            const { browserInstallCommand } = await import('./render/browser.js');
+            const { spawnSync } = await import('node:child_process');
+            const [bin, ...args] = browserInstallCommand();
+            console.log('downloading headless Chromium for linework...');
+            const r = spawnSync(bin, args, { stdio: 'inherit' });
+            io.code = r.status ?? 1;
+            return;
+        }
+        default:
+            fail(`unknown command "${cmd}". Run "linework help" for the list.`);
+    }
+}

package/dist/daemon.js

@@ -0,0 +1,193 @@
+// A background process that keeps Chromium, draw.io and ELK warm between builds.
+// Starting those is most of a build: about 0.8s of a 1s run. The first drawing
+// command starts this process as it exits; later ones hand their work to it and
+// finish in a fraction of the time. It exits after a few idle minutes.
+//
+// It listens on a Unix socket in a folder only the user can open, and only runs
+// the same commands the CLI runs. LINEWORK_NO_DAEMON=1 turns it off.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const IDLE_MS = Number(process.env.LINEWORK_DAEMON_IDLE ?? 300) * 1000;
+const cliPath = () => path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.js');
+/** Off on Windows (no Unix sockets with file permissions), in CI, and on request. */
+export function daemonAllowed() {
+    return process.platform !== 'win32' && !process.env.LINEWORK_NO_DAEMON && !process.env.CI && typeof process.getuid === 'function';
+}
+/**
+ * The socket for this exact build of linework and this browser setting, so an
+ * upgrade or a different LINEWORK_CHROME never talks to a stale process.
+ * Undefined when no private folder can be had.
+ */
+export function socketPath() {
+    const uid = process.getuid();
+    const dir = process.env.XDG_RUNTIME_DIR ? path.join(process.env.XDG_RUNTIME_DIR, 'linework') : path.join(os.tmpdir(), `linework-${uid}`);
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const st = fs.lstatSync(dir);
+        // Someone else's folder, or one others can write to, could hold a fake socket.
+        if (!st.isDirectory() || st.uid !== uid || (st.mode & 0o077) !== 0)
+            return undefined;
+        let stamp = '';
+        try {
+            stamp = String(fs.statSync(cliPath()).mtimeMs);
+        }
+        catch {
+            // running from source
+        }
+        const key = crypto.createHash('sha256').update([cliPath(), stamp, process.version, process.env.LINEWORK_CHROME ?? '', process.env.LINEWORK_NO_CACHE ?? ''].join('\0')).digest('hex').slice(0, 12);
+        return path.join(dir, `${key}.sock`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run a command in the background process. Resolves with its exit code, or
+ * undefined when no such process is running (the caller then runs it itself).
+ */
+export function viaDaemon(req, out, err) {
+    const sock = daemonAllowed() ? socketPath() : undefined;
+    if (!sock || !fs.existsSync(sock))
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const c = net.createConnection(sock);
+        let buf = '';
+        let started = false;
+        let code;
+        // A process that died without cleaning up leaves a socket nobody answers.
+        c.once('error', () => {
+            if (!started)
+                fs.rmSync(sock, { force: true });
+            resolve(started ? 1 : undefined);
+        });
+        c.once('connect', () => c.write(JSON.stringify(req) + '\n'));
+        c.setEncoding('utf8');
+        c.on('data', (chunk) => {
+            started = true;
+            buf += chunk;
+            for (let i = buf.indexOf('\n'); i >= 0; i = buf.indexOf('\n')) {
+                const msg = JSON.parse(buf.slice(0, i));
+                buf = buf.slice(i + 1);
+                if (msg.t === 'out')
+                    out(msg.d);
+                else if (msg.t === 'err')
+                    err(msg.d);
+                else if (msg.t === 'exit')
+                    code = msg.code;
+            }
+        });
+        c.once('close', () => resolve(code ?? (started ? 1 : undefined)));
+    });
+}
+/** Start the background process, detached, unless one is already listening. */
+export function startDaemon() {
+    if (!daemonAllowed())
+        return;
+    const sock = socketPath();
+    if (!sock || fs.existsSync(sock))
+        return;
+    try {
+        spawn(process.execPath, [cliPath(), 'daemon', 'run'], { detached: true, stdio: 'ignore', cwd: os.homedir() }).unref();
+    }
+    catch {
+        // No background process only costs speed.
+    }
+}
+/** Ask a running background process to stop. Returns whether one was running. */
+export async function stopDaemon() {
+    const code = await viaDaemon({ argv: ['daemon', 'stop'], cwd: process.cwd() }, () => { }, () => { });
+    return code === 0;
+}
+/** The background process itself. Returns when it has shut down. */
+export async function serve() {
+    const sock = daemonAllowed() ? socketPath() : undefined;
+    if (!sock)
+        return;
+    // One per socket: if another answers, leave it to it.
+    if (fs.existsSync(sock)) {
+        const alive = await new Promise((r) => {
+            const c = net.createConnection(sock);
+            c.once('connect', () => (c.destroy(), r(true)));
+            c.once('error', () => r(false));
+        });
+        if (alive)
+            return;
+        fs.rmSync(sock, { force: true });
+    }
+    const { DrawioBrowser } = await import('./render/browser.js');
+    const { run, warmUp, report, OPTIONS } = await import('./commands.js');
+    const { parseArgs } = await import('node:util');
+    const browser = await DrawioBrowser.launch({ scale: 2 });
+    await warmUp();
+    let idle;
+    let queue = Promise.resolve();
+    const server = net.createServer({ allowHalfOpen: true });
+    const shutdown = async () => {
+        clearTimeout(idle);
+        server.close();
+        fs.rmSync(sock, { force: true });
+        await browser.close().catch(() => { });
+        process.exit(0);
+    };
+    const arm = () => {
+        clearTimeout(idle);
+        idle = setTimeout(() => void shutdown(), IDLE_MS);
+    };
+    server.on('connection', (c) => {
+        clearTimeout(idle);
+        c.setEncoding('utf8');
+        c.on('error', () => { });
+        let buf = '';
+        c.on('data', (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf('\n');
+            if (nl < 0)
+                return;
+            const line = buf.slice(0, nl);
+            buf = '';
+            const send = (m) => void (c.writable && c.write(JSON.stringify(m) + '\n'));
+            // One command at a time: they share the page and the working directory.
+            queue = queue.then(async () => {
+                let code = 0;
+                try {
+                    const req = JSON.parse(line);
+                    if (req.argv[0] === 'daemon' && req.argv[1] === 'stop') {
+                        send({ t: 'exit', code: 0 });
+                        c.end();
+                        return void shutdown();
+                    }
+                    const io = { out: (d) => send({ t: 'out', d }), err: (d) => send({ t: 'err', d }), stdin: () => req.stdin ?? '', code: 0, warm: true };
+                    try {
+                        process.chdir(req.cwd);
+                        const [cmd, ...rest] = req.argv;
+                        const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: OPTIONS });
+                        await run(cmd, values, positionals, Promise.resolve(browser), io);
+                        code = io.code;
+                    }
+                    catch (e) {
+                        code = report(e, io);
+                    }
+                }
+                catch {
+                    code = 1;
+                }
+                send({ t: 'exit', code });
+                c.end();
+                arm();
+            });
+        });
+    });
+    // The socket is created with the folder's protection already in place.
+    const mask = process.umask(0o077);
+    await new Promise((resolve, reject) => server.once('error', reject).listen(sock, resolve));
+    process.umask(mask);
+    arm();
+    for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP'])
+        process.once(sig, () => void shutdown());
+    await new Promise(() => { });
+}

package/dist/drawio/merge.js

@@ -33,7 +33,7 @@ export function merge(d, old, fresh, opts = {}) {
     const isTable = (n) => kindDef(d.type, n.kind).shape === 'table';
     const abs = new Map(); // final absolute boxes for nodes
     const changed = new Set(); // nodes whose box differs from the old file
-    const stats = { kept: 0, handMoved: 0, placed: [], grown: [], removed: [], rerouted: 0, carried: 0, keptUnknown: [] };
+    const stats = { kept: 0, handMoved: 0, placed: [], grown: [], shrunk: [], removed: [], rerouted: 0, carried: 0, keptUnknown: [] };
     // 1. Existing nodes stay put.
     for (const n of d.nodes) {
         const c = cellOf.get(n.id);
@@ -96,6 +96,7 @@ export function merge(d, old, fresh, opts = {}) {
         const boxy = !['start', 'end', 'decision'].includes(n.kind);
         return { w: boxy ? Math.max(nat.w, commonW) : nat.w, h: nat.h };
     };
+    const memberOf = (nodeId, gid) => ancestors(d.nodes.find((x) => x.id === nodeId)?.parent).has(gid);
     const pending = d.nodes.filter((n) => !abs.has(n.id));
     while (pending.length) {
         let i = pending.findIndex((n) => [...preds(n.id), ...succs(n.id)].some((m) => abs.has(m)));
@@ -112,7 +113,7 @@ export function merge(d, old, fresh, opts = {}) {
         else {
             cand = fallbackSpot(n, f, abs, fresh, oldGroupBox(n.parent ?? ''));
         }
-        abs.set(n.id, freeSpot(cand, n, abs, d, ancestors(n.parent), oldGroupBox));
+        abs.set(n.id, freeSpot(cand, n, abs, d, ancestors(n.parent), oldGroupBox, memberOf));
         changed.add(n.id);
         stats.placed.push(n.id);
     }
@@ -125,9 +126,28 @@ export function merge(d, old, fresh, opts = {}) {
             ...d.groups.filter((x) => x.parent === g.id).map((x) => gabs.get(x.id)),
         ].filter(Boolean);
         const need = kids.length ? padded(union(kids)) : undefined;
-        const prev = oldGroupBox(g.id);
+        let prev = oldGroupBox(g.id);
+        // A group nobody sized by hand closes up when members leave it. Each side
+        // moves in by as much as its outermost member did, so the padding stays.
+        const gc = cellOf.get(g.id);
+        if (prev && kids.length && gc && !handEdits.has(gc.id)) {
+            const was = [
+                ...shown.diagram.nodes.filter((n) => n.parent === g.id).map((n) => absBox(old, cellOf.get(n.id).id)),
+                ...shown.diagram.groups.filter((x) => x.parent === g.id).map((x) => oldGroupBox(x.id)),
+            ].filter((b) => !!b);
+            if (was.length) {
+                const a = union(was), z = union(kids);
+                const l = Math.max(0, z.x - a.x), t = Math.max(0, z.y - a.y);
+                const r = Math.max(0, a.x + a.w - (z.x + z.w)), bt = Math.max(0, a.y + a.h - (z.y + z.h));
+                if (l + t + r + bt > 1) {
+                    prev = { x: prev.x + l, y: prev.y + t, w: prev.w - l - r, h: prev.h - t - bt };
+                    stats.shrunk.push(g.id);
+                }
+            }
+        }
         const box = prev ? (need ? union([prev, need]) : prev) : need ?? { x: 0, y: 0, w: 200, h: 120 };
-        if (prev && (box.w > prev.w + 1 || box.h > prev.h + 1))
+        const before = oldGroupBox(g.id);
+        if (before && (box.w > before.w + 1 || box.h > before.h + 1) && !stats.shrunk.includes(g.id))
             stats.grown.push(g.id);
         gabs.set(g.id, box);
     }
@@ -184,7 +204,13 @@ export function merge(d, old, fresh, opts = {}) {
         });
         const routeUntouched = !oc?.attrs.aiviz_auto || oc.attrs.aiviz_auto === routeAttr(oc.geom?.points ?? []);
         const stale = endMovedByHand && routeUntouched;
-        const keepParent = oc?.parent && (oc.parent === '1' || outIds.has(oc.parent)) ? oc.parent : undefined;
+        let keepParent = oc?.parent && (oc.parent === '1' || outIds.has(oc.parent)) ? oc.parent : undefined;
+        // A route stored relative to a group is stale once that group's corner moves.
+        if (keepParent && keepParent !== '1') {
+            const was = oldGroupBox(keepParent), now = gabs.get(keepParent);
+            if (!was || !now || Math.abs(was.x - now.x) > 0.5 || Math.abs(was.y - now.y) > 0.5)
+                keepParent = undefined;
+        }
         const attrs = { ...(oc ? ownAttrs(oc) : {}), ...edgeAttrs(e) };
         if (oc && (prev?.label ?? '') === (e.label ?? '') && oc.attrs.label != null)
             attrs.label = oc.attrs.label;
@@ -246,7 +272,8 @@ export function merge(d, old, fresh, opts = {}) {
     return {
         scene: {
             name: d.title ?? old.name,
-            meta: { ...withoutTheme(oldMeta), ...diagramMeta(d, { aiviz_layout: 'manual' }) },
+            // 'manual' marks a layout a person arranged; a merge into a machine layout doesn't.
+            meta: { ...withoutTheme(oldMeta), ...diagramMeta(d, opts.touched === false ? {} : { aiviz_layout: 'manual' }) },
             background: palette(d.theme).canvas,
             vertices,
             edges,
@@ -273,7 +300,7 @@ function fallbackSpot(n, f, abs, fresh, groupBox) {
     return { x: area.x, y: area.y + area.h + GAP * 2, w: f.w, h: f.h };
 }
 /** Nearest spot to `cand` on a 8px grid that doesn't collide with placed nodes or foreign groups. */
-function freeSpot(cand, n, abs, d, myGroups, groupBox) {
+function freeSpot(cand, n, abs, d, myGroups, groupBox, memberOf) {
     const obstacles = [];
     for (const [id, b] of abs)
         if (id !== n.id)
@@ -285,7 +312,19 @@ function freeSpot(cand, n, abs, d, myGroups, groupBox) {
         if (b)
             obstacles.push(b);
     }
-    const ok = (b) => obstacles.every((o) => !overlaps(b, o, GAP));
+    // Its own groups grow to hold it. That growth must not swallow a box that
+    // isn't in the group, or the picture says something the spec doesn't.
+    const mine = [...myGroups].map((g) => ({ g, box: groupBox(g) })).filter((x) => !!x.box);
+    const swallows = (b) => mine.some(({ g, box }) => {
+        const grown = union([box, padded(b)]);
+        if (grown.w <= box.w + 1 && grown.h <= box.h + 1)
+            return false;
+        for (const [id, o] of abs)
+            if (id !== n.id && !memberOf(id, g) && overlaps(grown, o) && !overlaps(box, o))
+                return true;
+        return false;
+    });
+    const ok = (b) => obstacles.every((o) => !overlaps(b, o, GAP)) && !swallows(b);
     const snap = (v) => Math.round(v / 8) * 8;
     const start = { ...cand, x: snap(cand.x), y: snap(cand.y) };
     if (ok(start))