@itsthecsguy/linework 0.2.0 → 0.2.1

package/README.md

@@ -258,7 +258,7 @@ Docs can't hold an SVG, so the diagram lives in Google Drive and draw.io's Googl
 
 ## Status
 
-All four phases of [PLAN.md](PLAN.md) are built. Two paths haven't been tried yet, because they need a real account or app: the Google Docs add-on round trip, and saving from the VS Code Draw.io Integration extension. Both use the same file format and protocol that the tests cover with draw.io's own editor.
+All five phases of [PLAN.md](PLAN.md) are built. Two paths haven't been tried yet, because they need a real account or app: the Google Docs add-on round trip, and saving from the VS Code Draw.io Integration extension. Both use the same file format and protocol that the tests cover with draw.io's own editor.
 
 ## Development
 
@@ -269,4 +269,20 @@ npm run build        # compile to dist/
 npm run dev -- build examples/checkout.yaml -o out/checkout.drawio.svg --png out/checkout.png
 ```
 
+Every push to `main` and every pull request runs the typecheck and the tests on Node 22 and 24 in GitHub Actions. To run the suite with a browser that isn't in one of the usual places, set `LINEWORK_CHROME=/path/to/chromium`.
+
+After a change to layout or rendering, rebuild the README gallery and look at what moved:
+
+```bash
+npm run build && node docs/gallery/build.mjs
+```
+
+### Releasing
+
+```bash
+npm run release            # patch; or: npm run release -- minor | major | 1.2.3
+```
+
+That bumps the version, commits it as `Release x.y.z`, tags `vx.y.z` and pushes both. The tag starts the release workflow, which runs the tests again, publishes to npm and opens a GitHub release with generated notes. Nobody logs in to npm: the workflow publishes through npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers), which is set up once in the package's settings on npmjs.com (GitHub Actions, repository `itsthecsguy/linework`, workflow `release.yml`).
+
 `assets/drawio` holds the parts of the draw.io web app that linework runs: the renderer it uses headless, and the editor behind `linework edit`. draw.io is Apache-2.0; see [NOTICE](NOTICE). To update it, check out a jgraph/drawio tag in `vendor/drawio` and run `npm run assets`.

package/dist/commands.js

@@ -32,7 +32,7 @@ Usage:
       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.
+      Convert a Mermaid diagram (flowchart, state, sequence, ER) to a 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.

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

@@ -162,7 +162,10 @@ function nodeSizes(d, tm, fonts) {
             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);

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/mcp/server.js

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itsthecsguy/linework",
-  "version": "0.2.0",
+  "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": {

package/skills/linework/references/spec.md

@@ -307,6 +307,6 @@ The middle is `--` for an identifying relationship (solid line) or `..` for a no
 
 ## Importing Mermaid
 
-`linework import file.mmd` prints an linework spec. `-o out.drawio.svg` builds it straight away. A Markdown file works too; use `--block N` when it has several Mermaid blocks. Supported: `flowchart`/`graph`, `stateDiagram`, `sequenceDiagram`, `erDiagram`.
+`linework import file.mmd` prints a linework spec. `-o out.drawio.svg` builds it straight away. A Markdown file works too; use `--block N` when it has several Mermaid blocks. Supported: `flowchart`/`graph`, `stateDiagram`, `sequenceDiagram`, `erDiagram`.
 
 A flowchart with diamonds becomes a `flow`. One with subgraphs or cylinders becomes an `architecture` diagram. In that case a `<br>` second line becomes `tech`, and kinds are guessed from shapes and names: a cylinder becomes a database, "Kafka" becomes a queue, "Stripe" becomes external. Mermaid styling (`classDef`, `style`, `click`) is dropped. Review the printed spec before building, and fix any kinds it guessed wrong.

package/skills/linework/references/style-guide.md

@@ -20,7 +20,7 @@ Linework handles the layout and the look. These rules are about content, which i
 - **Label edges in architecture diagrams with the protocol or the verb**: `HTTPS`, `gRPC`, `SQL`, `publishes OrderPlaced`, `reads session`. An unlabeled arrow makes the reader guess.
 - **Use `-.->` for async**: events, queues, webhooks, fire-and-forget. Readers rely on the solid/dashed distinction to see where latency and failure modes change.
 - **Point the arrow the way the request goes**, not the way data comes back. Only show a return edge when the reply is interesting.
-- **Label every edge out of a decision** in a flow (`yes`/`no`, or the condition).
+- **Label every edge out of a decision** in a flow (`yes`/`no`, or the condition). Keep those labels to a word or two: each one sits right beside its diamond, where the branch leaves it.
 - In state diagrams, label transitions with the event that triggers them (`payment_succeeded`), not the resulting state.
 
 ## Groups