@itsthecsguy/linework 0.1.4 → 0.2.1

package/dist/drawio/write.js

@@ -175,6 +175,23 @@ export function sceneFromLayout(d, l) {
         vertices.push(...nodeChildren(d, n, box));
     }
     const isCyl = (id) => { const n = d.nodes.find((x) => x.id === id); return !!n && kindDef(d.type, n.kind).shape === 'cylinder'; };
+    const isDecision = (id) => { const n = d.nodes.find((x) => x.id === id); return !!n && kindDef(d.type, n.kind).shape === 'diamond'; };
+    // How far an edge shares its first run with a sibling leaving the same point.
+    const sharedStem = (id, from) => {
+        const mine = l.edges.get(id).points;
+        let shared = 0;
+        for (const o of d.edges) {
+            const pts = o.id !== id && o.from === from && o.to !== from ? l.edges.get(o.id)?.points : undefined;
+            if (!pts || pts.length < 2 || mine.length < 2 || Math.hypot(pts[0].x - mine[0].x, pts[0].y - mine[0].y) > 1)
+                continue;
+            const dir = (p) => [Math.sign(Math.round(p[1].x - p[0].x)), Math.sign(Math.round(p[1].y - p[0].y))].join();
+            if (dir(pts) !== dir(mine))
+                continue;
+            const len = (p) => Math.hypot(p[1].x - p[0].x, p[1].y - p[0].y);
+            shared = Math.max(shared, Math.min(len(pts), len(mine)));
+        }
+        return shared;
+    };
     const edges = d.edges.map((e) => {
         const le = l.edges.get(e.id);
         const cyl = { from: isCyl(e.from), to: isCyl(e.to) };
@@ -197,7 +214,7 @@ export function sceneFromLayout(d, l) {
             ...base,
             style: base.style + portStyle(le.points, abs(e.from), abs(e.to), cyl),
             points: le.points.slice(1, -1),
-            labelX: le.label && e.label ? (labelSpot(le.points, le.label, l.direction) ?? labelFraction(le.points, { x: le.label.x + le.label.w / 2, y: le.label.y + le.label.h / 2 })) : undefined,
+            labelX: le.label && e.label ? ((isDecision(e.from) ? branchSpot(le.points, le.label, l.direction, sharedStem(e.id, e.from)) : undefined) ?? labelSpot(le.points, le.label, l.direction, [...l.nodes].filter(([id]) => id !== e.from && id !== e.to).map(([, b]) => b)) ?? labelFraction(le.points, { x: le.label.x + le.label.w / 2, y: le.label.y + le.label.h / 2 })) : undefined,
         };
     });
     alignLabels(d, l, edges);
@@ -334,7 +351,7 @@ export function toMxfile(d, l) {
  * 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, dir) {
+export function labelSpot(pts, label, dir, avoid = []) {
     let total = 0;
     let best;
     // Runs along the flow belong to one edge; runs across it are often shared
@@ -348,10 +365,57 @@ function labelSpot(pts, label, dir) {
         const along = dir ? vertical === flowVertical : true;
         const better = !best || (along && !best.along) || (along === best.along && room > best.room);
         if (room >= 0 && better)
-            best = { room, at: total + len / 2, along };
+            best = { room, at: total + len / 2, along, a, b, start: total, len };
         total += len;
     }
-    return best && total ? (best.at / total) * 2 - 1 : undefined;
+    if (!best || !total)
+        return undefined;
+    // Halfway along a long run can be right beside a box the edge only passes, where
+    // the label reads as that box's caption. Slide along the run to the nearest
+    // spot past the box, with a little air; stay in the middle when there is none.
+    const { a, b, start, len } = best;
+    const vertical = Math.abs(b.x - a.x) < Math.abs(b.y - a.y);
+    const half = (vertical ? label.h : label.w) / 2 + 10;
+    // Beside: level with the box along the run, and within 12px of it across the run.
+    const beside = (at, air) => {
+        const t = (at - start) / len, cx = a.x + t * (b.x - a.x), cy = a.y + t * (b.y - a.y);
+        const px = vertical ? 12 : air, py = vertical ? air : 12;
+        const r = { x: cx - label.w / 2 - px, y: cy - label.h / 2 - py, w: label.w + 2 * px, h: label.h + 2 * py };
+        return avoid.some((o) => r.x < o.x + o.w && r.x + r.w > o.x && r.y < o.y + o.h && r.y + r.h > o.y);
+    };
+    // Level by a few px or more: a label that only grazes the box's end is fine where it is.
+    if (beside(best.at, -4))
+        for (let step = 4; step <= len / 2 - half; step += 4)
+            for (const at of [best.at - step, best.at + step])
+                if (!beside(at, 4))
+                    return (at / total) * 2 - 1;
+    return (best.at / total) * 2 - 1;
+}
+/**
+ * A branch label ("yes", "no") belongs to its decision, so it sits where the
+ * branch leaves the diamond, not halfway to the next step: on the run out of the
+ * diamond's point when that has room, otherwise at the start of the first run
+ * along the flow, or of a long arm that forks off a short stem. `stem` is how much of the first run a sibling branch shares;
+ * the label starts past it, so it doesn't cover the place where they part.
+ */
+export function branchSpot(pts, label, dir, stem = 0) {
+    const flowVertical = dir === 'TB' || dir === 'BT';
+    const lens = pts.slice(1).map((b, i) => Math.hypot(b.x - pts[i].x, b.y - pts[i].y));
+    const total = lens.reduce((x, y) => x + y, 0);
+    let before = 0;
+    for (let i = 0; i < lens.length; i++) {
+        const a = pts[i], b = pts[i + 1], len = lens[i];
+        const vertical = Math.abs(b.x - a.x) < Math.abs(b.y - a.y);
+        const size = vertical ? label.h : label.w;
+        const lead = i === 0 && stem > 0 ? stem + 6 : 10;
+        // A long arm across the flow, straight after the stem out of the point, is
+        // nearer the diamond than the drop at its far end.
+        const arm = i === 1 && len >= 96 && lens[0] <= 24;
+        if ((i === 0 || arm || vertical === flowVertical) && len >= lead + size + 10)
+            return ((before + lead + size / 2) / total) * 2 - 1;
+        before += len;
+    }
+    return undefined;
 }
 // draw.io positions edge labels by fraction along the path, -1..1.
 // Project ELK's label centre onto the route and convert.

package/dist/layout/layout.js

@@ -156,9 +156,16 @@ function nodeSizes(d, tm, fonts) {
             continue;
         }
         if (shape === 'diamond') {
-            const t = textOf(n, fonts.maxText * 0.7);
+            // A diamond holds little text for its size. Past two lines, wrap wider:
+            // three lines in a wider diamond take less room than four in a tall one.
+            let t = textOf(n, fonts.maxText * 0.7);
+            if (t.lines > 2)
+                t = textOf(n, fonts.maxText);
             const w = snap(Math.max(128, t.width * 1.5 + 40));
-            sizes.set(n.id, { w, h: snap(Math.max(72, w * 0.5, t.lines * fonts.line * 2 + 24)) });
+            // The text takes about 0.6 of the width, which leaves it 0.4 of the height.
+            // Only that tall, and no taller: a diamond at half its width for a two-line
+            // question is the biggest thing in the flow, bigger than any step.
+            sizes.set(n.id, { w, h: snap(Math.max(72, w * 0.36, t.lines * fonts.line * 2.5 + 24)) });
             continue;
         }
         const extra = shapeExtra(shape, !!n.icon);
@@ -274,6 +281,45 @@ async function run(d, dir, sizes, labels, groupMin, groupTop, order, pins = new
         if (call)
             flipped.add(pairs === 'reply' ? e.id : call.id);
     });
+    // The edge that closes a loop (a retry, "new findings, investigate again")
+    // points back at a box that was declared earlier and already appears in an
+    // earlier edge. Lay it out reversed, so the main path keeps running forward
+    // whichever branch ELK happens to walk first.
+    const index = new Map(d.nodes.map((n, i) => [n.id, i]));
+    const firstUse = new Map();
+    d.edges.forEach((e, i) => {
+        for (const id of [e.from, e.to])
+            if (!firstUse.has(id))
+                firstUse.set(id, i);
+    });
+    const back = d.edges
+        .map((e, i) => ({ e, i }))
+        .filter(({ e, i }) => e.from !== e.to && index.get(e.to) < index.get(e.from) && firstUse.get(e.to) < i)
+        // Call-and-reply pairs are handled above.
+        .filter(({ e }) => !d.edges.some((x) => x.from === e.to && x.to === e.from))
+        // Last written first: once the loop's closing edge is cut, an earlier
+        // backward edge inside the same loop is no longer part of a cycle and stays.
+        .reverse()
+        .map(({ e }) => e);
+    const cut = new Set();
+    const reaches = (from, to) => {
+        const seen = new Set([from]);
+        for (const q = [from]; q.length;) {
+            const cur = q.pop();
+            if (cur === to)
+                return true;
+            for (const x of d.edges)
+                if (x.from === cur && !cut.has(x.id) && !seen.has(x.to))
+                    (seen.add(x.to), q.push(x.to));
+        }
+        return false;
+    };
+    for (const e of back) {
+        if (!reaches(e.to, e.from))
+            continue;
+        cut.add(e.id);
+        flipped.add(e.id);
+    }
     root.edges = d.edges.map((e, i) => {
         const src = pinFor(pins, e.from, e.id, 'from') ?? e.from, dst = pinFor(pins, e.to, e.id, 'to') ?? e.to;
         const flip = flipped.has(e.id);

package/dist/layout/polish.js

@@ -137,47 +137,108 @@ export function polish(d, l, inp) {
         const b = nodes.get(n.id);
         const cx = b.x + b.w / 2, cy = b.y + b.h / 2;
         const outs = edges.filter((e) => e.from === n.id && e.to !== n.id);
-        // The run each edge settles into once it is clear of the diamond.
-        const runX = (e) => {
-            const p = e.pts;
+        // The run each edge settles into once it is clear of the diamond. ELK usually
+        // leaves on a short stub and turns; when it leaves straight down instead, the
+        // first segment is the run.
+        const runAt = (p) => {
+            if (p.length >= 2 && vert(p[0], p[1]) && p[1].y > b.y + b.h + 24)
+                return 0;
             for (let i = 1; i < p.length - 1; i++)
                 if (vert(p[i], p[i + 1]) && p[i + 1].y > b.y + b.h + 1)
-                    return p[i].x;
-            return p[p.length - 1].x;
+                    return i;
+            return -1;
+        };
+        const runX = (e) => {
+            const i = runAt(e.pts);
+            return (i >= 0 ? e.pts[i] : e.pts[e.pts.length - 1]).x;
         };
+        // Points from the start of that run on.
         const tail = (e) => {
-            // Points from the start of that run on.
-            const p = e.pts;
-            for (let i = 1; i < p.length - 1; i++)
-                if (vert(p[i], p[i + 1]) && p[i + 1].y > b.y + b.h + 1)
-                    return p.slice(i);
-            return p.slice(-1);
+            const i = runAt(e.pts);
+            return i >= 0 ? e.pts.slice(i) : e.pts.slice(-1);
         };
         const sorted = [...outs].sort((a, c) => runX(a) - runX(c));
         let bottomTaken = false;
+        // One branch per side point: a second one there would hide the first.
+        const taken = { left: false, right: false };
+        // A branch whose run sits under the diamond would have to fork off the bottom
+        // point next to its sibling. Move the run out past the side point instead, so
+        // each branch leaves from its own corner: side point, a short stub, then down.
+        const sideStep = (e, rest, left) => {
+            if (rest.length < 2)
+                return undefined;
+            const lab = l.edges.get(e.id)?.label;
+            // Far enough out that the branch label, centred on the run, clears the diamond.
+            const out = Math.max(24, lab ? Math.ceil(f.boxTo(lab).w / 2) + 8 : 0);
+            const beside = left ? b.x - out : b.x + b.w + out;
+            const end = rest[1], t = nodes.get(e.to);
+            // A run that drops straight into the target has to stay over the target.
+            const drops = rest.length === 2;
+            if (drops ? ['diamond', 'table'].includes(shapeOf(e.to) ?? '') || !near(end.y, t.y, 1) : !horiz(end, rest[2]) || end.y < b.y + b.h + 12)
+                return undefined;
+            // Into the target's middle when that is already clear of the diamond, else just beside the diamond.
+            const mid = t.x + t.w / 2;
+            const tries = drops && (left ? mid <= beside : mid >= beside) ? [mid, beside] : [beside];
+            const sideP = { x: left ? b.x : b.x + b.w, y: cy };
+            for (const nx of tries) {
+                if (drops && (nx < t.x + R || nx > t.x + t.w - R || usedAt(e.to, nx, e, 'top')))
+                    continue;
+                const a = { x: nx, y: cy }, c = { x: nx, y: end.y };
+                if (!clear(sideP, a, [n.id]) || !clear(a, c, [n.id, e.to]) || !free(a, c, e))
+                    continue;
+                if (!drops && !clear(c, rest[2], [n.id, e.to]))
+                    continue;
+                return simplify([sideP, a, c, ...rest.slice(2)]);
+            }
+            return undefined;
+        };
         // The edge closest to straight down gets the bottom point.
-        const straight = sorted.reduce((m, e) => (!m || Math.abs(runX(e) - cx) < Math.abs(runX(m) - cx) ? e : m), undefined);
-        for (const e of sorted) {
+        const nearest = (list) => list.reduce((m, e) => (!m || Math.abs(runX(e) - cx) < Math.abs(runX(m) - cx) ? e : m), undefined);
+        // Or, failing that, the one whose target reaches under the bottom point, so it can drop straight.
+        const reaches = (e) => {
+            const t = nodes.get(e.to), rest = tail(e);
+            return rest.length === 2 && near(rest[1].y, t.y, 1) && !['diamond', 'table'].includes(shapeOf(e.to) ?? '') && cx >= t.x + 16 && cx <= t.x + t.w - 16;
+        };
+        const mid = nearest(sorted);
+        const straight = mid && Math.abs(runX(mid) - cx) < 12 ? mid : nearest(sorted.filter(reaches));
+        // The middle branch goes last: whether it can drop straight depends on where
+        // its siblings ended up, not on the stubs ELK gave them at the bottom point.
+        for (const e of [...sorted.filter((x) => x !== straight), ...(straight ? [straight] : [])]) {
             const x = runX(e), rest = tail(e);
             const bottom = { x: cx, y: b.y + b.h };
+            // A run that starts on the diamond itself: what follows is from its far end on.
+            const onEdge = rest[0].y <= b.y + b.h + 1 && rest.length > 1;
             if (e === straight && Math.abs(x - cx) < 12) {
-                e.pts = simplify([bottom, { x: cx, y: rest[0].y }, ...rest.slice(1)].map((pt, i) => (i === 1 ? pt : pt)));
-                if (rest.length && !near(rest[0].x, cx))
-                    e.pts = simplify([bottom, { x: cx, y: rest[0].y }, ...rest]);
+                const run = onEdge ? rest.slice(1) : rest;
+                e.pts = simplify([bottom, { x: cx, y: run[0].y }, ...run.slice(1)]);
+                if (!near(run[0].x, cx))
+                    e.pts = simplify([bottom, { x: cx, y: run[0].y }, ...run]);
+                bottomTaken = true;
+                continue;
+            }
+            const t = nodes.get(e.to), floor = { x: cx, y: t.y };
+            if (e === straight && reaches(e) && !usedAt(e.to, cx, e, 'top') && clear(bottom, floor, [n.id, e.to]) && free(bottom, floor, e)) {
+                e.pts = [bottom, floor];
                 bottomTaken = true;
                 continue;
             }
             const left = x < cx;
             const sideP = { x: left ? b.x : b.x + b.w, y: cy };
             const corner = { x, y: cy };
-            const sideOk = (left ? x < b.x - 10 : x > b.x + b.w + 10) && clear(sideP, corner, [n.id]) && clear(corner, rest[0], [n.id, e.to]);
-            if (sideOk) {
-                e.pts = simplify([sideP, corner, ...rest]);
-                continue;
+            const key = left ? 'left' : 'right';
+            if (!taken[key]) {
+                const sideOk = (left ? x < b.x - 10 : x > b.x + b.w + 10) && clear(sideP, corner, [n.id]) && clear(corner, rest[0], [n.id, e.to]);
+                const pts = sideOk ? simplify([sideP, corner, ...rest]) : sideStep(e, rest, left);
+                if (pts) {
+                    e.pts = pts;
+                    taken[key] = true;
+                    continue;
+                }
             }
             // Branches that both head down fork from the bottom point on a short stem.
-            const y = Math.min(rest[0].y, b.y + b.h + 16);
-            e.pts = simplify([bottom, { x: cx, y }, { x, y }, ...rest]);
+            // Such a run turns onto the stem below the point.
+            const y = onEdge ? b.y + b.h + 16 : Math.min(rest[0].y, b.y + b.h + 16);
+            e.pts = simplify([bottom, { x: cx, y }, { x, y }, ...(onEdge ? rest.slice(1) : rest)]);
             bottomTaken = true;
         }
         for (const e of edges.filter((x) => x.to === n.id && x.from !== n.id)) {
@@ -188,9 +249,38 @@ export function polish(d, l, inp) {
                     e.pts[m - 1] = { x: cx, y: b.y };
                 continue;
             }
+            // Arriving sideways and then dropping to a port beside the top point: carry
+            // the sideways run on to the middle. Stepping down first leaves a small kink.
+            const before = p[m - 3];
+            const across = { x: cx, y: prev.y };
+            if (before && horiz(before, prev) && !near(before.x, cx) && clear(prev, across, [e.from, n.id]) && clear(across, { x: cx, y: b.y }, [e.from, n.id])) {
+                e.pts = simplify([...p.slice(0, m - 2), across, { x: cx, y: b.y }]);
+                continue;
+            }
             const y = Math.max(prev.y, b.y - 16);
             e.pts = simplify([...p.slice(0, m - 1), { x: last.x, y }, { x: cx, y }, { x: cx, y: b.y }]);
         }
+        // Branches that join above a decision meet at one height, not a few px apart.
+        const joins = edges.flatMap((e) => {
+            const p = e.pts, m = p.length;
+            if (e.to !== n.id || e.from === n.id || m < 4)
+                return [];
+            const [up, a, c, top] = [p[m - 4], p[m - 3], p[m - 2], p[m - 1]];
+            const ok = vert(up, a) && up.y < a.y && horiz(a, c) && near(c.x, cx) && vert(c, top) && near(top.y, b.y, 1);
+            return ok ? [{ e, a, c }] : [];
+        });
+        if (joins.length > 1) {
+            const y = Math.max(...joins.map((j) => j.a.y));
+            for (const j of joins) {
+                if (near(j.a.y, y) || y - j.a.y > 24)
+                    continue;
+                const na = { x: j.a.x, y }, nc = { x: cx, y };
+                if (!clear(na, nc, [j.e.from, n.id]))
+                    continue;
+                const m = j.e.pts.length;
+                j.e.pts = simplify([...j.e.pts.slice(0, m - 3), na, nc, j.e.pts[m - 1]]);
+            }
+        }
     }
     dejog(true);
     // Self-loops: wide enough to read as a loop, label outside it.

package/dist/lint/check.js

@@ -63,9 +63,25 @@ export function check(cells) {
         if (p?.container && !inside(n.box, p.box, 2))
             findings.push({ level: 'warning', rule: 'outside-group', message: `${name(n)} sticks out of its group ${name(p)}` });
     }
+    // A box drawn inside a group reads as a member of it.
+    const groups = containers.filter((g) => !scaffold(g));
+    for (const n of nodes) {
+        const mine = ancestors(n.id);
+        for (const g of groups)
+            if (!mine.has(g.id) && inter(n.box, g.box) > 0.25 * n.box.w * n.box.h)
+                findings.push({ level: 'warning', rule: 'in-other-group', message: `${name(n)} sits inside ${name(g)} but isn't in that group; move it out, or put it in the group` });
+    }
     for (const e of edges) {
         const pts = e.points;
         const skip = new Set([e.source, e.target, ...ancestors(e.source), ...ancestors(e.target)]);
+        // A line through a group it has no end in looks like it connects to something there.
+        for (const g of groups) {
+            if (skip.has(g.id))
+                continue;
+            const r = shrink(g.box, 6);
+            if (pts.some((p, i) => i < pts.length - 1 && segHitsBox(p, pts[i + 1], r)))
+                findings.push({ level: 'warning', rule: 'edge-through-group', message: `edge ${edgeName(e, byId)} runs through ${name(g)}, which neither end is in` });
+        }
         for (const n of nodes) {
             if (skip.has(n.id))
                 continue;

package/dist/mcp/server.js

@@ -30,7 +30,7 @@ const PKG = (() => {
     }
     throw new Error('linework: bundled skill not found. Reinstall linework.');
 })();
-const TOOL_NAMES = `In this MCP server the CLI commands in the guide are tools: build -> build_diagram, show -> show_diagram, check -> check_diagram, render -> render_diagram, tidy -> tidy_diagram, import -> import_mermaid, icons -> list_icons, edit -> edit_diagram, publish -> publish_diagram. Pass the spec text to build_diagram directly instead of writing a file.\n\n`;
+const TOOL_NAMES = `In this MCP server the CLI commands in the guide are tools: build -> build_diagram, show -> show_diagram, check -> check_diagram, render -> render_diagram, tidy -> tidy_diagram, import -> import_mermaid, icons -> list_icons, edit -> edit_diagram, publish -> publish_diagram. Pass the spec text to build_diagram directly instead of writing a file. There are no set, add or rm tools: for a small change, call show_diagram, edit its output and pass that to build_diagram, which keeps the layout the same way.\n\n`;
 export function createServer(opts) {
     let browser;
     const getBrowser = () => (browser ??= DrawioBrowser.launch({ scale: 2 }));
@@ -66,13 +66,13 @@ export function createServer(opts) {
         description: 'Returns the linework guide: diagram types, the YAML spec format with examples, and the style rules. Read it before your first diagram.',
         inputSchema: z.object({
             topic: z
-                .enum(['overview', 'spec', 'style', 'google-docs'])
+                .enum(['overview', 'spec', 'style', 'google-docs', 'troubleshooting'])
                 .default('overview')
-                .describe('overview: workflow and cheat sheet. spec: the full spec reference. style: what makes a good diagram. google-docs: getting diagrams into Google Docs.'),
+                .describe('overview: workflow and cheat sheet. spec: the full spec reference. style: what makes a good diagram. google-docs: getting diagrams into Google Docs. troubleshooting: what to do when a command fails.'),
         }),
         annotations: { readOnlyHint: true },
     }, async ({ topic }) => {
-        const file = { overview: 'SKILL.md', spec: 'references/spec.md', style: 'references/style-guide.md', 'google-docs': 'references/google-docs.md' }[topic];
+        const file = { overview: 'SKILL.md', spec: 'references/spec.md', style: 'references/style-guide.md', 'google-docs': 'references/google-docs.md', troubleshooting: 'references/troubleshooting.md' }[topic];
         const body = fs.readFileSync(path.join(PKG, 'skills', 'linework', file), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, '');
         return { content: [text(TOOL_NAMES + body)] };
     });
@@ -137,8 +137,8 @@ export function createServer(opts) {
         return { content: [text([res.fixed ? `rerouted ${res.fixed} edges in ${file}` : 'nothing to fix', ...checkLines(res.check)].join('\n'))] };
     })());
     server.registerTool('import_mermaid', {
-        title: 'Convert Mermaid to an linework spec',
-        description: 'Converts a Mermaid diagram (flowchart, stateDiagram, sequenceDiagram, erDiagram) to an linework spec. Returns the spec; review the guessed node kinds, then build it. With path, builds it straight away.',
+        title: 'Convert Mermaid to a linework spec',
+        description: 'Converts a Mermaid diagram (flowchart, stateDiagram, sequenceDiagram, erDiagram) to a linework spec. Returns the spec; review the guessed node kinds, then build it. With path, builds it straight away.',
         inputSchema: z.object({ source: z.string().describe('Mermaid source, without the ``` fence.'), path: pathArg.optional() }),
     }, (args) => wrap(async () => {
         const { importMermaid } = await import('../import/mermaid.js');

package/dist/patch.js

@@ -0,0 +1,167 @@
+// One-line changes to an existing diagram: set a field, add or remove a box or
+// an edge. Each reads the file's current spec (hand edits included), changes it
+// and builds, so the layout merges the same way a show / edit / build round does.
+import YAML, { isMap, isScalar, isSeq } from 'yaml';
+import { build, show } from './api.js';
+export class PatchError extends Error {
+}
+const TOP = new Set(['title', 'theme', 'direction']);
+const TEXT = new Set(['label', 'tech', 'title']);
+// "from ARROW to" or "from ARROW to: label". ER cardinalities count as arrows too.
+const EDGE = /^(\S+)\s+(\S*(?:->|=>|--|\.\.)\S*|<->)\s+([^\s:]+)(?::\s*(.*))?$/;
+function mapAt(doc, key, create = false) {
+    const m = doc.get(key);
+    if (isMap(m))
+        return m;
+    if (!create)
+        return undefined;
+    const made = doc.createNode({});
+    doc.set(key, made);
+    return made;
+}
+function seqAt(doc, key, create = false) {
+    const s = doc.get(key);
+    if (isSeq(s))
+        return s;
+    if (!create)
+        return undefined;
+    const made = doc.createNode([]);
+    doc.set(key, made);
+    return made;
+}
+const edgeEnds = (item) => {
+    if (isScalar(item) && typeof item.value === 'string') {
+        const m = EDGE.exec(item.value.trim());
+        return m ? { from: m[1], to: m[3] } : undefined;
+    }
+    // Unquoted, "a -> b: label" is a one-pair YAML map whose key is the edge.
+    if (isMap(item) && item.items.length === 1 && isScalar(item.items[0].key) && typeof item.items[0].key.value === 'string') {
+        const m = EDGE.exec(item.items[0].key.value.trim());
+        if (m)
+            return { from: m[1], to: m[3] };
+    }
+    if (isMap(item) && item.has('from') && item.has('to'))
+        return { from: String(item.get('from')), to: String(item.get('to')) };
+    return undefined;
+};
+/** Apply the ops to a spec's YAML text and return the new text. */
+export function patchSpec(yaml, ops) {
+    const doc = YAML.parseDocument(yaml);
+    const sequence = doc.get('type') === 'sequence';
+    const nodesKey = sequence ? 'participants' : 'nodes';
+    const edgesKey = sequence ? 'messages' : 'edges';
+    const has = (key, id) => !!mapAt(doc, key)?.has(id);
+    const known = () => [...(mapAt(doc, nodesKey)?.items ?? []), ...(mapAt(doc, 'groups')?.items ?? [])].map((p) => String(isScalar(p.key) ? p.key.value : p.key)).join(', ');
+    for (const { op, args } of ops) {
+        if (!args.length)
+            throw new PatchError(`${op} needs at least one argument`);
+        for (const arg of args) {
+            if (op === 'set') {
+                const eq = arg.indexOf('=');
+                if (eq < 1)
+                    throw new PatchError(`can't read "${arg}". Write it as id.field=value, for example api.label="Checkout API", or theme=dark.`);
+                const path = arg.slice(0, eq), raw = arg.slice(eq + 1);
+                const dot = path.lastIndexOf('.');
+                const field = dot < 0 ? path : path.slice(dot + 1);
+                const value = TEXT.has(field) ? raw : YAML.parse(raw);
+                if (dot < 0) {
+                    if (!TOP.has(path))
+                        throw new PatchError(`"${path}" isn't a diagram setting. Settings: title, theme, direction. For a box, write id.field=value.`);
+                    if (raw === '')
+                        doc.delete(path);
+                    else
+                        doc.set(path, value);
+                    continue;
+                }
+                const id = path.slice(0, dot);
+                const key = has(nodesKey, id) ? nodesKey : has('groups', id) ? 'groups' : undefined;
+                if (!key)
+                    throw new PatchError(`no box or group named "${id}". There are: ${known()}`);
+                const owner = mapAt(doc, key);
+                const found = owner.get(id, true);
+                let entry;
+                if (isMap(found))
+                    entry = found;
+                else {
+                    // "id: Label" and "id:" are short for a map.
+                    const label = isScalar(found) && found.value != null ? { label: found.value } : {};
+                    entry = doc.createNode(label, { flow: true });
+                    owner.set(id, entry);
+                }
+                if (raw === '')
+                    entry.delete(field);
+                else
+                    entry.set(field, value);
+            }
+            else if (op === 'add') {
+                const text = arg.trim();
+                if (EDGE.test(text)) {
+                    seqAt(doc, edgesKey, true).add(doc.createNode(text));
+                    continue;
+                }
+                const group = /^group\s+/.test(text);
+                const parsed = YAML.parse(group ? text.replace(/^group\s+/, '') : text);
+                const entries = typeof parsed === 'string' ? [[parsed, {}]] : parsed && typeof parsed === 'object' ? Object.entries(parsed) : [];
+                if (!entries.length)
+                    throw new PatchError(`can't read "${arg}". A box: "fraud: { label: Fraud check, in: vpc }". An edge: "api -> fraud: score". A group: "group vpc: { label: Production VPC }".`);
+                const key = group ? 'groups' : nodesKey;
+                for (const [id, v] of entries) {
+                    if (has(nodesKey, id) || has('groups', id))
+                        throw new PatchError(`"${id}" already exists. Use set to change it.`);
+                    const val = typeof v === 'string' ? { label: v } : (v ?? {});
+                    mapAt(doc, key, true).set(id, doc.createNode(val, { flow: true }));
+                }
+            }
+            else {
+                const text = arg.trim();
+                const m = EDGE.exec(text);
+                if (m) {
+                    const list = seqAt(doc, edgesKey);
+                    const i = list?.items.findIndex((it) => {
+                        const e = edgeEnds(it);
+                        return e && e.from === m[1] && e.to === m[3];
+                    });
+                    if (!list || i === undefined || i < 0)
+                        throw new PatchError(`no edge from "${m[1]}" to "${m[3]}"`);
+                    list.delete(i);
+                    continue;
+                }
+                if (has(nodesKey, text)) {
+                    mapAt(doc, nodesKey).delete(text);
+                    const list = seqAt(doc, edgesKey);
+                    if (list)
+                        for (let i = list.items.length - 1; i >= 0; i--) {
+                            const e = edgeEnds(list.items[i]);
+                            if (e && (e.from === text || e.to === text))
+                                list.delete(i);
+                        }
+                }
+                else if (has('groups', text)) {
+                    // Its members move up to the group it was in, or out to the top level.
+                    const groups = mapAt(doc, 'groups');
+                    const self = groups.get(text);
+                    const up = isMap(self) ? self.get('in') : undefined;
+                    groups.delete(text);
+                    for (const k of [nodesKey, 'groups'])
+                        for (const p of mapAt(doc, k)?.items ?? [])
+                            if (isMap(p.value) && p.value.get('in') === text) {
+                                if (up)
+                                    p.value.set('in', up);
+                                else
+                                    p.value.delete('in');
+                            }
+                    if (!groups.items.length)
+                        doc.delete('groups');
+                }
+                else
+                    throw new PatchError(`no box, group or edge matches "${arg}". There are: ${known()}`);
+            }
+        }
+    }
+    return doc.toString({ lineWidth: 0 });
+}
+/** Change a diagram file in place. The existing layout is kept. */
+export async function patchFile(file, ops, opts = {}) {
+    const yaml = patchSpec(show(file).yaml, ops);
+    return build(yaml, { ...opts, out: file });
+}

package/dist/report.js

@@ -8,6 +8,8 @@ export function buildLines(res, png) {
             parts.push(`placed ${m.placed.join(', ')}`);
         if (m.grown.length)
             parts.push(`grew ${m.grown.join(', ')}`);
+        if (m.shrunk.length)
+            parts.push(`closed up ${m.shrunk.join(', ')}`);
         if (m.removed.length)
             parts.push(`removed ${m.removed.join(', ')}`);
         if (m.rerouted)

package/dist/spec/parse.js

@@ -243,6 +243,8 @@ export function parseSpec(raw) {
             const out = edges.filter((e) => e.from === n.id);
             if (out.some((e) => !e.label))
                 warnings.push({ path: `nodes.${n.id}`, message: 'label every edge leaving a decision, e.g. "yes"/"no"' });
+            if (n.label.length > 40)
+                warnings.push({ path: `nodes.${n.id}`, message: `a diamond holds little text; shorten "${n.label.slice(0, 24)}..." to a short question and put the detail in the step before it` });
         }
     }
     highlightWarning(real, edges, warnings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsthecsguy/linework",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Software diagrams an AI can write and a person can edit. YAML spec in, .drawio.svg out, editable in draw.io.",
   "keywords": [
     "diagram",
@@ -41,6 +41,7 @@
     "assets": "node scripts/copy-drawio-assets.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",
+    "release": "node scripts/release.mjs",
     "fonts": "node scripts/copy-fonts.mjs"
   },
   "dependencies": {