@liminis/diagrams 0.1.2 → 0.1.4

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,21 +87,21 @@ 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 -- render-c4 diagram.puml
+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
-[`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
+[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
@@ -107,13 +109,13 @@ to render real diagrams instead of hand-drawing them.
 `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.
 
@@ -122,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

@@ -6,7 +6,7 @@
  * 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.
+ * 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,
@@ -14,6 +14,8 @@
  */
 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;
@@ -27,4 +29,21 @@ export declare function outputPathFor(inputPath: string, options: Options): stri
  * (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

@@ -6,7 +6,7 @@
  * 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.
+ * 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,
@@ -22,6 +22,8 @@ function printUsage() {
 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)
@@ -31,7 +33,7 @@ Options:
 `);
 }
 export function parseArgs(argv) {
-    const options = { files: [], dark: false, check: false, stdin: false };
+    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) {
@@ -41,6 +43,9 @@ export function parseArgs(argv) {
             case '--dark':
                 options.dark = true;
                 break;
+            case '--from-markdown':
+                options.fromMarkdown = true;
+                break;
             case '--check':
                 options.check = true;
                 break;
@@ -92,7 +97,84 @@ export function validateStdinCombination(options) {
     }
     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;

package/dist/core/layout.js

@@ -757,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,
     };
@@ -826,24 +860,7 @@ 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;
-    const result = {
-        nodes: allNodes,
-        edges,
-        width,
-        height,
-        viewBoxX: 0,
-        viewBoxY: 0,
-    };
+    const result = { nodes: allNodes, edges, ...boundsFor(allNodes, edges) };
     roundGeometryInPlace(result);
     return result;
 }

package/dist/playground/C4Playground.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A ready-made C4 playground: source on one side, a live diagram on the other.
+ *
+ * The editing shell this package's own documentation uses, and the one every
+ * Liminis documentation site used to keep its own copy of. Five identical
+ * copies drifted apart the moment the renderer gained a feature — zoom shipped
+ * in 0.1.3 and four of the five sites had no way to reach it — which is what
+ * moved it in here.
+ *
+ * Styling comes from `@liminis/diagrams/playground.css`, which must be imported
+ * separately. It ships working defaults and reads a handful of `--c4-*` custom
+ * properties, so a host can make it look native in a few lines rather than
+ * overriding rules.
+ *
+ * Mount it client-side only. The drag layer measures the live SVG through
+ * `getScreenCTM`, which does not exist during a server render — under Astro
+ * that means `client:only="react"` rather than `client:visible`.
+ */
+export interface C4PlaygroundProps {
+    /** Initial C4-PlantUML source. */
+    source: string;
+    /**
+     * Whether the reader may drag nodes. `false` is a fixed illustration: drag is
+     * off and there is no control to turn it on. Anything else starts with drag
+     * enabled and offers the toggle.
+     */
+    editable?: boolean;
+    /** Hide the source pane — for diagrams that illustrate rather than invite editing. */
+    readOnly?: boolean;
+    /** Height of the diagram pane when inline, in CSS units. */
+    height?: string;
+    /**
+     * Whether to draw in dark mode.
+     *
+     * A prop rather than something detected here, for the same reason
+     * `C4InteractiveRenderer` takes one: this package has no idea how its host
+     * decides what "dark" means. A host following the `data-theme` convention can
+     * use the `useIsDarkMode` hook exported alongside this component and pass the
+     * result straight in; a host with its own theming passes its own answer.
+     */
+    isDarkMode?: boolean;
+}
+export default function C4Playground({ source, editable, readOnly, height, isDarkMode, }: C4PlaygroundProps): import("react").JSX.Element;

package/dist/playground/C4Playground.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { parseC4, validateC4 } from '../core/parser.js';
+import { C4InteractiveRenderer } from '../react/C4InteractiveRenderer.js';
+import { C4ErrorDisplay } from '../react/renderer.js';
+/**
+ * Zoom steps, rather than a continuous factor.
+ *
+ * A diagram is not a photograph: there is a size at which its labels are legible
+ * and sizes either side of it that are not, so the useful range is small and
+ * discrete. Steps also keep the control to two buttons and a readout, which is
+ * the entire UI anyone needs here.
+ */
+/**
+ * Zoom steps, as multiples of the fitted size.
+ *
+ * 100% is the view that shows the whole diagram, not 1 SVG unit per pixel.
+ * That is the size the reader arrives at, so it is the one the number should
+ * describe — and it keeps the readout still when the lightbox opens, where the
+ * diagram is drawn larger but is still, conceptually, the same whole-diagram
+ * view. Reporting absolute scale made expanding look like a zoom: 57% became
+ * 100% while nothing about what you could see had changed.
+ *
+ * The range starts at fit because there is nothing below it worth seeing. Once
+ * the whole diagram is visible, smaller only buys whitespace.
+ */
+const ZOOM_STEPS = [1, 1.5, 2, 3, 4];
+/**
+ * The scale at which the whole diagram is visible in the pane it is given.
+ *
+ * Never above 1. A diagram larger than its pane should shrink to fit, but a
+ * small one blown up to fill a lightbox is a surprise: nothing was gained and
+ * the reader now has to work out what the size means. Fitting is about seeing
+ * all of it, not about filling space.
+ *
+ * Returns null when there is nothing to measure yet — before hydration, or if
+ * the pane has no size because it is display:none.
+ */
+function fitScale(canvas) {
+    const svg = canvas?.querySelector('svg');
+    if (!canvas || !svg)
+        return null;
+    const { width: diagramWidth, height: diagramHeight } = svg.viewBox.baseVal;
+    if (!diagramWidth || !diagramHeight)
+        return null;
+    // The pane's usable space, less its own padding — measuring the border box
+    // would overshoot by the padding and clip what fitting is meant to reveal.
+    const style = getComputedStyle(canvas);
+    // `|| 0` on each: a computed padding is always a px string in a browser, but
+    // it can be empty where no stylesheet has been applied, and `parseFloat('')`
+    // is NaN. One NaN makes the whole fit NaN, which reads as "no fitting at all"
+    // rather than as an error — the diagram silently opens at actual size.
+    const px = (value) => parseFloat(value) || 0;
+    const available = {
+        width: canvas.clientWidth - px(style.paddingLeft) - px(style.paddingRight),
+        height: canvas.clientHeight - px(style.paddingTop) - px(style.paddingBottom),
+    };
+    if (!(available.width > 0) || !(available.height > 0))
+        return null;
+    return Math.min(1, available.width / diagramWidth, available.height / diagramHeight);
+}
+export default function C4Playground({ source, editable = true, readOnly = false, height = '22rem', isDarkMode = false, }) {
+    const [text, setText] = useState(source.trim());
+    const [positions, setPositions] = useState({});
+    const [isEditMode, setIsEditMode] = useState(editable);
+    const [isExpanded, setIsExpanded] = useState(false);
+    // Zoom as a multiple of the fitted size: 1 is "the whole diagram", which is
+    // where every view starts. The absolute scale handed to the renderer is this
+    // times whatever fitting currently works out to.
+    const [relativeZoom, setRelativeZoom] = useState(1);
+    const [fittedZoom, setFittedZoom] = useState(1);
+    const canvasRef = useRef(null);
+    const panelRef = useRef(null);
+    const returnFocusTo = useRef(null);
+    // Escape closes; the page behind must not scroll while the lightbox is open.
+    //
+    // Expanding is a CSS overlay rather than the Fullscreen API on purpose: iOS
+    // Safari implements `requestFullscreen` for video only, so the API is a no-op
+    // on an iPad — a device this package's touch support exists for.
+    useEffect(() => {
+        if (!isExpanded)
+            return;
+        // Where focus came from, so closing puts it back rather than dumping the
+        // reader at the top of the document.
+        returnFocusTo.current = document.activeElement;
+        const panel = panelRef.current;
+        const focusable = () => Array.from(panel?.querySelectorAll('button, [href], input, textarea, select, [tabindex]:not([tabindex="-1"])') ?? []).filter((el) => !el.hasAttribute('disabled'));
+        focusable()[0]?.focus();
+        // `aria-modal` promises the rest of the page is unreachable, and a promise
+        // the markup does not keep is worse than not making it: a keyboard user
+        // tabs into content hidden behind the backdrop with no way to tell where
+        // they are. Tab is cycled within the panel to make it true.
+        const onKey = (e) => {
+            if (e.key === 'Escape') {
+                setIsExpanded(false);
+                return;
+            }
+            if (e.key !== 'Tab')
+                return;
+            const items = focusable();
+            if (items.length === 0)
+                return;
+            const first = items[0];
+            const last = items[items.length - 1];
+            // Focus can be outside the panel entirely — the browser's own UI hands it
+            // back to the document, an extension moves it. Both directions have to
+            // catch that case, or Tab walks into the page behind the backdrop, which
+            // is exactly what aria-modal promises cannot happen.
+            const active = document.activeElement;
+            const escaped = !panel?.contains(active);
+            if (e.shiftKey && (escaped || active === first)) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && (escaped || active === last)) {
+                e.preventDefault();
+                first.focus();
+            }
+        };
+        window.addEventListener('keydown', onKey);
+        const previous = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+        return () => {
+            window.removeEventListener('keydown', onKey);
+            document.body.style.overflow = previous;
+            // Guarded: the element may have been unmounted while the panel was open.
+            const target = returnFocusTo.current;
+            if (target instanceof HTMLElement && target.isConnected)
+                target.focus();
+        };
+    }, [isExpanded]);
+    // Parse on every keystroke. The parser is pure and fast enough that
+    // debouncing would add latency without buying anything.
+    const parsed = useMemo(() => {
+        const result = parseC4(text);
+        if (result.diagram)
+            result.errors.push(...validateC4(result.diagram));
+        return result;
+    }, [text]);
+    // What the renderer is actually given. Fitting produces an arbitrary scale —
+    // 0.57 on this site's architecture page — and the reader's multiple applies
+    // on top of it.
+    const zoom = fittedZoom * relativeZoom;
+    const stepZoom = useCallback((direction) => {
+        setRelativeZoom((current) => {
+            const next = direction === 1
+                ? ZOOM_STEPS.find((step) => step > current + 0.001)
+                : [...ZOOM_STEPS].reverse().find((step) => step < current - 0.001);
+            return next ?? current;
+        });
+    }, []);
+    // Declared before the effect below, which depends on it: the source pane's
+    // presence changes how much width the diagram has to fit into.
+    const showSource = !readOnly;
+    // Measure after layout rather than after paint, so the diagram is never shown
+    // at the wrong size for a frame and then corrected — which reads as a flinch.
+    useLayoutEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        const measure = () => {
+            const fit = fitScale(canvas);
+            if (fit !== null)
+                setFittedZoom(fit);
+        };
+        measure();
+        // The pane resizes when the window does, when the lightbox opens, and when
+        // the source pane is shown or hidden. Observing it covers all three without
+        // enumerating them.
+        const observer = new ResizeObserver(measure);
+        observer.observe(canvas);
+        return () => observer.disconnect();
+        // `text` is a dependency because editing the source changes the diagram's
+        // dimensions, and `isExpanded` because the pane it has to fit changes.
+    }, [text, isExpanded, showSource]);
+    // Expanding is a request to see the whole diagram, so it returns to fitting
+    // even if the reader had zoomed in beforehand. Collapsing does the same, since
+    // the inline pane is a different size again.
+    useEffect(() => {
+        setRelativeZoom(1);
+    }, [isExpanded]);
+    const positionCount = Object.keys(positions).length;
+    const panel = (_jsxs("div", { ref: panelRef, className: 'c4-playground not-content' +
+            (isExpanded ? ' c4-playground--expanded' : '') +
+            (showSource ? '' : ' c4-playground--diagram-only'), role: isExpanded ? 'dialog' : undefined, "aria-modal": isExpanded || undefined, "aria-label": isExpanded ? 'C4 diagram, expanded' : undefined, children: [_jsxs("div", { className: "c4-playground__bar", children: [editable && (_jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: isEditMode, onChange: (e) => setIsEditMode(e.target.checked) }), ' ', "Drag to reposition"] })), editable && (_jsx("button", { type: "button", onClick: () => setPositions({}), disabled: positionCount === 0, children: "Reset layout" })), _jsx("span", { className: "c4-playground__hint", children: !editable
+                            ? 'laid out by dagre'
+                            : positionCount > 0
+                                ? `${positionCount} positions held in memory`
+                                : 'laid out by dagre' }), _jsxs("div", { className: "c4-playground__zoom", children: [_jsx("button", { type: "button", onClick: () => stepZoom(-1), disabled: relativeZoom <= ZOOM_STEPS[0] + 0.001, "aria-label": "Zoom out", title: "Zoom out", children: "\u2212" }), _jsxs("button", { type: "button", onClick: () => setRelativeZoom(1), disabled: relativeZoom === 1, "aria-label": "Zoom to fit", title: "Zoom to fit", children: [Math.round(relativeZoom * 100), "%"] }), _jsx("button", { type: "button", onClick: () => stepZoom(1), disabled: relativeZoom >= ZOOM_STEPS[ZOOM_STEPS.length - 1] - 0.001, "aria-label": "Zoom in", title: "Zoom in", children: "+" })] }), _jsx("button", { type: "button", className: "c4-playground__expand", onClick: () => setIsExpanded((v) => !v), "aria-pressed": isExpanded, "aria-label": isExpanded ? 'Close expanded diagram' : 'Expand diagram', title: isExpanded ? 'Close (Esc)' : 'Expand', children: isExpanded ? '✕' : '⤡' })] }), _jsxs("div", { className: "c4-playground__panes", style: { minHeight: isExpanded ? undefined : height }, children: [showSource && (_jsx("textarea", { className: "c4-playground__source", value: text, spellCheck: false, onChange: (e) => setText(e.target.value), "aria-label": "C4-PlantUML source" })), _jsx("div", { className: "c4-playground__canvas", ref: canvasRef, children: parsed.diagram && parsed.errors.length === 0 ? (_jsx(C4InteractiveRenderer, { diagram: parsed.diagram, isDarkMode: isDarkMode, isEditMode: editable && isEditMode, manualPositions: positions, onPositionChange: setPositions, zoom: zoom })) : (_jsx(C4ErrorDisplay, { errors: parsed.errors, isDarkMode: isDarkMode })) })] })] }));
+    if (!isExpanded)
+        return panel;
+    // Portalled to <body> rather than rendered in place. `position: fixed` resolves
+    // against the nearest ancestor with a transform, filter or containment rather
+    // than the viewport, and z-index is confined to that ancestor's stacking
+    // context — which is why the first attempt sat *under* Starlight's header and
+    // table of contents no matter how high its z-index went. Escaping the content
+    // tree is the fix; raising the number is not.
+    //
+    // The backdrop is a real element rather than a pseudo-element so clicking
+    // outside closes. The panel is its sibling, not its child, so a click inside
+    // the panel never reaches the backdrop's handler.
+    return createPortal(_jsxs("div", { className: "c4-playground__lightbox", children: [_jsx("div", { className: "c4-playground__backdrop", onClick: () => setIsExpanded(false), "aria-hidden": "true" }), panel] }), document.body);
+}

package/dist/playground/playground.css

@@ -0,0 +1,166 @@
+/* Styles for C4Playground (@liminis/diagrams/playground).
+ *
+ * Import once, anywhere in your app:
+ *
+ *     import '@liminis/diagrams/playground.css'
+ *
+ * Every colour, font and size below resolves through a `--c4-*` custom property
+ * with a working default, so this looks reasonable in a page that does nothing.
+ * To make it look native, set the properties — not the rules:
+ *
+ *     .c4-playground {
+ *       --c4-border: var(--sl-color-gray-5);
+ *       --c4-bg: var(--sl-color-bg);
+ *       --c4-muted: var(--sl-color-gray-3);
+ *       --c4-font-mono: var(--sl-font-mono);
+ *     }
+ *
+ * Overriding properties survives an upgrade in a way overriding rules does not.
+ */
+
+.c4-playground {
+  /* Defaults, deliberately plain. A host that sets nothing still gets something
+     legible in both colour schemes; a host that sets these gets its own look. */
+  --c4-border: #d4d4d8;
+  --c4-bg: #ffffff;
+  --c4-muted: #6b7280;
+  --c4-accent: #3b82f6;
+  --c4-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+  --c4-text-sm: 0.875rem;
+  --c4-text-xs: 0.75rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  .c4-playground {
+    --c4-border: #3f3f46;
+    --c4-bg: #18181b;
+    --c4-muted: #a1a1aa;
+  }
+}
+
+.c4-playground {
+  border: 1px solid var(--c4-border);
+  border-radius: 0.5rem;
+  overflow: hidden;
+  margin: 1.5rem 0;
+  background: var(--c4-bg);
+}
+.c4-playground__bar {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--c4-border);
+  font-size: var(--c4-text-sm);
+  flex-wrap: wrap;
+}
+.c4-playground__bar label { display: inline-flex; align-items: center; gap: 0.35rem; }
+.c4-playground__bar button {
+  border: 1px solid var(--c4-border);
+  background: transparent;
+  color: inherit;
+  border-radius: 0.3rem;
+  padding: 0.15rem 0.6rem;
+  cursor: pointer;
+  font: inherit;
+}
+.c4-playground__bar button:disabled { opacity: 0.45; cursor: default; }
+.c4-playground__hint { color: var(--c4-muted); }
+.c4-playground__panes { display: grid; grid-template-columns: minmax(0, 20rem) minmax(0, 1fr); }
+@media (max-width: 50rem) { .c4-playground__panes { grid-template-columns: 1fr; } }
+.c4-playground__source {
+  border: 0;
+  border-right: 1px solid var(--c4-border);
+  padding: 0.75rem;
+  font-family: var(--c4-font-mono);
+  font-size: var(--c4-text-xs);
+  line-height: 1.5;
+  resize: vertical;
+  background: transparent;
+  color: inherit;
+  min-height: 100%;
+}
+.c4-playground__source:focus { outline: 2px solid var(--c4-accent); outline-offset: -2px; }
+.c4-playground__canvas {
+  overflow: auto;
+  padding: 0.5rem;
+  display: flex;
+}
+
+/* Centred with auto margins, never `justify-content`/`align-items: center`.
+   Those centre the overflow too: a diagram wider than the pane spills equally
+   left and right, and the left half cannot be scrolled to — the scroll origin
+   is the container's start edge, which the centring has already moved content
+   past. It reads as a diagram with its left side cut off and no way to reach
+   it, because that is exactly what it is.
+
+   Auto margins collapse to zero once there is no free space, so the same rule
+   centres a small diagram and lets a large one start at its true origin and
+   scroll. The child here is the renderer's own positioning wrapper, not the
+   <svg>: that wrapper is the flex item, which is why a `max-width` on the svg
+   never constrained anything. */
+.c4-playground__canvas > * { margin: auto; }
+
+/* Lightbox. The first attempt was inset:0 with no backdrop — a takeover, not a
+   modal. The second used absolute + inset on the panel, which let the content
+   dictate the height and pushed it past the viewport.
+   
+   This version centres with flex and puts the margin on the *container* as
+   padding, so a gap on all four sides is guaranteed regardless of content. */
+.c4-playground__lightbox {
+  position: fixed;
+  inset: 0;
+  /* Above Starlight's header (z-index 10) and mobile nav. A body child, so
+     this number is not competing inside a nested stacking context. */
+  z-index: 9999;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 4vh 4vw;
+}
+.c4-playground__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgb(0 0 0 / 0.55);
+  backdrop-filter: blur(2px);
+}
+.c4-playground--expanded {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  max-width: 90rem;
+  display: flex;
+  flex-direction: column;
+  border-radius: 0.75rem;
+  box-shadow: 0 1.5rem 4rem rgb(0 0 0 / 0.45);
+  background: var(--c4-bg);
+  overflow: hidden;
+}
+.c4-playground--expanded .c4-playground__panes { flex: 1; min-height: 0; }
+.c4-playground--expanded .c4-playground__source,
+.c4-playground--expanded .c4-playground__canvas { min-height: 0; overflow: auto; }
+
+/* Diagram-only: an illustration, not an invitation to edit. */
+.c4-playground--diagram-only .c4-playground__panes { grid-template-columns: 1fr; }
+
+.c4-playground__zoom {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.15rem;
+  margin-left: auto;
+}
+.c4-playground__zoom button {
+  min-width: 2rem;
+  padding: 0.2rem 0.4rem;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+}
+/* The readout doubles as the reset control, disabled at 100% rather than
+   hidden — a control that vanishes when it does nothing is one the reader has
+   to rediscover. Disabled styling comes from the bar's own button rule. */
+
+.c4-playground__expand {
+  margin-left: 0.25rem;
+  line-height: 1;
+  padding: 0.2rem 0.5rem;
+}

package/dist/playground/useIsDarkMode.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Track the site's current theme.
+ *
+ * `C4InteractiveRenderer` takes `isDarkMode` as a prop rather than reading the
+ * document itself — deliberately, since the library has no idea how its host
+ * decides what "dark" means. That makes keeping it current the host's job, and
+ * a host that reads the theme once at mount has a diagram that keeps last
+ * night's colours until something else forces a re-render. Clicking one used to
+ * be what did it here, which is not a feature.
+ *
+ * Two sources have to be watched, because Starlight has three states:
+ *
+ *   - An explicit choice sets `data-theme="dark"|"light"` on `<html>`, so the
+ *     attribute is observed.
+ *   - The default "auto" sets nothing, and the theme follows the OS. So
+ *     `prefers-color-scheme` is watched too — otherwise a diagram would not
+ *     follow the system flipping to dark at sunset.
+ */
+export declare function useIsDarkMode(): boolean;

package/dist/playground/useIsDarkMode.js

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react';
+/**
+ * Track the site's current theme.
+ *
+ * `C4InteractiveRenderer` takes `isDarkMode` as a prop rather than reading the
+ * document itself — deliberately, since the library has no idea how its host
+ * decides what "dark" means. That makes keeping it current the host's job, and
+ * a host that reads the theme once at mount has a diagram that keeps last
+ * night's colours until something else forces a re-render. Clicking one used to
+ * be what did it here, which is not a feature.
+ *
+ * Two sources have to be watched, because Starlight has three states:
+ *
+ *   - An explicit choice sets `data-theme="dark"|"light"` on `<html>`, so the
+ *     attribute is observed.
+ *   - The default "auto" sets nothing, and the theme follows the OS. So
+ *     `prefers-color-scheme` is watched too — otherwise a diagram would not
+ *     follow the system flipping to dark at sunset.
+ */
+export function useIsDarkMode() {
+    const [isDark, setIsDark] = useState(false);
+    useEffect(() => {
+        const read = () => {
+            const explicit = document.documentElement.dataset.theme;
+            if (explicit === 'dark')
+                return true;
+            if (explicit === 'light')
+                return false;
+            return window.matchMedia('(prefers-color-scheme: dark)').matches;
+        };
+        setIsDark(read());
+        const observer = new MutationObserver(() => setIsDark(read()));
+        observer.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ['data-theme'],
+        });
+        const media = window.matchMedia('(prefers-color-scheme: dark)');
+        const onMedia = () => setIsDark(read());
+        media.addEventListener('change', onMedia);
+        return () => {
+            observer.disconnect();
+            media.removeEventListener('change', onMedia);
+        };
+    }, []);
+    return isDark;
+}

package/dist/playground.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@liminis/diagrams/playground` — a ready-made C4 editing surface.
+ *
+ * A React component with a source pane, a live draggable diagram, zoom, and an
+ * expand-to-lightbox affordance. This is the shell this package's own
+ * documentation uses; it lives here because five documentation sites were
+ * keeping identical copies of it, and they drifted the moment the renderer
+ * gained a feature.
+ *
+ * Requires `@liminis/diagrams/playground.css`, imported separately — bundlers
+ * differ too much about CSS-in-package for importing it from here to be safe.
+ *
+ * React and react-dom are optional peer dependencies, as they are for `./react`.
+ * Nothing in `./core` reaches this file.
+ */
+export { default as C4Playground } from './playground/C4Playground.js';
+export type { C4PlaygroundProps } from './playground/C4Playground.js';
+/**
+ * Tracks a host that follows the `data-theme="dark"|"light"` convention, falling
+ * back to `prefers-color-scheme`. Entirely optional: `C4Playground` takes
+ * `isDarkMode` as a prop, and a host with its own theming should pass its own
+ * answer rather than use this.
+ */
+export { useIsDarkMode } from './playground/useIsDarkMode.js';

package/dist/playground.js

@@ -0,0 +1,23 @@
+/**
+ * `@liminis/diagrams/playground` — a ready-made C4 editing surface.
+ *
+ * A React component with a source pane, a live draggable diagram, zoom, and an
+ * expand-to-lightbox affordance. This is the shell this package's own
+ * documentation uses; it lives here because five documentation sites were
+ * keeping identical copies of it, and they drifted the moment the renderer
+ * gained a feature.
+ *
+ * Requires `@liminis/diagrams/playground.css`, imported separately — bundlers
+ * differ too much about CSS-in-package for importing it from here to be safe.
+ *
+ * React and react-dom are optional peer dependencies, as they are for `./react`.
+ * Nothing in `./core` reaches this file.
+ */
+export { default as C4Playground } from './playground/C4Playground.js';
+/**
+ * Tracks a host that follows the `data-theme="dark"|"light"` convention, falling
+ * back to `prefers-color-scheme`. Entirely optional: `C4Playground` takes
+ * `isDarkMode` as a prop, and a host with its own theming should pass its own
+ * answer rather than use this.
+ */
+export { useIsDarkMode } from './playground/useIsDarkMode.js';

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

@@ -523,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'));
@@ -546,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,6 +1,6 @@
 {
   "name": "@liminis/diagrams",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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 \u2014 the SSH form does not work.",
@@ -48,6 +48,11 @@
       "types": "./dist/react.d.ts",
       "default": "./dist/react.js"
     },
+    "./playground": {
+      "types": "./dist/playground.d.ts",
+      "default": "./dist/playground.js"
+    },
+    "./playground.css": "./dist/playground/playground.css",
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
@@ -61,7 +66,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node scripts/copy-assets.mjs",
     "clean": "rm -rf dist",
     "prepack": "pnpm run build",
     "prepublishOnly": "node scripts/guard-publish.mjs",