@liminis/diagrams 0.1.1 → 0.1.3

package/README.md

@@ -7,13 +7,15 @@ editing.
 Extracted from [`@liminis/editor`](https://github.com/verveguy/liminis-editor), where it
 renders ` ```c4 ` fenced code blocks. Nothing here is bound to that editor.
 
+Documentation: **[v3rv.com/liminis-diagrams](https://v3rv.com/liminis-diagrams/)**.
+
 ## Demo
 
-**[https://v3rv.com/liminis-diagrams/](https://v3rv.com/liminis-diagrams/)** — edit
+**[https://v3rv.com/liminis-diagrams/demo/](https://v3rv.com/liminis-diagrams/demo/)** — edit
 C4-PlantUML source and see it re-render live, drag nodes to reposition them, toggle dark
 mode, and switch between a few preset diagrams. The demo keeps dragged positions in
 memory only, for as long as the tab is open — this package has no persistence of its
-own (see [Recipe 3](docs/recipes.md#recipe-3-position-persistence--the-hosts-choice)),
+own (see [Recipe 3](https://v3rv.com/liminis-diagrams/recipes/#recipe-3-position-persistence--the-hosts-choice)),
 and neither does this demo.
 
 ## Install
@@ -25,12 +27,12 @@ npm install @liminis/diagrams
 `react` and `react-dom` are **optional** peers. Installing the package gets you
 `@dagrejs/dagre` and nothing else, so `@liminis/diagrams/core` works in a CLI or CI job
 with no React on disk. Install the peers if you use `/react` or `/server` — see
-[`docs/architecture.md`](docs/architecture.md) for why the split exists and which entry
+[Architecture](https://v3rv.com/liminis-diagrams/architecture/) for why the split exists and which entry
 point to pick.
 
 ## Not sure this package does what you're assuming?
 
-Read [Limitations](docs/README.md#limitations--read-this-first) before you build
+Read [Limitations](https://v3rv.com/liminis-diagrams/#limitations--read-this-first) before you build
 against this package. In short: no editing UI, no persistence, element IDs aren't
 stable across diagrams, no cross-diagram links.
 
@@ -85,22 +87,35 @@ import { C4InteractiveRenderer } from '@liminis/diagrams/react';
 
 Pass `manualPositions` to `layoutC4Diagram` to bypass dagre for the elements you have
 positions for. Persisting them is entirely your call — see
-[Recipe 3](docs/recipes.md#recipe-3-position-persistence--the-hosts-choice) for a worked
+[Recipe 3](https://v3rv.com/liminis-diagrams/recipes/#recipe-3-position-persistence--the-hosts-choice) for a worked
 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 --package=react --package=react-dom -- 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
+[Rendering diagrams on GitHub](https://v3rv.com/liminis-diagrams/github-integration/) for the CI recipe, and
+[Rendering diagrams in Claude Code](https://v3rv.com/liminis-diagrams/claude-code-integration/) for getting Claude
+to render real diagrams instead of hand-drawing them.
+
 ## Supported syntax
 
 `Person`, `System`, `Container`, `Component` and their `_Ext` / `Db` / `Queue` variants,
 plus `Deployment_Node`, `Node`, and `InfrastructureNode` variants; boundary macros;
 `Rel` (with directional variants) and `BiRel`. See
-[`docs/dsl-reference.md`](docs/dsl-reference.md) for the full macro table and exactly
+[the C4-PlantUML reference](https://v3rv.com/liminis-diagrams/dsl-reference/) for the full macro table and exactly
 which directives (`@startuml`, `!include`, `SHOW_LEGEND()`, `LAYOUT_*`, …) are applied
 versus silently stripped.
 
 ## Documentation
 
-Building a tool on top of this package? [`docs/`](docs/README.md) covers the
+Building a tool on top of this package? [the documentation site](https://v3rv.com/liminis-diagrams/) covers the
 entry-point boundary, the full DSL reference, the data model, and runnable recipes for
 headless rendering, embedding the interactive renderer, and position persistence.
 
@@ -109,7 +124,7 @@ headless rendering, embedding the interactive renderer, and position persistence
 The commit history predates this repository: it was recovered from
 `verveguy/liminis` (`liminis-app/src/editor/app/editor/c4/`, later
 `packages/editor/src/app/editor/c4/`) and carries development from 2026-03-18 onward.
-`git log --follow` works across the move. See `docs/EXTRACTION-PLAN.md`.
+`git log --follow` works across the move.
 
 ## License
 

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

@@ -0,0 +1,49 @@
+#!/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 https://v3rv.com/liminis-diagrams/github-integration/ 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[];
+    /** Extract ```c4 fences from markdown inputs instead of treating the whole file as source. */
+    fromMarkdown: boolean;
+    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;
+/**
+ * ```c4 fences in a markdown file, with the 1-based line the fence body starts on
+ * so errors point at the real location in the file rather than at the snippet.
+ *
+ * Diagrams live in fenced blocks far more often than in standalone .puml files —
+ * that is how @liminis/editor stores them, how this package's own docs are
+ * written, and what a markdown-based diagram wiki produces. A renderer that only
+ * understood whole files would not fit the common case.
+ *
+ * A fence tagged `invalid` is skipped: a page documenting parse errors needs
+ * source that does not parse, and that is content rather than a defect.
+ */
+export declare function extractC4Fences(markdown: string): {
+    source: string;
+    line: number;
+    index: number;
+}[];
+export declare function renderFiles(options: Options): number;

package/dist/bin/render-c4.js

@@ -0,0 +1,256 @@
+#!/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 https://v3rv.com/liminis-diagrams/github-integration/ 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:
+  --from-markdown    Read fenced c4 blocks out of markdown inputs rather than
+                     treating each whole file as diagram source
+  --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: [], fromMarkdown: false, 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 '--from-markdown':
+                options.fromMarkdown = 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;
+}
+/**
+ * ```c4 fences in a markdown file, with the 1-based line the fence body starts on
+ * so errors point at the real location in the file rather than at the snippet.
+ *
+ * Diagrams live in fenced blocks far more often than in standalone .puml files —
+ * that is how @liminis/editor stores them, how this package's own docs are
+ * written, and what a markdown-based diagram wiki produces. A renderer that only
+ * understood whole files would not fit the common case.
+ *
+ * A fence tagged `invalid` is skipped: a page documenting parse errors needs
+ * source that does not parse, and that is content rather than a defect.
+ */
+export function extractC4Fences(markdown) {
+    const out = [];
+    const fence = /^```c4([^\n]*)\n([\s\S]*?)\n```$/gm;
+    let index = 0;
+    for (const match of markdown.matchAll(fence)) {
+        if (/\binvalid\b/.test(match[1] ?? ''))
+            continue;
+        index++;
+        const before = markdown.slice(0, match.index ?? 0);
+        out.push({
+            source: match[2],
+            line: before.split('\n').length + 1,
+            index,
+        });
+    }
+    return out;
+}
+function renderMarkdownFences(options) {
+    let failures = 0;
+    for (const inputPath of options.files) {
+        let markdown;
+        try {
+            markdown = readFileSync(inputPath, 'utf-8');
+        }
+        catch (err) {
+            failures++;
+            console.error(`${inputPath}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const fences = extractC4Fences(markdown);
+        if (fences.length === 0)
+            continue;
+        for (const fence of fences) {
+            const { svg, errors } = renderC4DiagramToSVG(fence.source, options.dark);
+            if (errors.length > 0) {
+                failures++;
+                for (const error of errors) {
+                    // Offset into the containing file, so the message is navigable.
+                    console.error(`${inputPath}:${fence.line + error.line - 1}:${error.column}: ${error.message}`);
+                }
+                continue;
+            }
+            if (options.check)
+                continue;
+            const base = basename(inputPath, extname(inputPath));
+            const svgName = `${base}-${fence.index}.svg`;
+            const outPath = options.outDir
+                ? join(options.outDir, svgName)
+                : join(dirname(inputPath), svgName);
+            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} [${fence.index}] -> ${outPath}`);
+        }
+    }
+    return failures > 0 ? 2 : 0;
+}
+export function renderFiles(options) {
+    if (options.fromMarkdown)
+        return renderMarkdownFences(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
 // =============================================================================
@@ -756,29 +757,63 @@ function layoutWithManualPositions(diagram, options, manualPositions) {
     }
     // Calculate edges using existing function
     const edges = calculateEdges(diagram.relationships, nodeMap);
-    // Calculate diagram bounding box (nodes may have negative coordinates
-    // when dragged past the top/left edge)
+    return { nodes: allNodes, edges, ...boundsFor(allNodes, edges) };
+}
+/**
+ * The viewBox and dimensions that actually contain the laid-out diagram.
+ *
+ * Shared by both layout paths, because they were only ever different by
+ * accident. The manual path always computed a real bounding box — dragging a
+ * node above or left of the origin produces negative coordinates, and the
+ * viewBox origin moves to cover them rather than shifting every node, which
+ * would desynchronise rendered positions from the positions a host persists.
+ *
+ * The auto path hardcoded `viewBoxX: 0, viewBoxY: 0` on the premise that dagre
+ * never emits negative coordinates. That premise was wrong, and documented as
+ * fact in data-model.md. Dagre's own output is non-negative, but the
+ * cross-boundary alignment pass that runs after it shifts elements outside a
+ * boundary to line up with their targets inside it, and that can move them left
+ * of the origin. The result was a `viewBox` starting at 0 with content at
+ * negative x: clipped, and unreachable by scrolling, because a viewBox is a
+ * window rather than a canvas. Four lines of C4 reproduce it — a Person outside
+ * a System_Boundary with a Rel to something inside.
+ *
+ * Edge points are included as well as node rects: an edge routed around a
+ * boundary can leave the union of the node rectangles.
+ *
+ * Diagrams that were already correct are unaffected. Where nothing sits within
+ * BOUNDARY_PADDING of the origin, `Math.min(0, …)` yields 0 and the width and
+ * height are what they were.
+ */
+function boundsFor(nodes, edges) {
     let minX = Infinity;
     let minY = Infinity;
     let maxX = 0;
     let maxY = 0;
-    for (const node of allNodes) {
+    for (const node of nodes) {
         minX = Math.min(minX, node.x);
         minY = Math.min(minY, node.y);
         maxX = Math.max(maxX, node.x + node.width);
         maxY = Math.max(maxY, node.y + node.height);
     }
-    // Use viewBox origin to handle negative coordinates instead of shifting
-    // nodes — this keeps stored positions and rendered positions in sync
+    for (const edge of edges) {
+        for (const point of edge.points) {
+            minX = Math.min(minX, point.x);
+            minY = Math.min(minY, point.y);
+            maxX = Math.max(maxX, point.x);
+            maxY = Math.max(maxY, point.y);
+        }
+    }
+    // An empty diagram leaves the minima at Infinity; treat it as the origin.
+    if (!Number.isFinite(minX))
+        minX = 0;
+    if (!Number.isFinite(minY))
+        minY = 0;
     const viewBoxX = Math.min(0, minX - BOUNDARY_PADDING);
     const viewBoxY = Math.min(0, minY - BOUNDARY_PADDING);
-    const width = maxX + BOUNDARY_PADDING - viewBoxX;
-    const height = maxY + BOUNDARY_PADDING - viewBoxY;
     return {
-        nodes: allNodes,
-        edges,
-        width,
-        height,
+        width: maxX + BOUNDARY_PADDING - viewBoxX,
+        height: maxY + BOUNDARY_PADDING - viewBoxY,
         viewBoxX,
         viewBoxY,
     };
@@ -800,9 +835,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
@@ -818,22 +860,46 @@ export function layoutC4Diagram(diagram, options, manualPositions) {
     alignCrossBoundaryElements(layoutNodes, diagram.relationships, nodeMap);
     // Calculate edges
     const edges = calculateEdges(diagram.relationships, nodeMap);
-    // Calculate total diagram dimensions
-    let width = 0;
-    let height = 0;
-    for (const node of allNodes) {
-        width = Math.max(width, node.x + node.width);
-        height = Math.max(height, node.y + node.height);
-    }
-    // Add margin
-    width += BOUNDARY_PADDING;
-    height += BOUNDARY_PADDING;
-    return {
-        nodes: allNodes,
-        edges,
-        width,
-        height,
-        viewBoxX: 0,
-        viewBoxY: 0,
-    };
+    const result = { nodes: allNodes, edges, ...boundsFor(allNodes, edges) };
+    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/C4InteractiveRenderer.d.ts

@@ -25,6 +25,29 @@ export interface C4InteractiveRendererProps {
         x: number;
         y: number;
     }>) => void;
+    /**
+     * Scale factor for the rendered diagram. 1 is actual size; 2 draws it twice as
+     * large. Defaults to 1, so a host that does not care is unaffected.
+     *
+     * This scales the SVG's rendered `width`/`height` and leaves the `viewBox`
+     * alone, rather than applying a CSS transform. Three things follow, and they
+     * are the reason for doing it this way:
+     *
+     *   - Dragging keeps working untouched. Screen coordinates are mapped through
+     *     `getScreenCTM().inverse()`, and that matrix already carries the ratio
+     *     between the viewBox and the rendered size — so a node still lands under
+     *     the pointer at any zoom, with no arithmetic anywhere in the drag code.
+     *   - The diagram genuinely occupies more space, so a scrolling container
+     *     scrolls it. A CSS `transform` is painted after layout: the element still
+     *     reports its unscaled size, and the overflow it appears to produce cannot
+     *     be scrolled to.
+     *   - Text stays sharp. It is re-rendered at the new scale rather than being a
+     *     bitmap stretched over it.
+     *
+     * Controls are deliberately not included. What a zoom control should look like
+     * is the host's business — this package renders diagrams.
+     */
+    zoom?: number;
 }
 /**
  * Interactive C4 diagram renderer with drag support.
@@ -32,5 +55,5 @@ export interface C4InteractiveRendererProps {
  * When isEditMode is true, nodes can be dragged to new positions.
  * Edges and boundaries are recalculated in real-time during drag.
  */
-export declare function C4InteractiveRenderer({ diagram, isDarkMode, isEditMode, manualPositions, onPositionChange, }: C4InteractiveRendererProps): JSX.Element;
+export declare function C4InteractiveRenderer({ diagram, isDarkMode, isEditMode, manualPositions, onPositionChange, zoom, }: C4InteractiveRendererProps): JSX.Element;
 export default C4InteractiveRenderer;

package/dist/react/C4InteractiveRenderer.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { C4RendererContent, computeLegendInfo } from './renderer.js';
+import { C4RendererContent, computeLegendInfo, normaliseZoom } from './renderer.js';
 import { layoutC4Diagram } from '../core/layout.js';
 import { useC4DiagramDrag } from './hooks/useC4DiagramDrag.js';
 /** Synthetic ID used to store legend position in manual positions map */
@@ -51,7 +51,7 @@ function collectDescendantIds(elements) {
  * When isEditMode is true, nodes can be dragged to new positions.
  * Edges and boundaries are recalculated in real-time during drag.
  */
-export function C4InteractiveRenderer({ diagram, isDarkMode, isEditMode, manualPositions, onPositionChange, }) {
+export function C4InteractiveRenderer({ diagram, isDarkMode, isEditMode, manualPositions, onPositionChange, zoom = 1, }) {
     const svgRef = useRef(null);
     // Local positions during drag (merged with persisted positions)
     const [dragPositions, setDragPositions] = useState({});
@@ -222,12 +222,15 @@ export function C4InteractiveRenderer({ diagram, isDarkMode, isEditMode, manualP
         return pos ?? null;
     }, [effectivePositions]);
     // Render with interactive wrappers
-    return (_jsx(C4InteractiveSvg, { layout: layout, isDarkMode: isDarkMode, isEditMode: isEditMode, draggedNodeId: draggedNodeId, svgRef: svgRef, onNodeMouseDown: startNodeDrag, legendInfo: legendInfo, legendPositionOverride: legendPositionOverride }));
+    return (_jsx(C4InteractiveSvg, { layout: layout, isDarkMode: isDarkMode, isEditMode: isEditMode, draggedNodeId: draggedNodeId, svgRef: svgRef, onNodeMouseDown: startNodeDrag, legendInfo: legendInfo, legendPositionOverride: legendPositionOverride, zoom: zoom }));
 }
 /**
  * SVG wrapper that adds interactive overlays for drag handling.
  */
-function C4InteractiveSvg({ layout, isDarkMode, isEditMode, draggedNodeId, svgRef, onNodeMouseDown, legendInfo, legendPositionOverride, }) {
+function C4InteractiveSvg({ layout, isDarkMode, isEditMode, draggedNodeId, svgRef, onNodeMouseDown, legendInfo, legendPositionOverride, zoom, }) {
+    // Guarded here as well as in C4Renderer: both are public entry points, and a
+    // host reaching this one never passes through the other.
+    const scale = normaliseZoom(zoom);
     // Get colors based on theme
     const handleColor = isDarkMode ? '#a0a0a0' : '#505050';
     // Create hit areas for each node (and legend if present)
@@ -276,7 +279,7 @@ function C4InteractiveSvg({ layout, isDarkMode, isEditMode, draggedNodeId, svgRe
         }
         return { svgWidth: w, svgHeight: h };
     }, [layout.width, layout.height, layout.viewBoxX, layout.viewBoxY, legendInfo, legendPositionOverride]);
-    return (_jsx("div", { style: { position: 'relative' }, children: _jsxs("svg", { ref: svgRef, width: svgWidth, height: svgHeight, viewBox: `${layout.viewBoxX} ${layout.viewBoxY} ${svgWidth} ${svgHeight}`, xmlns: "http://www.w3.org/2000/svg", "data-diagram": "c4", style: {
+    return (_jsx("div", { style: { position: 'relative' }, children: _jsxs("svg", { ref: svgRef, width: svgWidth * scale, height: svgHeight * scale, viewBox: `${layout.viewBoxX} ${layout.viewBoxY} ${svgWidth} ${svgHeight}`, xmlns: "http://www.w3.org/2000/svg", "data-diagram": "c4", style: {
                 fontFamily: 'system-ui, -apple-system, sans-serif',
                 cursor: isEditMode ? (draggedNodeId ? 'grabbing' : 'default') : 'default',
             }, children: [_jsx(C4RendererContent, { layout: layout, isDarkMode: isDarkMode, legendPositionOverride: legendPositionOverride }), isEditMode && (_jsx("g", { className: "interactive-layer", children: hitAreas.map((area) => (_jsx("rect", { "data-node-id": area.id, x: area.x, y: area.y, width: area.width, height: area.height, fill: "transparent", stroke: "transparent", style: {

package/dist/react/renderer.d.ts

@@ -27,11 +27,33 @@ export declare function computeLegendInfo(layout: LayoutResult): {
     width: number;
     height: number;
 } | null;
+/**
+ * A zoom factor that cannot produce an invalid SVG.
+ *
+ * `width`/`height` are attributes on a public entry point, so whatever a host
+ * passes ends up in the DOM. `0` collapses the diagram, a negative number is
+ * invalid, and `NaN` — the likely one, arriving from an uninitialised state
+ * variable or a division — renders nothing at all with no error to explain it.
+ * Anything that is not a positive finite number falls back to actual size.
+ *
+ * The upper bound is a guard against a browser being asked to lay out a
+ * hundred-thousand-pixel SVG, not a considered maximum; the lower bound is the
+ * point past which a diagram is a smudge. A host wanting more can scale the
+ * container.
+ */
+export declare function normaliseZoom(zoom: number): number;
 export interface C4RendererProps {
     /** Layout result from the layout engine */
     layout: LayoutResult;
     /** Whether dark mode is enabled */
     isDarkMode: boolean;
+    /**
+     * Scale factor for the rendered diagram. 1 is actual size. Scales the SVG's
+     * width/height and leaves the viewBox alone, so text is re-rendered at the new
+     * scale rather than stretched, and a scrolling container can actually scroll
+     * the result. Defaults to 1.
+     */
+    zoom?: number;
 }
 /**
  * C4 Diagram SVG Renderer.
@@ -39,7 +61,7 @@ export interface C4RendererProps {
  * Pure component: takes layout + theme, returns SVG.
  * Used directly in the editor and via renderToStaticMarkup for publishing.
  */
-export declare function C4Renderer({ layout, isDarkMode }: C4RendererProps): JSX.Element;
+export declare function C4Renderer({ layout, isDarkMode, zoom }: C4RendererProps): JSX.Element;
 /**
  * Renders C4 diagram content (nodes, edges, legend) as SVG group elements.
  * Exported for use by C4InteractiveRenderer to embed diagram content

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;
@@ -508,13 +523,36 @@ function renderNode(node, colors, allNodes, parentMap) {
             return _jsx(Container, { node: node, colors: colors, allNodes: allNodes, parentMap: parentMap }, node.id);
     }
 }
+// =============================================================================
+// MAIN COMPONENT
+// =============================================================================
+/**
+ * A zoom factor that cannot produce an invalid SVG.
+ *
+ * `width`/`height` are attributes on a public entry point, so whatever a host
+ * passes ends up in the DOM. `0` collapses the diagram, a negative number is
+ * invalid, and `NaN` — the likely one, arriving from an uninitialised state
+ * variable or a division — renders nothing at all with no error to explain it.
+ * Anything that is not a positive finite number falls back to actual size.
+ *
+ * The upper bound is a guard against a browser being asked to lay out a
+ * hundred-thousand-pixel SVG, not a considered maximum; the lower bound is the
+ * point past which a diagram is a smudge. A host wanting more can scale the
+ * container.
+ */
+export function normaliseZoom(zoom) {
+    if (!Number.isFinite(zoom) || zoom <= 0)
+        return 1;
+    return Math.min(Math.max(zoom, 0.05), 50);
+}
 /**
  * C4 Diagram SVG Renderer.
  *
  * Pure component: takes layout + theme, returns SVG.
  * Used directly in the editor and via renderToStaticMarkup for publishing.
  */
-export function C4Renderer({ layout, isDarkMode }) {
+export function C4Renderer({ layout, isDarkMode, zoom = 1 }) {
+    const scale = normaliseZoom(zoom);
     const colors = getColors(isDarkMode);
     const boundaryNodes = layout.nodes.filter((n) => n.element.type === 'system' &&
         ((n.children?.length ?? 0) > 0 || n.element.properties.style === 'boundary'));
@@ -531,7 +569,7 @@ export function C4Renderer({ layout, isDarkMode }) {
         totalWidth = lp.totalWidth;
         totalHeight = lp.totalHeight;
     }
-    return (_jsxs("svg", { width: totalWidth, height: totalHeight, viewBox: `${layout.viewBoxX} ${layout.viewBoxY} ${totalWidth} ${totalHeight}`, xmlns: "http://www.w3.org/2000/svg", "data-diagram": "c4", style: { fontFamily: 'system-ui, -apple-system, sans-serif' }, children: [_jsx("g", { className: "boundaries-layer", children: boundaryNodes.map((node) => renderNode(node, colors, layout.nodes, parentMap)) }), _jsx("g", { className: "nodes-layer", children: regularNodes.map((node) => renderNode(node, colors, layout.nodes, parentMap)) }), _jsx("g", { className: "edges-layer", children: processedEdges.map((edge, i) => (_jsx(EdgeComponent, { edge: edge, colors: colors }, `${edge.source}-${edge.target}-${i}`))) }), legendPlacement && legendEntries.length > 0 && (_jsx(Legend, { entries: legendEntries, placement: legendPlacement, colors: colors }))] }));
+    return (_jsxs("svg", { width: totalWidth * scale, height: totalHeight * scale, viewBox: `${layout.viewBoxX} ${layout.viewBoxY} ${totalWidth} ${totalHeight}`, xmlns: "http://www.w3.org/2000/svg", "data-diagram": "c4", style: { fontFamily: 'system-ui, -apple-system, sans-serif' }, children: [_jsx("g", { className: "boundaries-layer", children: boundaryNodes.map((node) => renderNode(node, colors, layout.nodes, parentMap)) }), _jsx("g", { className: "nodes-layer", children: regularNodes.map((node) => renderNode(node, colors, layout.nodes, parentMap)) }), _jsx("g", { className: "edges-layer", children: processedEdges.map((edge, i) => (_jsx(EdgeComponent, { edge: edge, colors: colors }, `${edge.source}-${edge.target}-${i}`))) }), legendPlacement && legendEntries.length > 0 && (_jsx(Legend, { entries: legendEntries, placement: legendPlacement, colors: colors }))] }));
 }
 export function C4RendererContent({ layout, isDarkMode, legendPositionOverride }) {
     const colors = getColors(isDarkMode);

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@liminis/diagrams",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",