@liminis/diagrams 0.1.1 → 0.1.2

package/README.md

@@ -89,6 +89,19 @@ positions for. Persisting them is entirely your call — see
 example (including how `@liminis/editor` does it) and why this package itself never
 writes them anywhere.
 
+## Render on the command line
+
+```bash
+npx --package=@liminis/diagrams -- render-c4 diagram.puml
+# diagram.puml -> diagram.svg
+```
+
+Useful for pre-rendering diagrams so a plain `![Diagram](diagram.svg)` is enough for
+GitHub (or any markdown renderer) to show them — see
+[`docs/github-integration.md`](docs/github-integration.md) for the CI recipe, and
+[`docs/claude-code-integration.md`](docs/claude-code-integration.md) for getting Claude
+to render real diagrams instead of hand-drawing them.
+
 ## Supported syntax
 
 `Person`, `System`, `Container`, `Component` and their `_Ext` / `Db` / `Queue` variants,

package/dist/bin/render-c4.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * `render-c4` — render C4-PlantUML source files to SVG on disk.
+ *
+ * This is the CLI form of `renderC4DiagramToSVG` (`@liminis/diagrams/server`),
+ * meant for pre-rendering diagrams in CI so that a plain `![Diagram](x.svg)` in
+ * a markdown file is enough for GitHub (or any other markdown renderer) to show
+ * it — no live rendering service, no image-provider proxy, nothing to host.
+ * See docs/github-integration.md for the recipe this exists for.
+ *
+ * No dependency is added for argument parsing: flags are hand-rolled to match
+ * the style of the other scripts in this repo (guard-publish.mjs,
+ * verify-package.mjs), and the surface here is small enough not to need one.
+ */
+export interface Options {
+    files: string[];
+    dark: boolean;
+    out?: string;
+    outDir?: string;
+    check: boolean;
+    stdin: boolean;
+}
+export declare function parseArgs(argv: string[]): Options | null;
+export declare function outputPathFor(inputPath: string, options: Options): string;
+/**
+ * Null when `options` is a valid combination; otherwise the message to report
+ * (without the `render-c4: ` prefix `main` adds).
+ */
+export declare function validateStdinCombination(options: Options): string | null;
+export declare function renderFiles(options: Options): number;

package/dist/bin/render-c4.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * `render-c4` — render C4-PlantUML source files to SVG on disk.
+ *
+ * This is the CLI form of `renderC4DiagramToSVG` (`@liminis/diagrams/server`),
+ * meant for pre-rendering diagrams in CI so that a plain `![Diagram](x.svg)` in
+ * a markdown file is enough for GitHub (or any other markdown renderer) to show
+ * it — no live rendering service, no image-provider proxy, nothing to host.
+ * See docs/github-integration.md for the recipe this exists for.
+ *
+ * No dependency is added for argument parsing: flags are hand-rolled to match
+ * the style of the other scripts in this repo (guard-publish.mjs,
+ * verify-package.mjs), and the surface here is small enough not to need one.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, basename, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderC4DiagramToSVG } from '../server/render-to-string.js';
+function printUsage() {
+    console.log(`Usage: render-c4 [options] <files...>
+
+Render C4-PlantUML source files to SVG.
+
+Options:
+  --dark             Render in dark mode
+  -o, --out <file>   Output path (only valid with exactly one input file)
+  --out-dir <dir>    Write outputs here, preserving basenames (.svg extension)
+  --check            Validate only — write nothing, exit non-zero on any error
+  --stdin            Read source from stdin, write SVG to stdout
+  -h, --help         Show this help
+`);
+}
+export function parseArgs(argv) {
+    const options = { files: [], dark: false, check: false, stdin: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '-h':
+            case '--help':
+                return null;
+            case '--dark':
+                options.dark = true;
+                break;
+            case '--check':
+                options.check = true;
+                break;
+            case '--stdin':
+                options.stdin = true;
+                break;
+            case '-o':
+            case '--out':
+                options.out = argv[++i];
+                break;
+            case '--out-dir':
+                options.outDir = argv[++i];
+                break;
+            default:
+                options.files.push(arg);
+        }
+    }
+    return options;
+}
+export function outputPathFor(inputPath, options) {
+    if (options.out)
+        return options.out;
+    const svgName = `${basename(inputPath, extname(inputPath))}.svg`;
+    return options.outDir ? join(options.outDir, svgName) : join(dirname(inputPath), svgName);
+}
+function renderStdin(dark) {
+    const chunks = [];
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => {
+        const source = Buffer.concat(chunks).toString('utf-8');
+        const { svg, errors } = renderC4DiagramToSVG(source, dark);
+        if (errors.length > 0) {
+            for (const error of errors) {
+                console.error(`<stdin>:${error.line}:${error.column}: ${error.message}`);
+            }
+            process.exitCode = 2;
+            return;
+        }
+        process.stdout.write(svg);
+    });
+}
+/**
+ * Null when `options` is a valid combination; otherwise the message to report
+ * (without the `render-c4: ` prefix `main` adds).
+ */
+export function validateStdinCombination(options) {
+    if (options.stdin && (options.check || options.out !== undefined || options.outDir !== undefined || options.files.length > 0)) {
+        return '--stdin cannot be combined with --check, -o/--out, --out-dir, or file arguments';
+    }
+    return null;
+}
+export function renderFiles(options) {
+    if (options.out && options.files.length > 1) {
+        console.error('render-c4: -o/--out only applies with a single input file');
+        return 1;
+    }
+    let failures = 0;
+    for (const inputPath of options.files) {
+        let source;
+        try {
+            source = readFileSync(inputPath, 'utf-8');
+        }
+        catch (err) {
+            failures++;
+            console.error(`${inputPath}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const { svg, errors } = renderC4DiagramToSVG(source, options.dark);
+        if (errors.length > 0) {
+            failures++;
+            for (const error of errors) {
+                console.error(`${inputPath}:${error.line}:${error.column}: ${error.message}`);
+            }
+            continue;
+        }
+        if (options.check)
+            continue;
+        const outPath = outputPathFor(inputPath, options);
+        try {
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, svg);
+        }
+        catch (err) {
+            failures++;
+            console.error(`${inputPath}: failed to write ${outPath}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        console.log(`${inputPath} -> ${outPath}`);
+    }
+    return failures > 0 ? 2 : 0;
+}
+function main() {
+    const rawArgs = process.argv.slice(2);
+    const options = parseArgs(rawArgs);
+    if (!options) {
+        printUsage();
+        return;
+    }
+    const stdinConflict = validateStdinCombination(options);
+    if (stdinConflict) {
+        console.error(`render-c4: ${stdinConflict}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.files.length === 0 && !options.stdin) {
+        if (rawArgs.length === 0) {
+            printUsage();
+            process.exitCode = 1;
+            return;
+        }
+        // Flags were given (e.g. `--check` over a glob that matched nothing) but no
+        // files resolved — "nothing to do" is success, not a usage error, so a CI
+        // step like `render-c4 --check $(git ls-files '*.puml')` doesn't fail a repo
+        // that has no diagrams yet.
+        console.log('render-c4: no input files');
+        return;
+    }
+    if (options.stdin) {
+        renderStdin(options.dark);
+    }
+    else {
+        process.exitCode = renderFiles(options);
+    }
+}
+// Only run when executed directly (`node render-c4.js`), not when imported —
+// e.g. by the test file below, which exercises `parseArgs`/`outputPathFor` in
+// isolation without wanting a real CLI invocation as a side effect of import.
+const isMain = process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+    main();
+}

package/dist/core/edge-clipping.js

@@ -4,6 +4,7 @@
  * Computes where edge polylines intersect label bounding boxes and splits
  * them into visible segments, creating clean gaps around label text.
  */
+import { svgNumber } from './precision.js';
 // =============================================================================
 // CONSTANTS
 // =============================================================================
@@ -127,12 +128,12 @@ export function buildClippedEdgePaths(points, labelCenter, labelHalfW, labelHalf
     }
     const paths = visibleSegments
         .filter((seg) => seg.length >= 2)
-        .map((seg) => seg.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x} ${p.y}`).join(' '));
+        .map((seg) => seg.map((p, i) => `${i === 0 ? 'M' : 'L'} ${svgNumber(p.x)} ${svgNumber(p.y)}`).join(' '));
     // Fallback: if clipping consumed the entire edge, draw the original path
     // rather than leaving a floating arrowhead with no line
     if (paths.length === 0 && points.length >= 2) {
         return [
-            points.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x} ${p.y}`).join(' '),
+            points.map((p, i) => `${i === 0 ? 'M' : 'L'} ${svgNumber(p.x)} ${svgNumber(p.y)}`).join(' '),
         ];
     }
     return paths;

package/dist/core/layout.js

@@ -6,6 +6,7 @@
  * with proper boundary group padding.
  */
 import dagre from '@dagrejs/dagre';
+import { svgNumber } from './precision.js';
 // =============================================================================
 // CONSTANTS
 // =============================================================================
@@ -800,9 +801,16 @@ export function layoutC4Diagram(diagram, options, manualPositions) {
         ...DEFAULT_OPTIONS,
         ...options,
     };
-    // Use manual layout if positions are provided
+    // Use manual layout if positions are provided. Rounded here rather than
+    // inside that function so the two layout paths cannot diverge on it: this is
+    // the branch the drag renderer takes, and the one `renderC4DiagramToSVG`
+    // takes when given `manualPositions`, so leaving it unrounded would have left
+    // the platform drift in place for exactly the diagrams a user had arranged
+    // by hand.
     if (manualPositions && Object.keys(manualPositions).length > 0) {
-        return layoutWithManualPositions(diagram, mergedOptions, manualPositions);
+        const manual = layoutWithManualPositions(diagram, mergedOptions, manualPositions);
+        roundGeometryInPlace(manual);
+        return manual;
     }
     const topLevelElements = getTopLevelElements(diagram.elements);
     // Layout top-level elements, using diagram direction if specified
@@ -828,7 +836,7 @@ export function layoutC4Diagram(diagram, options, manualPositions) {
     // Add margin
     width += BOUNDARY_PADDING;
     height += BOUNDARY_PADDING;
-    return {
+    const result = {
         nodes: allNodes,
         edges,
         width,
@@ -836,4 +844,45 @@ export function layoutC4Diagram(diagram, options, manualPositions) {
         viewBoxX: 0,
         viewBoxY: 0,
     };
+    roundGeometryInPlace(result);
+    return result;
+}
+/**
+ * Round every coordinate in a finished layout, in place.
+ *
+ * Done once here rather than at each of the ~80 places the renderer writes a
+ * coordinate into an attribute: the layout *is* the geometry, so producing it
+ * to a fixed precision means every consumer — the React renderer, the headless
+ * SVG serialiser, anything a host builds — inherits the same numbers without
+ * having to remember to round.
+ *
+ * In place rather than by copying, because a node appears both in the flat
+ * `nodes` list and in its parent's `children`, and rebuilding those would break
+ * the identity between them. `svgNumber` is idempotent, so visiting a node
+ * twice is harmless.
+ *
+ * See ./precision.ts for why this exists at all — the short version is that
+ * `atan2` is not bit-identical across platforms, and rendered SVGs get
+ * committed and diffed.
+ */
+function roundGeometryInPlace(result) {
+    // `result.nodes` comes from flattenLayoutNodes, so it already contains every
+    // descendant — a node reached through `children` is the same object, and one
+    // pass over the flat list covers the tree.
+    for (const node of result.nodes) {
+        node.x = svgNumber(node.x);
+        node.y = svgNumber(node.y);
+        node.width = svgNumber(node.width);
+        node.height = svgNumber(node.height);
+    }
+    for (const edge of result.edges) {
+        edge.points = edge.points.map((point) => ({
+            x: svgNumber(point.x),
+            y: svgNumber(point.y),
+        }));
+    }
+    result.width = svgNumber(result.width);
+    result.height = svgNumber(result.height);
+    result.viewBoxX = svgNumber(result.viewBoxX);
+    result.viewBoxY = svgNumber(result.viewBoxY);
 }

package/dist/core/precision.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Numeric precision at the boundary where geometry becomes SVG.
+ */
+/** Round for emission into SVG, without leaving `1.500` where `1.5` will do. */
+export declare function svgNumber(value: number): number;

package/dist/core/precision.js

@@ -0,0 +1,30 @@
+/**
+ * Numeric precision at the boundary where geometry becomes SVG.
+ */
+/**
+ * Decimal places kept when a computed number reaches the SVG.
+ *
+ * This is not cosmetic. IEEE 754 does not require `sin`, `cos` or `atan2` to be
+ * correctly rounded, so a platform's libm may return a result one unit in the
+ * last place away from another's. macOS and Linux disagree in exactly that way,
+ * and the disagreement reaches the output: an edge-label rotation came out as
+ * `-9.005931656396022` on one and `-9.005931656396024` on the other. Identical
+ * input, identical library version, different bytes.
+ *
+ * That matters because rendered SVGs get committed and checked for drift in CI.
+ * A check that fails depending on who ran it is worse than no check — it trains
+ * people to ignore it. Rounding at the boundary makes the output a function of
+ * the input alone.
+ *
+ * Three places is far below anything visible: at this diagram's scale a
+ * thousandth of a unit is a thousandth of a pixel, and a thousandth of a degree
+ * moves the end of a 200px label by 0.0035px.
+ */
+const SVG_PRECISION = 3;
+/** Round for emission into SVG, without leaving `1.500` where `1.5` will do. */
+export function svgNumber(value) {
+    const factor = 10 ** SVG_PRECISION;
+    // `+0` rather than the bare result: -0 serialises as "-0", which differs from
+    // "0" bytewise while being the same number.
+    return Math.round(value * factor) / factor + 0;
+}

package/dist/react/renderer.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { buildClippedEdgePaths } from '../core/edge-clipping.js';
+import { svgNumber } from '../core/precision.js';
 // =============================================================================
 // CONSTANTS
 // =============================================================================
@@ -75,7 +76,11 @@ function calculateArrowheadPoints(startPoint, endPoint) {
     const baseX = endPoint.x - ux * ARROW_SIZE;
     const baseY = endPoint.y - uy * ARROW_SIZE;
     const halfW = ARROW_SIZE * 0.5;
-    return `${tipX},${tipY} ${baseX + px * halfW},${baseY + py * halfW} ${baseX - px * halfW},${baseY - py * halfW}`;
+    // Rounded here rather than left raw: these coordinates come out of a sqrt-
+    // normalised direction vector, and the SVG they land in gets committed. See
+    // ../core/precision.
+    const n = svgNumber;
+    return `${n(tipX)},${n(tipY)} ${n(baseX + px * halfW)},${n(baseY + py * halfW)} ${n(baseX - px * halfW)},${n(baseY - py * halfW)}`;
 }
 function shortenEdgeEnd(points) {
     if (points.length < 2)
@@ -400,8 +405,18 @@ function EdgeComponent({ edge, colors }) {
         angleDeg += 180;
     if (Math.abs(angleDeg) > 60)
         angleDeg = 0;
-    const labelX = midpoint.x;
-    const labelY = midpoint.y;
+    // Rounded after the normalisation and the cutoff, so those decisions are made
+    // on the same value as before, and once rather than at each of the two places
+    // the angle is used — the transform attribute and the label-clipping geometry
+    // must agree on one angle. See ../core/precision: atan2 is not bit-identical
+    // across platforms.
+    angleDeg = svgNumber(angleDeg);
+    // Halving a pair of rounded coordinates is exact arithmetic, so this is not a
+    // drift risk — but binary representation still turns 249.7775 into
+    // 249.77749999999997, which then appears three times in the output. Rounded
+    // so the transform and the tspan read as the number they are.
+    const labelX = svgNumber(midpoint.x);
+    const labelY = svgNumber(midpoint.y);
     const labelTransform = `rotate(${angleDeg}, ${labelX}, ${labelY})`;
     // Compute edge paths with label clipping
     let edgePaths;
@@ -426,7 +441,7 @@ function EdgeComponent({ edge, colors }) {
         }
         else if (edge.isStepNumber || edge.isLegendRef) {
             // Circle/square shapes are opaque — no line clipping needed
-            edgePaths = [shortenedPoints.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x} ${p.y}`).join(' ')];
+            edgePaths = [shortenedPoints.map((p, i) => `${i === 0 ? 'M' : 'L'} ${svgNumber(p.x)} ${svgNumber(p.y)}`).join(' ')];
         }
         else {
             // Clip around text label
@@ -457,7 +472,7 @@ function EdgeComponent({ edge, colors }) {
         }
     }
     else {
-        edgePaths = [shortenedPoints.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x} ${p.y}`).join(' ')];
+        edgePaths = [shortenedPoints.map((p, i) => `${i === 0 ? 'M' : 'L'} ${svgNumber(p.x)} ${svgNumber(p.y)}`).join(' ')];
     }
     // Render label content
     let labelContent = null;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@liminis/diagrams",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "C4 architecture diagrams: parse C4-PlantUML, lay out with dagre, render to SVG",
   "license": "MIT",
-  "//repository": "Not cosmetic, and not optional. npm matches this URL against the GitHub Actions OIDC claim when publishing with --provenance; without it the registry rejects the publish outright (E422) after the release tag has already been cut. That is exactly how 0.1.0's first release attempt failed (#6). The `git+https://` scheme and the `.git` suffix are both part of the match — the SSH form does not work.",
+  "//repository": "Not cosmetic, and not optional. npm matches this URL against the GitHub Actions OIDC claim when publishing with --provenance; without it the registry rejects the publish outright (E422) after the release tag has already been cut. That is exactly how 0.1.0's first release attempt failed (#6). The `git+https://` scheme and the `.git` suffix are both part of the match \u2014 the SSH form does not work.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/verveguy/liminis-diagrams.git"
@@ -24,7 +24,7 @@
   ],
   "//publishing": "Carried over from @liminis/editor deliberately. `prepublishOnly` -> scripts/guard-publish.mjs refuses unless LIMINIS_ALLOW_PUBLISH=1, which is set at step scope in the release workflow and nowhere else, so a release is the only path that publishes. A `private: true` flag would not do this job: `npm publish --dry-run` does NOT report a private package as blocked (npm 10.8.2), so the guard has to be a script.",
   "packageManager": "pnpm@10.33.0",
-  "//engines": "A support statement, not a technical floor — @dagrejs/dagre declares no engines at all. It says which runtimes this package is maintained against, matching @liminis/editor.",
+  "//engines": "A support statement, not a technical floor \u2014 @dagrejs/dagre declares no engines at all. It says which runtimes this package is maintained against, matching @liminis/editor.",
   "engines": {
     "node": ">=22"
   },
@@ -32,6 +32,9 @@
   "//entrypoints": "These point at dist/ here, in the checked-in manifest, and must stay that way. @liminis/editor shipped a broken 0.1.0 by putting them under `publishConfig`: manifest-field overrides there are a pnpm/yarn feature, and npm honours `publishConfig` only for values like access/registry/tag, so it published src/ paths while `files` shipped only dist/. See that package's ADR-078.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "render-c4": "./dist/bin/render-c4.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",