@liquidcars/atlas 0.1.48 → 0.1.49

package/src/liquidcars-atlas.js

@@ -1,5 +1,11 @@
 import * as THREE from "./three.module.js";
 import atlasPackage from "../package.json" with { type: "json" };
+import { renderDiagramSvg, diagramSvgToPng } from "./diagram-svg.js";
+import { DiagramView, DIAGRAM_VIEW_CSS, DIAGRAM_TOOLBAR } from "./diagram-view.js";
+
+export { renderDiagramSvg, diagramSvgToPng };
+import { resolveAtlasReference } from "./document-navigation.js";
+import { renderPanelContent } from "./panel-content.js";
 
 // This value is bundled from the package manifest, so it always identifies
 // the Atlas module that is actually executing rather than the host
@@ -349,6 +355,8 @@ const CSS = [
 
 const TOOLBAR_CSS = ".toolbar{max-width:calc(100% - 16px);overflow:visible}.toolbar-group{display:flex;align-items:center;gap:2px}.toolbar-group+.toolbar-group{padding-left:6px;border-left:1px solid #38515f}.toolbar .toolbar-icon{display:grid;width:30px;padding:0;place-items:center}.toolbar-icon svg,.toolbar-menu>summary svg{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:1.7;stroke-linecap:round;stroke-linejoin:round}.toolbar-menu{position:relative}.toolbar-menu>summary{display:flex;align-items:center;height:30px;padding:0 8px;gap:6px;border-radius:5px;color:var(--lc-toolbar-text,#dbe7ec);cursor:pointer;list-style:none;user-select:none}.toolbar-menu>summary::-webkit-details-marker{display:none}.toolbar-menu>summary:hover,.toolbar-menu[open]>summary{background:var(--lc-toolbar-active,#1f3d4b);color:var(--lc-toolbar-active-text,#c5f2e9)}.toolbar-menu-status{max-width:92px;overflow:hidden;font-size:11px;text-overflow:ellipsis;white-space:nowrap}.toolbar-menu-chevron{width:10px;height:10px!important;transition:transform .16s ease}.toolbar-menu[open] .toolbar-menu-chevron{transform:rotate(180deg)}.toolbar-popover{position:absolute;right:0;bottom:calc(100% + 8px);display:grid;min-width:218px;padding:6px;border:1px solid var(--lc-toolbar-border,#3a5062);border-radius:9px;background:var(--lc-toolbar-bg,#15232ff7);box-shadow:0 14px 36px #0009}.toolbar-popover-title{padding:7px 9px 5px;color:var(--lc-hint,#8da6b8);font-size:9px;font-weight:700;letter-spacing:.1em;text-transform:uppercase}.toolbar .toolbar-option{display:grid;grid-template-columns:minmax(0,1fr) 18px;align-items:center;width:100%;height:auto;min-height:34px;padding:7px 9px;text-align:left}.toolbar-option span:first-child{overflow:hidden;text-overflow:ellipsis}.toolbar-option-check{color:var(--lc-toolbar-active-text,#c5f2e9);font-weight:700;text-align:center;visibility:hidden}.toolbar-option.active .toolbar-option-check{visibility:visible}.toolbar-option-separator{height:1px;margin:5px 7px;background:#38515f}.toolbar button[disabled]{opacity:.42;cursor:not-allowed}@media(max-width:620px){.toolbar-menu-status{display:none}.toolbar-menu>summary{width:30px;padding:0;justify-content:center}.toolbar-menu-chevron{display:none}.toolbar-group+.toolbar-group{padding-left:3px}.toolbar-popover{right:-4px}}";
 
+const NAVIGATION_CSS = ".toolbar-group[data-toolbar-group=navigation]{position:relative}.toolbar-group[hidden]{display:none}.atlas-history-popover{position:absolute;left:0;bottom:calc(100% + 8px);min-width:250px;max-width:min(360px,80vw);max-height:300px;overflow:auto;padding:6px;border:1px solid var(--lc-toolbar-border,#3a5062);border-radius:9px;background:var(--lc-toolbar-bg,#15232ff7);box-shadow:0 14px 36px #0009;z-index:12}.atlas-history-popover[hidden]{display:none}.atlas-history-popover .history-heading{padding:7px 9px 5px;color:var(--lc-hint,#8da6b8);font-size:10px;text-transform:uppercase;letter-spacing:.1em}.toolbar .atlas-history-popover button{display:block;width:100%;height:auto;padding:8px 9px;text-align:left;white-space:normal;overflow-wrap:anywhere}.atlas-history-popover small{display:block;opacity:.65;font-size:10px}.atlas-jump{position:absolute;z-index:9;display:grid;place-items:center;width:34px;height:34px;border:1px solid #73d9c7;border-radius:50%;background:#173e49;color:#c8fff2;box-shadow:0 4px 16px #0009;cursor:pointer}.atlas-jump[hidden]{display:none}.atlas-jump:hover,.atlas-jump:focus-visible{background:#286776;outline:2px solid #c8fff2}.atlas-jump svg{width:18px;height:18px;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}.panel .rich-content{color:var(--lc-panel-text,#b5c6d2);font-size:14px;line-height:1.55}.panel .rich-content h1,.panel .rich-content h2,.panel .rich-content h3{color:var(--lc-panel-title,#e9f0f5);letter-spacing:normal;margin:14px 0 8px}.panel .rich-content a{color:#6ad7c0}.panel .rich-content pre{overflow:auto;padding:8px;background:#091622;border-radius:5px}.panel .rich-content code{font-size:.9em}.panel .rich-content ul,.panel .rich-content ol{padding-left:20px}";
+const DOCUMENT_NAV_CSS = ".document-navigation{position:absolute;top:12px;right:12px;z-index:10;display:flex;padding:5px;border:1px solid var(--lc-toolbar-border,#3a5062);border-radius:8px;background:var(--lc-toolbar-bg,#15232fe8)}.document-navigation[hidden],:host([navigation-controls=external]) .document-navigation{display:none!important}.document-navigation button{display:grid;width:30px;height:30px;place-items:center;padding:0;border:0;border-radius:5px;background:none;color:var(--lc-toolbar-text,#dbe7ec);cursor:pointer}.document-navigation button:hover{background:var(--lc-toolbar-active,#1f3d4b);color:var(--lc-toolbar-active-text,#c5f2e9)}.document-navigation button:disabled{opacity:.42;cursor:not-allowed}.document-navigation svg{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:1.7;stroke-linecap:round;stroke-linejoin:round}.document-navigation .atlas-history-popover{top:calc(100% + 8px);right:0;bottom:auto;left:auto}.document-navigation .atlas-history-popover button{display:block;width:100%;height:auto;padding:8px 9px;text-align:left;white-space:normal;overflow-wrap:anywhere}@media print{.document-navigation,.atlas-jump{display:none!important}}";
 const PRINT_CSS = [
   ".viewport>.atlas-print-snapshot{display:none!important}",
   "@media print{",
@@ -370,6 +378,9 @@ const TOOLBAR_ICONS = {
   relations: toolbarIcon('<circle cx="5" cy="6" r="2"/><circle cx="19" cy="7" r="2"/><circle cx="12" cy="18" r="2"/><path d="m6.8 6.3 10.2.5M6.2 7.7l4.6 8.6m6.8-7.5-4.4 7.5"/>'),
   focus: toolbarIcon('<circle cx="12" cy="12" r="7"/><circle cx="12" cy="12" r="2.5"/><path d="M12 2v3M12 19v3M2 12h3M19 12h3"/>'),
   copy: toolbarIcon('<rect x="8" y="8" width="11" height="11" rx="2"/><path d="M16 8V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h2"/>'),
+  home: toolbarIcon('<path d="m3 11 9-7 9 7"/><path d="M5 10v10h14V10M10 20v-6h4v6"/>'),
+  back: toolbarIcon('<path d="m15 5-7 7 7 7"/>'),
+  forward: toolbarIcon('<path d="m9 5 7 7-7 7"/>'),
   chevron: toolbarIcon('<path d="m8 10 4 4 4-4"/>')
 };
 
@@ -391,7 +402,7 @@ export function focusMovesOutside(container, event) {
 const toolbarMenu = (id, icon, label, status, content) => `<details class="toolbar-menu" data-toolbar-menu="${id}"><summary aria-label="${label}" title="${label}">${icon}<span class="toolbar-menu-status" data-toolbar-status="${id}" aria-live="polite">${status}</span>${TOOLBAR_ICONS.chevron}</summary><div class="toolbar-popover" role="menu"><div class="toolbar-popover-title">${label}</div>${content}</div></details>`;
 const COPY_TOOLBAR_MARKUP = `<div class="toolbar-group" data-toolbar-group="copy">${toolbarMenu("copy", TOOLBAR_ICONS.copy, "Copy image", "PNG", toolbarAction("copy-theme", "PNG with background · HD 2×") + toolbarAction("copy-transparent", "Transparent PNG · HD 2×"))}</div>`;
 
-const TEMPLATE = `<div class="atlas"><section class="viewport"><canvas tabindex="0" aria-label="Interactive 3D model"></canvas><div class="toolbar" role="toolbar" aria-label="View controls"><div class="toolbar-group" data-toolbar-group="camera"><button class="toolbar-icon" data-action="minus" aria-label="Zoom out" title="Zoom out">${TOOLBAR_ICONS.minus}</button><button class="toolbar-icon" data-action="plus" aria-label="Zoom in" title="Zoom in">${TOOLBAR_ICONS.plus}</button><button class="toolbar-icon" data-action="fit" aria-label="Fit entire model" title="Fit entire model">${TOOLBAR_ICONS.fit}</button><button class="toolbar-icon" data-action="front" aria-label="Front view" title="Front view">${TOOLBAR_ICONS.front}</button></div><div class="toolbar-group" data-toolbar-group="view">${toolbarMenu("view", TOOLBAR_ICONS.view, "View", "View", toolbarOption("labels", "Labels", true) + toolbarOption("panel", "Information", true) + toolbarOption("item-facing", "Face camera", true) + '<div class="toolbar-option-separator"></div>' + toolbarOption("open-all", "Open all") + toolbarOption("close-all", "Close all"))}</div><div class="toolbar-group" data-toolbar-group="relations">${toolbarMenu("relations", TOOLBAR_ICONS.relations, "Relations", "Selection", toolbarOption("relations-all", "All") + toolbarOption("relations-selected", "Selection", true) + toolbarOption("relations-callers", "Upstream") + toolbarOption("relations-called", "Downstream") + toolbarOption("relations-none", "Hide") + '<div data-relation-groups-section hidden><div class="toolbar-option-separator"></div><div class="toolbar-popover-title">Groups</div><div data-relation-groups></div></div>')}</div><div class="toolbar-group" data-toolbar-group="focus">${toolbarMenu("focus", TOOLBAR_ICONS.focus, "Focus", "All", toolbarOption("focus-all", "All", true) + toolbarOption("focus-dim", "Connected") + toolbarOption("focus-hide", "Isolate") + '<div class="toolbar-option-separator"></div>' + toolbarOption("focus-selection", "Focus selection") + toolbarOption("focus-layout", "Reflow visible"))}</div></div><div class="hint">Rotate: drag · Pan: right button / ⇧+drag / 2 fingers · Zoom: wheel or pinch · Select: click · Focus: double-click</div></section><aside class="panel" aria-live="polite"></aside></div>`;
+const TEMPLATE = `<div class="atlas"><section class="viewport"><canvas tabindex="0" aria-label="Interactive 3D model"></canvas><button class="atlas-jump" data-action="atlas-jump" aria-label="Open linked Atlas" title="Open linked Atlas" hidden><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M10 13a5 5 0 0 0 7.1 0l2.1-2.1a5 5 0 0 0-7.1-7.1L10 6"/><path d="M14 11a5 5 0 0 0-7.1 0l-2.1 2.1a5 5 0 0 0 7.1 7.1L14 18"/></svg></button><div class="document-navigation" role="toolbar" aria-label="Atlas document navigation" hidden></div><div class="toolbar" role="toolbar" aria-label="View controls"><div class="toolbar-group" data-toolbar-group="navigation"><button class="toolbar-icon" data-action="atlas-home" aria-label="Atlas home" title="First Atlas document" disabled>${TOOLBAR_ICONS.home}</button><button class="toolbar-icon" data-action="atlas-back" aria-label="Atlas back" title="Back · hold for history" disabled>${TOOLBAR_ICONS.back}</button><button class="toolbar-icon" data-action="atlas-forward" aria-label="Atlas forward" title="Forward · hold for history" disabled>${TOOLBAR_ICONS.forward}</button><div class="atlas-history-popover" role="menu" aria-label="Atlas visits" hidden></div></div><div class="toolbar-group" data-toolbar-group="camera"><button class="toolbar-icon" data-action="minus" aria-label="Zoom out" title="Zoom out">${TOOLBAR_ICONS.minus}</button><button class="toolbar-icon" data-action="plus" aria-label="Zoom in" title="Zoom in">${TOOLBAR_ICONS.plus}</button><button class="toolbar-icon" data-action="fit" aria-label="Fit entire model" title="Fit entire model">${TOOLBAR_ICONS.fit}</button><button class="toolbar-icon" data-action="front" aria-label="Front view" title="Front view">${TOOLBAR_ICONS.front}</button></div><div class="toolbar-group" data-toolbar-group="view">${toolbarMenu("view", TOOLBAR_ICONS.view, "View", "View", toolbarOption("labels", "Labels", true) + toolbarOption("panel", "Information", true) + toolbarOption("item-facing", "Face camera", true) + '<div class="toolbar-option-separator"></div>' + toolbarOption("open-all", "Open all") + toolbarOption("close-all", "Close all"))}</div><div class="toolbar-group" data-toolbar-group="relations">${toolbarMenu("relations", TOOLBAR_ICONS.relations, "Relations", "Selection", toolbarOption("relations-all", "All") + toolbarOption("relations-selected", "Selection", true) + toolbarOption("relations-callers", "Upstream") + toolbarOption("relations-called", "Downstream") + toolbarOption("relations-none", "Hide") + '<div data-relation-groups-section hidden><div class="toolbar-option-separator"></div><div class="toolbar-popover-title">Groups</div><div data-relation-groups></div></div>')}</div><div class="toolbar-group" data-toolbar-group="focus">${toolbarMenu("focus", TOOLBAR_ICONS.focus, "Focus", "All", toolbarOption("focus-all", "All", true) + toolbarOption("focus-dim", "Connected") + toolbarOption("focus-hide", "Isolate") + '<div class="toolbar-option-separator"></div>' + toolbarOption("focus-selection", "Focus selection") + toolbarOption("focus-layout", "Reflow visible"))}</div></div><div class="hint">Rotate: drag · Pan: right button / ⇧+drag / 2 fingers · Zoom: wheel or pinch · Select: click · Focus: double-click</div></section><aside class="panel" aria-live="polite"></aside></div>`;
 
 function escapeHtml(value) {
   return String(value ?? "").replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
@@ -840,6 +851,57 @@ function partGeometry(part) {
   return makeGeometry(part.shape || part.geometry || "box", part.radius, part.segments, part.size);
 }
 
+// SVG images are rasterized for Three.js. Reuse a small set of those canvases
+// when Studio replaces one Atlas element with another, so the next diagram can
+// include its images in the very first SVG instead of showing empty planes.
+const geometryImageCache = new Map();
+const MAX_GEOMETRY_IMAGE_PIXELS = 12 * 1024 * 1024;
+let cachedGeometryImagePixels = 0;
+
+function cachedGeometryImage(source) {
+  const image = geometryImageCache.get(source);
+  if (image) {
+    geometryImageCache.delete(source);
+    geometryImageCache.set(source, image);
+  }
+  return image;
+}
+
+function rememberGeometryImage(source, canvas, aspect) {
+  if (!/^https?:\/\//i.test(source)) return;
+  const pixels = canvas.width * canvas.height;
+  if (pixels > MAX_GEOMETRY_IMAGE_PIXELS) return;
+  const previous = geometryImageCache.get(source);
+  if (previous) cachedGeometryImagePixels -= previous.canvas.width * previous.canvas.height;
+  geometryImageCache.delete(source);
+  geometryImageCache.set(source, { canvas, aspect });
+  cachedGeometryImagePixels += pixels;
+  while (cachedGeometryImagePixels > MAX_GEOMETRY_IMAGE_PIXELS) {
+    const oldest = geometryImageCache.keys().next().value;
+    cachedGeometryImagePixels -= geometryImageCache.get(oldest).canvas.width * geometryImageCache.get(oldest).canvas.height;
+    geometryImageCache.delete(oldest);
+  }
+}
+
+function fitGeometryImage(part, mesh, texture, imageAspect) {
+  const fit = part.imageFit || part.fit || "stretch";
+  const baseWidth = Math.abs(Number(part.size?.[0])) || 1;
+  const baseHeight = Math.abs(Number(part.size?.[1])) || 1;
+  const faceAspect = baseWidth / baseHeight;
+  if (fit === "cover") {
+    if (imageAspect > faceAspect) {
+      texture.repeat.set(faceAspect / imageAspect, 1);
+      texture.offset.set((1 - texture.repeat.x) / 2, 0);
+    } else {
+      texture.repeat.set(1, imageAspect / faceAspect);
+      texture.offset.set(0, (1 - texture.repeat.y) / 2);
+    }
+  } else if (fit === "contain" && mesh) {
+    if (imageAspect > faceAspect) mesh.scale.y = baseWidth / imageAspect;
+    else mesh.scale.x = baseHeight * imageAspect;
+  }
+}
+
 function createGeometryContent(definition, entity, modelPalette, invalidate, reportWarning) {
   const parameters = resolveGeometryParameters(entity, definition);
   const localPalette = {
@@ -879,110 +941,100 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
     let mesh;
     const icon = part.icon;
     const image = part.image;
+    let cachedImage = null;
     if (typeof image === "string" && image) {
-      const bitmap = new Image();
-      bitmap.crossOrigin = "anonymous";
-      material.map = new THREE.Texture(bitmap);
-      let cancelled = false;
-      let objectUrl = null;
-      let svgSource = /^\s*<svg(?:\s|>)/i.test(image) || /^data:image\/svg\+xml/i.test(image) || /\.svg(?:[?#]|$)/i.test(image);
-      const abortController = new AbortController();
-      const releaseObjectUrl = () => {
-        if (!objectUrl) return;
-        URL.revokeObjectURL(objectUrl);
-        objectUrl = null;
-      };
-      const removeListeners = () => {
-        bitmap.removeEventListener("load", onLoad);
-        bitmap.removeEventListener("error", onError);
-      };
-      const onLoad = () => {
-        removeListeners();
-        if (cancelled || !material.map) { releaseObjectUrl(); return; }
-        if (svgSource) {
+      cachedImage = cachedGeometryImage(image);
+      material.map = new THREE.Texture(cachedImage?.canvas || new Image());
+      if (!cachedImage) {
+        const bitmap = material.map.image;
+        bitmap.crossOrigin = "anonymous";
+        let cancelled = false;
+        let objectUrl = null;
+        let svgSource = /^\s*<svg(?:\s|>)/i.test(image) || /^data:image\/svg\+xml/i.test(image) || /\.svg(?:[?#]|$)/i.test(image);
+        const abortController = new AbortController();
+        const releaseObjectUrl = () => {
+          if (!objectUrl) return;
+          URL.revokeObjectURL(objectUrl);
+          objectUrl = null;
+        };
+        const removeListeners = () => {
+          bitmap.removeEventListener("load", onLoad);
+          bitmap.removeEventListener("error", onError);
+        };
+        const onLoad = () => {
+          removeListeners();
+          if (cancelled || !material.map) { releaseObjectUrl(); return; }
+          if (svgSource) {
+            try {
+              const aspect = (bitmap.naturalWidth || 1) / Math.max(1, bitmap.naturalHeight || 1);
+              const longestSide = 1024;
+              const canvas = document.createElement("canvas");
+              canvas.width = aspect >= 1 ? longestSide : Math.max(1, Math.round(longestSide * aspect));
+              canvas.height = aspect >= 1 ? Math.max(1, Math.round(longestSide / aspect)) : longestSide;
+              const context = canvas.getContext("2d");
+              if (!context) throw new Error("Canvas 2D is unavailable");
+              context.clearRect(0, 0, canvas.width, canvas.height);
+              context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
+              material.map.image = canvas;
+              rememberGeometryImage(image, canvas, bitmap.naturalWidth / Math.max(1, bitmap.naturalHeight));
+            } catch (error) {
+              reportWarning?.({ code: "SVG_RASTERIZE_FAILED", geometry: definition.id, entityId: entity.id, image, error });
+            }
+          }
+          releaseObjectUrl();
+          const imageAspect = bitmap.naturalWidth / Math.max(1, bitmap.naturalHeight);
+          fitGeometryImage(part, mesh, material.map, imageAspect);
+          material.map.needsUpdate = true;
+          invalidate?.();
+        };
+        const onError = () => {
+          removeListeners();
+          releaseObjectUrl();
+          if (!cancelled) {
+            reportWarning?.({ code: "IMAGE_LOAD_FAILED", geometry: definition.id, entityId: entity.id, image });
+            invalidate?.();
+          }
+        };
+        material.userData.atlasImageCleanup = () => {
+          cancelled = true;
+          abortController.abort();
+          removeListeners();
+          releaseObjectUrl();
+          bitmap.src = "";
+        };
+        bitmap.addEventListener("load", onLoad);
+        bitmap.addEventListener("error", onError);
+        const assignImageSource = async () => {
+          const inlineSvg = /^\s*<svg(?:\s|>)/i.test(image);
+          if (inlineSvg) {
+            objectUrl = URL.createObjectURL(new Blob([image], { type: "image/svg+xml" }));
+            bitmap.src = objectUrl;
+            return;
+          }
+          if (/^(?:data|blob):/i.test(image)) {
+            bitmap.src = image;
+            return;
+          }
           try {
-            const aspect = (bitmap.naturalWidth || 1) / Math.max(1, bitmap.naturalHeight || 1);
-            const longestSide = 1024;
-            const canvas = document.createElement("canvas");
-            canvas.width = aspect >= 1 ? longestSide : Math.max(1, Math.round(longestSide * aspect));
-            canvas.height = aspect >= 1 ? Math.max(1, Math.round(longestSide / aspect)) : longestSide;
-            const context = canvas.getContext("2d");
-            if (!context) throw new Error("Canvas 2D is unavailable");
-            context.clearRect(0, 0, canvas.width, canvas.height);
-            context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
-            material.map.image = canvas;
+            const response = await fetch(image, { mode: "cors", signal: abortController.signal });
+            if (!response.ok) throw new Error(`Image request failed with ${response.status}`);
+            let blob = await response.blob();
+            const contentType = response.headers.get("content-type") || blob.type;
+            const looksLikeSvg = /image\/svg\+xml/i.test(contentType) || /\.svg(?:[?#]|$)/i.test(image);
+            svgSource = svgSource || looksLikeSvg;
+            if (looksLikeSvg && blob.type !== "image/svg+xml") blob = new Blob([await blob.text()], { type: "image/svg+xml" });
+            if (cancelled) return;
+            objectUrl = URL.createObjectURL(blob);
+            bitmap.src = objectUrl;
           } catch (error) {
-            reportWarning?.({ code: "SVG_RASTERIZE_FAILED", geometry: definition.id, entityId: entity.id, image, error });
-          }
-        }
-        releaseObjectUrl();
-        const fit = part.imageFit || part.fit || "stretch";
-        const imageAspect = bitmap.naturalWidth / Math.max(1, bitmap.naturalHeight);
-        const baseWidth = Math.abs(Number(part.size?.[0])) || 1;
-        const baseHeight = Math.abs(Number(part.size?.[1])) || 1;
-        const faceAspect = baseWidth / baseHeight;
-        if (fit === "cover") {
-          if (imageAspect > faceAspect) {
-            material.map.repeat.set(faceAspect / imageAspect, 1);
-            material.map.offset.set((1 - material.map.repeat.x) / 2, 0);
-          } else {
-            material.map.repeat.set(1, imageAspect / faceAspect);
-            material.map.offset.set(0, (1 - material.map.repeat.y) / 2);
+            if (cancelled || error?.name === "AbortError") return;
+            // Preserve the previous direct-image behaviour as a fallback. The
+            // server must still permit cross-origin use for a WebGL texture.
+            bitmap.src = image;
           }
-        } else if (fit === "contain" && mesh) {
-          if (imageAspect > faceAspect) mesh.scale.y = baseWidth / imageAspect;
-          else mesh.scale.x = baseHeight * imageAspect;
-        }
-        material.map.needsUpdate = true;
-        invalidate?.();
-      };
-      const onError = () => {
-        removeListeners();
-        releaseObjectUrl();
-        if (!cancelled) {
-          reportWarning?.({ code: "IMAGE_LOAD_FAILED", geometry: definition.id, entityId: entity.id, image });
-          invalidate?.();
-        }
-      };
-      material.userData.atlasImageCleanup = () => {
-        cancelled = true;
-        abortController.abort();
-        removeListeners();
-        releaseObjectUrl();
-        bitmap.src = "";
-      };
-      bitmap.addEventListener("load", onLoad);
-      bitmap.addEventListener("error", onError);
-      const assignImageSource = async () => {
-        const inlineSvg = /^\s*<svg(?:\s|>)/i.test(image);
-        if (inlineSvg) {
-          objectUrl = URL.createObjectURL(new Blob([image], { type: "image/svg+xml" }));
-          bitmap.src = objectUrl;
-          return;
-        }
-        if (/^(?:data|blob):/i.test(image)) {
-          bitmap.src = image;
-          return;
-        }
-        try {
-          const response = await fetch(image, { mode: "cors", signal: abortController.signal });
-          if (!response.ok) throw new Error(`Image request failed with ${response.status}`);
-          let blob = await response.blob();
-          const contentType = response.headers.get("content-type") || blob.type;
-          const looksLikeSvg = /image\/svg\+xml/i.test(contentType) || /\.svg(?:[?#]|$)/i.test(image);
-          svgSource = svgSource || looksLikeSvg;
-          if (looksLikeSvg && blob.type !== "image/svg+xml") blob = new Blob([await blob.text()], { type: "image/svg+xml" });
-          if (cancelled) return;
-          objectUrl = URL.createObjectURL(blob);
-          bitmap.src = objectUrl;
-        } catch (error) {
-          if (cancelled || error?.name === "AbortError") return;
-          // Preserve the previous direct-image behaviour as a fallback. The
-          // server must still permit cross-origin use for a WebGL texture.
-          bitmap.src = image;
-        }
-      };
-      assignImageSource();
+        };
+        assignImageSource();
+      }
       material.map.colorSpace = THREE.SRGBColorSpace;
       material.needsUpdate = true;
     } else if (icon != null && icon !== "") {
@@ -993,6 +1045,7 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
     mesh = new THREE.Mesh(geometry, material);
     mesh.position.fromArray(Array.isArray(part.position) ? part.position : [0, 0, 0]);
     mesh.scale.fromArray(Array.isArray(part.size) ? part.size : [1, 1, 1]);
+    if (cachedImage) fitGeometryImage(part, mesh, material.map, cachedImage.aspect);
     if (Array.isArray(part.rotation)) mesh.rotation.set(...part.rotation.map(Number));
     root.add(mesh);
     meshes.push(mesh);
@@ -1327,8 +1380,11 @@ class LiquidCarsAtlas extends HTMLElement {
   constructor() {
     super();
     this.attachShadow({ mode: "open" });
-    this.shadowRoot.innerHTML = "<style>" + CSS + TOOLBAR_CSS + PRINT_CSS + "</style>" + TEMPLATE;
+    this.shadowRoot.innerHTML = "<style>" + CSS + TOOLBAR_CSS + NAVIGATION_CSS + DOCUMENT_NAV_CSS + PRINT_CSS + DIAGRAM_VIEW_CSS + "</style>" + TEMPLATE;
     this.shadowRoot.querySelector('[data-toolbar-group="focus"]')?.insertAdjacentHTML?.("afterend", COPY_TOOLBAR_MARKUP);
+    this.shadowRoot.querySelector('[data-toolbar-group="navigation"]')?.insertAdjacentHTML?.("afterend", '<div class="toolbar-group" data-toolbar-group="mode"><button data-action="view-mode" aria-label="Switch to 2D diagram" title="Switch to 2D diagram">2D</button></div>');
+    this.shadowRoot.querySelector('[data-toolbar-group="camera"]')?.insertAdjacentHTML?.("beforebegin", DIAGRAM_TOOLBAR);
+    this.shadowRoot.querySelector(".viewport")?.insertAdjacentHTML?.("afterbegin", '<div class="diagram-view" aria-label="Interactive 2D diagram" hidden><div class="diagram-content"></div></div>');
     this.canvas = this.shadowRoot.querySelector("canvas");
     this.panel = this.shadowRoot.querySelector(".panel");
     this.scene = new THREE.Scene();
@@ -1343,6 +1399,15 @@ class LiquidCarsAtlas extends HTMLElement {
     this.selected = null;
     this.selectedRelationIndex = null;
     this.modelData = null;
+    this.documentUri = null;
+    this.documentResolver = null;
+    this.contentResolver = null;
+    this._visits = [];
+    this._visitIndex = -1;
+    this._navigationToken = 0;
+    this._contentToken = 0;
+    this._historyPressTimer = null;
+    this._historyLongPress = false;
     this._loading = false;
     this._pendingSelection = null;
     // Custom elements must not add or mutate host attributes while their
@@ -1376,6 +1441,15 @@ class LiquidCarsAtlas extends HTMLElement {
     this._toolbarVisible = this.getAttribute("toolbar") !== "off";
     this._panelVisible = this.getAttribute("panel") !== "off";
     this.toolbar = this.shadowRoot.querySelector(".toolbar");
+    this.viewMode = "3d";
+    this.diagramView = new DiagramView(this);
+    this.navigationToolbar = this.shadowRoot.querySelector(".document-navigation");
+    this.navigationToolbar.append(this.toolbar.querySelector('[data-toolbar-group="navigation"]'));
+    this.jumpButton = this.shadowRoot.querySelector(".atlas-jump");
+    this.historyPopover = this.shadowRoot.querySelector(".atlas-history-popover");
+    this._outsideHistoryListener = event => {
+      if (!event.composedPath().includes(this.navigationToolbar)) this._closeHistoryPopover();
+    };
     this._copyStatusTimer = null;
     this._printState = null;
     this._beforePrintListener = () => this.prepareForPrint();
@@ -1386,16 +1460,24 @@ class LiquidCarsAtlas extends HTMLElement {
       if (this.ready && this.modelData) this._build();
     };
     this._bindControls();
+    this.panel.addEventListener("click", event => {
+      const link = event.target.closest?.("a[href^='atlas:'], [data-action='atlas-link']");
+      if (!link) return;
+      event.preventDefault();
+      void this.openAtlas(link.getAttribute("href") || link.dataset.atlasRef).catch(() => {});
+    });
     this._syncFocusToolbar();
     this._syncRelationToolbar();
     this._syncLabelsToolbar();
     this._syncPanelToolbar();
     this._syncItemFacingToolbar();
+    this._syncDocumentToolbar();
     this.resizeObserver = new ResizeObserver(() => this.resize());
     this.resizeObserver.observe(this.canvas);
   }
 
   connectedCallback() {
+    globalThis.document?.addEventListener?.("pointerdown", this._outsideHistoryListener);
     globalThis.addEventListener?.("lc-geometry-registry-change", this._geometryRegistryListener);
     globalThis.addEventListener?.("beforeprint", this._beforePrintListener);
     globalThis.addEventListener?.("afterprint", this._afterPrintListener);
@@ -1407,6 +1489,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   disconnectedCallback() {
+    globalThis.document?.removeEventListener?.("pointerdown", this._outsideHistoryListener);
     globalThis.removeEventListener?.("lc-geometry-registry-change", this._geometryRegistryListener);
     globalThis.removeEventListener?.("beforeprint", this._beforePrintListener);
     globalThis.removeEventListener?.("afterprint", this._afterPrintListener);
@@ -1414,6 +1497,7 @@ class LiquidCarsAtlas extends HTMLElement {
     else this._printMedia?.removeListener?.(this._printMediaListener);
     this.restoreAfterPrint();
     if (this._copyStatusTimer) globalThis.clearTimeout?.(this._copyStatusTimer);
+    if (this._historyPressTimer) globalThis.clearTimeout?.(this._historyPressTimer);
     this.resizeObserver.disconnect();
     if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
     this._clearObjects();
@@ -1458,6 +1542,212 @@ class LiquidCarsAtlas extends HTMLElement {
   get model() { return this.modelData; }
   set model(value) { this.load(value); }
 
+  setDocumentResolver(resolver) {
+    if (resolver !== null && typeof resolver !== "function") throw new TypeError("Document resolver must be a function.");
+    this.documentResolver = resolver;
+    this._syncDocumentToolbar();
+    this._syncJumpButton();
+    return this;
+  }
+
+  setContentResolver(resolver) {
+    if (resolver !== null && typeof resolver !== "function") throw new TypeError("Content resolver must be a function.");
+    this.contentResolver = resolver;
+    return this;
+  }
+
+  setDocumentUri(uri) {
+    this.documentUri = resolveAtlasReference(uri).uri;
+    this._visits = [this._captureVisit()];
+    this._visitIndex = 0;
+    this._syncDocumentToolbar();
+    this._renderPanel();
+    return this;
+  }
+
+  _captureVisit() {
+    return {
+      uri: this.documentUri,
+      model: this.modelData ? structuredClone(this.modelData) : null,
+      camera: this.getCameraView(),
+      open: [...this.open],
+      selection: this.selection
+    };
+  }
+
+  async openAtlas(reference) {
+    const { uri, fragment } = resolveAtlasReference(reference, this.documentUri);
+    if (!this.documentResolver) throw new Error("No Atlas document resolver is configured.");
+    const token = ++this._navigationToken;
+    try {
+      const resolved = uri === this.documentUri ? { model: this.modelData, uri } : await this.documentResolver({ uri, from: this.documentUri });
+      if (token !== this._navigationToken) return this;
+      if (!resolved?.model) throw new Error("Resolver did not return a model for " + uri);
+      const destination = resolveAtlasReference(resolved.uri || uri).uri;
+      if (this._visitIndex >= 0) this._visits[this._visitIndex] = this._captureVisit();
+      await this.load(resolved.model, { navigation: true, uri: destination });
+      if (token !== this._navigationToken) return this;
+      this._visits = this._visits.slice(0, this._visitIndex + 1);
+      if (fragment) this.select(fragment, { source: "atlas-link" });
+      this._visits.push(this._captureVisit());
+      this._visitIndex = this._visits.length - 1;
+      this._syncDocumentToolbar();
+      this._renderPanel();
+      this._emit("lc-navigation", { uri: destination, index: this._visitIndex, length: this._visits.length });
+      return this;
+    } catch (error) {
+      this._emit("lc-navigation-error", { reference, message: error.message });
+      this.panel?.insertAdjacentHTML?.("afterbegin", '<p class="navigation-error" role="alert">' + escapeHtml(error.message) + "</p>");
+      throw error;
+    }
+  }
+
+  async _restoreVisit(index) {
+    if (!Number.isInteger(index) || index < 0 || index >= this._visits.length) return this;
+    this._closeHistoryPopover();
+    if (index === this._visitIndex) return this;
+    ++this._navigationToken;
+    this._visits[this._visitIndex] = this._captureVisit();
+    const visit = this._visits[index];
+    await this.load(visit.model, { navigation: true, uri: visit.uri });
+    this._visitIndex = index;
+    this._syncDocumentToolbar();
+    this.setOpenContainers(visit.open, { emit: false });
+    if (visit.selection?.kind === "entity") this.select(visit.selection.id, { emit: false, navigation: "preserve" });
+    else if (visit.selection?.kind === "relation") this.selectRelation(visit.selection.id, { emit: false, navigation: "preserve" });
+    this.setCameraView(visit.camera, { animate: false });
+    this._renderPanel();
+    this._emit("lc-navigation", { uri: visit.uri, index, length: this._visits.length });
+    return this;
+  }
+
+  goBack() { return this._restoreVisit(this._visitIndex - 1); }
+  goForward() { return this._restoreVisit(this._visitIndex + 1); }
+  goHome() { return this._restoreVisit(0); }
+  goToVisit(index) { return this._restoreVisit(index); }
+
+  getDocumentHistory() {
+    return {
+      index: this._visitIndex,
+      visits: this._visits.map(visit => ({
+        uri: visit.uri,
+        title: visit.model?.title || visit.model?.name || decodeURIComponent((visit.uri || "").split("/").pop() || "Atlas")
+      }))
+    };
+  }
+
+  /** Carry the visit stack to another Atlas view of the same document. */
+  captureNavigationState() {
+    if (this._visitIndex < 0) return null;
+    const visits = structuredClone(this._visits);
+    visits[this._visitIndex] = this._captureVisit();
+    return { visits, index: this._visitIndex };
+  }
+
+  restoreNavigationState(state) {
+    if (!state || !Array.isArray(state.visits) || !Number.isInteger(state.index)
+      || state.index < 0 || state.index >= state.visits.length
+      || state.visits[state.index]?.uri !== this.documentUri) {
+      throw new TypeError("Navigation state does not match the current Atlas document.");
+    }
+    this._visits = structuredClone(state.visits);
+    this._visitIndex = state.index;
+    this._visits[this._visitIndex] = this._captureVisit();
+    this._syncDocumentToolbar();
+    return this;
+  }
+
+  _syncDocumentToolbar() {
+    const canNavigate = Boolean(this.documentResolver) && this._visitIndex >= 0;
+    const group = this.navigationToolbar?.querySelector('[data-toolbar-group="navigation"]');
+    if (group) group.hidden = !canNavigate;
+    if (this.navigationToolbar) this.navigationToolbar.hidden = !canNavigate || !this.toolbarVisible;
+    for (const [action, enabled] of [
+      ["atlas-home", canNavigate && this._visitIndex > 0],
+      ["atlas-back", canNavigate && this._visitIndex > 0],
+      ["atlas-forward", canNavigate && this._visitIndex < this._visits.length - 1]
+    ]) {
+      const button = this.navigationToolbar?.querySelector(`[data-action="${action}"]`);
+      if (button) button.disabled = !enabled;
+    }
+    if (!canNavigate) this._closeHistoryPopover();
+  }
+
+  _closeHistoryPopover() {
+    if (this.historyPopover) this.historyPopover.hidden = true;
+  }
+
+  _showHistoryPopover(direction) {
+    const indexes = direction === "back"
+      ? Array.from({ length: this._visitIndex }, (_, offset) => this._visitIndex - offset - 1)
+      : Array.from({ length: this._visits.length - this._visitIndex - 1 }, (_, offset) => this._visitIndex + offset + 1);
+    if (!indexes.length || !this.historyPopover) return;
+    const heading = direction === "back" ? "Previous Atlas documents" : "Next Atlas documents";
+    this.historyPopover.innerHTML = '<div class="history-heading">' + heading + '</div>' + indexes.map(index => {
+      const visit = this._visits[index];
+      const uri = visit.uri || "";
+      const basename = decodeURIComponent(uri.split("/").pop() || "Atlas");
+      const title = visit.model?.title || visit.model?.name || basename;
+      return '<button type="button" role="menuitem" data-action="atlas-history-visit" data-visit-index="' + index + '"><span>' + escapeHtml(title) + '</span><small>' + escapeHtml(uri) + '</small></button>';
+    }).join("");
+    this.historyPopover.hidden = false;
+  }
+
+  _syncJumpButton() {
+    if (!this.jumpButton) return;
+    const relation = this.selectedRelationIndex == null ? null : this.relations[this.selectedRelationIndex];
+    const target = this.selected || relation;
+    const reference = this.documentResolver && String(target?.atlasRef || "").trim();
+    this.jumpButton.hidden = !reference;
+    if (reference) {
+      this.jumpButton.dataset.atlasRef = reference;
+      this.jumpButton.title = `Open linked Atlas · ${reference}`;
+      this.jumpButton.setAttribute("aria-label", `Open linked Atlas for ${target.name || target.label || "selection"}`);
+    } else delete this.jumpButton.dataset.atlasRef;
+  }
+
+  _positionJumpButton() {
+    if (!this.jumpButton || this.jumpButton.hidden) return;
+    let point;
+    if (this.selected) {
+      if (!this._isVisible(this.selected)) { this.jumpButton.style.visibility = "hidden"; return; }
+      point = this._worldPosition(this.selected).clone();
+      point.y += (this.selected.s?.[1] || 1) / 2 + .25;
+    } else {
+      const relation = this.relations[this.selectedRelationIndex];
+      const from = relation && this.nodes.get(relation.from);
+      const to = relation && this.nodes.get(relation.to);
+      if (!from || !to) { this.jumpButton.style.visibility = "hidden"; return; }
+      point = this._worldPosition(from).add(this._worldPosition(to)).multiplyScalar(.5);
+      point.y += .4;
+    }
+    point.project(this.camera);
+    const width = this.canvas.clientWidth;
+    const height = this.canvas.clientHeight;
+    if (!width || !height || Math.abs(point.x) > 1 || Math.abs(point.y) > 1 || point.z < -1 || point.z > 1) {
+      this.jumpButton.style.visibility = "hidden";
+      return;
+    }
+    this.jumpButton.style.visibility = "visible";
+    this.jumpButton.style.left = Math.max(20, Math.min(width - 20, (point.x + 1) * width / 2 + 20)) + "px";
+    this.jumpButton.style.top = Math.max(20, Math.min(height - 20, (1 - point.y) * height / 2 - 16)) + "px";
+  }
+
+  _renderRichContent(content, title = "") {
+    const target = this.panel.querySelector("[data-rich-content]");
+    const token = ++this._contentToken;
+    if (!target || !content) return;
+    if (content.source) {
+      target.textContent = "Loading content…";
+      if (!this.contentResolver) { target.textContent = "No content resolver is configured."; return; }
+      Promise.resolve().then(() => this.contentResolver({ source: content.source, from: this.documentUri, format: content.format }))
+        .then(value => {
+          if (token === this._contentToken) target.innerHTML = renderPanelContent({ format: content.format, value }, { title });
+        })
+        .catch(error => { if (token === this._contentToken) target.textContent = "Could not load content: " + error.message; });
+    } else target.innerHTML = renderPanelContent(content, { title });
+  }
+
   get selectedId() { return this.selected?.id || null; }
   get selectedRelation() { return this._publicRelation(this.selectedRelationIndex); }
   get selection() {
@@ -1476,6 +1766,60 @@ class LiquidCarsAtlas extends HTMLElement {
     return captureRendererFrame(this.renderer, this.scene, this.camera, this.ownerDocument, { ...options, background });
   }
 
+  exportDiagramSvg(options = {}) {
+    return renderDiagramSvg(this, options);
+  }
+
+  getViewMode() { return this.viewMode; }
+
+  setViewMode(mode, options = {}) {
+    if (!["2d", "3d"].includes(mode)) throw new TypeError("Atlas view mode must be '2d' or '3d'.");
+    if (mode === this.viewMode && !options.force) return this;
+    if (mode === "3d" && this.ready && !this._ensureRenderer()) return this;
+    this.viewMode = mode;
+    this.setAttribute("data-view-mode", mode);
+    this.diagramView.root.hidden = mode !== "2d";
+    const button = this.toolbar.querySelector('[data-action="view-mode"]');
+    button.textContent = mode === "2d" ? "3D" : "2D";
+    button.setAttribute("aria-label", mode === "2d" ? "Switch to 3D model" : "Switch to 2D diagram");
+    button.title = button.getAttribute("aria-label");
+    const facing = this.toolbar.querySelector('[data-action="item-facing"]');
+    if (facing) {
+      facing.disabled = mode === "2d";
+      facing.title = mode === "2d" ? "Face camera is available in 3D" : "Face camera";
+    }
+    this.shadowRoot.querySelector(".hint").textContent = mode === "2d"
+      ? "Pan: drag · Zoom: + / − or Alt + wheel · Select: click · Orientation and filters: toolbar"
+      : "Rotate: drag · Pan: right button / ⇧+drag / 2 fingers · Zoom: wheel or pinch · Select: click · Focus: double-click";
+    if (mode === "2d") {
+      if (this.animationFrame) {
+        cancelAnimationFrame(this.animationFrame);
+        this.animationFrame = 0;
+      }
+      for (const node of this.nodes.values()) if (node.group) node.group.visible = this._isVisible(node);
+      if (!this.diagramView.refresh()) requestAnimationFrame(() => { if (this.viewMode === "2d") this.diagramView.refresh(); });
+    } else {
+      this._syncLabelsToolbar();
+      this._syncRelationToolbar();
+      this._syncFocusToolbar();
+      this._syncItemFacingToolbar();
+      this.resize();
+      this.invalidate();
+    }
+    if (options.emit !== false) this._emit("lc-view-mode-change", { mode, source: options.source || "api" });
+    return this;
+  }
+
+  getDiagramView() { return this.diagramView.state; }
+  captureDiagramView() { return this.diagramView.captureState(); }
+  setDiagramView(state) { this.diagramView.setState(state); return this; }
+
+  async exportDiagramPng(options = {}) {
+    const result = options.svg ? { svg: options.svg } : this.exportDiagramSvg(options);
+    const canvas = await diagramSvgToPng(result.svg, this.ownerDocument);
+    return { ...result, blob: await canvasToPngBlob(canvas) };
+  }
+
   async copyFrame(options = {}) {
     const background = options.background === "transparent" ? "transparent" : "theme";
     const scale = Math.max(1, Math.min(4, Number(options.scale) || 2));
@@ -1516,6 +1860,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   prepareForPrint() {
+    if (this.viewMode === "2d") return this;
     if (this._printState) return this;
     const snapshot = this.captureFrame();
     const styleProperties = ["height", "min-height", "aspect-ratio", "--lc-height", "--lc-print-aspect"];
@@ -1803,7 +2148,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   _applyModelRenderOptions() {
-    const render = this.modelData?.render;
+    const render = { ...this.modelData?.render, ...this.modelData?.render?.views?.["3d"] };
     if (!render || typeof render !== "object") return this;
     if (RELATION_DISPLAY_MODES.includes(render.relationMode) && render.relationMode !== this.relationMode) this.setRelationMode(render.relationMode);
     if (normalizeRelationMarker(render.relationMarker) !== this.relationMarker) this.setRelationMarker(render.relationMarker, { emit: false, source: "model" });
@@ -1863,6 +2208,10 @@ class LiquidCarsAtlas extends HTMLElement {
     ];
     const state = { changed: changedContainers.length > 0, previous, current, changedContainers };
     if (state.changed) this.open = currentSet;
+    if (state.changed && this.viewMode === "2d" && this.nodes?.size) {
+      for (const node of this.nodes.values()) if (node.group) node.group.visible = this._isVisible(node);
+      this.diagramView?.refresh();
+    }
     if ((state.changed || options.forceRefresh) && options.refresh !== false) {
       this._renderPanel?.();
       this._rebuildRelations?.();
@@ -1908,6 +2257,7 @@ class LiquidCarsAtlas extends HTMLElement {
     this.modelData = normalizeModel(this.modelData);
     const containerState = this._syncInitialContainerState({ refresh: false, emit: false, source: "model" });
     this._build({ preserveSelection: selectedId, preserveRelation: selectedRelationReference });
+    if (this.viewMode === "2d") requestAnimationFrame(() => this.diagramView.refresh());
     this._emitContainerStateChange(containerState, { source: "model" });
     this._emit("lc-model-change", { kind, model: this.modelData, ...detail });
     return this;
@@ -1916,7 +2266,9 @@ class LiquidCarsAtlas extends HTMLElement {
   updateModel(patch = {}, options = {}) {
     if (!patch || typeof patch !== "object" || Array.isArray(patch)) throw new TypeError("The model patch must be an object.");
     const current = this.modelData || normalizeModel({});
-    const previousCamera = JSON.stringify(current.render?.camera || null);
+    const previousCamera = JSON.stringify(current.render?.views?.["3d"]?.camera || current.render?.camera || null);
+    const previousDiagram = JSON.stringify(current.render?.views?.["2d"] || null);
+    const previousInitialMode = current.render?.initialMode;
     const next = {
       ...current,
       ...patch,
@@ -1929,10 +2281,14 @@ class LiquidCarsAtlas extends HTMLElement {
     this.theme = this.modelData.theme;
     this._commitModelChange("model-update", { patch }, options);
     this._applyModelRenderOptions();
-    const nextCamera = JSON.stringify(this.modelData.render?.camera || null);
-    if (nextCamera !== previousCamera && this.modelData.render?.camera) {
-      this.setCameraView(this.modelData.render.camera, { animate: options.animateCamera !== false });
-    }
+    const nextCameraValue = this.modelData.render?.views?.["3d"]?.camera || this.modelData.render?.camera;
+    const nextCamera = JSON.stringify(nextCameraValue || null);
+    if (nextCamera !== previousCamera && nextCameraValue) {
+      this.setCameraView(nextCameraValue, { animate: options.animateCamera !== false });
+    }
+    if (JSON.stringify(this.modelData.render?.views?.["2d"] || null) !== previousDiagram) this.diagramView.setState(this.modelData.render?.views?.["2d"] || {});
+    if (this.modelData.render?.initialMode !== previousInitialMode) this.setViewMode(this.modelData.render?.initialMode === "2d" ? "2d" : "3d", { emit: false, source: "model" });
+    else this.diagramView.refresh();
     return this;
   }
 
@@ -2126,7 +2482,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   restoreInitialCamera(options = {}) {
-    const initial = this.modelData?.render?.camera;
+    const initial = this.modelData?.render?.views?.["3d"]?.camera || this.modelData?.render?.camera;
     if (initial) return this.setCameraView(initial, options);
     this.yaw = .37;
     this.pitch = .22;
@@ -2329,6 +2685,7 @@ class LiquidCarsAtlas extends HTMLElement {
       // disappear after a theme/model update.
       toolbar.style.setProperty("display", toolbarVisible ? "flex" : "none", "important");
     }
+    this._syncDocumentToolbar();
     if (panel) { panel.dataset.hidden = String(!panelVisible); panel.hidden = !panelVisible; }
     this._syncPanelToolbar();
     if (hint) { hint.dataset.hidden = String(!hintVisible); hint.hidden = !hintVisible; }
@@ -2344,12 +2701,19 @@ class LiquidCarsAtlas extends HTMLElement {
     catch (error) { this._showError("Could not read the JSON model: " + error.message); this.dispatchEvent(new CustomEvent("lc-error", { detail: error })); }
   }
 
-  async load(source) {
+  async load(source, options = {}) {
     this._loading = true;
     this._pendingSelection = null;
     try {
       const data = typeof source === "string" ? await fetch(source).then(response => response.json()) : source;
       this.modelData = normalizeModel(data);
+      if (!options.navigation) {
+        ++this._navigationToken;
+        this.documentUri = options.uri ? resolveAtlasReference(options.uri).uri : null;
+        this._visits = [];
+        this._visitIndex = -1;
+      } else this.documentUri = options.uri || null;
+      this._syncDocumentToolbar();
       this.selected = null;
       this.selectedRelationIndex = null;
       this.open.clear();
@@ -2361,9 +2725,13 @@ class LiquidCarsAtlas extends HTMLElement {
       this.theme = this.modelData.theme;
       this._applyTheme();
       this._syncInitialContainerState({ force: true, refresh: false, emit: false });
+      this.viewMode = this.modelData.render?.initialMode === "2d" ? "2d" : "3d";
       this._build();
       this._applyModelRenderOptions();
-      if (this.modelData.render?.camera) this.setCameraView(this.modelData.render.camera, { animate: false });
+      const render = this.modelData.render || {};
+      if (render.views?.["3d"]?.camera || render.camera) this.setCameraView(render.views?.["3d"]?.camera || render.camera, { animate: false });
+      this.diagramView.setState(render.views?.["2d"] || {});
+      this.setViewMode(render.initialMode === "2d" ? "2d" : "3d", { force: true, emit: false, source: "model" });
       this.dispatchEvent(new CustomEvent("lc-ready", { detail: { model: this.modelData } }));
       this.dispatchEvent(new CustomEvent("lc-model-change", { detail: { model: this.modelData } }));
       const pendingSelection = this._pendingSelection;
@@ -2472,7 +2840,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   _build(options = {}) {
-    if (!this._ensureRenderer()) return;
+    if (this.viewMode !== "2d" && !this._ensureRenderer()) return;
     const selectedId = options.preserveSelection || null;
     const selectedRelationReference = options.preserveRelation ?? null;
     this._clearObjects();
@@ -2496,7 +2864,7 @@ class LiquidCarsAtlas extends HTMLElement {
       node.ports = { ...(definition?.anchors || {}), ...(entity.ports || {}) };
       if (isCustom) {
         try {
-          const content = createGeometryContent(definition, entity, this.modelData.palette, () => this.invalidate(), detail => this.dispatchEvent(new CustomEvent("lc-warning", { detail })));
+          const content = createGeometryContent(definition, entity, this.modelData.palette, () => this._geometryContentUpdated(), detail => this.dispatchEvent(new CustomEvent("lc-warning", { detail })));
           content.root.scale.multiply(new THREE.Vector3().fromArray(entity.s));
           node.appearanceMaterials = [];
           content.root.traverse(object => {
@@ -2566,6 +2934,7 @@ class LiquidCarsAtlas extends HTMLElement {
     this.selected = selectedId && this.nodes.has(selectedId) ? this.nodes.get(selectedId) : null;
     const selectedRelationIndex = this._relationIndex(selectedRelationReference);
     this.selectedRelationIndex = !this.selected && selectedRelationIndex >= 0 && selectedRelationIndex < this.relations.length ? selectedRelationIndex : null;
+    if (this.viewMode === "2d") for (const node of this.nodes.values()) node.group.visible = this._isVisible(node);
     this._renderPanel();
     this._rebuildRelations();
     this.ready = true;
@@ -2838,13 +3207,14 @@ class LiquidCarsAtlas extends HTMLElement {
 
   _renderPanel() {
     if (!this.modelData) return;
+    this._syncJumpButton();
     const selectedRelation = this.selectedRelationIndex === null ? null : this.relations[this.selectedRelationIndex];
     if (selectedRelation) {
       const mode = relationVisualMode(selectedRelation);
       const relationGroup = (this.modelData.relationGroups || []).find(group => group.id === selectedRelation.group);
       const relationGroups = new Map((this.modelData.relationGroups || []).map(group => [group.id, group]));
       const bundle = this.getRelationBundle(this.selectedRelationIndex);
-      const description = selectedRelation.text ? '<p>' + escapeHtml(selectedRelation.text) + '</p>' : '';
+      const description = selectedRelation.content ? '<div class="rich-content" data-rich-content></div>' : selectedRelation.text ? '<p>' + escapeHtml(selectedRelation.text) + '</p>' : '';
       const externalLink = externalLinkMarkup(selectedRelation.url);
       const groupMarkup = relationGroup ? '<h3>GRUPO</h3><p>' + escapeHtml(relationGroup.label || relationGroup.id) + '</p>' : '';
       const bundleMarkup = bundle.map(({ index, relation }) => {
@@ -2854,6 +3224,7 @@ class LiquidCarsAtlas extends HTMLElement {
       }).join("");
       const connectionLabel = bundle.length === 1 ? "1 connection" : `${bundle.length} connections`;
       this.panel.innerHTML = '<button class="back" data-action="overview">← Overview</button><button data-action="focus-selection">◎ Focus selection</button><div class="eyebrow">RELATION</div><h2>' + escapeHtml(selectedRelation.label || `${selectedRelation.from} → ${selectedRelation.to}`) + '</h2><div class="sub">' + escapeHtml(selectedRelation.from) + ' → ' + escapeHtml(selectedRelation.to) + '</div>' + description + externalLink + groupMarkup + '<h3>MODE</h3><p>' + escapeHtml(mode) + '</p><h3>VIRTUAL TUBE</h3><p>' + escapeHtml(`${selectedRelation.from} ↔ ${selectedRelation.to} · ${connectionLabel}`) + '</p>' + bundleMarkup;
+      this._renderRichContent(selectedRelation.content, selectedRelation.label || `${selectedRelation.from} → ${selectedRelation.to}`);
       this.panel.querySelector('[data-action="overview"]')?.addEventListener("click", () => this.reset());
       this.panel.querySelector('[data-action="focus-selection"]')?.addEventListener("click", () => this.focusSelection());
       this.panel.querySelectorAll('[data-action="relation"]').forEach(button => button.addEventListener("click", () => this.selectRelation(Number(button.dataset.relationIndex), { source: "panel" })));
@@ -2882,7 +3253,8 @@ class LiquidCarsAtlas extends HTMLElement {
       const description = relation.text ? '<small>' + escapeHtml(relation.text) + '</small>' : '';
       return '<button class="relation" data-action="relation" data-relation-index="' + index + '"><strong>' + escapeHtml(relation.label || (relation.from === node.id ? relation.to : relation.from)) + '</strong><small>' + escapeHtml(relation.from) + ' → ' + escapeHtml(relation.to) + '</small>' + description + '</button>';
     }).join("");
-    this.panel.innerHTML = '<button class="back" data-action="overview">← Overview</button>' + pathMarkup + '<button data-action="focus-selection">◎ Focus selection</button><div class="eyebrow">' + escapeHtml(isContainerType(node.type) ? "CONTAINER" : node.type === "actor" ? "EXTERNAL ACTOR" : "COMPONENT") + '</div><h2>' + escapeHtml(node.name) + '</h2><div class="sub">' + escapeHtml(node.sub || "") + '</div><p>' + escapeHtml(node.text || "") + '</p>' + externalLinkMarkup(node.url) + (isContainerType(node.type) ? '<button data-action="toggle-shell">' + (this.open.has(node.id) ? "Close container" : "Open container") + '</button>' : "") + (children.length ? '<h3>CONTAINS</h3><p>' + children.length + ' internal item' + (children.length === 1 ? '' : 's') + '.</p>' : "") + '<h3>RELATIONS</h3>' + (relationMarkup || '<p>No direct relations.</p>');
+    this.panel.innerHTML = pathMarkup + '<button data-action="focus-selection">◎ Focus selection</button><div class="eyebrow">' + escapeHtml(isContainerType(node.type) ? "CONTAINER" : node.type === "actor" ? "EXTERNAL ACTOR" : "COMPONENT") + '</div><h2>' + escapeHtml(node.name) + '</h2><div class="sub">' + escapeHtml(node.sub || "") + '</div>' + (node.content ? '<div class="rich-content" data-rich-content></div>' : '<p>' + escapeHtml(node.text || "") + '</p>') + externalLinkMarkup(node.url) + (isContainerType(node.type) ? '<button data-action="toggle-shell">' + (this.open.has(node.id) ? "Close container" : "Open container") + '</button>' : "") + (children.length ? '<h3>CONTAINS</h3><p>' + children.length + ' internal item' + (children.length === 1 ? '' : 's') + '.</p>' : "") + '<h3>RELATIONS</h3>' + (relationMarkup || '<p>No direct relations.</p>');
+    this._renderRichContent(node.content, node.name);
     this.panel.querySelectorAll('[data-action="overview"]').forEach(button => button.addEventListener("click", () => this.reset()));
     this.panel.querySelectorAll('[data-action="path"]').forEach(button => button.addEventListener("click", () => this.select(button.dataset.id)));
     this.panel.querySelectorAll('[data-action="relation"]').forEach(button => button.addEventListener("click", () => this.selectRelation(Number(button.dataset.relationIndex), { source: "panel" })));
@@ -3006,6 +3378,7 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   resize() {
+    if (this.viewMode === "2d") this.diagramView.refresh();
     if (!this.renderer) return;
     const rect = this.canvas.getBoundingClientRect();
     if (!rect.width || !rect.height) return;
@@ -3017,12 +3390,19 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   invalidate() {
-    if (!this.animationFrame && this.renderer) this.animationFrame = requestAnimationFrame(time => this._renderFrame(time));
+    if (this.viewMode === "3d" && !this.animationFrame && this.renderer) this.animationFrame = requestAnimationFrame(time => this._renderFrame(time));
+  }
+
+  _geometryContentUpdated() {
+    // Images in geometry packs may finish loading after the initial diagram
+    // SVG was generated. Refresh that projection without waking the 3D loop.
+    if (this.viewMode === "2d") this.diagramView.scheduleRefresh();
+    else this.invalidate();
   }
 
   _renderFrame(time) {
     this.animationFrame = 0;
-    if (!this.renderer) return;
+    if (!this.renderer || this.viewMode !== "3d") return;
     const zoomGap = Math.abs(this.targetZoom - this.zoom);
     const focusGap = this.targetFocus.distanceTo(this.focus);
     this.zoom += (this.targetZoom - this.zoom) * .12;
@@ -3181,6 +3561,7 @@ class LiquidCarsAtlas extends HTMLElement {
       }
     }
     this.renderer.render(this.scene, this.camera);
+    this._positionJumpButton();
     if (zoomGap > .001 || focusGap > .001 || this.relationGroup.children.length || this.drag) this.invalidate();
   }
 
@@ -3249,6 +3630,38 @@ class LiquidCarsAtlas extends HTMLElement {
   }
 
   _bindControls() {
+    for (const action of ["atlas-back", "atlas-forward"]) {
+      const button = this.navigationToolbar?.querySelector(`[data-action="${action}"]`);
+      if (!button) continue;
+      let origin = null;
+      const cancel = () => { if (this._historyPressTimer) clearTimeout(this._historyPressTimer); this._historyPressTimer = null; };
+      button.addEventListener("pointerdown", event => {
+        if (button.disabled || event.button !== 0) return;
+        origin = { x: event.clientX, y: event.clientY };
+        cancel();
+        this._historyPressTimer = setTimeout(() => {
+          this._historyPressTimer = null;
+          this._historyLongPress = action;
+          this._showHistoryPopover(action === "atlas-back" ? "back" : "forward");
+        }, 480);
+      });
+      button.addEventListener("pointermove", event => {
+        if (origin && Math.hypot(event.clientX - origin.x, event.clientY - origin.y) > 7) cancel();
+      });
+      button.addEventListener("pointerup", () => { origin = null; cancel(); setTimeout(() => { this._historyLongPress = null; }, 100); });
+      button.addEventListener("pointercancel", cancel);
+      button.addEventListener("pointerleave", cancel);
+      button.addEventListener("contextmenu", event => {
+        event.preventDefault();
+        if (!button.disabled) this._showHistoryPopover(action === "atlas-back" ? "back" : "forward");
+      });
+      button.addEventListener("keydown", event => {
+        if (event.key !== "ArrowDown" || button.disabled) return;
+        event.preventDefault();
+        this._showHistoryPopover(action === "atlas-back" ? "back" : "forward");
+        this.historyPopover?.querySelector("button")?.focus();
+      });
+    }
     this.toolbar?.querySelectorAll(".toolbar-menu").forEach(menu => menu.addEventListener("toggle", () => {
       if (menu.open) this._closeToolbarMenus(menu);
     }));
@@ -3256,17 +3669,33 @@ class LiquidCarsAtlas extends HTMLElement {
       // Safari may leave relatedTarget null because pointer-clicked buttons
       // do not necessarily receive focus. Only a known destination outside
       // the toolbar may close the <details> menu before click is dispatched.
-      if (focusMovesOutside(this.toolbar, event)) this._closeToolbarMenus();
+      if (focusMovesOutside(this.toolbar, event)) { this._closeToolbarMenus(); this._closeHistoryPopover(); }
+    });
+    this.navigationToolbar?.addEventListener("focusout", event => {
+      if (focusMovesOutside(this.navigationToolbar, event)) this._closeHistoryPopover();
     });
     this.shadowRoot.addEventListener("keydown", event => {
       if (event.key !== "Escape") return;
+      this._closeHistoryPopover();
       this._closeToolbarMenus();
       this.canvas.focus({ preventScroll: true });
     });
     this.shadowRoot.addEventListener("click", event => {
       const actionControl = closestEventElement(event, "[data-action]");
       const action = actionControl?.dataset.action;
+      if (this._historyLongPress === action) { this._historyLongPress = null; return; }
+      if (!closestEventElement(event, ".atlas-history-popover")) this._closeHistoryPopover();
       if (!closestEventElement(event, ".toolbar-menu")) this._closeToolbarMenus();
+      if (action === "atlas-home") void this.goHome();
+      if (action === "atlas-back") void this.goBack();
+      if (action === "atlas-forward") void this.goForward();
+      if (action === "atlas-history-visit") { this._closeHistoryPopover(); void this._restoreVisit(Number(actionControl.dataset.visitIndex)); }
+      if (action === "atlas-jump") void this.openAtlas(actionControl.dataset.atlasRef).catch(() => {});
+      if (action === "view-mode") this.setViewMode(this.viewMode === "2d" ? "3d" : "2d", { source: "toolbar" });
+      if (this.viewMode === "2d" && actionControl?.closest?.(".toolbar") && this.diagramView.action(action, actionControl)) {
+        if (actionControl?.closest?.(".toolbar-popover") && action !== "relation-group-toggle") this._closeToolbarMenus();
+        return;
+      }
       if (action === "minus") this.zoomOut();
       if (action === "plus") this.zoomIn();
       if (action === "fit") this.fit();