@liminis/diagrams 0.1.3 → 0.1.5

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/remark/remark-c4.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Turn ```c4 fenced code blocks into live <C4Playground> islands.
+ *
+ * The point is a single source of truth that renders usefully in both places:
+ *
+ *   - **GitHub** shows the fence as a syntax-highlighted code block. Honest and
+ *     readable with no build step, which matters because these files are read on
+ *     github.com as often as on the docs site.
+ *   - **The docs site** replaces it with the interactive component.
+ *
+ * The alternative was hand-writing `<C4Playground source={...} />` per diagram,
+ * which duplicates the source into JSX, makes the page unreadable on GitHub, and
+ * forces every page carrying a diagram to be MDX-authored rather than markdown.
+ *
+ * Fence meta becomes props, so a diagram can say how it wants to be shown:
+ *
+ *     ```c4 readOnly height=26rem
+ *     ```c4 static            (readOnly, drag off — a pure illustration)
+ *
+ * Unknown meta words are ignored rather than throwing: a fence is content, and
+ * a typo in it should not fail a docs build.
+ */
+/**
+ * The mdast/mdx node shapes this plugin touches, typed only as far as it uses
+ * them. Deliberately not `@types/mdast`: that would be a dependency for a
+ * build-time plugin, and the tree this walks is already whatever the host's
+ * remark version produced. `unknown`-valued extras keep the shape open.
+ */
+export interface MdastNode {
+    type: string;
+    name?: string;
+    lang?: string;
+    meta?: string;
+    value?: string;
+    children?: MdastNode[];
+    attributes?: {
+        type: string;
+        name?: string;
+        value?: unknown;
+    }[];
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface RemarkC4Options {
+    /**
+     * Module specifier the injected `import` points at. Defaults to
+     * `@site/components/C4Playground.tsx`, the convention the Liminis sites use:
+     * an alias, so one string is correct at every page depth.
+     */
+    component?: string;
+}
+export declare function remarkC4(options?: RemarkC4Options): (tree: MdastNode) => void;
+export default remarkC4;

package/dist/remark/remark-c4.js

@@ -0,0 +1,222 @@
+/**
+ * Turn ```c4 fenced code blocks into live <C4Playground> islands.
+ *
+ * The point is a single source of truth that renders usefully in both places:
+ *
+ *   - **GitHub** shows the fence as a syntax-highlighted code block. Honest and
+ *     readable with no build step, which matters because these files are read on
+ *     github.com as often as on the docs site.
+ *   - **The docs site** replaces it with the interactive component.
+ *
+ * The alternative was hand-writing `<C4Playground source={...} />` per diagram,
+ * which duplicates the source into JSX, makes the page unreadable on GitHub, and
+ * forces every page carrying a diagram to be MDX-authored rather than markdown.
+ *
+ * Fence meta becomes props, so a diagram can say how it wants to be shown:
+ *
+ *     ```c4 readOnly height=26rem
+ *     ```c4 static            (readOnly, drag off — a pure illustration)
+ *
+ * Unknown meta words are ignored rather than throwing: a fence is content, and
+ * a typo in it should not fail a docs build.
+ */
+const COMPONENT = 'C4Playground';
+/**
+ * Where the island component is imported from, by default.
+ *
+ * An alias rather than a relative path: the injected import is the same string
+ * on every page, but pages need not sit at the same depth, and a relative path
+ * would be correct for exactly one of them. Hosts using a different convention
+ * pass `component` instead.
+ */
+const DEFAULT_COMPONENT_PATH = '@site/components/C4Playground.tsx';
+/**
+ * Walk every node, depth-first, with its parent and index.
+ *
+ * `unist-util-visit` does this and more, and using it would have made
+ * @liminis/diagrams depend on something beyond dagre — an invariant the package
+ * asserts about itself and that keeps `./core` as small as it claims to be. Both
+ * uses here are plain traversals, so the general version buys nothing.
+ *
+ * Children are walked before the callback sees the parent's later siblings, and
+ * the callback must not splice: collect first, mutate after. Both callers do.
+ */
+function walk(node, visitor, parent = null, index = null) {
+    visitor(node, index, parent);
+    const children = node.children;
+    if (!Array.isArray(children))
+        return;
+    // A copy, so a callback that does mutate cannot make this skip a node.
+    for (const [i, child] of [...children].entries())
+        walk(child, visitor, node, i);
+}
+/** An mdast attribute whose value is a JS expression rather than a string. */
+function expressionAttribute(name, value) {
+    return {
+        type: 'mdxJsxAttribute',
+        name,
+        value: {
+            type: 'mdxJsxAttributeValueExpression',
+            value: JSON.stringify(value),
+            data: {
+                estree: {
+                    type: 'Program',
+                    sourceType: 'module',
+                    body: [
+                        {
+                            type: 'ExpressionStatement',
+                            expression: { type: 'Literal', value, raw: JSON.stringify(value) },
+                        },
+                    ],
+                },
+            },
+        },
+    };
+}
+function booleanAttribute(name, value) {
+    return value
+        ? { type: 'mdxJsxAttribute', name, value: null }
+        : expressionAttribute(name, false);
+}
+function parseMeta(meta) {
+    // Keyed by attribute name, so a fence can only ever produce one of each.
+    //
+    // `static` is shorthand for two attributes, which made `static editable=true`
+    // emit `editable` twice — leaving which one wins to whatever the downstream
+    // JSX serialiser does with a duplicate. Later tokens now overwrite earlier
+    // ones, so that fence means what it reads like: static, but editable after
+    // all. Order is what decides, in both directions: `editable=true static` is
+    // static, because `static` came last.
+    const props = new Map();
+    if (!meta)
+        return [];
+    const set = (attribute) => props.set(attribute.name, attribute);
+    for (const token of meta.trim().split(/\s+/)) {
+        if (!token)
+            continue;
+        const [key, raw] = token.split('=');
+        switch (key) {
+            case 'readOnly':
+                set(booleanAttribute('readOnly', true));
+                break;
+            case 'static':
+                // Shorthand: an illustration, not an invitation to edit or drag.
+                set(booleanAttribute('readOnly', true));
+                set(booleanAttribute('editable', false));
+                break;
+            case 'editable':
+                set(booleanAttribute('editable', raw !== 'false'));
+                break;
+            case 'height':
+                if (raw)
+                    set({ type: 'mdxJsxAttribute', name: 'height', value: raw });
+                break;
+            default:
+                // Ignored on purpose — see the note above.
+                break;
+        }
+    }
+    return [...props.values()];
+}
+/** `import C4Playground from '…'`, built as estree rather than parsed. */
+function importNode(componentPath) {
+    // JSON.stringify rather than wrapping in quotes: a path containing a quote or
+    // a backslash would otherwise produce invalid JS in the text *and* a `raw`
+    // that disagrees with the value beside it — two representations of the same
+    // import, differing. Bundlers read the estree; humans read the text.
+    const literal = JSON.stringify(componentPath);
+    return {
+        type: 'mdxjsEsm',
+        value: `import ${COMPONENT} from ${literal}`,
+        data: {
+            estree: {
+                type: 'Program',
+                sourceType: 'module',
+                body: [
+                    {
+                        type: 'ImportDeclaration',
+                        specifiers: [
+                            {
+                                type: 'ImportDefaultSpecifier',
+                                local: { type: 'Identifier', name: COMPONENT },
+                            },
+                        ],
+                        source: { type: 'Literal', value: componentPath, raw: literal },
+                        attributes: [],
+                    },
+                ],
+            },
+        },
+    };
+}
+/**
+ * The generated `<picture>` blocks exist for GitHub, which has no build step.
+ * Here the island renders the same diagram interactively, so showing both would
+ * be duplication — they are stripped. See scripts/render-diagrams.mjs.
+ *
+ * Identified by the paths inside them rather than by a marker comment: MDX does
+ * not permit HTML comments at all, so `<!-- … -->` is a syntax error rather than
+ * a marker.
+ *
+ * Bare `<img>` is still matched: a page written before the light/dark
+ * `<picture>` existed should lose its old block rather than keep it beside the
+ * island.
+ */
+function referencesGeneratedDiagram(node) {
+    if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement')
+        return false;
+    return (node.attributes ?? []).some((a) => (a.name === 'src' || a.name === 'srcset') &&
+        typeof a.value === 'string' &&
+        a.value.includes('/diagrams/'));
+}
+function isGeneratedImage(node) {
+    if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement')
+        return false;
+    if (node.name === 'img')
+        return referencesGeneratedDiagram(node);
+    if (node.name !== 'picture')
+        return false;
+    return (node.children ?? []).some(referencesGeneratedDiagram);
+}
+function stripRenderedImages(tree) {
+    const doomed = [];
+    walk(tree, (node, index, parent) => {
+        if (parent && index !== null && isGeneratedImage(node))
+            doomed.push({ index, parent });
+    });
+    // Remove back-to-front so earlier indices stay valid.
+    for (const { index, parent } of doomed.reverse())
+        parent.children?.splice(index, 1);
+}
+export function remarkC4(options = {}) {
+    const componentPath = options.component ?? DEFAULT_COMPONENT_PATH;
+    return (tree) => {
+        stripRenderedImages(tree);
+        const replacements = [];
+        walk(tree, (node, index, parent) => {
+            if (node.type !== 'code' || node.lang !== 'c4' || !parent || index === null)
+                return;
+            replacements.push({ node, index, parent });
+        });
+        if (replacements.length === 0)
+            return;
+        for (const { node, index, parent } of replacements) {
+            parent.children[index] = {
+                type: 'mdxJsxFlowElement',
+                name: COMPONENT,
+                attributes: [
+                    // The drag layer measures the live SVG via getScreenCTM, which does
+                    // not exist during a server render, so these cannot be hydrated with
+                    // client:visible.
+                    { type: 'mdxJsxAttribute', name: 'client:only', value: 'react' },
+                    expressionAttribute('source', node.value),
+                    ...parseMeta(node.meta),
+                ],
+                children: [],
+            };
+        }
+        // One import for the file, regardless of how many diagrams it holds.
+        tree.children?.unshift(importNode(componentPath));
+    };
+}
+export default remarkC4;

package/dist/remark.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@liminis/diagrams/remark` — turn ```c4 fences into live diagram islands.
+ *
+ * A build-time remark plugin. It rewrites each fenced `c4` block into a JSX
+ * element and injects one import per file, so a markdown page reads as markdown
+ * on GitHub and renders as an interactive diagram on a site.
+ *
+ * It also strips the generated `<picture>` blocks that sit beside those fences
+ * for GitHub's benefit: on a site the island renders the same diagram, so
+ * showing both would be duplication.
+ *
+ *     import { remarkC4 } from '@liminis/diagrams/remark'
+ *     export default defineConfig({ markdown: { remarkPlugins: [remarkC4] } })
+ *
+ * Nothing here imports React, or anything at all beyond the language: it runs
+ * in Node during a build, and the package's single runtime dependency is unchanged.
+ */
+export { remarkC4, remarkC4 as default } from './remark/remark-c4.js';
+export type { RemarkC4Options, MdastNode } from './remark/remark-c4.js';

package/dist/remark.js

@@ -0,0 +1,18 @@
+/**
+ * `@liminis/diagrams/remark` — turn ```c4 fences into live diagram islands.
+ *
+ * A build-time remark plugin. It rewrites each fenced `c4` block into a JSX
+ * element and injects one import per file, so a markdown page reads as markdown
+ * on GitHub and renders as an interactive diagram on a site.
+ *
+ * It also strips the generated `<picture>` blocks that sit beside those fences
+ * for GitHub's benefit: on a site the island renders the same diagram, so
+ * showing both would be duplication.
+ *
+ *     import { remarkC4 } from '@liminis/diagrams/remark'
+ *     export default defineConfig({ markdown: { remarkPlugins: [remarkC4] } })
+ *
+ * Nothing here imports React, or anything at all beyond the language: it runs
+ * in Node during a build, and the package's single runtime dependency is unchanged.
+ */
+export { remarkC4, remarkC4 as default } from './remark/remark-c4.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liminis/diagrams",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,15 @@
       "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",
+    "./remark": {
+      "types": "./dist/remark.d.ts",
+      "default": "./dist/remark.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
@@ -61,7 +70,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",