@liquidcars/atlas-layout 0.1.9 → 0.1.13

package/README.md

@@ -49,6 +49,11 @@ como alias de compatibilidad. Un contenedor puede no tener geometría o usar una
 primitiva `geo.*`; las geometrías personalizadas de los packs, como `infra.cloud`,
 sólo se permiten en entidades hoja.
 
+Un contenedor puede declarar `open: true` para comenzar expandido. El estado
+cerrado es el valor predeterminado, por lo que `open: false` se normaliza
+omitiendo la propiedad. Declarar `open` en una hoja o usar un valor que no sea
+booleano produce un diagnóstico fatal.
+
 La presentación puede conservar una vista inicial sin introducir datos de
 cámara en el algoritmo de layout:
 
@@ -134,13 +139,15 @@ relations:
     from: source
     to: rules
     label: feeds
+    text: Sends normalized source data to the rules engine.
+    url: https://example.com/relations/source-to-rules
     mode: bidirectional
   - from: rules
     to: output
     mode: broken
 ```
 
-`mode` es la forma recomendada y el compilador siempre la emite normalizada. Para facilitar la migración se aceptan también `visual`, `render`, `type`, `direction`, `bidirectional: true` y `broken: true`, además de los alias `two-way`, `both` e `interrupted`. La forma abreviada puede incluir el modo como cuarto valor: `[from, to, label, mode]`. Un modo desconocido conserva la relación como `directed` y añade el diagnóstico `UNKNOWN_RELATION_MODE`.
+`label` es el título corto visible junto a la conexión, `text` permite documentar su significado y `url` enlaza documentación externa desde el panel de información. `mode` es la forma recomendada y el compilador siempre la emite normalizada. Para facilitar la migración se aceptan también `visual`, `render`, `type`, `direction`, `bidirectional: true` y `broken: true`, además de los alias `two-way`, `both` e `interrupted`. La forma abreviada puede incluir el modo como cuarto valor: `[from, to, label, mode]`. Un modo desconocido conserva la relación como `directed` y añade el diagnóstico `UNKNOWN_RELATION_MODE`.
 
 En un documento Markdown dividido, el bloque de relaciones contiene una lista YAML:
 
@@ -194,4 +201,67 @@ El resultado mantiene `palette`, `theme`, `entities` y `relations`, con `p` y `s
 
 El espacio de una celda y el tamaño de la geometría son conceptos distintos. Cuando el layout asigna una celda rectangular a una geometría sin `size` explícito, la figura se centra y se escala uniformemente para caber en el menor volumen compatible; no se estira por separado en `x`, `y` y `z`. Por eso una esfera conserva `s[0] === s[1] === s[2]`, aunque su celda sea rectangular. Un `size` explícito sigue teniendo prioridad y permite al autor solicitar una proporción concreta.
 
-`row`, `grid`/`masonry` y `volume` producen posiciones deterministas. Las constraints de tamaño y alineación, el empaquetado compacto, los grupos virtuales y la distribución `justify` forman parte del contrato estable de autoría. El algoritmo `graph` sigue reservado: por ahora emite `GRAPH_LAYOUT_FALLBACK` y usa `grid`. La proyección y el enrutado avanzado de relaciones entre contenedores permanecen como líneas de desarrollo posteriores.
+`row`, `grid`/`masonry` y `volume` producen posiciones deterministas. `variant: masonry` desplaza las filas alternas media celda sin exigir una sección `stagger`; `stagger.offset` queda disponible como override explícito. Para conservar legibilidad frontal se recomienda `plane: xy`, y para una composición lateral, `plane: yz`. Las constraints de tamaño y alineación, el empaquetado compacto, los grupos virtuales y la distribución `justify` forman parte del contrato estable de autoría.
+
+`auto` delega en el optimizador global la elección de algoritmo, dirección y
+plano para ese propietario de layout. El compilador prueba alternativas de
+`graph`, `row`, `grid` y `volume` mediante una búsqueda determinista y puntúa el modelo
+completo, no cada contenedor de forma aislada. La búsqueda resuelve primero los
+contenidos anidados y después sus propietarios, de modo que la composición global
+se decide con tamaños y afinidades estables. `graph` también aporta variantes
+espaciales internas con varios carriles de profundidad; `auto` puede elegirlas
+sin que el autor tenga que fijar un nuevo algoritmo. Las intersecciones físicas
+3D y los solapamientos son condiciones estrictas. Entre las soluciones válidas,
+la función perceptiva equilibra los atravesamientos y cruces proyectados con la
+legibilidad frontal, la alineación ortogonal, la longitud media de las relaciones,
+la compacidad volumétrica, la coherencia de orientación y las proporciones
+excesivamente alargadas. Los carriles de profundidad automáticos emplean un paso
+compacto; un layout `graph` explícito conserva el paso completo. Un `direction`, `plane`,
+`gap` o `padding` declarado junto a `auto` queda bloqueado y limita las
+alternativas. Si no se declara `gap`, se utiliza `3`.
+
+```yaml
+layout:
+  algorithm: auto
+  # direction: z  # opcional: bloquea el eje, pero no el algoritmo resuelto
+```
+
+La cámara inicial de `render.camera` es la vista principal de la puntuación. Se
+combina con una vista frontal canónica —que mide cuántos frentes quedan ocultos—
+y varias perspectivas oblicuas para evitar una solución que solo resulte legible
+desde un ángulo. Un host como
+Atlas Studio también puede pasar la vista interactiva con
+`compileAtlasModel(source, { autoLayoutCamera: camera })`. Cada propietario
+automático produce un diagnóstico informativo `AUTO_LAYOUT_RESOLVED` con la
+configuración elegida y las métricas globales, incluidas la oclusión frontal,
+las peores métricas proyectadas y las intersecciones espaciales. `analyzeAtlasLayout(model,
+{ camera })` permite puntuar un modelo ya compilado con la misma función
+objetivo.
+
+`graph` implementa un layout por capas sensible a las relaciones. Proyecta las
+relaciones de descendientes sobre los hijos inmediatos del contenedor, asigna
+capas según la dirección del flujo y utiliza barridos de baricentro para reducir
+cruces y longitud de conexiones. Los empates conservan el orden de autoría para
+que el resultado sea determinista. Las relaciones con `layout: false` no
+participan. Los ciclos se rompen de forma estable y producen el diagnóstico
+`GRAPH_CYCLE_STABILIZED`. Cuando varios contenedores usan `graph`, una pasada
+jerárquica adicional utiliza las relaciones que cruzan sus límites para alinear
+carriles entre contenedores. De este modo, dos elementos relacionados pueden
+quedar en la misma vertical u horizontal aunque no sean hermanos directos.
+
+El `gap` predeterminado de `graph` es `3`; puede reducirse de forma explícita
+para modelos compactos. Las relaciones siguen determinando las capas sobre
+`direction`. Elegir automáticamente entre composiciones alternativas en `x`,
+`y` o `z` pertenece a una fase de optimización asistida, no al compilador
+determinista.
+
+```yaml
+layout:
+  algorithm: graph
+  direction: y
+  plane: xy
+  gap: 3
+```
+
+El enrutado avanzado de tubos alrededor de geometrías permanece como una fase
+posterior e independiente de la colocación de nodos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas-layout",
-  "version": "0.1.9",
+  "version": "0.1.13",
   "description": "Declarative layout compiler for LiquidCars Atlas models",
   "type": "module",
   "main": "./src/index.js",

package/spec/ATLAS-LAYOUT-SPEC-v1.md

@@ -47,7 +47,7 @@ subject to sizeMode and diagnostics.
 
 Required: id.
 
-Common fields: name, sub, text, type, parent, children, geometry, geometryOptions,
+Common fields: name, sub, text, url, type, open, parent, children, geometry, geometryOptions,
 geometryPalette, style, layout, weight, span, size, sizeMode, p, s, c and radius.
 
 An entity with children is a container and must explicitly declare `type: container`.
@@ -55,6 +55,9 @@ A leaf entity may omit `type`, in which case it is normalized as an item. The
 legacy value `type: shell` remains accepted as a compatibility alias for
 `container`, but is not emitted by the compiler or suggested by the editor.
 
+Only a container may declare `open`. `open: true` makes it initially expanded;
+omitting the property (or declaring `false`) means initially closed.
+
 Containers may omit geometry or use a built-in primitive such as `geo.box`.
 Custom geometry-pack geometries such as `infra.cloud` and `media.image-box` are
 leaf geometries and cannot be used on containers. The compiler reports these violations
@@ -71,9 +74,42 @@ fit permits assisted layout to use the geometry's canonical size.
 
 ## Assisted layout
 
-layout.algorithm accepts row, grid, volume or graph. direction accepts x, y or z.
+layout.algorithm accepts auto, row, grid, volume or graph. direction accepts x,
+y or z. Auto is an explicit permission for the compiler to evaluate graph, row,
+grid, volume and internal spatial-graph alternatives against the whole model.
+Real 3D relation/item intersections and visible traversals have first-class
+priority. Front-face occlusion is measured from the canonical front view; the
+primary and canonical oblique views then contribute relation crossings,
+projected overlap, sibling orientation consistency, elongation, relation length
+and footprint to the deterministic score. An authored direction, plane,
+gap or padding beside auto is locked and narrows the search. Auto uses gap 3
+when none is authored. The selected concrete layout is reported through
+`AUTO_LAYOUT_RESOLVED`; it does not replace `algorithm: auto` in the authored
+source.
+
+The initial render.camera is the primary projection used for scoring and is
+combined with the canonical front view and canonical oblique views so the result
+does not overfit one angle. A host may instead supply the current interactive view as the
+`autoLayoutCamera` compile option. `analyzeAtlasLayout` exposes the same metrics
+for already compiled models.
+
+Graph uses a deterministic layered layout driven by relations whose `layout`
+field is not false. Relations between descendants are projected onto the
+immediate children of the container being laid out. Atlas orders each layer to
+reduce crossings and edge length while retaining authored order as the stable
+tie-breaker. When two or more graph-layout owners are linked by relations, a
+hierarchical sweep also projects those external relations into normalized lane
+hints. This aligns related children across container boundaries without adding
+authored constraints. When `auto` has not been limited to an authored plane, it
+may also distribute graph nodes across deterministic depth lanes. Directed cycles are broken deterministically and reported
+as `GRAPH_CYCLE_STABILIZED`. Graph uses a default gap of 3 world units; the
+other algorithms retain their existing defaults. Axis and plane selection stay
+declarative and are not changed implicitly by compilation.
 Grid layouts also accept variant uniform or masonry, optional columns and rows, and
-a plane of xz (the default), xy or yz. Volume layouts additionally accept layers.
+a plane of xz (the default), xy or yz. Masonry offsets alternate rows by half a cell
+unless `stagger.offset` explicitly overrides that distance. Use plane xy for layouts
+intended to remain legible from the natural frontal camera, or yz for a lateral view.
+Volume layouts additionally accept layers.
 gap and padding are absolute numbers. justify accepts start, center, end,
 space-between, space-around or space-evenly. These modes become distinct when a
 row receives an explicit or constrained size. Distributed modes treat gap as the
@@ -145,7 +181,10 @@ constraints:
 
 Relations require from and to entity ids. mode is directed, bidirectional or broken.
 The aliases visual, render, type and direction are accepted for compatibility.
-Optional fields include id, label, fromAnchor, toAnchor, priority and layout.
+Optional fields include id, label, text, url, fromAnchor, toAnchor, priority and layout.
+`label` is the compact caption associated with the connection; `text` is its longer
+description and `url` links to external documentation when the relation is selected
+in the information panel.
 
 ## Rendering
 

package/src/index.js

@@ -142,6 +142,18 @@ function normalizeEntityTypes(flat, geometryCatalog, diagnostics) {
     const type = hasChildren || declared === "container" || declared === "shell" ? "container" : "item";
     entity.type = type;
 
+    if (Object.hasOwn(source, "open") && typeof source.open !== "boolean") {
+      diagnostic(diagnostics, "fatal", "INVALID_CONTAINER_OPEN_STATE",
+        "Entity '" + entity.id + "' has a non-boolean open value. Use true or omit the property.",
+        { entityId: entity.id, open: source.open });
+    } else if (Object.hasOwn(source, "open") && type !== "container") {
+      diagnostic(diagnostics, "fatal", "OPEN_STATE_REQUIRES_CONTAINER",
+        "Entity '" + entity.id + "' declares open but is not a container.",
+        { entityId: entity.id, open: source.open });
+    }
+    if (type === "container" && source.open === true) entity.open = true;
+    else delete entity.open;
+
     if (type === "container" && source.geometry && !isPrimitiveGeometry(source.geometry, geometryCatalog)) {
       diagnostic(diagnostics, "fatal", "CUSTOM_GEOMETRY_ON_CONTAINER",
         "Container '" + entity.id + "' cannot use non-primitive geometry '" + source.geometry + "'.",
@@ -242,6 +254,8 @@ function normalizeRelations(input, validIds, diagnostics) {
       index
     };
     if (relation.id != null) normalized.id = String(relation.id);
+    if (relation.text != null) normalized.text = String(relation.text);
+    if (relation.url != null) normalized.url = String(relation.url);
     if (relation.fromAnchor != null || relation.from_anchor != null) normalized.fromAnchor = String(relation.fromAnchor ?? relation.from_anchor);
     if (relation.toAnchor != null || relation.to_anchor != null) normalized.toAnchor = String(relation.toAnchor ?? relation.to_anchor);
     return [normalized];
@@ -565,20 +579,20 @@ function compactRowBands(placements, constraints, spec, lockedAxes = new Map())
   }
 }
 
-function layoutFunction(spec, diagnostics, ownerId) {
+function layoutFunction(spec, diagnostics, ownerId, graphContext = null) {
   const algorithm = ALGORITHMS.has(spec?.algorithm) ? spec.algorithm : "grid";
   if (!ALGORITHMS.has(spec?.algorithm || "grid")) diagnostic(diagnostics, "warning", "UNKNOWN_LAYOUT_ALGORITHM",
     `Unknown layout algorithm '${spec?.algorithm}', using grid.`, { entityId: ownerId });
-  if (algorithm === "graph") diagnostic(diagnostics, "warning", "GRAPH_LAYOUT_FALLBACK",
-    `Graph layout for '${ownerId || "root"}' is reserved for a later compiler pass; using grid for now.`, { entityId: ownerId });
   return algorithm === "row"
     ? rowLayout
     : algorithm === "volume"
       ? volumeLayout
-      : gridLayout;
+      : algorithm === "graph"
+        ? (items, layoutSpec, layoutDiagnostics) => graphLayout(items, layoutSpec, layoutDiagnostics, graphContext, ownerId)
+        : gridLayout;
 }
 
-function materializeLayoutGroups(items, spec, diagnostics, ownerId) {
+function materializeLayoutGroups(items, spec, diagnostics, ownerId, graphContext = null) {
   const definitions = Array.isArray(spec?.groups) ? spec.groups : [];
   if (!definitions.length) return { items, groups: new Map() };
 
@@ -634,7 +648,9 @@ function materializeLayoutGroups(items, spec, diagnostics, ownerId) {
       definition,
       diagnostics,
       definition.id,
-      layoutFunction(groupSpec, diagnostics, definition.id)
+      layoutFunction(groupSpec, diagnostics, definition.id, graphContext),
+      null,
+      graphContext
     );
     const virtual = {
       entity: { id: definition.id, type: "layout-group", __atlasVirtualGroup: true },
@@ -700,8 +716,8 @@ function flattenLayoutGroups(placements) {
   return flattened;
 }
 
-function constrainedLayout(items, spec, source, diagnostics, ownerId, layout, availableSize = null) {
-  const grouped = materializeLayoutGroups(items, spec, diagnostics, ownerId);
+function constrainedLayout(items, spec, source, diagnostics, ownerId, layout, availableSize = null, graphContext = null) {
+  const grouped = materializeLayoutGroups(items, spec, diagnostics, ownerId, graphContext);
   const constraints = layoutConstraints(source, spec);
   applyEqualSizeConstraints(grouped.items, constraints, diagnostics, ownerId);
   reflowLayoutGroups(grouped.items, diagnostics);
@@ -890,7 +906,12 @@ function packedGridLayout(items, spec, diagnostics, dimension = 2) {
     for (const item of placements) {
       const columnSize = item.span[0] * columnCell + (item.span[0] - 1) * gap;
       const rowSize = item.span[1] * rowCell + (item.span[1] - 1) * gap;
-      const offset = spec.variant === "masonry" && item.cell[1] % 2 === 1 ? (spec.stagger?.offset === "half-cell" ? (columnCell + gap) / 2 : scalar(spec.stagger?.offset, 0)) : 0;
+      const staggerOffset = spec.stagger?.offset;
+      const offset = spec.variant === "masonry" && item.cell[1] % 2 === 1
+        ? (staggerOffset == null || staggerOffset === "half-cell"
+            ? (columnCell + gap) / 2
+            : scalar(staggerOffset, 0))
+        : 0;
       const slotSize = [0, 0, 0];
       slotSize[columnAxis] = columnSize;
       slotSize[rowAxis] = rowSize;
@@ -949,6 +970,180 @@ function volumeLayout(items, spec, diagnostics) {
   return packedGridLayout(items, spec, diagnostics, 3);
 }
 
+function graphAxes(spec = {}) {
+  const main = { x: 0, y: 1, z: 2 }[spec.direction] ?? 1;
+  const plane = GRID_PLANES[spec.plane] || (main === 2 ? GRID_PLANES.xz : GRID_PLANES.xy);
+  const cross = plane.find(axis => axis !== main) ?? [0, 1, 2].find(axis => axis !== main);
+  const depth = [0, 1, 2].find(axis => axis !== main && axis !== cross);
+  return { main, cross, depth };
+}
+
+function graphEndpointItem(endpointId, itemIds, directItemById, byId) {
+  let cursor = byId?.get(endpointId);
+  const seen = new Set();
+  while (cursor && !seen.has(cursor.id)) {
+    seen.add(cursor.id);
+    const direct = directItemById.get(cursor.id);
+    if (direct && itemIds.has(direct)) return direct;
+    cursor = cursor.parent ? byId.get(cursor.parent) : null;
+  }
+  return null;
+}
+
+function graphLayout(items, spec, diagnostics, context = null, ownerId = null) {
+  const gap = Math.max(0, scalar(spec.gap, 3));
+  const padding = Math.max(0, scalar(spec.padding, 1));
+  if (!items.length) return boundsOf([], padding);
+
+  const ids = items.map(item => item.entity.id);
+  const itemIds = new Set(ids);
+  const authoredIndex = new Map(ids.map((id, index) => [id, index]));
+  const directItemById = new Map();
+  for (const item of items) {
+    directItemById.set(item.entity.id, item.entity.id);
+    if (item.entity.__atlasVirtualGroup) {
+      for (const member of item.memberItems || []) directItemById.set(member.entity.id, item.entity.id);
+    }
+  }
+
+  const edgeWeights = new Map();
+  for (const relation of context?.relations || []) {
+    if (relation.layout === false) continue;
+    const from = graphEndpointItem(relation.from, itemIds, directItemById, context.byId);
+    const to = graphEndpointItem(relation.to, itemIds, directItemById, context.byId);
+    if (!from || !to || from === to) continue;
+    const key = `${from}\u0000${to}`;
+    edgeWeights.set(key, (edgeWeights.get(key) || 0) + positiveNumber(relation.priority, 1));
+  }
+  const edges = [...edgeWeights].map(([key, weight]) => {
+    const [from, to] = key.split("\u0000");
+    return { from, to, weight };
+  });
+
+  const predecessors = new Map(ids.map(id => [id, []]));
+  const successors = new Map(ids.map(id => [id, []]));
+  const indegree = new Map(ids.map(id => [id, 0]));
+  for (const edge of edges) {
+    predecessors.get(edge.to).push(edge);
+    successors.get(edge.from).push(edge);
+    indegree.set(edge.to, indegree.get(edge.to) + 1);
+  }
+
+  const layerById = new Map(ids.map(id => [id, 0]));
+  const processed = new Set();
+  let cycleReported = false;
+  while (processed.size < ids.length) {
+    let available = ids.filter(id => !processed.has(id) && indegree.get(id) === 0);
+    if (!available.length) {
+      available = ids.filter(id => !processed.has(id)).slice(0, 1);
+      if (!cycleReported) {
+        cycleReported = true;
+        diagnostic(diagnostics, "warning", "GRAPH_CYCLE_STABILIZED",
+          "Graph layout contains a directed cycle; authored order was used to break it deterministically.");
+      }
+    }
+    available.sort((left, right) => authoredIndex.get(left) - authoredIndex.get(right));
+    const id = available[0];
+    const resolvedPredecessors = predecessors.get(id).filter(edge => processed.has(edge.from));
+    layerById.set(id, resolvedPredecessors.length
+      ? Math.max(...resolvedPredecessors.map(edge => layerById.get(edge.from) + 1))
+      : 0);
+    processed.add(id);
+    for (const edge of successors.get(id)) indegree.set(edge.to, Math.max(0, indegree.get(edge.to) - 1));
+  }
+
+  const layers = [];
+  for (const id of ids) {
+    const layer = layerById.get(id);
+    layers[layer] ||= [];
+    layers[layer].push(id);
+  }
+  const order = new Map();
+  const updateOrder = () => layers.forEach(layer => layer.forEach((id, index) => order.set(id, index)));
+  const ownerHints = context?.graphOrderHints?.get(ownerId ?? null);
+  const reorder = (layer, neighbors) => layer.sort((left, right) => {
+    const score = id => {
+      const related = neighbors.get(id).filter(edge => order.has(edge.from === id ? edge.to : edge.from));
+      const external = ownerHints?.get(id);
+      if (!related.length && !external) return null;
+      const internalWeight = related.reduce((sum, edge) => sum + edge.weight, 0);
+      const internalScore = related.reduce((sum, edge) => {
+        const other = edge.from === id ? edge.to : edge.from;
+        const otherLayer = layers[layerById.get(other)] || [];
+        const normalizedOrder = otherLayer.length > 1
+          ? order.get(other) / (otherLayer.length - 1)
+          : .5;
+        return sum + normalizedOrder * Math.max(0, layer.length - 1) * edge.weight;
+      }, 0);
+      const externalWeight = external?.weight || 0;
+      const externalScore = (external?.rank || 0) * Math.max(0, layer.length - 1);
+      const totalWeight = internalWeight + externalWeight;
+      return totalWeight ? (internalScore + externalScore * externalWeight) / totalWeight : null;
+    };
+    const leftScore = score(left);
+    const rightScore = score(right);
+    if (leftScore == null && rightScore == null) return authoredIndex.get(left) - authoredIndex.get(right);
+    if (leftScore == null) return 1;
+    if (rightScore == null) return -1;
+    return leftScore - rightScore || authoredIndex.get(left) - authoredIndex.get(right);
+  });
+
+  updateOrder();
+  if (ownerHints?.size) {
+    const adjacent = new Map(ids.map(id => [id, [...predecessors.get(id), ...successors.get(id)]]));
+    for (const layer of layers) reorder(layer, adjacent);
+    updateOrder();
+  }
+  for (let pass = 0; pass < 6; pass++) {
+    for (let layer = 1; layer < layers.length; layer++) {
+      reorder(layers[layer], predecessors);
+      updateOrder();
+    }
+    for (let layer = layers.length - 2; layer >= 0; layer--) {
+      reorder(layers[layer], successors);
+      updateOrder();
+    }
+  }
+
+  const { main, cross, depth } = graphAxes(spec);
+  const byItemId = new Map(items.map(item => [item.entity.id, item]));
+  const layerExtents = layers.map(layer => Math.max(...layer.map(id => byItemId.get(id).size[main])));
+  const mainPositions = [];
+  let mainCursor = 0;
+  for (let index = 0; index < layers.length; index++) {
+    if (index) mainCursor += layerExtents[index - 1] / 2 + gap * 1.6 + layerExtents[index] / 2;
+    mainPositions[index] = mainCursor;
+  }
+  const directionSign = main === 0 ? 1 : -1;
+  const spatialLayers = spec.spatial === true
+    ? Math.max(2, Math.min(4, Math.floor(positiveNumber(spec.depthLayers, 3))))
+    : 1;
+  const spatialPhase = Math.floor(scalar(spec.spatialPhase, 0));
+  const depthPitch = (Math.max(...items.map(item => item.size[depth]), 1) + gap)
+    * positiveNumber(spec.depthScale, 1);
+  const placements = [];
+  layers.forEach((layer, layerIndex) => {
+    const totalCross = layer.reduce((sum, id) => sum + byItemId.get(id).size[cross], 0)
+      + Math.max(0, layer.length - 1) * gap;
+    let crossCursor = -totalCross / 2;
+    for (let itemIndex = 0; itemIndex < layer.length; itemIndex++) {
+      const id = layer[itemIndex];
+      const item = byItemId.get(id);
+      const position = [0, 0, 0];
+      crossCursor += item.size[cross] / 2;
+      position[main] = mainPositions[layerIndex] * directionSign;
+      position[cross] = crossCursor;
+      if (spatialLayers > 1) {
+        const lane = (layerIndex + itemIndex + spatialPhase) % spatialLayers;
+        position[depth] = (lane - (spatialLayers - 1) / 2) * depthPitch;
+      }
+      crossCursor += item.size[cross] / 2 + gap;
+      placements.push({ ...item, position, graphLayer: layerIndex });
+    }
+  });
+  return boundsOf(placements, padding);
+}
+
 function resolveTheme(source) {
   const theme = source.theme || source.styles || {};
   const render = source.render || {};
@@ -1039,7 +1234,602 @@ export function compileAtlasProjection(input, visibleIds, options = {}) {
   return compileAtlasModel(projectedAtlasSource(input, visibleIds), options);
 }
 
-export function compileAtlasModel(input, options = {}) {
+function globalGraphOrderHints(source, flat, relations, byId) {
+  const depthOf = id => {
+    let depth = 0;
+    let cursor = id ? byId.get(id) : null;
+    const seen = new Set();
+    while (cursor?.parent && !seen.has(cursor.id)) {
+      seen.add(cursor.id);
+      depth += 1;
+      cursor = byId.get(cursor.parent);
+    }
+    return depth;
+  };
+  const owners = [];
+  const rootChildren = flat.entities.filter(entity => !entity.parent).map(entity => entity.id);
+  if (source.layout?.algorithm === "graph" && rootChildren.length) {
+    owners.push({ id: null, depth: -1, children: rootChildren });
+  }
+  for (const entity of flat.entities) {
+    const children = flat.childrenById.get(entity.id) || [];
+    const layout = flat.sourceById.get(entity.id)?.layout;
+    if (layout?.algorithm === "graph" && children.length) {
+      owners.push({ id: entity.id, depth: depthOf(entity.id), children: [...children] });
+    }
+  }
+  if (owners.length < 2) return new Map();
+
+  const immediateChild = (endpointId, owner) => {
+    let cursor = byId.get(endpointId);
+    const seen = new Set();
+    while (cursor && !seen.has(cursor.id)) {
+      seen.add(cursor.id);
+      if (owner.id === null && !cursor.parent) return owner.children.includes(cursor.id) ? cursor.id : null;
+      if (cursor.parent === owner.id) return owner.children.includes(cursor.id) ? cursor.id : null;
+      cursor = cursor.parent ? byId.get(cursor.parent) : null;
+    }
+    return null;
+  };
+  const membership = endpointId => owners
+    .map(owner => ({ owner, child: immediateChild(endpointId, owner) }))
+    .filter(item => item.child)
+    .sort((left, right) => right.owner.depth - left.owner.depth)[0] || null;
+
+  const links = new Map(owners.map(owner => [owner.id, new Map(owner.children.map(id => [id, []]))]));
+  for (const relation of relations) {
+    if (relation.layout === false) continue;
+    const from = membership(relation.from);
+    const to = membership(relation.to);
+    if (!from || !to || from.owner.id === to.owner.id) continue;
+    const weight = positiveNumber(relation.priority, 1);
+    links.get(from.owner.id).get(from.child).push({ ownerId: to.owner.id, childId: to.child, weight });
+    links.get(to.owner.id).get(to.child).push({ ownerId: from.owner.id, childId: from.child, weight });
+  }
+
+  const authored = new Map();
+  const ranks = new Map();
+  for (const owner of owners) {
+    const divisor = Math.max(1, owner.children.length - 1);
+    authored.set(owner.id, new Map(owner.children.map((id, index) => [id, index])));
+    ranks.set(owner.id, new Map(owner.children.map((id, index) => [id, index / divisor])));
+  }
+  const sweep = orderedOwners => {
+    for (const owner of orderedOwners) {
+      const ownerLinks = links.get(owner.id);
+      const previousRanks = ranks.get(owner.id);
+      const scored = owner.children.map(id => {
+        const neighbors = ownerLinks.get(id) || [];
+        const total = neighbors.reduce((sum, neighbor) => sum + neighbor.weight, 0);
+        const score = total
+          ? neighbors.reduce((sum, neighbor) => sum + (ranks.get(neighbor.ownerId)?.get(neighbor.childId) ?? .5) * neighbor.weight, 0) / total
+          : previousRanks.get(id);
+        return { id, score, linked: total > 0 };
+      });
+      scored.sort((left, right) => left.score - right.score
+        || Number(right.linked) - Number(left.linked)
+        || authored.get(owner.id).get(left.id) - authored.get(owner.id).get(right.id));
+      const divisor = Math.max(1, scored.length - 1);
+      ranks.set(owner.id, new Map(scored.map((item, index) => [item.id, index / divisor])));
+    }
+  };
+  for (let pass = 0; pass < 8; pass += 1) {
+    sweep(owners);
+    sweep([...owners].reverse());
+  }
+
+  const hints = new Map();
+  for (const owner of owners) {
+    const ownerHints = new Map();
+    for (const childId of owner.children) {
+      const neighbors = links.get(owner.id).get(childId) || [];
+      const total = neighbors.reduce((sum, neighbor) => sum + neighbor.weight, 0);
+      if (!total) continue;
+      const rank = neighbors.reduce((sum, neighbor) =>
+        sum + (ranks.get(neighbor.ownerId)?.get(neighbor.childId) ?? .5) * neighbor.weight, 0) / total;
+      ownerHints.set(childId, { rank, weight: total * 2 });
+    }
+    if (ownerHints.size) hints.set(owner.id, ownerHints);
+  }
+  return hints;
+}
+
+const AUTO_LAYOUT_DEFAULT_CAMERA = Object.freeze({
+  position: [12, 8, 14],
+  target: [0, 0, 0]
+});
+
+function autoLayoutOwners(source) {
+  const owners = [];
+  const add = (owner, id, root = false) => {
+    if (owner?.layout?.algorithm === "auto") owners.push({ owner, id, root, authoredLayout: structuredClone(owner.layout) });
+    for (const group of owner?.layout?.groups || []) add(group, `${id ?? "root"}::group:${group.id || owners.length}`);
+  };
+  add(source, null, true);
+  const visit = items => {
+    for (const entity of Array.isArray(items) ? items : []) {
+      add(entity, entity.id);
+      visit(entity.children);
+    }
+  };
+  visit(source.entities);
+  return owners;
+}
+
+function autoGraphPlanes(direction) {
+  if (direction === "x") return ["xy", "xz"];
+  if (direction === "y") return ["xy", "yz"];
+  return ["xz", "yz"];
+}
+
+function autoLayoutCandidates(entry) {
+  const authored = entry.authoredLayout || entry.owner.layout || {};
+  const common = { ...authored, gap: authored.gap ?? 3, padding: authored.padding ?? 1 };
+  delete common.algorithm;
+  const directions = authored.direction ? [authored.direction] : entry.root ? ["y", "x", "z"] : ["z", "x", "y"];
+  const planes = authored.plane ? [authored.plane] : ["xy", "xz", "yz"];
+  const candidates = [];
+  for (const direction of directions) {
+    const graphPlanes = authored.plane ? planes : autoGraphPlanes(direction);
+    for (const plane of graphPlanes) {
+      candidates.push({ ...common, algorithm: "graph", direction, plane });
+      if (!authored.plane) {
+        for (let spatialPhase = 0; spatialPhase < 3; spatialPhase++) {
+          candidates.push({
+            ...common,
+            algorithm: "graph",
+            direction,
+            plane,
+            spatial: true,
+            depthLayers: 3,
+            spatialPhase,
+            // Automatic depth lanes are an escape route for real collisions,
+            // not a reason to inflate the whole scene. Explicit graph layouts
+            // retain the historical full pitch unless they opt into a scale.
+            depthScale: .55
+          });
+        }
+      }
+    }
+  }
+  for (const direction of directions) candidates.push({ ...common, algorithm: "row", direction });
+  if (!authored.direction || authored.plane) {
+    for (const plane of planes) candidates.push({ ...common, algorithm: "grid", plane });
+  }
+  // Volume has no privileged axis or plane. Only offer it when the author has
+  // not locked either of those decisions; otherwise choosing it would silently
+  // ignore an explicit constraint.
+  if (!authored.direction && !authored.plane) candidates.push({ ...common, algorithm: "volume" });
+  const keys = new Set();
+  return candidates.filter(candidate => {
+    const key = JSON.stringify([
+      candidate.algorithm,
+      candidate.direction || "",
+      candidate.plane || "",
+      candidate.columns || "",
+      candidate.rows || "",
+      candidate.layers || "",
+      candidate.spatial || false,
+      candidate.depthLayers || "",
+      candidate.spatialPhase || "",
+      candidate.depthScale || "",
+      candidate.gap,
+      candidate.padding
+    ]);
+    if (keys.has(key)) return false;
+    keys.add(key);
+    return true;
+  });
+}
+
+function vectorSubtract(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+
+function vectorDot(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+function vectorCross(a, b) {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0]
+  ];
+}
+
+function vectorNormalize(value, fallback) {
+  const length = Math.hypot(...value);
+  return length > 1e-9 ? value.map(item => item / length) : [...fallback];
+}
+
+function autoProjection(render = {}) {
+  const camera = render.camera || AUTO_LAYOUT_DEFAULT_CAMERA;
+  const position = asVector(camera.position, AUTO_LAYOUT_DEFAULT_CAMERA.position);
+  const target = asVector(camera.target, AUTO_LAYOUT_DEFAULT_CAMERA.target);
+  const forward = vectorNormalize(vectorSubtract(target, position), [0, 0, -1]);
+  let right = vectorNormalize(vectorCross(forward, [0, 1, 0]), [1, 0, 0]);
+  if (Math.abs(vectorDot(right, right)) < 1e-9) right = [1, 0, 0];
+  const up = vectorNormalize(vectorCross(right, forward), [0, 1, 0]);
+  return point => {
+    const relative = vectorSubtract(point, target);
+    return [vectorDot(relative, right), vectorDot(relative, up), vectorDot(relative, forward)];
+  };
+}
+
+function orientation2d(a, b, c) {
+  return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+}
+
+function strictSegmentIntersection2d(a, b, c, d) {
+  const abC = orientation2d(a, b, c);
+  const abD = orientation2d(a, b, d);
+  const cdA = orientation2d(c, d, a);
+  const cdB = orientation2d(c, d, b);
+  const epsilon = 1e-7;
+  return ((abC > epsilon && abD < -epsilon) || (abC < -epsilon && abD > epsilon))
+    && ((cdA > epsilon && cdB < -epsilon) || (cdA < -epsilon && cdB > epsilon));
+}
+
+function segmentIntersectsRect2d(a, b, rect) {
+  const inset = Math.min(rect.maxX - rect.minX, rect.maxY - rect.minY) * .08;
+  const minX = rect.minX + inset;
+  const maxX = rect.maxX - inset;
+  const minY = rect.minY + inset;
+  const maxY = rect.maxY - inset;
+  if (minX >= maxX || minY >= maxY) return false;
+  const inside = point => point[0] > minX && point[0] < maxX && point[1] > minY && point[1] < maxY;
+  if (inside(a) || inside(b)) return true;
+  const corners = [[minX, minY], [maxX, minY], [maxX, maxY], [minX, maxY]];
+  return corners.some((corner, index) => strictSegmentIntersection2d(a, b, corner, corners[(index + 1) % corners.length]));
+}
+
+function segmentIntersectsBox3d(a, b, box) {
+  let minimum = 0;
+  let maximum = 1;
+  for (let axis = 0; axis < 3; axis++) {
+    const delta = b[axis] - a[axis];
+    if (Math.abs(delta) < 1e-9) {
+      if (a[axis] <= box.min[axis] || a[axis] >= box.max[axis]) return false;
+      continue;
+    }
+    let near = (box.min[axis] - a[axis]) / delta;
+    let far = (box.max[axis] - a[axis]) / delta;
+    if (near > far) [near, far] = [far, near];
+    minimum = Math.max(minimum, near);
+    maximum = Math.min(maximum, far);
+    if (minimum >= maximum) return false;
+  }
+  return maximum > 1e-7 && minimum < 1 - 1e-7;
+}
+
+function boxesOverlap3d(left, right) {
+  return [0, 1, 2].every(axis =>
+    Math.min(left.max[axis], right.max[axis]) > Math.max(left.min[axis], right.min[axis]));
+}
+
+function projectedLayoutMetrics(model, world, boxes, camera) {
+  const project = autoProjection({ camera });
+  const points = new Map([...world].map(([id, point]) => [id, project(point)]));
+  const rectangles = new Map();
+  for (const [id, box] of boxes) {
+    const corners = [];
+    for (const x of [box.min[0], box.max[0]]) for (const y of [box.min[1], box.max[1]]) for (const z of [box.min[2], box.max[2]]) {
+      corners.push(project([x, y, z]));
+    }
+    rectangles.set(id, {
+      minX: Math.min(...corners.map(point => point[0])),
+      maxX: Math.max(...corners.map(point => point[0])),
+      minY: Math.min(...corners.map(point => point[1])),
+      maxY: Math.max(...corners.map(point => point[1]))
+    });
+  }
+  const segments = (model.relations || []).filter(relation => relation.layout !== false).flatMap(relation => {
+    const from = points.get(relation.from);
+    const to = points.get(relation.to);
+    return from && to ? [{ relation, from, to }] : [];
+  });
+  let crossings = 0;
+  for (let left = 0; left < segments.length; left++) for (let right = left + 1; right < segments.length; right++) {
+    const a = segments[left];
+    const b = segments[right];
+    if ([a.relation.from, a.relation.to].some(id => id === b.relation.from || id === b.relation.to)) continue;
+    if (strictSegmentIntersection2d(a.from, a.to, b.from, b.to)) crossings += 1;
+  }
+  let traversals = 0;
+  for (const segment of segments) {
+    for (const [id, rect] of rectangles) {
+      if (id === segment.relation.from || id === segment.relation.to) continue;
+      if (segmentIntersectsRect2d(segment.from, segment.to, rect)) traversals += 1;
+    }
+  }
+  let overlaps = 0;
+  let occlusion = 0;
+  const rectangleEntries = [...rectangles];
+  for (let left = 0; left < rectangleEntries.length; left++) for (let right = left + 1; right < rectangleEntries.length; right++) {
+    const a = rectangleEntries[left][1];
+    const b = rectangleEntries[right][1];
+    const overlapWidth = Math.min(a.maxX, b.maxX) - Math.max(a.minX, b.minX);
+    const overlapHeight = Math.min(a.maxY, b.maxY) - Math.max(a.minY, b.minY);
+    if (overlapWidth > 0 && overlapHeight > 0) {
+      overlaps += 1;
+      const leftArea = Math.max(1e-9, (a.maxX - a.minX) * (a.maxY - a.minY));
+      const rightArea = Math.max(1e-9, (b.maxX - b.minX) * (b.maxY - b.minY));
+      occlusion += overlapWidth * overlapHeight / Math.min(leftArea, rightArea);
+    }
+  }
+  const projected = [...points.values()];
+  const width = projected.length ? Math.max(...projected.map(point => point[0])) - Math.min(...projected.map(point => point[0])) : 0;
+  const height = projected.length ? Math.max(...projected.map(point => point[1])) - Math.min(...projected.map(point => point[1])) : 0;
+  return { crossings, traversals, overlaps, occlusion, footprint: width * height };
+}
+
+const AUTO_LAYOUT_FRONT_CAMERA = Object.freeze({
+  position: [0, 0, 100],
+  target: [0, 0, 0]
+});
+
+const AUTO_LAYOUT_CANONICAL_CAMERAS = Object.freeze([
+  Object.freeze({ position: [12, 8, 14], target: [0, 0, 0] }),
+  Object.freeze({ position: [-12, 8, 14], target: [0, 0, 0] }),
+  Object.freeze({ position: [12, 8, -14], target: [0, 0, 0] }),
+  Object.freeze({ position: [-12, 8, -14], target: [0, 0, 0] })
+]);
+
+function cameraDirectionKey(camera) {
+  const position = asVector(camera?.position, AUTO_LAYOUT_DEFAULT_CAMERA.position);
+  const target = asVector(camera?.target, AUTO_LAYOUT_DEFAULT_CAMERA.target);
+  return vectorNormalize(vectorSubtract(target, position), [0, 0, -1]).map(value => value.toFixed(3)).join(":");
+}
+
+function autoLayoutCameras(model, options = {}) {
+  const primary = options.camera || model.render?.camera || AUTO_LAYOUT_DEFAULT_CAMERA;
+  const seen = new Set();
+  return [{ camera: primary, weight: 1, primary: true }, ...AUTO_LAYOUT_CANONICAL_CAMERAS.map(camera => ({ camera, weight: .35, primary: false }))]
+    .filter(entry => {
+      const key = cameraDirectionKey(entry.camera);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+function layoutPlane(layout = {}) {
+  if (["graph", "grid"].includes(layout.algorithm) && ["xy", "xz", "yz"].includes(layout.plane)) return layout.plane;
+  if (layout.algorithm === "row") return { x: "yz", y: "xz", z: "xy" }[layout.direction] || null;
+  return null;
+}
+
+function layoutOrientationMismatches(source) {
+  if (!source || typeof source !== "object") return 0;
+  let mismatches = 0;
+  const visit = owner => {
+    const expected = layoutPlane(owner.layout);
+    for (const child of Array.isArray(owner.entities) ? owner.entities : Array.isArray(owner.children) ? owner.children : []) {
+      if (isContainerType(child?.type) || Array.isArray(child?.children)) {
+        const actual = layoutPlane(child.layout);
+        if (expected && actual && expected !== actual) mismatches += 1;
+      }
+      visit(child);
+    }
+  };
+  visit(source);
+  return mismatches;
+}
+
+function elongationPenalty(extents) {
+  const ordered = extents.map(value => Math.max(0, value)).sort((left, right) => right - left);
+  const ratio = ordered[0] / Math.max(ordered[1], 1e-6);
+  return { ratio, penalty: Math.max(0, ratio - 3) ** 2 };
+}
+
+function median(values, fallback = 1) {
+  if (!values.length) return fallback;
+  const ordered = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(ordered.length / 2);
+  return ordered.length % 2
+    ? ordered[middle]
+    : (ordered[middle - 1] + ordered[middle]) / 2;
+}
+
+function autoLayoutMetrics(model, options = {}) {
+  const byId = new Map((model.entities || []).map(entity => [entity.id, entity]));
+  const world = new Map();
+  const resolveWorld = id => {
+    if (world.has(id)) return world.get(id);
+    const entity = byId.get(id);
+    if (!entity) return [0, 0, 0];
+    const position = asVector(entity.p);
+    const resolved = entity.parent ? add(resolveWorld(entity.parent), position) : position;
+    world.set(id, resolved);
+    return resolved;
+  };
+  for (const id of byId.keys()) resolveWorld(id);
+  const boxes = new Map();
+  for (const entity of model.entities || []) {
+    if (isContainerType(entity.type)) continue;
+    const center = world.get(entity.id);
+    const size = asVector(entity.s, [1, 1, 1]);
+    boxes.set(entity.id, {
+      min: center.map((value, axis) => value - size[axis] * .42),
+      max: center.map((value, axis) => value + size[axis] * .42)
+    });
+  }
+  const spatialSegments = (model.relations || []).filter(relation => relation.layout !== false).flatMap(relation => {
+    const from = world.get(relation.from);
+    const to = world.get(relation.to);
+    return from && to ? [{ relation, from, to }] : [];
+  });
+  let spatialTraversals = 0;
+  for (const segment of spatialSegments) {
+    for (const [id, box] of boxes) {
+      if (id === segment.relation.from || id === segment.relation.to) continue;
+      if (segmentIntersectsBox3d(segment.from, segment.to, box)) spatialTraversals += 1;
+    }
+  }
+  let spatialOverlaps = 0;
+  const boxEntries = [...boxes];
+  for (let left = 0; left < boxEntries.length; left++) for (let right = left + 1; right < boxEntries.length; right++) {
+    if (boxesOverlap3d(boxEntries[left][1], boxEntries[right][1])) spatialOverlaps += 1;
+  }
+  const views = autoLayoutCameras(model, options).map(entry => ({
+    ...projectedLayoutMetrics(model, world, boxes, entry.camera),
+    weight: entry.weight,
+    primary: entry.primary
+  }));
+  const front = projectedLayoutMetrics(model, world, boxes, AUTO_LAYOUT_FRONT_CAMERA);
+  const primary = views.find(view => view.primary) || views[0] || { crossings: 0, traversals: 0, overlaps: 0, footprint: 0 };
+  const robustCrossings = views.reduce((sum, view) => sum + view.crossings * view.weight, 0);
+  const robustTraversals = views.reduce((sum, view) => sum + view.traversals * view.weight, 0);
+  const robustOverlaps = views.reduce((sum, view) => sum + view.overlaps * view.weight, 0);
+  const footprint = views.reduce((sum, view) => sum + view.footprint * view.weight, 0);
+  const edgeLength = spatialSegments.reduce((sum, segment) => sum + Math.hypot(
+    segment.to[0] - segment.from[0],
+    segment.to[1] - segment.from[1],
+    segment.to[2] - segment.from[2]
+  ), 0);
+  const bounds = [...boxes.values()];
+  const extents = bounds.length ? [0, 1, 2].map(axis =>
+    Math.max(...bounds.map(box => box.max[axis])) - Math.min(...bounds.map(box => box.min[axis]))) : [0, 0, 0];
+  const elongation = elongationPenalty(extents);
+  const orientationMismatches = layoutOrientationMismatches(options.source);
+  const characteristicSize = median([...boxes.values()].map(box => Math.hypot(
+    box.max[0] - box.min[0],
+    box.max[1] - box.min[1],
+    box.max[2] - box.min[2]
+  )));
+  const relationCount = Math.max(1, spatialSegments.length);
+  const normalizedEdgeLength = edgeLength / relationCount / Math.max(characteristicSize, 1e-6);
+  const sceneVolume = extents.reduce((product, extent) => product * Math.max(extent, 1e-6), 1);
+  const itemVolume = [...boxes.values()].reduce((sum, box) => sum
+    + (box.max[0] - box.min[0])
+    * (box.max[1] - box.min[1])
+    * (box.max[2] - box.min[2]), 0);
+  const volumeRatio = sceneVolume / Math.max(itemVolume, 1e-6);
+  const compactnessPenalty = Math.cbrt(Math.max(1, volumeRatio));
+  const frontProject = autoProjection({ camera: AUTO_LAYOUT_FRONT_CAMERA });
+  const orthogonalDeviation = spatialSegments.reduce((sum, segment) => {
+    const from = frontProject(segment.from);
+    const to = frontProject(segment.to);
+    return sum + Math.min(Math.abs(to[0] - from[0]), Math.abs(to[1] - from[1]))
+      / Math.max(characteristicSize, 1e-6);
+  }, 0) / relationCount;
+  // Formal 3D validity remains effectively absolute. Once candidates are
+  // physically valid, projected defects compete with the qualities people use
+  // to judge a diagram: short relations, compact grouping and orthogonal flow.
+  // This prevents the optimizer from "winning" by moving valid groups ever
+  // farther apart merely to remove a small projected crossing.
+  const aestheticScore = primary.traversals * 120
+    + front.traversals * 100
+    + robustTraversals * 25
+    + front.overlaps * 250
+    + front.occlusion * 600
+    + primary.crossings * 6
+    + front.crossings * 5
+    + robustCrossings * 2
+    + robustOverlaps * 40
+    + orientationMismatches * 50
+    + elongation.penalty * 30
+    + normalizedEdgeLength * 80
+    + compactnessPenalty * 100
+    + orthogonalDeviation * 35;
+  return {
+    crossings: primary.crossings,
+    traversals: primary.traversals,
+    overlaps: primary.overlaps,
+    worstCrossings: Math.max(0, ...views.map(view => view.crossings)),
+    worstTraversals: Math.max(0, ...views.map(view => view.traversals)),
+    frontCrossings: front.crossings,
+    frontTraversals: front.traversals,
+    frontOverlaps: front.overlaps,
+    frontOcclusion: front.occlusion,
+    spatialTraversals,
+    spatialOverlaps,
+    orientationMismatches,
+    elongation: elongation.ratio,
+    elongationPenalty: elongation.penalty,
+    edgeLength,
+    normalizedEdgeLength,
+    sceneVolume,
+    volumeRatio,
+    compactnessPenalty,
+    orthogonalDeviation,
+    footprint,
+    aestheticScore,
+    views: views.map(({ weight, primary: isPrimary, ...metrics }) => ({ ...metrics, weight, primary: isPrimary })),
+    score: spatialTraversals * 1e12
+      + spatialOverlaps * 1e10
+      + aestheticScore
+  };
+}
+
+function compareAutoLayoutMetrics(left, right) {
+  // A line or an item may never pass through another item in real 3D space.
+  // Everything after those two feasibility checks is a perceptual trade-off;
+  // comparing each projected metric lexicographically made very sparse scenes
+  // look optimal even when a human would immediately compact them.
+  const fields = [
+    "spatialTraversals",
+    "spatialOverlaps"
+  ];
+  for (const field of fields) {
+    const difference = (left?.[field] || 0) - (right?.[field] || 0);
+    if (Math.abs(difference) > 1e-7) return difference;
+  }
+  const scoreDifference = (left?.aestheticScore || 0) - (right?.aestheticScore || 0);
+  if (Math.abs(scoreDifference) > 1e-7) return scoreDifference;
+  // Stable deterministic tie-breakers retain the authored/candidate order only
+  // after two layouts are perceptually indistinguishable.
+  for (const field of ["frontOcclusion", "frontOverlaps", "normalizedEdgeLength", "compactnessPenalty", "footprint"]) {
+    const difference = (left?.[field] || 0) - (right?.[field] || 0);
+    if (Math.abs(difference) > 1e-7) return difference;
+  }
+  return (left?.score || 0) - (right?.score || 0);
+}
+
+export function analyzeAtlasLayout(model, options = {}) {
+  return { ...autoLayoutMetrics(model, options) };
+}
+
+function resolveAutomaticLayouts(input, options = {}) {
+  const authored = structuredClone(normalizeRoot(input));
+  const source = structuredClone(authored);
+  const owners = autoLayoutOwners(source);
+  if (!owners.length) return null;
+
+  for (const entry of owners) {
+    const initial = autoLayoutCandidates(entry)[0];
+    entry.owner.layout = initial;
+  }
+  const decisions = new Map();
+  const metricOptions = { camera: options.autoLayoutCamera, source };
+  let metrics = autoLayoutMetrics(compileResolvedAtlasModel(source, { ...options, throwOnFatal: false }), metricOptions);
+  for (let pass = 0; pass < 3; pass++) {
+    let changed = false;
+    // Resolve nested content before its owner. Container dimensions and the
+    // external connection lanes are then stable when the parent chooses its
+    // global arrangement, avoiding a sparse root decision based on provisional
+    // child layouts.
+    for (const entry of [...owners].reverse()) {
+      const previous = entry.owner.layout;
+      let best = { layout: previous, metrics };
+      for (const candidate of autoLayoutCandidates(entry)) {
+        entry.owner.layout = candidate;
+        const candidateModel = compileResolvedAtlasModel(source, { ...options, throwOnFatal: false });
+        const candidateMetrics = autoLayoutMetrics(candidateModel, metricOptions);
+        if (compareAutoLayoutMetrics(candidateMetrics, best.metrics) < 0) best = { layout: candidate, metrics: candidateMetrics };
+      }
+      entry.owner.layout = best.layout;
+      if (JSON.stringify(best.layout) !== JSON.stringify(previous)) changed = true;
+      metrics = best.metrics;
+      decisions.set(entry.id, best.layout);
+    }
+    if (!changed) break;
+  }
+  return { authored, source, owners, decisions, metrics };
+}
+
+function compileResolvedAtlasModel(input, options = {}) {
   const diagnostics = [];
   const source = normalizeRoot(input);
   const palette = paletteFrom(source);
@@ -1050,6 +1840,8 @@ export function compileAtlasModel(input, options = {}) {
   const relations = normalizeRelations(source.relations, validIds, diagnostics);
   resolveStyles(flat.entities, flat.sourceById, flat.childrenById, palette, diagnostics);
   const byId = new Map(flat.entities.map(entity => [entity.id, entity]));
+  const graphContext = { relations, byId };
+  graphContext.graphOrderHints = globalGraphOrderHints(source, flat, relations, byId);
   const geometrySizes = { ...DEFAULT_SIZES };
   for (const definition of options.geometryCatalog || []) {
     if (!definition?.id || !Array.isArray(definition.canonicalSize) || definition.canonicalSize.length !== 3) continue;
@@ -1074,15 +1866,11 @@ export function compileAtlasModel(input, options = {}) {
     const spec = sourceEntity.layout || { algorithm: "grid" };
     const algorithm = ALGORITHMS.has(spec.algorithm) ? spec.algorithm : "grid";
     if (!ALGORITHMS.has(spec.algorithm || "grid")) diagnostic(diagnostics, "warning", "UNKNOWN_LAYOUT_ALGORITHM", `Unknown layout algorithm '${spec.algorithm}', using grid.`, { entityId });
-    if (algorithm === "graph") diagnostic(diagnostics, "warning", "GRAPH_LAYOUT_FALLBACK", `Graph layout for '${entityId}' is reserved for a later compiler pass; using grid for now.`, { entityId });
     const declared = Array.isArray(entity.size) && entity.size.length === 3 ? asVector(entity.size) : null;
     const result = constrainedLayout(childItems, spec, sourceEntity, diagnostics, entityId,
-      algorithm === "row"
-        ? rowLayout
-        : algorithm === "volume"
-          ? volumeLayout
-          : gridLayout,
-      declared);
+      layoutFunction(spec, diagnostics, entityId, graphContext),
+      declared,
+      graphContext);
     for (const placement of result.positions) {
       const child = byId.get(placement.entity.id);
       child.p = placement.position;
@@ -1100,13 +1888,10 @@ export function compileAtlasModel(input, options = {}) {
   const rootItems = flat.entities.filter(entity => !entity.parent).map(entity => ({ entity, size: layoutEntity(entity.id) }));
   const rootSpec = source.layout || { algorithm: "row", direction: "y", gap: 1.5, padding: 1 };
   const rootAlgorithm = ALGORITHMS.has(rootSpec.algorithm) ? rootSpec.algorithm : "row";
-  if (rootAlgorithm === "graph") diagnostic(diagnostics, "warning", "GRAPH_LAYOUT_FALLBACK", "Graph layout for the root is reserved for a later compiler pass; using grid for now.");
   const rootResult = constrainedLayout(rootItems, rootSpec, source, diagnostics, null,
-    rootAlgorithm === "row"
-      ? rowLayout
-      : rootAlgorithm === "volume"
-        ? volumeLayout
-        : gridLayout);
+    layoutFunction(rootSpec, diagnostics, null, graphContext),
+    null,
+    graphContext);
   for (const placement of rootResult.positions) {
     const entity = byId.get(placement.entity.id);
     entity.p = placement.position;
@@ -1132,6 +1917,39 @@ export function compileAtlasModel(input, options = {}) {
   return output;
 }
 
+export function compileAtlasModel(input, options = {}) {
+  const automatic = resolveAutomaticLayouts(input, options);
+  if (!automatic) return compileResolvedAtlasModel(input, options);
+  const model = compileResolvedAtlasModel(automatic.source, options);
+  model.layout = automatic.authored.layout || undefined;
+  for (const entry of automatic.owners) {
+    const resolved = automatic.decisions.get(entry.id) || entry.owner.layout;
+    diagnostic(model.diagnostics, "info", "AUTO_LAYOUT_RESOLVED",
+      `Automatic layout resolved '${entry.id ?? "root"}' to ${resolved.algorithm} on ${resolved.direction || resolved.plane || "default axes"}.`, {
+        ownerId: entry.id,
+        resolvedLayout: { ...resolved },
+        score: automatic.metrics.score,
+        crossings: automatic.metrics.crossings,
+        traversals: automatic.metrics.traversals,
+        worstCrossings: automatic.metrics.worstCrossings,
+        worstTraversals: automatic.metrics.worstTraversals,
+        spatialTraversals: automatic.metrics.spatialTraversals,
+        spatialOverlaps: automatic.metrics.spatialOverlaps,
+        frontCrossings: automatic.metrics.frontCrossings,
+        frontTraversals: automatic.metrics.frontTraversals,
+        frontOverlaps: automatic.metrics.frontOverlaps,
+        frontOcclusion: automatic.metrics.frontOcclusion,
+        orientationMismatches: automatic.metrics.orientationMismatches,
+        elongation: automatic.metrics.elongation,
+        normalizedEdgeLength: automatic.metrics.normalizedEdgeLength,
+        compactnessPenalty: automatic.metrics.compactnessPenalty,
+        orthogonalDeviation: automatic.metrics.orthogonalDeviation,
+        volumeRatio: automatic.metrics.volumeRatio
+      });
+  }
+  return model;
+}
+
 export function compileAtlasModelWithDiagnostics(input, options = {}) {
   const model = compileAtlasModel(input, options);
   return { model, diagnostics: model.diagnostics || [] };

package/src/spec.js

@@ -30,7 +30,9 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         name: field("Visible title.", null, { type: "string" }),
         sub: field("Visible subtitle.", null, { type: "string" }),
         text: field("Description shown by the inspector.", null, { type: "string" }),
+        url: field("External documentation opened from the inspector.", null, { type: "url" }),
         type: field("Structural role. Use container when declaring children; omit it for a leaf item.", ["container"]),
+        open: field("Initial expansion state for a container; omitted means closed.", [true, false]),
         parent: field("Parent entity id.", null, { type: "string", authoring: "absolute" }),
         children: field("Nested entities.", null, { context: "entity", sequence: true }),
         geometry: field("Geometry id supplied by Atlas or a registered pack.", null, { valueSource: "geometryCatalog" }),
@@ -56,6 +58,8 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         from: field("Source entity id.", null, { type: "string", required: true }),
         to: field("Target entity id.", null, { type: "string", required: true }),
         label: field("Text shown on the relation.", null, { type: "string" }),
+        text: field("Description shown by the inspector.", null, { type: "string" }),
+        url: field("External documentation opened from the inspector.", null, { type: "url" }),
         mode: field("Canonical visual relation mode.", ["directed", "bidirectional", "broken"]),
         visual: field("Historical alias for relation mode.", ["directed", "bidirectional", "broken"]),
         fromAnchor: field("Named source anchor.", null, { type: "string" }),
@@ -67,9 +71,9 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
     layout: freeze({
       label: "Layout",
       properties: freeze({
-        algorithm: field("Spatial strategy.", ["row", "grid", "volume", "graph"]),
+        algorithm: field("Spatial strategy. Auto evaluates the whole model; graph derives layers and sibling order from relations.", ["auto", "row", "grid", "volume", "graph"]),
         direction: field("Primary semantic axis.", ["x", "y", "z"]),
-        variant: field("Regular or staggered grid cells.", ["uniform", "masonry"]),
+        variant: field("Regular cells or masonry rows staggered by half a cell by default.", ["uniform", "masonry"]),
         plane: field("Axes used by a two-dimensional grid.", ["xz", "xy", "yz"]),
         packing: field("Preserve initial slots or compact free space after constraints.", ["preserve", "compact"]),
         groups: field("Invisible sibling groups used only during layout.", null, { context: "layoutGroup", sequence: true }),
@@ -79,7 +83,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         gap: field("Spacing between children.", null, { type: "number" }),
         padding: field("Spacing to the container boundary.", null, { type: "number" }),
         justify: field("Row alignment or distribution within an assigned size.", ["start", "center", "end", "space-between", "space-around", "space-evenly"]),
-        stagger: field("Optional masonry offset.", null, { context: "stagger" }),
+        stagger: field("Optional override for the masonry row offset.", null, { context: "stagger" }),
         constraints: field("Equal-size and edge-alignment rules for this layout's siblings.", null, { context: "constraint", sequence: true })
       })
     }),
@@ -137,10 +141,17 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
         selectionMode: field("Selection ownership.", ["internal", "event"]),
         toolbar: field("Built-in toolbar visibility.", [true, false]),
         shellLabels: field("Text-label contrast outline.", [true, false]),
+        navigation: field("Camera behavior triggered by selection.", null, { context: "navigation" }),
         focus: field("Selection-driven visual filtering.", null, { context: "focus" }),
         camera: field("Initial camera snapshot in model-space coordinates.", null, { context: "camera" })
       })
     }),
+    navigation: freeze({
+      label: "Selection navigation",
+      properties: freeze({
+        onSelect: field("Camera movement after a click or select() call.", ["preserve", "center", "fit"])
+      })
+    }),
     focus: freeze({
       label: "Visual focus",
       properties: freeze({
@@ -169,7 +180,7 @@ export const ATLAS_LAYOUT_SPEC_V1 = freeze({
     stagger: freeze({
       label: "Stagger",
       properties: freeze({
-        offset: field("Masonry row offset.", ["half-cell"], { type: "string" })
+        offset: field("Masonry row offset; defaults to half-cell.", ["half-cell"], { type: "string" })
       })
     }),
     label: freeze({ label: "Label appearance", properties: freeze({ color: field("Label colour.", null, { valueSource: "palette" }), opacity: field("Label opacity.", null, { type: "number" }) }) }),
@@ -196,6 +207,7 @@ export function atlasLayoutContextForPath(path = []) {
     ["palette", "palette"],
     ["theme", "theme"],
     ["render", "render"],
+    ["navigation", "navigation"],
     ["focus", "focus"],
     ["camera", "camera"],
     ["span", "span"],