@liquidcars/atlas 0.1.48 → 0.1.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Reusable 3D conceptual atlas Web Component for LiquidCars-style models",
   "type": "module",
   "scripts": {

package/src/diagram-svg.js

@@ -0,0 +1,603 @@
+import * as THREE from "./three.module.js";
+
+const round = value => Number(value.toFixed(3));
+const escapeXml = value => String(value ?? "").replace(/[&<>"']/g, character => ({
+  "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;"
+})[character]);
+const cross = (a, b, c) => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+const textureCache = new WeakMap();
+const sourceTextureCache = new WeakMap();
+
+function blendHex(background, foreground, opacity) {
+  const back = Number.parseInt(background.slice(1), 16);
+  const front = Number.parseInt(foreground.slice(1), 16);
+  const channel = shift => Math.round(((back >> shift) & 255) * (1 - opacity) + ((front >> shift) & 255) * opacity);
+  return `#${[16, 8, 0].map(shift => channel(shift).toString(16).padStart(2, "0")).join("")}`;
+}
+
+function relationMode(relation) {
+  const raw = String(relation.mode || relation.visual || relation.render || relation.type || relation.direction || "")
+    .trim().toLowerCase().replace(/[_\s]+/g, "-");
+  if (relation.bidirectional === true || ["bidirectional", "both", "two-way", "duplex"].includes(raw)) return "bidirectional";
+  if (relation.broken === true || ["broken", "interrupted", "disconnected", "failed"].includes(raw)) return "broken";
+  return "directed";
+}
+
+function textureImage(texture) {
+  const source = texture?.image;
+  if (!source || !(source.naturalWidth || source.width) || !(source.naturalHeight || source.height)) return null;
+  if (textureCache.get(texture)?.source === source) return textureCache.get(texture).image;
+  const shared = sourceTextureCache.get(source);
+  if (shared) {
+    textureCache.set(texture, { source, image: shared });
+    return shared;
+  }
+  try {
+    const canvas = globalThis.document.createElement("canvas");
+    const sourceWidth = source.naturalWidth || source.width;
+    const sourceHeight = source.naturalHeight || source.height;
+    const ratio = Math.min(1, 512 / Math.max(sourceWidth, sourceHeight));
+    canvas.width = Math.max(1, Math.round(sourceWidth * ratio));
+    canvas.height = Math.max(1, Math.round(sourceHeight * ratio));
+    canvas.getContext("2d").drawImage(source, 0, 0, canvas.width, canvas.height);
+    const image = { uri: canvas.toDataURL("image/png"), width: canvas.width, height: canvas.height };
+    textureCache.set(texture, { source, image });
+    sourceTextureCache.set(source, image);
+    return image;
+  } catch { return null; }
+}
+
+function texturedFace(geometry, matrix, texture, image) {
+  const position = geometry.getAttribute("position");
+  const uv = geometry.getAttribute("uv");
+  if (!uv || !position || !image) return null;
+  const index = geometry.index;
+  const points = [];
+  const mapped = [];
+  for (let i = 0; i < position.count; i += 1) {
+    const vertex = new THREE.Vector3().fromBufferAttribute(position, i).applyMatrix4(matrix);
+    points.push(vertex);
+    mapped.push({
+      x: (uv.getX(i) * texture.repeat.x + texture.offset.x) * image.width,
+      y: (1 - uv.getY(i) * texture.repeat.y - texture.offset.y) * image.height,
+      px: vertex.x, py: -vertex.y
+    });
+  }
+  // A single affine image can represent a planar face. Curved or warped UVs
+  // need their own 2D geometry contract and continue through the mesh fallback.
+  const count = index ? index.count : position.count;
+  for (let i = 0; i + 2 < count; i += 3) {
+    const a = mapped[index ? index.getX(i) : i];
+    const b = mapped[index ? index.getX(i + 1) : i + 1];
+    const c = mapped[index ? index.getX(i + 2) : i + 2];
+    const determinant = (b.x - a.x) * (c.y - a.y) - (c.x - a.x) * (b.y - a.y);
+    if (Math.abs(determinant) < 1e-6) continue;
+    const A = ((b.px - a.px) * (c.y - a.y) - (c.px - a.px) * (b.y - a.y)) / determinant;
+    const C = ((c.px - a.px) * (b.x - a.x) - (b.px - a.px) * (c.x - a.x)) / determinant;
+    const B = ((b.py - a.py) * (c.y - a.y) - (c.py - a.py) * (b.y - a.y)) / determinant;
+    const D = ((c.py - a.py) * (b.x - a.x) - (b.py - a.py) * (c.x - a.x)) / determinant;
+    const E = a.px - A * a.x - C * a.y;
+    const F = a.py - B * a.x - D * a.y;
+    if (mapped.some(p => Math.hypot(A * p.x + C * p.y + E - p.px, B * p.x + D * p.y + F - p.py) > 1e-3)) return null;
+    return { image, points, transform: [A, B, C, D, E, F], depth: points.reduce((sum, p) => sum + p.z, 0) / points.length };
+  }
+  return null;
+}
+
+function convexHull(points) {
+  const sorted = [...points].sort((a, b) => a.x - b.x || a.y - b.y);
+  if (sorted.length < 3) return sorted;
+  const lower = [];
+  const upper = [];
+  for (const point of sorted) {
+    while (lower.length > 1 && cross(lower.at(-2), lower.at(-1), point) <= 0) lower.pop();
+    lower.push(point);
+  }
+  for (const point of sorted.reverse()) {
+    while (upper.length > 1 && cross(upper.at(-2), upper.at(-1), point) <= 0) upper.pop();
+    upper.push(point);
+  }
+  return lower.slice(0, -1).concat(upper.slice(0, -1));
+}
+
+function frontFaces(node, independent = false) {
+  const root = node.mesh;
+  if (!root) return null;
+  const opacityOf = material => independent
+    ? (material === node.material ? 1 : material.userData?.atlasBaseOpacity ?? material.opacity ?? 1)
+    : material.opacity ?? 1;
+  node.group.updateWorldMatrix(true, true);
+  const inverse = node.group.matrixWorld.clone().invert();
+  const triangles = [];
+  const textured = [];
+  const points = [];
+  let unsupportedTexture = false;
+  root.traverse(mesh => {
+    if (!mesh.isMesh || !mesh.visible || mesh === node.pickMesh) return;
+    const geometry = mesh.geometry;
+    const position = geometry?.getAttribute?.("position");
+    if (!position) return;
+    const matrix = inverse.clone().multiply(mesh.matrixWorld);
+    const index = geometry.index;
+    const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+    const count = index ? index.count : position.count;
+    const v = new THREE.Vector3();
+    const p = vertex => v.fromBufferAttribute(position, vertex).applyMatrix4(matrix).clone();
+    if (materials.length === 1 && materials[0]?.map) {
+      const face = texturedFace(geometry, matrix, materials[0].map, textureImage(materials[0].map));
+      if (face) {
+        face.opacity = opacityOf(materials[0]);
+        textured.push(face);
+        points.push(...face.points);
+        return;
+      }
+      unsupportedTexture = true;
+    }
+    for (let i = 0; i + 2 < count; i += 3) {
+      const materialIndex = geometry.groups.find(group => i >= group.start && i < group.start + group.count)?.materialIndex || 0;
+      const material = materials[materialIndex] || materials[0];
+      if (!material?.visible || material.colorWrite === false || opacityOf(material) <= 0) continue;
+      if (material.map) unsupportedTexture = true;
+      const a = p(index ? index.getX(i) : i);
+      const b = p(index ? index.getX(i + 1) : i + 1);
+      const c = p(index ? index.getX(i + 2) : i + 2);
+      const area = cross(a, b, c);
+      if (Math.abs(area) < 1e-9 || (area < 0 && material.side !== THREE.DoubleSide && material.side !== THREE.BackSide)) continue;
+      if (area > 0 && material.side === THREE.BackSide) continue;
+      points.push(a, b, c);
+      triangles.push({ vertices: [a, b, c], depth: (a.z + b.z + c.z) / 3,
+        color: `#${material.color.getHexString()}`, opacity: opacityOf(material) });
+    }
+  });
+  if (!triangles.length && !textured.length) return null;
+  triangles.sort((a, b) => a.depth - b.depth);
+  const bounds = { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity };
+  for (const point of points) {
+    bounds.minX = Math.min(bounds.minX, point.x);
+    bounds.maxX = Math.max(bounds.maxX, point.x);
+    bounds.minY = Math.min(bounds.minY, point.y);
+    bounds.maxY = Math.max(bounds.maxY, point.y);
+  }
+  const hull = convexHull(points.map(p => ({ x: p.x, y: p.y })));
+  return { triangles, textured, bounds, hull, unsupportedTexture };
+}
+
+function rayBoundary(item, towards) {
+  const dx = towards.x - item.x;
+  const dy = towards.y - item.y;
+  const length = Math.hypot(dx, dy) || 1;
+  const direction = { x: dx / length, y: dy / length };
+  const polygon = item.hull.map(p => ({ x: item.x + p.x * item.scale, y: item.y - p.y * item.scale }));
+  let closest = Infinity;
+  for (let i = 0; i < polygon.length; i += 1) {
+    const a = polygon[i];
+    const b = polygon[(i + 1) % polygon.length];
+    const edge = { x: b.x - a.x, y: b.y - a.y };
+    const determinant = direction.x * edge.y - direction.y * edge.x;
+    if (Math.abs(determinant) < 1e-9) continue;
+    const offset = { x: a.x - item.x, y: a.y - item.y };
+    const distance = (offset.x * edge.y - offset.y * edge.x) / determinant;
+    const fraction = (offset.x * direction.y - offset.y * direction.x) / determinant;
+    if (distance >= 0 && fraction >= 0 && fraction <= 1) closest = Math.min(closest, distance);
+  }
+  const distance = Number.isFinite(closest) ? closest + 2 : 0;
+  return { x: round(item.x + direction.x * distance), y: round(item.y + direction.y * distance) };
+}
+
+function separateOverlaps(items, gap) {
+  for (let iteration = 0; iteration < 96; iteration += 1) {
+    let moved = false;
+    for (let i = 0; i < items.length; i += 1) for (let j = i + 1; j < items.length; j += 1) {
+      const a = items[i];
+      const b = items[j];
+      const boundsA = itemBounds(a, a.labelLines.length > 0);
+      const boundsB = itemBounds(b, b.labelLines.length > 0);
+      const x = Math.min(boundsA.maxX, boundsB.maxX) - Math.max(boundsA.minX, boundsB.minX) + gap;
+      const y = Math.min(boundsA.maxY, boundsB.maxY) - Math.max(boundsA.minY, boundsB.minY) + gap;
+      if (x <= 0 || y <= 0) continue;
+      moved = true;
+      if (x < y) {
+        const push = x / 2 + .01;
+        const sign = a.x <= b.x ? 1 : -1;
+        a.x -= sign * push;
+        b.x += sign * push;
+      } else {
+        const push = y / 2 + .01;
+        const sign = a.y <= b.y ? 1 : -1;
+        a.y -= sign * push;
+        b.y += sign * push;
+      }
+    }
+    if (!moved) break;
+  }
+}
+
+function labelLines(name) {
+  const lines = [];
+  for (const word of String(name).split(/\s+/).filter(Boolean)) {
+    const previous = lines.at(-1);
+    if (previous && previous.length + word.length + 1 <= 20) lines[lines.length - 1] += ` ${word}`;
+    else for (let i = 0; i < word.length; i += 20) lines.push(word.slice(i, i + 20));
+  }
+  return lines;
+}
+
+function itemBounds(item, labels) {
+  const halfLabel = labels ? Math.max(...item.labelLines.map(line => line.length), 0) * item.labelFontSize * .31 : 0;
+  return {
+    minX: item.x + Math.min(item.bounds.minX * item.scale, -halfLabel),
+    maxX: item.x + Math.max(item.bounds.maxX * item.scale, halfLabel),
+    minY: item.y - item.bounds.maxY * item.scale,
+    maxY: item.y - item.bounds.minY * item.scale + (labels ? item.labelLines.length * item.labelLineHeight + item.labelGap : 0)
+  };
+}
+
+function compactProjectedPositions(items, nodes, scale) {
+  if (items.length < 2) return;
+  const sizes = items.map(item => Math.max(item.width, item.height)).sort((a, b) => a - b);
+  const minimumSpan = Math.max(80, sizes[Math.floor(sizes.length / 2)]) * Math.sqrt(items.length) * 1.5;
+  // Turning a deep model can turn depth into thousands of empty diagram pixels.
+  // Bound only the center positions, leaving each face and label at full size.
+  for (const [diagramAxis, worldAxis] of [["x", "x"], ["y", "y"]]) {
+    const projected = items.map(item => item[diagramAxis]);
+    const first = Math.min(...projected), last = Math.max(...projected);
+    const span = last - first;
+    if (!span) continue;
+    const frontal = items.map(item => nodes.get(item.id).group.position[worldAxis] * scale);
+    const frontalSpan = Math.max(...frontal) - Math.min(...frontal);
+    const factor = Math.min(1, Math.max(frontalSpan, minimumSpan) / span);
+    const middle = (first + last) / 2;
+    for (const item of items) item[diagramAxis] = middle + (item[diagramAxis] - middle) * factor;
+  }
+}
+
+function compactWithinContainers(items, nodes, scale) {
+  const groups = new Map();
+  for (const item of items) {
+    let node = nodes.get(item.id), root = null, guard = 0;
+    while (node?.parent && guard++ < nodes.size) {
+      node = nodes.get(node.parent);
+      if (node?.type === "container" || node?.type === "shell") root = node.id;
+    }
+    if (!root) continue;
+    if (!groups.has(root)) groups.set(root, []);
+    groups.get(root).push(item);
+  }
+  for (const group of groups.values()) compactProjectedPositions(group, nodes, scale);
+  return groups;
+}
+
+function compactRootBlocks(blocks, gap, aspect) {
+  if (blocks.length < 2) return null;
+  const left = Math.min(...blocks.map(block => block.box.minX));
+  const right = Math.max(...blocks.map(block => block.box.maxX));
+  const top = Math.min(...blocks.map(block => block.box.minY));
+  const bottom = Math.max(...blocks.map(block => block.box.maxY));
+  const currentWidth = right - left, currentHeight = bottom - top;
+  const score = (width, height) => Math.max(width / aspect, height);
+  const area = blocks.reduce((sum, block) => sum +
+    (block.box.maxX - block.box.minX + gap) * (block.box.maxY - block.box.minY + gap), 0);
+  const target = Math.sqrt(area * aspect);
+  const orders = [
+    [...blocks].sort((a, b) => (a.box.minY + a.box.maxY) - (b.box.minY + b.box.maxY)),
+    [...blocks].sort((a, b) => (a.box.minX + a.box.maxX) - (b.box.minX + b.box.maxX))
+  ];
+  let best = null;
+  for (const order of orders) for (const ratio of [.8, 1, 1.2, 1.5, 1.9]) {
+    const limit = target * ratio;
+    let x = 0, y = 0, rowHeight = 0, width = 0;
+    const placements = new Map();
+    for (const block of order) {
+      const w = block.box.maxX - block.box.minX;
+      const h = block.box.maxY - block.box.minY;
+      if (x && x + w > limit) { x = 0; y += rowHeight + gap; rowHeight = 0; }
+      placements.set(block, { x, y });
+      width = Math.max(width, x + w);
+      rowHeight = Math.max(rowHeight, h);
+      x += w + gap;
+    }
+    const height = y + rowHeight;
+    const candidate = { placements, width, height, score: score(width, height) };
+    if (!best || candidate.score < best.score) best = candidate;
+  }
+  if (best.score >= score(currentWidth, currentHeight) * .88
+    || best.width * best.height >= currentWidth * currentHeight * 1.15) return null;
+  return best.placements;
+}
+
+/** Vector front views of the already laid out 3D nodes, projected onto one orthographic plane. */
+export function renderDiagramSvg(atlas, options = {}) {
+  if (!atlas?.nodes || !atlas?.camera) throw new TypeError("An initialized Atlas instance is required.");
+  const scale = Math.max(1, Number(options.scale) || 80);
+  const gap = Math.max(0, Number(options.gap) || 0);
+  const observerScale = Number(options.observerScale) > 0 ? Number(options.observerScale) : null;
+  // Fit can start from a huge rotated page. Without a ceiling, its tiny preview
+  // scale inflates labels and container margins, making the next page even larger.
+  const labelScale = observerScale ? Math.max(.2, observerScale) : null;
+  const labelFontSize = labelScale ? 12 / labelScale : 18;
+  const labelLineHeight = labelScale ? 15 / labelScale : 21;
+  const labelGap = labelScale ? 4 / labelScale : 7;
+  // The diagram starts from the model's canonical front, independently of the
+  // interactive 3D camera. A caller can supply another orientation explicitly.
+  const view = options.cameraView || { position: [0, 0, 1], target: [0, 0, 0] };
+  const camera = new THREE.PerspectiveCamera();
+  camera.position.fromArray(view.position);
+  camera.lookAt(new THREE.Vector3().fromArray(view.target));
+  const right = new THREE.Vector3(1, 0, 0).applyQuaternion(camera.quaternion);
+  const up = new THREE.Vector3(0, 1, 0).applyQuaternion(camera.quaternion);
+  const forward = new THREE.Vector3(0, 0, 1).applyQuaternion(camera.quaternion);
+  const target = new THREE.Vector3().fromArray(view.target);
+  const include = options.includeIds ? new Set(options.includeIds) : null;
+  const groups = options.relationGroups ? new Set(options.relationGroups) : null;
+  const focused = options.focus?.ids?.length ? new Set(options.focus.ids) : null;
+  const hiddenByFocus = id => focused && options.focus.effect === "hide" && !focused.has(id);
+  const dimmed = id => focused && !focused.has(id) ? round(options.focus.opacity ?? .2) : 1;
+  const reflowFocus = options.focus?.layout === "reflow";
+  const isContainer = node => node.type === "container" || node.type === "shell";
+  const isClosed = node => isContainer(node) && atlas.open && !atlas.open.has(node.id);
+  const independent = atlas.viewMode === "2d" && typeof atlas._isVisible === "function";
+  const isVisible = node => independent ? atlas._isVisible(node) : node.group?.visible;
+  const depth = Array.isArray(options.depth) ? options.depth : [-Infinity, Infinity];
+  let items = [];
+  const warnings = [];
+  for (const node of atlas.nodes.values()) {
+    if (include && !include.has(node.id)) continue;
+    if (!isVisible(node) || (isContainer(node) && !isClosed(node))) continue;
+    if (reflowFocus && hiddenByFocus(node.id)) continue;
+    const origin = node.group.position.clone().sub(target);
+    const distance = origin.dot(forward);
+    if (distance < depth[0] || distance > depth[1]) continue;
+    const faceCache = options.faceCache;
+    let face = faceCache?.has(node) ? faceCache.get(node) : frontFaces(node, independent);
+    if (faceCache && !faceCache.has(node)) faceCache.set(node, face);
+    if (!face) { warnings.push(`${node.id}: no vector front face`); continue; }
+    // The 3D renderer can leave an opened shell's material translucent when
+    // switching to 2D. A closed container is a solid diagram entity.
+    if (isClosed(node)) face = {
+      ...face,
+      triangles: face.triangles.map(triangle => ({ ...triangle, opacity: 1 })),
+      textured: face.textured.map(triangle => ({ ...triangle, opacity: 1 }))
+    };
+    if (face.unsupportedTexture) warnings.push(`${node.id}: some image texture could not be embedded`);
+    const lines = options.labels === false ? [] : labelLines(node.name || "");
+    const geometryWidth = (face.bounds.maxX - face.bounds.minX) * scale;
+    const geometryHeight = (face.bounds.maxY - face.bounds.minY) * scale;
+    items.push({ id: node.id, name: node.name || "", x: origin.dot(right) * scale,
+      y: -origin.dot(up) * scale, scale, depth: distance, ...face, labelLines: lines,
+      labelFontSize, labelLineHeight, labelGap,
+      width: geometryWidth, height: geometryHeight });
+  }
+  if (options.cameraFrame && items.length) {
+    const { zoom = 1, aspect = 1 } = options.cameraFrame;
+    const ratio = Math.max(.25, Math.min(8, Number(zoom) || 1));
+    const frameAspect = Math.max(.25, Math.min(5, Number(aspect) || 1));
+    const positions = [...atlas.nodes.values()].filter(node => isVisible(node)
+      && (!isContainer(node) || isClosed(node))).map(node => node.group.position);
+    const sceneCenter = new THREE.Vector3(...["x", "y", "z"].map(axis => (
+      Math.min(...positions.map(point => point[axis])) + Math.max(...positions.map(point => point[axis]))
+    ) / 2)).sub(target);
+    const centerX = sceneCenter.dot(right) * scale;
+    const centerY = -sceneCenter.dot(up) * scale;
+    const bounds = items.map(item => itemBounds(item, false));
+    const halfX = Math.max(80, ...bounds.flatMap(box => [Math.abs(box.minX - centerX), Math.abs(box.maxX - centerX)]));
+    const halfY = Math.max(80, ...bounds.flatMap(box => [Math.abs(box.minY - centerY), Math.abs(box.maxY - centerY)]));
+    const halfHeight = Math.max(halfY, halfX / frameAspect) * 1.1 / ratio;
+    const halfWidth = halfHeight * frameAspect;
+    items = items.filter(item => {
+      const box = itemBounds(item, false);
+      return box.minX <= halfWidth && box.maxX >= -halfWidth
+        && box.minY <= halfHeight && box.maxY >= -halfHeight;
+    });
+  }
+  const itemGroups = compactWithinContainers(items, atlas.nodes, scale);
+  compactProjectedPositions(items, atlas.nodes, scale);
+  if (forward.z < .97 && itemGroups.size) {
+    const groupedItems = new Set([...itemGroups.values()].flat());
+    for (const group of itemGroups.values()) separateOverlaps(group, gap);
+    separateOverlaps(items.filter(item => !groupedItems.has(item)), gap);
+  } else separateOverlaps(items, gap);
+  const byId = new Map(items.map(item => [item.id, item]));
+  const activeRelations = options.relationIndexes == null ? null : new Set(options.relationIndexes);
+  const visible = atlas.relations.filter((relation, index) => byId.has(relation.from) && byId.has(relation.to)
+    && (!activeRelations || activeRelations.has(index))
+    && (!groups || groups.has(relation.group || "default"))
+    && (options.relationFocusId == null || relation.from === options.relationFocusId || relation.to === options.relationFocusId)
+    && !(hiddenByFocus(relation.from) || hiddenByFocus(relation.to))
+    && options.relations !== "none"
+    && (options.relations !== "within" || atlas.nodes.get(relation.from)?.parent === atlas.nodes.get(relation.to)?.parent));
+  const padding = Math.max(12, Number(options.padding) || 24);
+  const containers = [...atlas.nodes.values()].filter(node => isContainer(node) && isVisible(node) && !isClosed(node)
+    && !(reflowFocus && hiddenByFocus(node.id)));
+  const containerFontSize = labelScale ? 11 / labelScale : 18;
+  const sidePadding = labelScale ? Math.max(23, 10 / labelScale) : 23;
+  const topPadding = labelScale ? Math.max(41, 22 / labelScale) : 41;
+  const bottomPadding = labelScale ? Math.max(23, 10 / labelScale) : 23;
+  const containerDepth = node => {
+    let level = 0, parent = node.parent, guard = 0;
+    while (parent && guard++ < atlas.nodes.size) { level++; parent = atlas.nodes.get(parent)?.parent; }
+    return level;
+  };
+  const buildBoxes = () => {
+    const boxes = new Map();
+    for (const node of containers.sort((a, b) => containerDepth(b) - containerDepth(a))) {
+      const members = [
+        ...items.filter(item => atlas.nodes.get(item.id)?.parent === node.id).map(item => itemBounds(item, options.labels !== false)),
+        ...containers.filter(child => child.parent === node.id && boxes.has(child.id)).map(child => boxes.get(child.id))
+      ];
+      if (!members.length) continue;
+      let minX = Math.min(...members.map(box => box.minX)) - sidePadding;
+      let maxX = Math.max(...members.map(box => box.maxX)) + sidePadding;
+      const titleWidth = (node.name || node.id).length * containerFontSize * .72 + 2 * sidePadding;
+      if (maxX - minX < titleWidth) {
+        const extra = (titleWidth - (maxX - minX)) / 2;
+        minX -= extra;
+        maxX += extra;
+      }
+      boxes.set(node.id, { node, minX, maxX,
+        minY: Math.min(...members.map(box => box.minY)) - topPadding,
+        maxY: Math.max(...members.map(box => box.maxY)) + bottomPadding });
+    }
+    return boxes;
+  };
+  let boxes = buildBoxes();
+  const rootGroups = containers.filter(node => boxes.has(node.id) && !boxes.has(node.parent));
+  const rootMembers = new Map(rootGroups.map(root => [root.id, items.filter(item => {
+    let parent = atlas.nodes.get(item.id)?.parent, guard = 0;
+    while (parent && guard++ < atlas.nodes.size) {
+      if (parent === root.id) return true;
+      parent = atlas.nodes.get(parent)?.parent;
+    }
+    return false;
+  })]));
+  const groupGap = labelScale ? 8 / labelScale : gap;
+  for (let iteration = 0; iteration < 24; iteration += 1) {
+    let moved = false;
+    for (let i = 0; i < rootGroups.length; i += 1) for (let j = i + 1; j < rootGroups.length; j += 1) {
+      const a = boxes.get(rootGroups[i].id), b = boxes.get(rootGroups[j].id);
+      const overlapX = Math.min(a.maxX, b.maxX) - Math.max(a.minX, b.minX) + groupGap;
+      const overlapY = Math.min(a.maxY, b.maxY) - Math.max(a.minY, b.minY) + groupGap;
+      if (overlapX <= 0 || overlapY <= 0) continue;
+      const axis = overlapX < overlapY ? "x" : "y";
+      const centerA = (a[axis === "x" ? "minX" : "minY"] + a[axis === "x" ? "maxX" : "maxY"]) / 2;
+      const centerB = (b[axis === "x" ? "minX" : "minY"] + b[axis === "x" ? "maxX" : "maxY"]) / 2;
+      const push = (axis === "x" ? overlapX : overlapY) / 2 + .01;
+      const sign = centerA <= centerB ? 1 : -1;
+      for (const item of rootMembers.get(rootGroups[i].id)) item[axis] -= sign * push;
+      for (const item of rootMembers.get(rootGroups[j].id)) item[axis] += sign * push;
+      boxes = buildBoxes();
+      moved = true;
+    }
+    if (!moved) break;
+  }
+  const grouped = new Set([...rootMembers.values()].flat());
+  const blocks = rootGroups.map(root => ({ box: boxes.get(root.id), members: rootMembers.get(root.id) }));
+  for (const item of items) if (!grouped.has(item)) {
+    blocks.push({ box: itemBounds(item, options.labels !== false), members: [item] });
+  }
+  // Keep the canonical front's authored grouping. A turned camera can spread
+  // those same root groups across a very large page, so arrange the already
+  // resolved group rectangles into a compact reading surface.
+  const placement = forward.z < .97 ? compactRootBlocks(blocks, groupGap,
+    Math.max(.5, Math.min(3, Number(options.cameraFrame?.aspect) || 1.7))) : null;
+  if (placement) {
+    for (const block of blocks) {
+      const position = placement.get(block);
+      for (const item of block.members) {
+        item.x += position.x - block.box.minX;
+        item.y += position.y - block.box.minY;
+      }
+    }
+    boxes = buildBoxes();
+  }
+  // Captured diagrams keep the user's chosen 2D arrangement independently of
+  // later changes to the packing heuristic or viewport aspect.
+  if (options.placements && typeof options.placements === "object") {
+    for (const item of items) {
+      const position = options.placements[item.id];
+      if (Array.isArray(position) && position.length === 2 && position.every(Number.isFinite)) {
+        item.x = position[0];
+        item.y = position[1];
+      }
+    }
+    boxes = buildBoxes();
+  }
+  const extent = [...items.map(item => itemBounds(item, options.labels !== false)), ...boxes.values()];
+  const left = (extent.length ? Math.min(...extent.map(box => box.minX)) : 0) - padding;
+  const top = (extent.length ? Math.min(...extent.map(box => box.minY)) : 0) - padding;
+  const rightEdge = (extent.length ? Math.max(...extent.map(box => box.maxX)) : 0) + padding;
+  const bottom = (extent.length ? Math.max(...extent.map(box => box.maxY)) : 0) + padding;
+  const width = Math.max(1, Math.ceil(rightEdge - left));
+  const height = Math.max(1, Math.ceil(bottom - top));
+  if (options.measureOnly) return { width, height, warnings };
+  const fmt = p => `${round(p.x - left)} ${round(p.y - top)}`;
+  const relations = visible.map(relation => {
+    const a = byId.get(relation.from);
+    const b = byId.get(relation.to);
+    if (a === b) return "";
+    const start = rayBoundary(a, b);
+    const end = rayBoundary(b, a);
+    const mode = relationMode(relation);
+    const id = escapeXml(relation.id || `${relation.from}-${relation.to}`);
+    const opacity = Math.min(dimmed(relation.from), dimmed(relation.to));
+    const alpha = opacity < 1 ? ` opacity="${opacity}"` : "";
+    if (mode === "broken") {
+      const length = Math.hypot(end.x - start.x, end.y - start.y);
+      const gap = Math.min(16, length * .3);
+      const ratio = length ? gap / (2 * length) : 0;
+      const midpoint = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
+      const before = { x: midpoint.x - (end.x - start.x) * ratio,
+        y: midpoint.y - (end.y - start.y) * ratio };
+      const after = { x: midpoint.x + (end.x - start.x) * ratio,
+        y: midpoint.y + (end.y - start.y) * ratio };
+      return `<path data-relation="${id}" data-mode="broken" d="M${fmt(start)} L${fmt(before)} M${fmt(after)} L${fmt(end)}" fill="none" stroke="#c43748" stroke-width="2.5" stroke-dasharray="6 4" stroke-linecap="round"${alpha}/>`;
+    }
+    return `<path data-relation="${id}" data-mode="${mode}" d="M${fmt(start)} L${fmt(end)}" fill="none" stroke="${escapeXml(options.connectionColor || "#58788d")}" stroke-width="2"${mode === "bidirectional" ? ' marker-start="url(#atlas-diagram-arrow)"' : ""} marker-end="url(#atlas-diagram-arrow)"${alpha}/>`;
+  }).join("");
+  const canvasColor = options.canvasColor || "#f5f5f5";
+  const boxBackdrops = new Map();
+  const containersSvg = [...boxes.values()].sort((a, b) => containerDepth(a.node) - containerDepth(b.node)).map(box => {
+    if (hiddenByFocus(box.node.id)) return "";
+    const baseColor = box.node.material?.color || new THREE.Color("#58788d");
+    const color = `#${baseColor.getHexString()}`;
+    const ink = `#${baseColor.clone().lerp(new THREE.Color("#254253"), .48).getHexString()}`;
+    let parent = box.node.parent, guard = 0;
+    while (parent && !boxBackdrops.has(parent) && guard++ < atlas.nodes.size) parent = atlas.nodes.get(parent)?.parent;
+    const parentBackdrop = boxBackdrops.get(parent) || canvasColor;
+    const backdrop = blendHex(parentBackdrop, color, .14);
+    boxBackdrops.set(box.node.id, backdrop);
+    const x = round(box.minX - left);
+    const y = round(box.minY - top);
+    const labelX = labelScale ? round(8 / labelScale) : 12;
+    const labelY = labelScale ? round(14 / labelScale) : 26;
+    const fill = options.maskGrid ? `fill="${backdrop}"` : `fill="${color}" fill-opacity="0.14"`;
+    const underlay = options.maskGrid && dimmed(box.node.id) < 1
+      ? `<rect x="${x}" y="${y}" width="${round(box.maxX - box.minX)}" height="${round(box.maxY - box.minY)}" rx="12" fill="${parentBackdrop}"/>` : "";
+    return `${underlay}<g data-container="${escapeXml(box.node.id)}"${dimmed(box.node.id) < 1 ? ` opacity="${dimmed(box.node.id)}"` : ""}><title>${escapeXml(box.node.name || box.node.id)}</title><rect x="${x}" y="${y}" width="${round(box.maxX - box.minX)}" height="${round(box.maxY - box.minY)}" rx="12" ${fill} stroke="${ink}" stroke-opacity="0.72" stroke-width="2"/><g data-diagram-label="container" transform="translate(${x} ${y})"><text x="${labelX}" y="${labelY}" font-family="system-ui,sans-serif" font-size="${round(containerFontSize)}" font-weight="600" fill="${ink}">${escapeXml(box.node.name || box.node.id)}</text></g></g>`;
+  }).join("");
+  const entities = items.sort((a, b) => a.depth - b.depth).map(item => {
+    if (hiddenByFocus(item.id)) return "";
+    let parent = atlas.nodes.get(item.id)?.parent, guard = 0;
+    while (parent && !boxBackdrops.has(parent) && guard++ < atlas.nodes.size) parent = atlas.nodes.get(parent)?.parent;
+    const mask = options.maskGrid && !boxBackdrops.has(parent) && item.hull.length > 2
+      ? `<polygon points="${item.hull.map(point => `${round(point.x * scale)},${round(-point.y * scale)}`).join(" ")}" fill="${escapeXml(canvasColor)}"/>` : "";
+    const paths = [...item.triangles, ...item.textured].sort((a, b) => a.depth - b.depth).map((triangle, index) => {
+      if (triangle.image) {
+        const clipId = `atlas-clip-${escapeXml(item.id).replace(/[^a-zA-Z0-9_-]/g, "-")}-${index}`;
+        const hull = convexHull(triangle.points.map(point => ({ x: point.x, y: point.y })));
+        const clipPoints = hull.map(point => `${round(point.x * scale)},${round(-point.y * scale)}`).join(" ");
+        const [a, b, c, d, e, f] = triangle.transform.map(value => round(value * scale));
+        return `<defs><clipPath id="${clipId}"><polygon points="${clipPoints}"/></clipPath></defs><g clip-path="url(#${clipId})"><image href="${triangle.image.uri}" width="${triangle.image.width}" height="${triangle.image.height}" transform="matrix(${a} ${b} ${c} ${d} ${e} ${f})" opacity="${round(triangle.opacity)}"/></g>`;
+      }
+      const p = triangle.vertices.map(point => `${round(point.x * scale)},${round(-point.y * scale)}`).join(" ");
+      const stroke = triangle.opacity < 1 ? "" : ` stroke="${triangle.color}" stroke-width="0.8" stroke-linejoin="round"`;
+      return `<polygon points="${p}" fill="${triangle.color}"${stroke}${triangle.opacity < 1 ? ` opacity="${round(triangle.opacity)}"` : ""}/>`;
+    }).join("");
+    const labelBottom = round(-item.bounds.minY * scale);
+    const label = options.labels === false || !item.labelLines.length ? "" : `<g data-diagram-label="entity" transform="translate(0 ${labelBottom})">${item.labelLines.map((line, i) => `<text x="0" y="${round(item.labelGap + item.labelFontSize + i * item.labelLineHeight)}" text-anchor="middle" font-family="system-ui,sans-serif" font-size="${round(item.labelFontSize)}" fill="${escapeXml(options.labelColor || "#172c3a")}">${escapeXml(line)}</text>`).join("")}</g>`;
+    const transform = `translate(${round(item.x - left)} ${round(item.y - top)})`;
+    return `${mask ? `<g transform="${transform}" pointer-events="none">${mask}</g>` : ""}<g data-entity="${escapeXml(item.id)}" transform="${transform}"${dimmed(item.id) < 1 ? ` opacity="${dimmed(item.id)}"` : ""}><title>${escapeXml(item.name || item.id)}</title>${paths}${label}</g>`;
+  }).join("");
+  const background = options.background ? `<rect width="100%" height="100%" fill="${escapeXml(options.background)}"/>` : "";
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}"><defs><marker id="atlas-diagram-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10Z" fill="${escapeXml(options.connectionColor || "#58788d")}"/></marker></defs>${background}<g class="containers">${containersSvg}</g><g class="relations">${relations}</g><g class="entities">${entities}</g></svg>`;
+  return { svg, width, height, warnings, items: items.map(({ id, x, y, width: w, height: h }) => ({ id, x: round(x - left), y: round(y - top), width: round(w), height: round(h) })) };
+}
+
+export async function diagramSvgToPng(svg, ownerDocument = globalThis.document) {
+  const image = new Image();
+  const blob = new Blob([svg], { type: "image/svg+xml;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  try {
+    await new Promise((resolve, reject) => {
+      image.onload = resolve;
+      image.onerror = () => reject(new Error("Could not rasterize Atlas Diagram SVG."));
+      image.src = url;
+    });
+    const canvas = ownerDocument.createElement("canvas");
+    canvas.width = image.naturalWidth;
+    canvas.height = image.naturalHeight;
+    canvas.getContext("2d").drawImage(image, 0, 0);
+    return canvas;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}