@diagrammo/dgmo 0.25.3 → 0.25.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.25.3",
+  "version": "0.25.4",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -1506,15 +1506,6 @@ async function main(): Promise<void> {
     opts.theme === 'dark' ? 'dark' : 'light'
   ];
 
-  // Word clouds require Canvas APIs (HTMLCanvasElement.getContext('2d'))
-  // which are unavailable in Node.js — check before attempting render.
-  const wordcloudRe = /^\s*chart\s*:\s*wordcloud\b/im;
-  if (wordcloudRe.test(content)) {
-    exitWithJsonError(
-      'Error: Word clouds are not supported in the CLI (requires Canvas). Use the desktop app or browser instead.'
-    );
-  }
-
   // Parse first to collect diagnostics
   const { diagnostics } = parseDgmo(content);
   const errors = diagnostics.filter((d) => d.severity === 'error');

package/src/d3.ts

@@ -5771,6 +5771,106 @@ function getRotateFn(mode: WordCloudRotate): () => number {
   return () => 0;
 }
 
+/**
+ * d3-cloud rasterizes each glyph to a canvas sprite for pixel-perfect
+ * collision detection. In headless Node (jsdom), `getContext('2d')` returns
+ * null, so d3-cloud throws (`getImageData` on null). This detects whether a
+ * usable 2D canvas exists; when it doesn't, we fall back to a canvas-free
+ * spiral packer so word clouds still render in SSG (remark wrappers), the MCP
+ * server, and the CLI.
+ */
+function hasCanvas2d(): boolean {
+  try {
+    if (typeof document === 'undefined') return false;
+    const canvas = document.createElement('canvas');
+    return typeof canvas.getContext === 'function' && !!canvas.getContext('2d');
+  } catch {
+    return false;
+  }
+}
+
+/** Average glyph advance for Inter as a fraction of the font size. Slightly
+ * generous so estimated boxes err toward not overlapping. */
+const WORDCLOUD_GLYPH_ADVANCE = 0.62;
+
+function estimateWordWidth(text: string, size: number): number {
+  return text.length * size * WORDCLOUD_GLYPH_ADVANCE;
+}
+
+type PlacedCloudWord = WordCloudWord & {
+  size: number;
+  x: number;
+  y: number;
+  rotate: number;
+};
+
+/**
+ * Canvas-free word-cloud layout. Places the largest words first at the centre
+ * and walks an Archimedean spiral outward, using axis-aligned bounding-box
+ * overlap tests (text width estimated from font metrics). Returns words in
+ * placement order with `x`/`y` relative to the cloud centre — the same shape
+ * d3-cloud hands to its `end` callback — so the existing draw code is reused.
+ * Words that can't be placed within the box are dropped, matching d3-cloud.
+ */
+function layoutWordsNoCanvas(
+  words: Array<WordCloudWord & { size: number }>,
+  width: number,
+  height: number,
+  padding: number,
+  rotateFn: () => number
+): PlacedCloudWord[] {
+  const sorted = [...words].sort((a, b) => b.size - a.size);
+  const placed: Array<PlacedCloudWord & { halfW: number; halfH: number }> = [];
+  const maxR = Math.sqrt(width * width + height * height) / 2;
+  // Bias the spiral to the box aspect so wide clouds spread horizontally.
+  const aspect = width > 0 ? height / width : 1;
+
+  for (const w of sorted) {
+    const rotate = rotateFn();
+    const rawW = estimateWordWidth(w.text, w.size) + padding * 2;
+    const rawH = w.size + padding * 2;
+    const rad = (rotate * Math.PI) / 180;
+    const cos = Math.abs(Math.cos(rad));
+    const sin = Math.abs(Math.sin(rad));
+    const halfW = (rawW * cos + rawH * sin) / 2;
+    const halfH = (rawW * sin + rawH * cos) / 2;
+
+    let spot: { x: number; y: number } | null = null;
+    for (let t = 0; t < 4000; t++) {
+      const a = t * 0.25;
+      const r = a * 1.4;
+      if (r > maxR) break;
+      const x = Math.cos(a) * r;
+      const y = Math.sin(a) * r * aspect;
+      if (
+        x - halfW < -width / 2 ||
+        x + halfW > width / 2 ||
+        y - halfH < -height / 2 ||
+        y + halfH > height / 2
+      ) {
+        continue;
+      }
+      let collides = false;
+      for (const p of placed) {
+        if (
+          Math.abs(x - p.x) < halfW + p.halfW &&
+          Math.abs(y - p.y) < halfH + p.halfH
+        ) {
+          collides = true;
+          break;
+        }
+      }
+      if (!collides) {
+        spot = { x, y };
+        break;
+      }
+    }
+    if (!spot) continue;
+    placed.push({ ...w, rotate, x: spot.x, y: spot.y, halfW, halfH });
+  }
+  return placed;
+}
+
 // ============================================================
 // Word Cloud Renderer
 // ============================================================
@@ -5839,40 +5939,55 @@ export function renderWordCloud(
       `translate(${width / 2},${sTitleHeight + cloudHeight / 2})`
     );
 
+  const sized = words.map((w) => ({ ...w, size: fontSize(w.weight) }));
+
+  const draw = (
+    layoutWords: Array<{
+      text?: string;
+      size?: number;
+      x?: number;
+      y?: number;
+      rotate?: number;
+    }>
+  ): void => {
+    g.selectAll('text')
+      .data(layoutWords)
+      .join('text')
+      .style('font-size', (d) => `${d.size}px`)
+      .style('font-family', FONT_FAMILY)
+      .style('font-weight', '600')
+      // colors is non-empty; modulo guarantees in-bounds.
+      .style('fill', (_d, i) => colors[i % colors.length]!)
+      .style('cursor', (d) =>
+        onClickItem && (d as WordCloudWord).lineNumber ? 'pointer' : 'default'
+      )
+      .attr('text-anchor', 'middle')
+      .attr('transform', (d) => `translate(${d.x},${d.y}) rotate(${d.rotate})`)
+      .attr('data-line-number', (d) => {
+        const ln = (d as WordCloudWord).lineNumber;
+        return ln ? String(ln) : null;
+      })
+      .text((d) => d.text!)
+      .on('click', (_event, d) => {
+        const ln = (d as WordCloudWord).lineNumber;
+        if (onClickItem && ln) onClickItem(ln);
+      });
+  };
+
+  // No real 2D canvas (headless Node) → fall back to the spiral packer.
+  if (!hasCanvas2d()) {
+    draw(layoutWordsNoCanvas(sized, width, cloudHeight, sPadding, rotateFn));
+    return;
+  }
+
   cloud<WordCloudWord & cloud.Word>()
     .size([width, cloudHeight])
-    .words(words.map((w) => ({ ...w, size: fontSize(w.weight) })))
+    .words(sized)
     .padding(sPadding)
     .rotate(rotateFn)
     .fontSize((d) => d.size!)
     .font(FONT_FAMILY)
-    .on('end', (layoutWords) => {
-      g.selectAll('text')
-        .data(layoutWords)
-        .join('text')
-        .style('font-size', (d) => `${d.size}px`)
-        .style('font-family', FONT_FAMILY)
-        .style('font-weight', '600')
-        // colors is non-empty; modulo guarantees in-bounds.
-        .style('fill', (_d, i) => colors[i % colors.length]!)
-        .style('cursor', (d) =>
-          onClickItem && (d as WordCloudWord).lineNumber ? 'pointer' : 'default'
-        )
-        .attr('text-anchor', 'middle')
-        .attr(
-          'transform',
-          (d) => `translate(${d.x},${d.y}) rotate(${d.rotate})`
-        )
-        .attr('data-line-number', (d) => {
-          const ln = (d as WordCloudWord).lineNumber;
-          return ln ? String(ln) : null;
-        })
-        .text((d) => d.text!)
-        .on('click', (_event, d) => {
-          const ln = (d as WordCloudWord).lineNumber;
-          if (onClickItem && ln) onClickItem(ln);
-        });
-    })
+    .on('end', draw)
     .start();
 }
 
@@ -5942,30 +6057,49 @@ function renderWordCloudAsync(
         `translate(${width / 2},${titleHeight + cloudHeight / 2})`
       );
 
+    const sized = words.map((w) => ({ ...w, size: fontSize(w.weight) }));
+
+    const draw = (
+      layoutWords: Array<{
+        text?: string;
+        size?: number;
+        x?: number;
+        y?: number;
+        rotate?: number;
+      }>
+    ): void => {
+      g.selectAll('text')
+        .data(layoutWords)
+        .join('text')
+        .style('font-size', (d) => `${d.size}px`)
+        .style('font-family', FONT_FAMILY)
+        .style('font-weight', '600')
+        // colors is non-empty; modulo guarantees in-bounds.
+        .style('fill', (_d, i) => colors[i % colors.length]!)
+        .attr('text-anchor', 'middle')
+        .attr(
+          'transform',
+          (d) => `translate(${d.x},${d.y}) rotate(${d.rotate})`
+        )
+        .text((d) => d.text!);
+      resolve();
+    };
+
+    // No real 2D canvas (headless Node: SSG wrappers, MCP, CLI) → d3-cloud's
+    // sprite rasterization can't run. Use the canvas-free spiral packer.
+    if (!hasCanvas2d()) {
+      draw(layoutWordsNoCanvas(sized, width, cloudHeight, 2, rotateFn));
+      return;
+    }
+
     cloud<WordCloudWord & cloud.Word>()
       .size([width, cloudHeight])
-      .words(words.map((w) => ({ ...w, size: fontSize(w.weight) })))
+      .words(sized)
       .padding(2)
       .rotate(rotateFn)
       .fontSize((d) => d.size!)
       .font(FONT_FAMILY)
-      .on('end', (layoutWords) => {
-        g.selectAll('text')
-          .data(layoutWords)
-          .join('text')
-          .style('font-size', (d) => `${d.size}px`)
-          .style('font-family', FONT_FAMILY)
-          .style('font-weight', '600')
-          // colors is non-empty; modulo guarantees in-bounds.
-          .style('fill', (_d, i) => colors[i % colors.length]!)
-          .attr('text-anchor', 'middle')
-          .attr(
-            'transform',
-            (d) => `translate(${d.x},${d.y}) rotate(${d.rotate})`
-          )
-          .text((d) => d.text!);
-        resolve();
-      })
+      .on('end', draw)
       .start();
   });
 }

package/src/render.ts

@@ -5,45 +5,81 @@ import type { DgmoError } from './diagnostics';
 import { getPalette } from './palettes/registry';
 import type { CompactViewState } from './sharing';
 
-/**
- * Ensures DOM globals are available for D3 renderers.
- * No-ops in browser environments where `document` already exists.
- * Dynamically imports jsdom only in Node.js to avoid bundling it for browsers.
- */
-async function ensureDom(): Promise<void> {
-  if (typeof document !== 'undefined') return;
+// DOM globals installed for Node-side D3 rendering, scoped with ref-counting.
+//
+// These need to exist on `globalThis` while a D3 renderer runs (it reaches for
+// `document`). The naive approach — install them once and leave them — leaks a
+// jsdom `window` into the host Node process forever. That breaks hosts that run
+// their OWN SSR/SSG in the same process after calling render(): notably
+// Docusaurus static export, whose theme then believes it is in a browser
+// (`canUseDOM` true) and crashes on bare globals this shim does NOT define
+// (`requestAnimationFrame`, `MutationObserver`) or on opaque-origin
+// `localStorage`. So we install on the first concurrent render and tear down
+// once the last one finishes, leaving the host a clean Node environment.
+const DOM_GLOBALS = [
+  'document',
+  'window',
+  'navigator',
+  'HTMLElement',
+  'SVGElement',
+] as const;
+let domRefCount = 0;
+let domInstallPromise: Promise<void> | null = null;
+let domInstalledByUs = false;
 
+async function installDom(): Promise<void> {
   const { JSDOM } = await loadJsdom();
-  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+  // Concrete URL → non-opaque origin, so host code that touches
+  // window.localStorage during a same-process render doesn't throw.
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+    url: 'http://localhost/',
+  });
   const win = dom.window;
+  const values: Record<(typeof DOM_GLOBALS)[number], unknown> = {
+    document: win.document,
+    window: win,
+    navigator: win.navigator,
+    HTMLElement: win.HTMLElement,
+    SVGElement: win.SVGElement,
+  };
+  for (const key of DOM_GLOBALS) {
+    Object.defineProperty(globalThis, key, {
+      value: values[key],
+      configurable: true,
+    });
+  }
+  domInstalledByUs = true;
+}
 
-  Object.defineProperty(globalThis, 'document', {
-    value: win.document,
-    configurable: true,
-  });
-  Object.defineProperty(globalThis, 'window', {
-    value: win,
-    configurable: true,
-  });
-  Object.defineProperty(globalThis, 'navigator', {
-    value: win.navigator,
-    configurable: true,
-  });
-  Object.defineProperty(globalThis, 'HTMLElement', {
-    value: win.HTMLElement,
-    configurable: true,
-  });
-  Object.defineProperty(globalThis, 'SVGElement', {
-    value: win.SVGElement,
-    configurable: true,
-  });
+/**
+ * Make DOM globals available for the duration of a render. No-ops in a real
+ * browser or any host that already provides `document` (we never touch globals
+ * we did not install). Pair every successful call with `releaseDom()`.
+ */
+async function acquireDom(): Promise<void> {
+  if (typeof document !== 'undefined' && !domInstalledByUs) return;
+  domRefCount++;
+  if (!domInstallPromise) domInstallPromise = installDom();
+  await domInstallPromise;
+}
+
+/** Tear down the jsdom globals once no render is in flight. */
+function releaseDom(): void {
+  if (!domInstalledByUs) return;
+  if (--domRefCount > 0) return;
+  for (const key of DOM_GLOBALS) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+  domInstalledByUs = false;
+  domInstallPromise = null;
+  domRefCount = 0;
 }
 
 /**
  * Load jsdom server-side. The specifier is constructed at runtime so
  * downstream bundlers (Vite, Rollup, esbuild, webpack) cannot statically
  * resolve it. Without this indirection, every browser bundle of
- * @diagrammo/dgmo emits a 5+ MB jsdom chunk even though `ensureDom()`
+ * @diagrammo/dgmo emits a 5+ MB jsdom chunk even though `acquireDom()`
  * guards execution with a `typeof document` check — the guard prevents
  * runtime evaluation, but the static dependency edge still pulls jsdom
  * into the bundle.
@@ -128,16 +164,21 @@ export async function render(
   }
 
   // Visualization/diagram and unknown/null types all go through the unified renderer
-  await ensureDom();
-  const svg = await renderForExport(content, theme, paletteColors, viewState, {
-    ...(options?.c4Level !== undefined && { c4Level: options.c4Level }),
-    ...(options?.c4System !== undefined && { c4System: options.c4System }),
-    ...(options?.c4Container !== undefined && {
-      c4Container: options.c4Container,
-    }),
-    ...(options?.tagGroup !== undefined && { tagGroup: options.tagGroup }),
-    ...(options?.mapData !== undefined && { mapData: options.mapData }),
-  });
+  await acquireDom();
+  let svg: string;
+  try {
+    svg = await renderForExport(content, theme, paletteColors, viewState, {
+      ...(options?.c4Level !== undefined && { c4Level: options.c4Level }),
+      ...(options?.c4System !== undefined && { c4System: options.c4System }),
+      ...(options?.c4Container !== undefined && {
+        c4Container: options.c4Container,
+      }),
+      ...(options?.tagGroup !== undefined && { tagGroup: options.tagGroup }),
+      ...(options?.mapData !== undefined && { mapData: options.mapData }),
+    });
+  } finally {
+    releaseDom();
+  }
 
   // The map pipeline resolves names AFTER parsing (gazetteer/ISO lookup), so its
   // unknown-place / unknown-subdivision errors live on the ResolvedMap, not the