@liquidcars/atlas 0.1.49 → 0.1.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liquidcars/atlas",
3
- "version": "0.1.49",
3
+ "version": "0.1.51",
4
4
  "description": "Reusable 3D conceptual atlas Web Component for LiquidCars-style models",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -539,7 +539,7 @@ export function renderDiagramSvg(atlas, options = {}) {
539
539
  if (hiddenByFocus(box.node.id)) return "";
540
540
  const baseColor = box.node.material?.color || new THREE.Color("#58788d");
541
541
  const color = `#${baseColor.getHexString()}`;
542
- const ink = `#${baseColor.clone().lerp(new THREE.Color("#254253"), .48).getHexString()}`;
542
+ const ink = `#${baseColor.clone().lerp(new THREE.Color(options.containerInk || "#254253"), options.containerInk ? .65 : .48).getHexString()}`;
543
543
  let parent = box.node.parent, guard = 0;
544
544
  while (parent && !boxBackdrops.has(parent) && guard++ < atlas.nodes.size) parent = atlas.nodes.get(parent)?.parent;
545
545
  const parentBackdrop = boxBackdrops.get(parent) || canvasColor;
@@ -1,4 +1,5 @@
1
1
  /** The document's 2D presentation. The SVG is also the source of SVG/PNG exports. */
2
+ import * as THREE from "./three.module.js";
2
3
  const escapeHtml = value => String(value ?? "").replace(/[&<>"']/g, char => ({
3
4
  "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;"
4
5
  })[char]);
@@ -6,9 +7,10 @@ const escapeHtml = value => String(value ?? "").replace(/[&<>"']/g, char => ({
6
7
  const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
7
8
 
8
9
  export const DIAGRAM_VIEW_CSS = `
9
- .diagram-view{position:absolute;inset:0;overflow:auto;background-color:#f5f5f5;background-image:radial-gradient(circle,#b3b3b3 .8px,transparent 1px);background-size:16px 16px;color:#172c3a;cursor:grab;touch-action:none}
10
+ .toolbar button[hidden],.toolbar-menu[hidden]{display:none!important}
11
+ .diagram-view{position:absolute;inset:0;overflow:auto;background-color:var(--lc-diagram-background,#f5f5f5);background-image:radial-gradient(circle,var(--lc-diagram-dot,#b3b3b3) .8px,transparent 1px);background-size:16px 16px;color:#172c3a;cursor:grab;touch-action:none}
10
12
  .diagram-view[hidden],:host(:not([data-view-mode="2d"])) .diagram-view{display:none!important}
11
- :host([data-view-mode="2d"]) .viewport>canvas,:host([data-view-mode="2d"]) .atlas-jump{visibility:hidden;pointer-events:none}
13
+ :host([data-view-mode="2d"]) .viewport>canvas{visibility:hidden;pointer-events:none}
12
14
  :host([data-view-mode="2d"]) .toolbar-group[data-toolbar-group="camera"],
13
15
  :host([data-view-mode="2d"]) .toolbar-group[data-toolbar-group="copy"]{display:none}
14
16
  :host(:not([data-view-mode="2d"])) .toolbar-group[data-toolbar-group="diagram"]{display:none}
@@ -37,7 +39,7 @@ export const DIAGRAM_VIEW_CSS = `
37
39
  .diagram-orientation-cube circle{fill:#132b3b;stroke:#50758b}
38
40
  .diagram-toolbar .diagram-orbit,.diagram-toolbar .diagram-camera-zoom{display:block;padding:6px 9px;color:#dbe7ec;font-size:12px}
39
41
  .diagram-toolbar .diagram-orbit select,.diagram-toolbar .diagram-camera-zoom input{display:block;width:100%;margin-top:4px}
40
- :host([data-view-mode="2d"]) .hint{color:#527286}
42
+ :host([data-view-mode="2d"]) .hint{color:var(--lc-diagram-hint,#527286)}
41
43
  @media print{:host([data-view-mode="2d"]) .diagram-view{display:block!important;overflow:hidden}.diagram-orientation-cube{display:none!important}}
42
44
  `;
43
45
 
@@ -56,6 +58,7 @@ export const DIAGRAM_TOOLBAR = `<div class="toolbar-group diagram-toolbar" data-
56
58
  const DEFAULT_VIEW = Object.freeze({
57
59
  cameraView: { position: [0, 0, 30], target: [0, 0, 0] },
58
60
  cameraZoom: 1, gap: 20, labels: true, relations: "all", showOrientationCube: true,
61
+ theme: "auto", grid: true,
59
62
  focus: { mode: "all", effect: "dim", layout: "preserve", opacity: .2 }
60
63
  });
61
64
 
@@ -69,6 +72,8 @@ export function normalizedDiagramView(value = {}) {
69
72
  cameraZoom: clamp(Number(view.cameraZoom) || 1, .5, 5),
70
73
  gap: clamp(Number(view.gap ?? 20) || 0, 0, 150),
71
74
  labels: view.labels !== false,
75
+ theme: ["auto", "light", "dark"].includes(view.theme) ? view.theme : "auto",
76
+ grid: view.grid !== false,
72
77
  showOrientationCube: view.showOrientationCube !== false,
73
78
  relations: ["all", "within", "selected", "callers", "called", "none"].includes(view.relations) ? view.relations : "all",
74
79
  focus: {
@@ -188,13 +193,22 @@ export class DiagramView {
188
193
  renderOptions(extra = {}) {
189
194
  const state = this.config;
190
195
  const focused = this._focusedIds();
196
+ const background = state.background || (state.theme === "dark" ? "#2d2f31" : state.theme === "light" ? "#f5f5f5" : null)
197
+ || globalThis.getComputedStyle?.(this.root).backgroundColor || "#f5f5f5";
198
+ const color = new THREE.Color(background);
199
+ const dark = color.r * .2126 + color.g * .7152 + color.b * .0722 < .32;
200
+ // Computed CSS colours are rgb(...); SVG backdrop blending requires #rrggbb.
201
+ const canvasColor = `#${color.getHexString()}`;
191
202
  return {
192
203
  cameraView: state.cameraView, cameraFrame: { zoom: state.cameraZoom, aspect: state.frameAspect || this.root.clientWidth / Math.max(1, this.root.clientHeight) },
193
204
  includeIds: state.includeIds, relationGroups: state.relationGroups,
194
205
  relations: state.relations, relationIndexes: this._relationIndexes(),
195
206
  focus: focused ? { ids: [...focused], ...state.focus } : null,
196
207
  gap: state.gap, labels: state.labels, placements: state.placements,
197
- background: "#f5f5f5", ...extra
208
+ background: canvasColor, canvasColor,
209
+ labelColor: dark ? "#e9f0f5" : "#172c3a",
210
+ connectionColor: dark ? "#b1c7d3" : "#58788d",
211
+ ...(dark ? { containerInk: "#e9f0f5" } : {}), ...extra
198
212
  };
199
213
  }
200
214
 
@@ -250,9 +264,23 @@ export class DiagramView {
250
264
  this._refreshQueued = false;
251
265
  if (this.atlas.viewMode !== "2d" || !this.atlas.ready || !this.root.clientWidth) return false;
252
266
  this._syncControls();
267
+ this.root.style.backgroundColor = this.config.background || (this.config.theme === "dark" ? "#2d2f31" : this.config.theme === "light" ? "#f5f5f5" : "");
268
+ this.root.style.backgroundImage = this.config.grid ? "" : "none";
269
+ if (this.config.theme === "auto") this.root.style.removeProperty("--lc-diagram-dot");
270
+ else this.root.style.setProperty("--lc-diagram-dot", this.config.theme === "dark" ? "#73777c" : "#b3b3b3");
253
271
  const options = this.renderOptions({ faceCache: new Map(), background: null, maskGrid: true });
254
272
  const viewport = { width: this.root.clientWidth, height: this.root.clientHeight };
255
- const fit = result => Math.min(1, (viewport.width - 32) / result.width, (viewport.height - 32) / result.height);
273
+ const toolbar = this.atlas.toolbar;
274
+ const insets = {
275
+ top: this.atlas.shadowRoot.querySelector(".hint")?.hidden ? 16 : 34,
276
+ right: 16,
277
+ bottom: this.atlas.toolbarVisible && !toolbar.hidden ? toolbar.offsetHeight + 44 : 16,
278
+ left: this.cube.hidden ? 16 : 132
279
+ };
280
+ this.content.style.padding = `${insets.top}px ${insets.right}px ${insets.bottom}px ${insets.left}px`;
281
+ const fit = result => Math.min(1,
282
+ (viewport.width - insets.left - insets.right) / result.width,
283
+ (viewport.height - insets.top - insets.bottom) / result.height);
256
284
  const initial = this.atlas.exportDiagramSvg({ ...options, measureOnly: true });
257
285
  let zoom = this.zoom === "fit" ? fit(initial) : this.zoom;
258
286
  for (let i = 0; i < (this.zoom === "fit" ? 8 : 1); i += 1) {
@@ -264,6 +292,7 @@ export class DiagramView {
264
292
  zoom = next;
265
293
  }
266
294
  const result = this.atlas.exportDiagramSvg({ ...options, observerScale: zoom });
295
+ if (this.zoom === "fit") this._lastFitZoom = zoom;
267
296
  this.result = result;
268
297
  const previousX = this.root.scrollLeft, previousY = this.root.scrollTop;
269
298
  this.content.innerHTML = result.svg;
@@ -273,6 +302,7 @@ export class DiagramView {
273
302
  this.root.scrollLeft = this.zoom === "fit" ? 0 : previousX;
274
303
  this.root.scrollTop = this.zoom === "fit" ? 0 : previousY;
275
304
  this._syncSelection();
305
+ this.atlas._positionJumpButton?.();
276
306
  return true;
277
307
  }
278
308
 
@@ -284,6 +314,7 @@ export class DiagramView {
284
314
  if (this.atlas.selectedRelation?.id) for (const element of this.content.querySelectorAll("[data-relation]")) {
285
315
  if (element.dataset.relation === this.atlas.selectedRelation.id) element.classList.add("selected");
286
316
  }
317
+ this.atlas._positionJumpButton?.();
287
318
  }
288
319
 
289
320
  _syncControls() {
@@ -339,8 +370,7 @@ export class DiagramView {
339
370
 
340
371
  focusSelection() {
341
372
  if (this.zoom === "fit" && this.result) {
342
- const fit = Math.min(1, (this.root.clientWidth - 32) / this.result.width,
343
- (this.root.clientHeight - 32) / this.result.height);
373
+ const fit = this._lastFitZoom || 1;
344
374
  this.zoom = clamp(Math.max(.75, fit * 1.8), .08, 4);
345
375
  this.refresh();
346
376
  }
@@ -358,8 +388,8 @@ export class DiagramView {
358
388
  if (!action) return false;
359
389
  if (action === "diagram-fit") { this.zoom = "fit"; this.refresh(); return true; }
360
390
  if (action === "diagram-plus" || action === "diagram-minus") {
361
- const current = this.zoom === "fit" ? Math.min(1, (this.root.clientWidth - 32) / (this.result?.width || 1), (this.root.clientHeight - 32) / (this.result?.height || 1)) : this.zoom;
362
- this.zoom = clamp(current * (action === "diagram-plus" ? 1.4 : 1 / 1.4), .08, 4);
391
+ const current = this.zoom === "fit" ? this._lastFitZoom || 1 : this.zoom;
392
+ this.zoom = clamp(current * (action === "diagram-plus" ? 1.15 : 1 / 1.15), .08, 4);
363
393
  this.refresh(); return true;
364
394
  }
365
395
  if (action === "labels") { this.setConfig({ labels: !this.config.labels }, { layout: true }); return true; }
@@ -395,6 +425,7 @@ export class DiagramView {
395
425
  }
396
426
 
397
427
  _bind() {
428
+ this.root.addEventListener("scroll", () => this.atlas._positionJumpButton?.());
398
429
  this.atlas.addEventListener("lc-select", () => {
399
430
  if (this.atlas.viewMode !== "2d") return;
400
431
  if (["selected", "callers", "called"].includes(this.config.relations) || this.config.focus.mode === "connected") this.refresh();
@@ -479,8 +510,7 @@ export class DiagramView {
479
510
  const remainingY = dy + this.root.scrollTop - oldY;
480
511
  if ((remainingX || remainingY) && this.config.cameraZoom > 1) {
481
512
  const angles = cameraAngles(this.config.cameraView);
482
- const zoom = this.zoom === "fit" ? Math.min(1, this.root.clientWidth / (this.result?.width || 1),
483
- this.root.clientHeight / (this.result?.height || 1)) : this.zoom;
513
+ const zoom = this.zoom === "fit" ? this._lastFitZoom || 1 : this.zoom;
484
514
  const target = panTarget(this.config.cameraView.target, angles, remainingX, remainingY, 80 * Math.max(.08, zoom));
485
515
  this.setConfig({ cameraView: cameraView(target, angles.yaw, angles.pitch) }, { layout: true, defer: true });
486
516
  }
@@ -494,7 +524,7 @@ export class DiagramView {
494
524
  this.root.addEventListener("wheel", event => {
495
525
  if (!event.altKey && !event.ctrlKey) return;
496
526
  event.preventDefault();
497
- const zoom = this.zoom === "fit" ? Math.min(1, this.root.clientWidth / (this.result?.width || 1), this.root.clientHeight / (this.result?.height || 1)) : this.zoom;
527
+ const zoom = this.zoom === "fit" ? this._lastFitZoom || 1 : this.zoom;
498
528
  this.zoom = clamp(zoom * (event.deltaY < 0 ? 1.15 : 1 / 1.15), .08, 4);
499
529
  this.scheduleRefresh();
500
530
  }, { passive: false });
@@ -1,27 +1,54 @@
1
- /**
2
- * Atlas paths are rooted in a document collection. atlas:/ starts at its root;
3
- * atlas:foo resolves beside the current document. The fragment names an entity.
4
- */
1
+ /** Logical Atlas references. The fragment selects an entity; ?model selects a named model. */
5
2
  export function resolveAtlasReference(reference, from = null) {
6
3
  const raw = String(reference || "").trim();
7
4
  if (!raw.startsWith("atlas:")) throw new TypeError("Expected an atlas: reference.");
8
5
  const body = raw.slice(6);
9
- if (body.startsWith("//")) throw new TypeError("Atlas authorities are not supported.");
10
6
  const hash = body.indexOf("#");
11
- const path = hash < 0 ? body : body.slice(0, hash);
7
+ const target = hash < 0 ? body : body.slice(0, hash);
12
8
  const fragment = hash < 0 ? "" : decodeURIComponent(body.slice(hash + 1));
13
- const base = from ? resolveAtlasReference(from).uri.slice(6) : "/";
14
- if (!path && !from) throw new TypeError("An Atlas reference needs a document path.");
15
- if (!path) return { uri: "atlas:" + base, fragment };
16
- const segments = (path.startsWith("/") ? [] : base.split("/").slice(0, -1).filter(Boolean));
17
- for (const part of path.split("/")) {
9
+ const query = target.indexOf("?");
10
+ const path = query < 0 ? target : target.slice(0, query);
11
+ const parameters = new URLSearchParams(query < 0 ? "" : target.slice(query + 1));
12
+ if ([...parameters.keys()].some(key => key !== "model") || parameters.getAll("model").length > 1) {
13
+ throw new TypeError("Atlas references only accept one model selector.");
14
+ }
15
+ const modelName = parameters.get("model");
16
+ if (modelName === "") throw new TypeError("The Atlas model selector cannot be empty.");
17
+ const suffix = modelName === null ? "" : "?model=" + encodeURIComponent(modelName);
18
+ const base = from ? resolveAtlasReference(from) : null;
19
+ if (path.startsWith("//")) {
20
+ const match = /^\/\/cloud\/([^/@?#]+)@(published|draft|r[1-9]\d*)$/.exec(path);
21
+ if (!match) throw new TypeError("Expected atlas://cloud/<documentId>@published, @draft or @rN.");
22
+ const documentId = decodeURIComponent(match[1]);
23
+ if (!/^[a-zA-Z0-9_-]+$/.test(documentId)) throw new TypeError("Invalid Atlas cloud document ID.");
24
+ return { uri: "atlas://cloud/" + encodeURIComponent(documentId) + "@" + match[2] + suffix, fragment };
25
+ }
26
+ if (!path) {
27
+ if (!base) throw new TypeError("An Atlas reference needs a document path.");
28
+ const documentUri = base.uri.split("?")[0];
29
+ return { uri: query < 0 ? base.uri : documentUri + suffix, fragment };
30
+ }
31
+ if (base?.uri.startsWith("atlas://cloud/")) throw new TypeError("Cloud documents cannot reference local files.");
32
+ const segments = path.startsWith("/") ? [] : (base?.uri.slice(6).split("?")[0] || "/").split("/").slice(0, -1).filter(Boolean).map(decodeURIComponent);
33
+ for (const encoded of path.split("/")) {
34
+ const part = decodeURIComponent(encoded);
18
35
  if (!part || part === ".") continue;
19
36
  if (part === "..") {
20
37
  if (!segments.length) throw new TypeError("Atlas reference escapes the collection root.");
21
38
  segments.pop();
22
39
  } else {
23
- segments.push(decodeURIComponent(part));
40
+ if (/[\/\\]/.test(part)) throw new TypeError("Invalid Atlas path segment.");
41
+ segments.push(part);
24
42
  }
25
43
  }
26
- return { uri: "atlas:/" + segments.map(encodeURIComponent).join("/"), fragment };
44
+ return { uri: "atlas:/" + segments.map(encodeURIComponent).join("/") + suffix, fragment };
45
+ }
46
+
47
+ export function atlasReferenceTarget(reference, from = null) {
48
+ const resolved = resolveAtlasReference(reference, from);
49
+ const documentUri = resolved.uri.split("?")[0];
50
+ const modelName = new URLSearchParams(resolved.uri.split("?")[1] || "").get("model");
51
+ const cloud = /^atlas:\/\/cloud\/([^/]+)@(published|draft|r[1-9]\d*)$/.exec(documentUri);
52
+ return { ...resolved, documentUri, modelName, kind: cloud ? "cloud" : "local",
53
+ ...(cloud ? { documentId: decodeURIComponent(cloud[1]), version: cloud[2] } : { path: documentUri.slice(7).split("/").map(decodeURIComponent).join("/") }) };
27
54
  }
@@ -4,7 +4,8 @@ import { renderDiagramSvg, diagramSvgToPng } from "./diagram-svg.js";
4
4
  import { DiagramView, DIAGRAM_VIEW_CSS, DIAGRAM_TOOLBAR } from "./diagram-view.js";
5
5
 
6
6
  export { renderDiagramSvg, diagramSvgToPng };
7
- import { resolveAtlasReference } from "./document-navigation.js";
7
+ import { resolveAtlasReference, atlasReferenceTarget } from "./document-navigation.js";
8
+ export { resolveAtlasReference, atlasReferenceTarget } from "./document-navigation.js";
8
9
  import { renderPanelContent } from "./panel-content.js";
9
10
 
10
11
  // This value is bundled from the package manifest, so it always identifies
@@ -944,9 +945,11 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
944
945
  let cachedImage = null;
945
946
  if (typeof image === "string" && image) {
946
947
  cachedImage = cachedGeometryImage(image);
947
- material.map = new THREE.Texture(cachedImage?.canvas || new Image());
948
+ material.map = cachedImage
949
+ ? new THREE.CanvasTexture(cachedImage.canvas)
950
+ : part.fallbackIcon ? iconTexture(part.fallbackIcon) : new THREE.Texture(new Image());
948
951
  if (!cachedImage) {
949
- const bitmap = material.map.image;
952
+ const bitmap = part.fallbackIcon ? new Image() : material.map.image;
950
953
  bitmap.crossOrigin = "anonymous";
951
954
  let cancelled = false;
952
955
  let objectUrl = null;
@@ -964,6 +967,7 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
964
967
  const onLoad = () => {
965
968
  removeListeners();
966
969
  if (cancelled || !material.map) { releaseObjectUrl(); return; }
970
+ let loadedImage = bitmap;
967
971
  if (svgSource) {
968
972
  try {
969
973
  const aspect = (bitmap.naturalWidth || 1) / Math.max(1, bitmap.naturalHeight || 1);
@@ -975,16 +979,27 @@ function createGeometryContent(definition, entity, modelPalette, invalidate, rep
975
979
  if (!context) throw new Error("Canvas 2D is unavailable");
976
980
  context.clearRect(0, 0, canvas.width, canvas.height);
977
981
  context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
978
- material.map.image = canvas;
982
+ loadedImage = canvas;
979
983
  rememberGeometryImage(image, canvas, bitmap.naturalWidth / Math.max(1, bitmap.naturalHeight));
980
984
  } catch (error) {
981
985
  reportWarning?.({ code: "SVG_RASTERIZE_FAILED", geometry: definition.id, entityId: entity.id, image, error });
986
+ if (part.fallbackIcon) loadedImage = null;
982
987
  }
983
988
  }
984
989
  releaseObjectUrl();
985
990
  const imageAspect = bitmap.naturalWidth / Math.max(1, bitmap.naturalHeight);
986
- fitGeometryImage(part, mesh, material.map, imageAspect);
987
- material.map.needsUpdate = true;
991
+ if (loadedImage) {
992
+ // A 2D projection may have read the fallback map already. Swap the
993
+ // complete texture so WebGL also uploads the decoded image.
994
+ const previousMap = material.map;
995
+ const nextMap = loadedImage === bitmap ? new THREE.Texture(bitmap) : new THREE.CanvasTexture(loadedImage);
996
+ nextMap.colorSpace = THREE.SRGBColorSpace;
997
+ fitGeometryImage(part, mesh, nextMap, imageAspect);
998
+ nextMap.needsUpdate = true;
999
+ material.map = nextMap;
1000
+ material.needsUpdate = true;
1001
+ previousMap.dispose();
1002
+ }
988
1003
  invalidate?.();
989
1004
  };
990
1005
  const onError = () => {
@@ -1556,6 +1571,12 @@ class LiquidCarsAtlas extends HTMLElement {
1556
1571
  return this;
1557
1572
  }
1558
1573
 
1574
+ setNavigationGuard(guard) {
1575
+ if (guard !== null && typeof guard !== "function") throw new TypeError("Navigation guard must be a function.");
1576
+ this.navigationGuard = guard;
1577
+ return this;
1578
+ }
1579
+
1559
1580
  setDocumentUri(uri) {
1560
1581
  this.documentUri = resolveAtlasReference(uri).uri;
1561
1582
  this._visits = [this._captureVisit()];
@@ -1571,21 +1592,50 @@ class LiquidCarsAtlas extends HTMLElement {
1571
1592
  model: this.modelData ? structuredClone(this.modelData) : null,
1572
1593
  camera: this.getCameraView(),
1573
1594
  open: [...this.open],
1574
- selection: this.selection
1595
+ selection: this.selection,
1596
+ context: this._documentContext ? structuredClone(this._documentContext) : null,
1597
+ viewMode: this.viewMode,
1598
+ diagram: this.diagramView ? this.captureDiagramView() : null,
1599
+ diagramViewport: this.diagramView ? { zoom: this.diagramView.zoom, scrollLeft: this.diagramView.root?.scrollLeft, scrollTop: this.diagramView.root?.scrollTop } : null,
1600
+ focusFilter: this.focusFilter ? { ...this.focusFilter } : null,
1601
+ relationMode: this.relationMode,
1602
+ visibleRelationGroups: this.visibleRelationGroups === undefined ? undefined : this.visibleRelationGroups ? [...this.visibleRelationGroups] : null
1575
1603
  };
1576
1604
  }
1577
1605
 
1606
+ _restoreVisitPresentation(visit) {
1607
+ this.setOpenContainers(visit.open || [], { emit: false, source: "studio" });
1608
+ if (visit.selection?.kind === "entity") this.select(visit.selection.id, { emit: false, navigation: "preserve" });
1609
+ else if (visit.selection?.kind === "relation") this.selectRelation(visit.selection.id, { emit: false, navigation: "preserve" });
1610
+ if (visit.focusFilter) this.setFocusFilter(visit.focusFilter, { emit: false, source: "studio" });
1611
+ if (visit.relationMode !== undefined) this.setRelationMode(visit.relationMode);
1612
+ if (visit.visibleRelationGroups !== undefined) this.setVisibleRelationGroups(visit.visibleRelationGroups, { emit: false, source: "studio" });
1613
+ if (visit.diagram && this.diagramView) this.setDiagramView(visit.diagram);
1614
+ if (visit.viewMode && this.diagramView) this.setViewMode(visit.viewMode, { emit: false, source: "studio" });
1615
+ if (visit.diagramViewport && this.diagramView?.root) {
1616
+ this.diagramView.zoom = visit.diagramViewport.zoom;
1617
+ this.diagramView.refresh();
1618
+ this.diagramView.root.scrollLeft = visit.diagramViewport.scrollLeft || 0;
1619
+ this.diagramView.root.scrollTop = visit.diagramViewport.scrollTop || 0;
1620
+ this._positionJumpButton();
1621
+ }
1622
+ this.setCameraView(visit.camera, { animate: false });
1623
+ }
1624
+
1578
1625
  async openAtlas(reference) {
1579
- const { uri, fragment } = resolveAtlasReference(reference, this.documentUri);
1580
- if (!this.documentResolver) throw new Error("No Atlas document resolver is configured.");
1581
1626
  const token = ++this._navigationToken;
1582
1627
  try {
1583
- const resolved = uri === this.documentUri ? { model: this.modelData, uri } : await this.documentResolver({ uri, from: this.documentUri });
1628
+ const { uri, fragment } = resolveAtlasReference(reference, this.documentUri);
1629
+ if (!this.documentResolver) throw new Error("No Atlas document resolver is configured.");
1630
+ await this.navigationGuard?.({ uri, from: this.documentUri, history: false });
1631
+ if (token !== this._navigationToken) return this;
1632
+ const resolved = uri === this.documentUri ? { model: this.modelData, uri, context: this._documentContext } : await this.documentResolver({ uri, from: this.documentUri });
1584
1633
  if (token !== this._navigationToken) return this;
1585
1634
  if (!resolved?.model) throw new Error("Resolver did not return a model for " + uri);
1635
+ if (fragment && !resolved.model.entities?.some(entity => entity.id === fragment)) throw new Error("The linked Atlas element is unavailable: " + fragment);
1586
1636
  const destination = resolveAtlasReference(resolved.uri || uri).uri;
1587
1637
  if (this._visitIndex >= 0) this._visits[this._visitIndex] = this._captureVisit();
1588
- await this.load(resolved.model, { navigation: true, uri: destination });
1638
+ await this.load(resolved.model, { navigation: true, uri: destination, context: resolved.context });
1589
1639
  if (token !== this._navigationToken) return this;
1590
1640
  this._visits = this._visits.slice(0, this._visitIndex + 1);
1591
1641
  if (fragment) this.select(fragment, { source: "atlas-link" });
@@ -1593,9 +1643,10 @@ class LiquidCarsAtlas extends HTMLElement {
1593
1643
  this._visitIndex = this._visits.length - 1;
1594
1644
  this._syncDocumentToolbar();
1595
1645
  this._renderPanel();
1596
- this._emit("lc-navigation", { uri: destination, index: this._visitIndex, length: this._visits.length });
1646
+ this._emit("lc-navigation", { uri: destination, context: this._documentContext, index: this._visitIndex, length: this._visits.length });
1597
1647
  return this;
1598
1648
  } catch (error) {
1649
+ if (token !== this._navigationToken) return this;
1599
1650
  this._emit("lc-navigation-error", { reference, message: error.message });
1600
1651
  this.panel?.insertAdjacentHTML?.("afterbegin", '<p class="navigation-error" role="alert">' + escapeHtml(error.message) + "</p>");
1601
1652
  throw error;
@@ -1606,18 +1657,29 @@ class LiquidCarsAtlas extends HTMLElement {
1606
1657
  if (!Number.isInteger(index) || index < 0 || index >= this._visits.length) return this;
1607
1658
  this._closeHistoryPopover();
1608
1659
  if (index === this._visitIndex) return this;
1609
- ++this._navigationToken;
1610
- this._visits[this._visitIndex] = this._captureVisit();
1660
+ const token = ++this._navigationToken;
1611
1661
  const visit = this._visits[index];
1612
- await this.load(visit.model, { navigation: true, uri: visit.uri });
1662
+ let resolved = { uri: visit.uri, model: visit.model, context: visit.context };
1663
+ try {
1664
+ await this.navigationGuard?.({ uri: visit.uri, from: this.documentUri, history: true });
1665
+ // Recheck cloud access on history visits too. Published visits use the
1666
+ // concrete revision returned by the resolver, while Draft catches up.
1667
+ if (atlasReferenceTarget(visit.uri).kind === "cloud") resolved = await this.documentResolver({ uri: visit.uri, from: this.documentUri, history: true });
1668
+ if (token !== this._navigationToken) return this;
1669
+ if (!resolved?.model) throw new Error("The linked Atlas model is unavailable.");
1670
+ } catch (error) {
1671
+ if (token !== this._navigationToken) return this;
1672
+ this._emit("lc-navigation-error", { reference: visit.uri, message: error.message });
1673
+ return this;
1674
+ }
1675
+ this._visits[this._visitIndex] = this._captureVisit();
1676
+ await this.load(resolved.model, { navigation: true, uri: visit.uri, context: resolved.context });
1677
+ if (token !== this._navigationToken) return this;
1613
1678
  this._visitIndex = index;
1614
1679
  this._syncDocumentToolbar();
1615
- this.setOpenContainers(visit.open, { emit: false });
1616
- if (visit.selection?.kind === "entity") this.select(visit.selection.id, { emit: false, navigation: "preserve" });
1617
- else if (visit.selection?.kind === "relation") this.selectRelation(visit.selection.id, { emit: false, navigation: "preserve" });
1618
- this.setCameraView(visit.camera, { animate: false });
1680
+ this._restoreVisitPresentation(visit);
1619
1681
  this._renderPanel();
1620
- this._emit("lc-navigation", { uri: visit.uri, index, length: this._visits.length });
1682
+ this._emit("lc-navigation", { uri: visit.uri, context: this._documentContext, restored: true, index, length: this._visits.length });
1621
1683
  return this;
1622
1684
  }
1623
1685
 
@@ -1644,7 +1706,7 @@ class LiquidCarsAtlas extends HTMLElement {
1644
1706
  return { visits, index: this._visitIndex };
1645
1707
  }
1646
1708
 
1647
- restoreNavigationState(state) {
1709
+ restoreNavigationState(state, options = {}) {
1648
1710
  if (!state || !Array.isArray(state.visits) || !Number.isInteger(state.index)
1649
1711
  || state.index < 0 || state.index >= state.visits.length
1650
1712
  || state.visits[state.index]?.uri !== this.documentUri) {
@@ -1652,13 +1714,16 @@ class LiquidCarsAtlas extends HTMLElement {
1652
1714
  }
1653
1715
  this._visits = structuredClone(state.visits);
1654
1716
  this._visitIndex = state.index;
1717
+ this._documentContext = this._visits[state.index].context || null;
1718
+ if (options.restorePresentation) this._restoreVisitPresentation(this._visits[state.index]);
1655
1719
  this._visits[this._visitIndex] = this._captureVisit();
1656
1720
  this._syncDocumentToolbar();
1657
1721
  return this;
1658
1722
  }
1659
1723
 
1660
1724
  _syncDocumentToolbar() {
1661
- const canNavigate = Boolean(this.documentResolver) && this._visitIndex >= 0;
1725
+ const canNavigate = Boolean(this.documentResolver) && this._visitIndex >= 0
1726
+ && (!this._toolbarControls || this._toolbarControls.has("navigation"));
1662
1727
  const group = this.navigationToolbar?.querySelector('[data-toolbar-group="navigation"]');
1663
1728
  if (group) group.hidden = !canNavigate;
1664
1729
  if (this.navigationToolbar) this.navigationToolbar.hidden = !canNavigate || !this.toolbarVisible;
@@ -1704,10 +1769,27 @@ class LiquidCarsAtlas extends HTMLElement {
1704
1769
  this.jumpButton.title = `Open linked Atlas · ${reference}`;
1705
1770
  this.jumpButton.setAttribute("aria-label", `Open linked Atlas for ${target.name || target.label || "selection"}`);
1706
1771
  } else delete this.jumpButton.dataset.atlasRef;
1772
+ if (reference && this.ready) this._positionJumpButton();
1707
1773
  }
1708
1774
 
1709
1775
  _positionJumpButton() {
1710
1776
  if (!this.jumpButton || this.jumpButton.hidden) return;
1777
+ if (this.viewMode === "2d") {
1778
+ const relation = this.relations[this.selectedRelationIndex];
1779
+ const key = this.selected ? "entity" : "relation";
1780
+ const id = this.selected?.id || relation?.id;
1781
+ const node = [...(this.diagramView?.content?.querySelectorAll("[data-" + key + "]") || [])].find(element => element.dataset[key] === id);
1782
+ const frame = this.shadowRoot.querySelector(".viewport").getBoundingClientRect();
1783
+ const bounds = node?.getBoundingClientRect();
1784
+ if (!bounds || !bounds.width || bounds.right < frame.left || bounds.left > frame.right || bounds.bottom < frame.top || bounds.top > frame.bottom) {
1785
+ this.jumpButton.style.visibility = "hidden";
1786
+ return;
1787
+ }
1788
+ this.jumpButton.style.visibility = "visible";
1789
+ this.jumpButton.style.left = Math.max(20, Math.min(frame.width - 40, bounds.right - frame.left + 8)) + "px";
1790
+ this.jumpButton.style.top = Math.max(20, Math.min(frame.height - 40, bounds.top - frame.top - 12)) + "px";
1791
+ return;
1792
+ }
1711
1793
  let point;
1712
1794
  if (this.selected) {
1713
1795
  if (!this._isVisible(this.selected)) { this.jumpButton.style.visibility = "hidden"; return; }
@@ -2147,9 +2229,37 @@ class LiquidCarsAtlas extends HTMLElement {
2147
2229
  return this.setFocusFilter({ mode: "all" }, options);
2148
2230
  }
2149
2231
 
2232
+ _setToolbarControls(value) {
2233
+ const controls = Array.isArray(value) ? new Set(value.map(item => String(item).trim())) : null;
2234
+ this._toolbarControls = controls;
2235
+ if (!this.toolbar) return;
2236
+ const allowed = (...names) => !controls || controls.has("all") || names.some(name => controls.has(name));
2237
+ const group = this.toolbar;
2238
+ const buttons = {
2239
+ "view-mode": ["mode", "view-mode"],
2240
+ minus: ["zoom", "minus"], plus: ["zoom", "plus"], fit: ["fit"], front: ["front"],
2241
+ "diagram-minus": ["zoom", "diagram-minus"], "diagram-plus": ["zoom", "diagram-plus"],
2242
+ "diagram-fit": ["fit", "diagram-fit"]
2243
+ };
2244
+ for (const button of group.querySelectorAll('.toolbar-group > button[data-action]')) {
2245
+ button.hidden = !allowed(...(buttons[button.dataset.action] || [button.dataset.action]));
2246
+ }
2247
+ for (const menu of group.querySelectorAll('.toolbar-group > .toolbar-menu')) {
2248
+ const name = menu.dataset.toolbarMenu;
2249
+ menu.hidden = !allowed(name, name?.replace(/^diagram-/, ""));
2250
+ if (menu.hidden) menu.open = false;
2251
+ }
2252
+ for (const section of group.querySelectorAll('.toolbar-group:not([data-toolbar-group="navigation"])')) {
2253
+ section.hidden = !section.querySelector(':scope > button[data-action]:not([hidden]), :scope > .toolbar-menu:not([hidden])');
2254
+ }
2255
+ this._syncDocumentToolbar();
2256
+ }
2257
+
2150
2258
  _applyModelRenderOptions() {
2151
2259
  const render = { ...this.modelData?.render, ...this.modelData?.render?.views?.["3d"] };
2152
2260
  if (!render || typeof render !== "object") return this;
2261
+ const toolbar = this.modelData?.render?.ui?.toolbar ?? render.toolbar;
2262
+ this._setToolbarControls(Array.isArray(toolbar) ? toolbar : this.modelData?.render?.ui?.controls);
2153
2263
  if (RELATION_DISPLAY_MODES.includes(render.relationMode) && render.relationMode !== this.relationMode) this.setRelationMode(render.relationMode);
2154
2264
  if (normalizeRelationMarker(render.relationMarker) !== this.relationMarker) this.setRelationMarker(render.relationMarker, { emit: false, source: "model" });
2155
2265
  if (Array.isArray(render.visibleRelationGroups)) this.setVisibleRelationGroups(render.visibleRelationGroups, { emit: false, source: "model" });
@@ -2157,7 +2267,7 @@ class LiquidCarsAtlas extends HTMLElement {
2157
2267
  if (Object.hasOwn(render, "selectionMode") && render.selectionMode !== this.selectionMode) this.setSelectionMode(render.selectionMode);
2158
2268
  const selectionNavigation = render.navigation?.onSelect ?? render.selectionNavigation;
2159
2269
  if (selectionNavigation != null && selectionNavigation !== this.selectionNavigation) this.setSelectionNavigation(selectionNavigation);
2160
- if (Object.hasOwn(render, "toolbar") && (render.toolbar !== false) !== this.toolbarVisible) this.setToolbarVisible(render.toolbar !== false);
2270
+ if (toolbar !== undefined && (toolbar !== false) !== this.toolbarVisible) this.setToolbarVisible(toolbar !== false);
2161
2271
  if (Object.hasOwn(render, "shellLabels") && (render.shellLabels !== false) !== this.showShellLabels) this.setShellLabels(render.shellLabels !== false);
2162
2272
  if (Object.hasOwn(render, "itemFacing") && normalizeItemFacing(render.itemFacing) !== this.itemFacing) this.setItemFacing(render.itemFacing, { emit: false, source: "model" });
2163
2273
  if (render.focus) this.setFocusFilter(render.focus, { emit: false });
@@ -2676,7 +2786,7 @@ class LiquidCarsAtlas extends HTMLElement {
2676
2786
  if (atlas) atlas.dataset.panel = this.panelVisible ? "visible" : "hidden";
2677
2787
  const toolbarVisible = this.toolbarVisible;
2678
2788
  const panelVisible = this.panelVisible;
2679
- const hintVisible = theme.ui.hint !== false;
2789
+ const hintVisible = (this.modelData?.render?.ui?.hint ?? theme.ui.hint) !== false;
2680
2790
  if (toolbar) {
2681
2791
  toolbar.dataset.hidden = String(!toolbarVisible);
2682
2792
  toolbar.hidden = !toolbarVisible;
@@ -2707,6 +2817,7 @@ class LiquidCarsAtlas extends HTMLElement {
2707
2817
  try {
2708
2818
  const data = typeof source === "string" ? await fetch(source).then(response => response.json()) : source;
2709
2819
  this.modelData = normalizeModel(data);
2820
+ this._documentContext = options.context || null;
2710
2821
  if (!options.navigation) {
2711
2822
  ++this._navigationToken;
2712
2823
  this.documentUri = options.uri ? resolveAtlasReference(options.uri).uri : null;