@liquidcars/atlas-layout 0.1.3 → 0.1.7

package/src/index.js

@@ -1,3 +1,5 @@
+import { ATLAS_LAYOUT_SPEC_V1 } from "./spec.js";
+
 const DEFAULT_COLOR = "#b9d8eb";
 
 const DEFAULT_SIZES = Object.freeze({
@@ -16,6 +18,8 @@ const DEFAULT_SIZES = Object.freeze({
   icosahedron: [2.3, 2.3, 2.3]
 });
 
+const BUILTIN_GEOMETRY_IDS = new Set(Object.keys(DEFAULT_SIZES));
+
 const ASPECT_FACTORS = Object.freeze({
   compact: [1, 1, 1],
   wide: [1.35, 0.86, 0.86],
@@ -24,7 +28,7 @@ const ASPECT_FACTORS = Object.freeze({
   flat: [1.08, 0.56, 1.08]
 });
 
-const ALGORITHMS = new Set(["row", "grid", "volume", "graph"]);
+const ALGORITHMS = new Set(ATLAS_LAYOUT_SPEC_V1.contexts.layout.properties.algorithm.values);
 
 // Relation modes are part of the declarative model contract. The renderer
 // accepts a few historical aliases, but the build-time compiler always emits
@@ -86,6 +90,66 @@ function diagnostic(diagnostics, level, code, message, extra = {}) {
   diagnostics.push({ level, code, message, ...extra, recoverable: level !== "fatal" });
 }
 
+function isContainerType(type) {
+  return type === "container" || type === "shell";
+}
+
+function geometryCatalogDefinition(geometry, geometryCatalog = []) {
+  const requested = typeof geometry === "string" ? geometry.trim() : "";
+  return geometryCatalog.find(definition =>
+    definition?.id === requested || definition?.aliases?.includes(requested)
+  ) || null;
+}
+
+function isPrimitiveGeometry(geometry, geometryCatalog = []) {
+  if (geometry == null || geometry === "") return true;
+  const requested = String(geometry).trim();
+  const definition = geometryCatalogDefinition(requested, geometryCatalog);
+  if (definition) return Boolean(definition.primitive);
+  const localId = requested.includes(".") ? requested.split(".").at(-1) : requested;
+  return BUILTIN_GEOMETRY_IDS.has(localId)
+    && (!requested.includes(".") || requested.toLowerCase().startsWith("geo."));
+}
+
+function normalizeEntityTypes(flat, geometryCatalog, diagnostics) {
+  for (const entity of flat.entities) {
+    const source = flat.sourceById.get(entity.id) || {};
+    const declaredValue = source.type;
+    const declared = typeof declaredValue === "string" ? declaredValue.trim().toLowerCase() : "";
+    const childIds = flat.childrenById.get(entity.id) || [];
+    const hasChildren = childIds.length > 0 || (Array.isArray(source.children) && source.children.length > 0);
+
+    if (declaredValue != null && typeof declaredValue !== "string") {
+      diagnostic(diagnostics, "fatal", "UNKNOWN_ENTITY_TYPE",
+        "Entity '" + entity.id + "' has a non-string type. Use container or omit type for a leaf item.",
+        { entityId: entity.id, type: declaredValue });
+    } else if (hasChildren && declared === "item") {
+      diagnostic(diagnostics, "fatal", "ITEM_CANNOT_HAVE_CHILDREN",
+        "Entity '" + entity.id + "' is declared as an item but contains children.",
+        { entityId: entity.id });
+    } else if (hasChildren && !["container", "shell"].includes(declared)) {
+      diagnostic(diagnostics, "fatal", "CONTAINER_TYPE_REQUIRED_FOR_CHILDREN",
+        "Entity '" + entity.id + "' declares children and must set type: container.",
+        { entityId: entity.id });
+    }
+
+    if (declared && !["item", "container", "shell"].includes(declared)) {
+      diagnostic(diagnostics, "fatal", "UNKNOWN_ENTITY_TYPE",
+        "Unknown entity type '" + source.type + "' on '" + entity.id + "'. Use container or omit type for a leaf item.",
+        { entityId: entity.id, type: source.type });
+    }
+
+    const type = hasChildren || declared === "container" || declared === "shell" ? "container" : "item";
+    entity.type = type;
+
+    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 + "'.",
+        { entityId: entity.id, geometry: source.geometry });
+    }
+  }
+}
+
 function flattenEntities(input, diagnostics) {
   const entities = [];
   const childrenById = new Map();
@@ -110,7 +174,7 @@ function flattenEntities(input, diagnostics) {
       delete entity.layout;
       entity.__atlasExplicitSize = Array.isArray(raw.size) && raw.size.length === 3;
       entity.parent = parent ?? raw.parent ?? null;
-      entity.type = children.length || raw.type === "container" || raw.type === "shell" ? "shell" : raw.type;
+      entity.type = raw.type;
       entities.push(entity);
       sourceById.set(entity.id, raw);
       childrenById.set(entity.id, children.map(child => child && child.id).filter(Boolean));
@@ -234,7 +298,7 @@ function intrinsicSize(entity, algorithm = "grid", geometrySizes = DEFAULT_SIZES
 
 function sizeForSlot(item, slotSize) {
   const base = item.size;
-  if (item.entity.type === "shell" || item.entity.__atlasExplicitSize) return [...base];
+  if (isContainerType(item.entity.type) || item.entity.__atlasExplicitSize) return [...base];
   const scale = Math.min(
     slotSize[0] / Math.max(base[0], 0.0001),
     slotSize[1] / Math.max(base[1], 0.0001),
@@ -265,6 +329,394 @@ function spanFor(entity, dimension, minimumWeight) {
   return [columns, rows, Math.max(1, Math.ceil(target / (columns * rows)))];
 }
 
+const CONSTRAINT_DIMENSIONS = Object.freeze({ width: 0, height: 1, depth: 2, x: 0, y: 1, z: 2 });
+const ALIGNMENT_EDGES = Object.freeze({
+  left: [0, -1],
+  centerX: [0, 0],
+  right: [0, 1],
+  bottom: [1, -1],
+  centerY: [1, 0],
+  top: [1, 1],
+  back: [2, -1],
+  centerZ: [2, 0],
+  front: [2, 1]
+});
+
+function layoutConstraints(source, spec) {
+  if (Array.isArray(source?.constraints)) return source.constraints;
+  return Array.isArray(spec?.constraints) ? spec.constraints : [];
+}
+
+function constraintIds(value) {
+  return Array.isArray(value) ? [...new Set(value.filter(id => typeof id === "string" && id))] : [];
+}
+
+function constraintLevel(constraint) {
+  return constraint?.strength === "required" ? "error" : "warning";
+}
+
+function applyEqualSizeConstraints(items, constraints, diagnostics, ownerId = null) {
+  const byId = new Map(items.map(item => [item.entity.id, item]));
+  for (const constraint of constraints) {
+    const ids = constraintIds(constraint?.equal);
+    if (!ids.length) continue;
+    const selected = ids.map(id => byId.get(id)).filter(Boolean);
+    const missing = ids.filter(id => !byId.has(id));
+    if (missing.length) diagnostic(diagnostics, constraintLevel(constraint), "UNKNOWN_CONSTRAINT_ENTITY",
+      `Equal-size constraint references entities outside the sibling group: ${missing.join(", ")}.`,
+      { ownerId, entityIds: missing });
+    if (selected.length < 2) continue;
+    const requested = constraint.dimensions ?? constraint.dimension ?? constraint.edge ?? ["width", "height", "depth"];
+    const names = Array.isArray(requested) ? requested : [requested];
+    const axes = [...new Set(names.map(name => CONSTRAINT_DIMENSIONS[name]).filter(Number.isInteger))];
+    const invalid = names.filter(name => !Number.isInteger(CONSTRAINT_DIMENSIONS[name]));
+    if (invalid.length) diagnostic(diagnostics, constraintLevel(constraint), "UNKNOWN_CONSTRAINT_DIMENSION",
+      `Unknown equal-size dimension: ${invalid.join(", ")}.`, { ownerId, dimensions: invalid });
+    for (const axis of axes) {
+      const extent = Math.max(...selected.map(item => item.size[axis]));
+      for (const item of selected) {
+        item.size = [...item.size];
+        item.size[axis] = extent;
+        item.entity.s = [...item.size];
+      }
+    }
+  }
+}
+
+function boundaryValue(item, edge) {
+  const [axis, side] = ALIGNMENT_EDGES[edge];
+  return item.position[axis] + side * item.size[axis] / 2;
+}
+
+function placementsOverlap(a, b, epsilon = 1e-9) {
+  return [0, 1, 2].every(axis =>
+    Math.abs(a.position[axis] - b.position[axis]) + epsilon < (a.size[axis] + b.size[axis]) / 2
+  );
+}
+
+function separateAlignmentOverlaps(placements, lockedAxes, requiredIds, spec, diagnostics, ownerId) {
+  const directionAxis = { x: 0, y: 1, z: 2 }[spec?.direction];
+  const priority = [...new Set([directionAxis, 0, 1, 2].filter(Number.isInteger))];
+  const gap = Math.max(0, scalar(spec?.gap, 1));
+  const warned = new Set();
+
+  for (let index = 1; index < placements.length; index++) {
+    const item = placements[index];
+    let passes = 0;
+    while (passes++ < placements.length * 3) {
+      const blocker = placements.slice(0, index).find(candidate => placementsOverlap(item, candidate));
+      if (!blocker) break;
+      const locked = lockedAxes.get(item.entity.id) || new Set();
+      let axis = priority.find(candidate => !locked.has(candidate));
+      if (!Number.isInteger(axis)) {
+        axis = priority[0] ?? 0;
+        const key = item.entity.id;
+        if (!warned.has(key)) {
+          warned.add(key);
+          diagnostic(diagnostics, requiredIds.has(key) ? "error" : "warning", "ALIGNMENT_COLLISION_AVOIDED",
+            `Alignment for '${key}' over-constrains all three axes; non-overlap takes precedence.`,
+            { ownerId, entityId: key, axis: ["x", "y", "z"][axis] });
+        }
+      }
+      const relevant = placements.slice(0, index).filter(candidate =>
+        [0, 1, 2].every(otherAxis =>
+          otherAxis === axis ||
+          Math.abs(item.position[otherAxis] - candidate.position[otherAxis]) + 1e-9 <
+            (item.size[otherAxis] + candidate.size[otherAxis]) / 2
+        )
+      );
+      item.position = [...item.position];
+      item.position[axis] = Math.max(...(relevant.length ? relevant : [blocker]).map(candidate =>
+        candidate.position[axis] + (item.size[axis] + candidate.size[axis]) / 2 + gap
+      ));
+    }
+  }
+}
+
+function applyAlignmentConstraints(placements, constraints, diagnostics, ownerId = null, spec = {}) {
+  const lockedAxes = new Map();
+  const requiredIds = new Set();
+  const byId = new Map(placements.map(item => [item.entity.id, item]));
+  for (const constraint of constraints) {
+    const ids = constraintIds(constraint?.align);
+    if (!ids.length) continue;
+    const selected = ids.map(id => byId.get(id)).filter(Boolean);
+    const missing = ids.filter(id => !byId.has(id));
+    if (missing.length) diagnostic(diagnostics, constraintLevel(constraint), "UNKNOWN_CONSTRAINT_ENTITY",
+      `Alignment constraint references entities outside the sibling group: ${missing.join(", ")}.`,
+      { ownerId, entityIds: missing });
+    if (selected.length < 2) continue;
+    const requested = constraint.edges ?? constraint.edge;
+    const edges = Array.isArray(requested) ? requested : [requested];
+    const validEdges = edges.filter(edge => ALIGNMENT_EDGES[edge]);
+    const invalid = edges.filter(edge => !ALIGNMENT_EDGES[edge]);
+    if (invalid.length) diagnostic(diagnostics, constraintLevel(constraint), "UNKNOWN_ALIGNMENT_EDGE",
+      `Unknown alignment edge: ${invalid.join(", ")}.`, { ownerId, edges: invalid });
+    for (const edge of validEdges) {
+      const [axis, side] = ALIGNMENT_EDGES[edge];
+      const target = boundaryValue(selected[0], edge);
+      for (const item of selected) {
+        if (!lockedAxes.has(item.entity.id)) lockedAxes.set(item.entity.id, new Set());
+        lockedAxes.get(item.entity.id).add(axis);
+        if (constraint.strength === "required") requiredIds.add(item.entity.id);
+      }
+      for (const item of selected.slice(1)) {
+        item.position = [...item.position];
+        item.position[axis] = target - side * item.size[axis] / 2;
+      }
+    }
+  }
+  separateAlignmentOverlaps(placements, lockedAxes, requiredIds, spec, diagnostics, ownerId);
+  return lockedAxes;
+}
+
+function compactBandCrossAxis(items, primaryAxis, lockedAxes, gap) {
+  if (items.length < 2) return;
+  const axis = [0, 1, 2].find(candidate =>
+    candidate !== primaryAxis &&
+    items.some(item => !(lockedAxes.get(item.entity.id) || new Set()).has(candidate)) &&
+    Math.max(...items.map(item => item.position[candidate])) -
+      Math.min(...items.map(item => item.position[candidate])) > 1e-9
+  );
+  if (!Number.isInteger(axis)) return;
+
+  const ordered = [...items].sort((left, right) =>
+    left.position[axis] - right.position[axis] ||
+    items.indexOf(left) - items.indexOf(right)
+  );
+  const locked = item => (lockedAxes.get(item.entity.id) || new Set()).has(axis);
+
+  for (let index = 1; index < ordered.length; index++) {
+    const item = ordered[index];
+    if (locked(item)) continue;
+    const previous = ordered[index - 1];
+    const target = previous.position[axis] + (previous.size[axis] + item.size[axis]) / 2 + gap;
+    if (target < item.position[axis]) {
+      item.position = [...item.position];
+      item.position[axis] = target;
+    }
+  }
+  for (let index = ordered.length - 2; index >= 0; index--) {
+    const item = ordered[index];
+    if (locked(item)) continue;
+    const next = ordered[index + 1];
+    const target = next.position[axis] - (next.size[axis] + item.size[axis]) / 2 - gap;
+    if (target > item.position[axis]) {
+      item.position = [...item.position];
+      item.position[axis] = target;
+    }
+  }
+}
+
+function compactRowBands(placements, constraints, spec, lockedAxes = new Map()) {
+  if (spec?.packing !== "compact" || spec?.algorithm !== "row" || placements.length < 2) return;
+  const axis = { x: 0, y: 1, z: 2 }[spec.direction] ?? 0;
+  const parent = placements.map((_, index) => index);
+  const byId = new Map(placements.map((item, index) => [item.entity.id, index]));
+  const find = index => {
+    while (parent[index] !== index) {
+      parent[index] = parent[parent[index]];
+      index = parent[index];
+    }
+    return index;
+  };
+  const union = (left, right) => {
+    const leftRoot = find(left);
+    const rightRoot = find(right);
+    if (leftRoot !== rightRoot) parent[rightRoot] = leftRoot;
+  };
+
+  for (const constraint of constraints) {
+    const ids = constraintIds(constraint?.align).filter(id => byId.has(id));
+    const requested = constraint?.edges ?? constraint?.edge;
+    const edges = Array.isArray(requested) ? requested : [requested];
+    if (ids.length < 2 || !edges.some(edge => ALIGNMENT_EDGES[edge]?.[0] === axis)) continue;
+    const first = byId.get(ids[0]);
+    for (const id of ids.slice(1)) union(first, byId.get(id));
+  }
+
+  const bandsByRoot = new Map();
+  placements.forEach((item, index) => {
+    const root = find(index);
+    if (!bandsByRoot.has(root)) bandsByRoot.set(root, []);
+    bandsByRoot.get(root).push(item);
+  });
+  const bands = [...bandsByRoot.values()].sort((left, right) =>
+    placements.indexOf(left[0]) - placements.indexOf(right[0])
+  ).map(items => {
+    const minimum = Math.min(...items.map(item => item.position[axis] - item.size[axis] / 2));
+    const maximum = Math.max(...items.map(item => item.position[axis] + item.size[axis] / 2));
+    return { items, center: (minimum + maximum) / 2, length: maximum - minimum };
+  });
+
+  const gap = Math.max(0, scalar(spec.gap, 1));
+  for (const band of bands) compactBandCrossAxis(band.items, axis, lockedAxes, gap);
+  const total = bands.reduce((sum, band) => sum + band.length, 0) + Math.max(0, bands.length - 1) * gap;
+  const orderSign = axis === 0 ? 1 : -1;
+  let cursor = -total / 2;
+  for (const band of bands) {
+    const target = orderSign * (cursor + band.length / 2);
+    const delta = target - band.center;
+    for (const item of band.items) {
+      item.position = [...item.position];
+      item.position[axis] += delta;
+    }
+    cursor += band.length + gap;
+  }
+}
+
+function layoutFunction(spec, diagnostics, ownerId) {
+  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;
+}
+
+function materializeLayoutGroups(items, spec, diagnostics, ownerId) {
+  const definitions = Array.isArray(spec?.groups) ? spec.groups : [];
+  if (!definitions.length) return { items, groups: new Map() };
+
+  const itemById = new Map(items.map(item => [item.entity.id, item]));
+  const claimed = new Map();
+  const groups = new Map();
+  const validDefinitions = [];
+
+  for (const definition of definitions) {
+    const id = typeof definition?.id === "string" ? definition.id.trim() : "";
+    if (!id) {
+      diagnostic(diagnostics, "error", "LAYOUT_GROUP_ID_REQUIRED",
+        "A layout group requires a non-empty id.", { ownerId });
+      continue;
+    }
+    if (itemById.has(id) || groups.has(id)) {
+      diagnostic(diagnostics, "error", "DUPLICATE_LAYOUT_GROUP_ID",
+        `Layout group id '${id}' conflicts with another sibling or group.`, { ownerId, groupId: id });
+      continue;
+    }
+    groups.set(id, null);
+    validDefinitions.push({ ...definition, id });
+  }
+
+  const virtualByMember = new Map();
+  for (const definition of validDefinitions) {
+    const rawMembers = Array.isArray(definition.members) ? definition.members : [];
+    const members = [...new Set(rawMembers.filter(id => typeof id === "string" && id))];
+    const repeated = rawMembers.filter((id, index) => rawMembers.indexOf(id) !== index);
+    if (repeated.length) diagnostic(diagnostics, "error", "DUPLICATE_LAYOUT_GROUP_MEMBER",
+      `Layout group '${definition.id}' repeats members: ${[...new Set(repeated)].join(", ")}.`,
+      { ownerId, groupId: definition.id, entityIds: [...new Set(repeated)] });
+    const unknown = members.filter(id => !itemById.has(id));
+    if (unknown.length) diagnostic(diagnostics, "error", "UNKNOWN_LAYOUT_GROUP_MEMBER",
+      `Layout group '${definition.id}' references entities outside the sibling group: ${unknown.join(", ")}.`,
+      { ownerId, groupId: definition.id, entityIds: unknown });
+    const available = members.filter(id => itemById.has(id) && !claimed.has(id));
+    const duplicateClaims = members.filter(id => claimed.has(id));
+    if (duplicateClaims.length) diagnostic(diagnostics, "error", "LAYOUT_GROUP_MEMBER_ALREADY_CLAIMED",
+      `Layout group '${definition.id}' reuses members already assigned to another group: ${duplicateClaims.join(", ")}.`,
+      { ownerId, groupId: definition.id, entityIds: duplicateClaims });
+    if (!available.length) {
+      groups.delete(definition.id);
+      continue;
+    }
+    for (const id of available) claimed.set(id, definition.id);
+
+    const groupSpec = definition.layout || { algorithm: "row", direction: "x", gap: 1, padding: 0 };
+    const memberItems = available.map(id => itemById.get(id));
+    const groupResult = constrainedLayout(
+      memberItems,
+      groupSpec,
+      definition,
+      diagnostics,
+      definition.id,
+      layoutFunction(groupSpec, diagnostics, definition.id)
+    );
+    const virtual = {
+      entity: { id: definition.id, type: "layout-group", __atlasVirtualGroup: true },
+      size: [...groupResult.size],
+      intrinsicSize: [...groupResult.size],
+      groupResult,
+      groupSpec,
+      groupSource: definition,
+      memberItems
+    };
+    groups.set(definition.id, virtual);
+    for (const id of available) virtualByMember.set(id, virtual);
+  }
+
+  const outerItems = [];
+  const inserted = new Set();
+  for (const item of items) {
+    const virtual = virtualByMember.get(item.entity.id);
+    if (!virtual) {
+      outerItems.push(item);
+      continue;
+    }
+    if (!inserted.has(virtual.entity.id)) {
+      inserted.add(virtual.entity.id);
+      outerItems.push(virtual);
+    }
+  }
+  return { items: outerItems, groups };
+}
+
+function reflowLayoutGroups(items, diagnostics) {
+  for (const item of items) {
+    if (!item.entity.__atlasVirtualGroup || item.groupSpec?.algorithm !== "row" ||
+        !["start", "end", "space-between", "space-around", "space-evenly"].includes(item.groupSpec?.justify)) continue;
+    const expanded = item.size.some((value, axis) => value > item.intrinsicSize[axis] + 1e-9);
+    if (!expanded) continue;
+    item.groupResult = constrainedLayout(
+      item.memberItems,
+      item.groupSpec,
+      item.groupSource,
+      diagnostics,
+      item.entity.id,
+      layoutFunction(item.groupSpec, diagnostics, item.entity.id),
+      item.size
+    );
+  }
+}
+
+function flattenLayoutGroups(placements) {
+  const flattened = [];
+  for (const placement of placements) {
+    if (!placement.entity.__atlasVirtualGroup) {
+      flattened.push(placement);
+      continue;
+    }
+    for (const member of placement.groupResult.positions) {
+      flattened.push({
+        ...member,
+        position: member.position.map((value, axis) => value + placement.position[axis])
+      });
+    }
+  }
+  return flattened;
+}
+
+function constrainedLayout(items, spec, source, diagnostics, ownerId, layout, availableSize = null) {
+  const grouped = materializeLayoutGroups(items, spec, diagnostics, ownerId);
+  const constraints = layoutConstraints(source, spec);
+  applyEqualSizeConstraints(grouped.items, constraints, diagnostics, ownerId);
+  reflowLayoutGroups(grouped.items, diagnostics);
+  const result = layout(grouped.items, spec, diagnostics, availableSize);
+  const lockedAxes = applyAlignmentConstraints(result.positions, constraints, diagnostics, ownerId, spec);
+  compactRowBands(result.positions, constraints, spec, lockedAxes);
+  const normalized = constraints.some(constraint => constraint?.align) || spec?.packing === "compact"
+    ? boundsOf(result.positions, Math.max(0, scalar(spec.padding, 1)))
+    : result;
+  return {
+    ...normalized,
+    positions: flattenLayoutGroups(normalized.positions)
+  };
+}
+
 function boundsOf(placements, padding) {
   if (!placements.length) return { positions: [], size: [padding * 2, padding * 2, padding * 2] };
   const min = [Infinity, Infinity, Infinity];
@@ -283,29 +735,75 @@ function boundsOf(placements, padding) {
   return { positions, size: max.map((value, axis) => value - min[axis] + padding * 2) };
 }
 
-function rowLayout(items, spec, diagnostics) {
+function boundsOfAssignedAxis(placements, padding, axis, assignedSize) {
+  if (!placements.length) return { positions: [], size: [padding * 2, padding * 2, padding * 2] };
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const item of placements) {
+    for (let itemAxis = 0; itemAxis < 3; itemAxis++) {
+      min[itemAxis] = Math.min(min[itemAxis], item.position[itemAxis] - item.size[itemAxis] / 2);
+      max[itemAxis] = Math.max(max[itemAxis], item.position[itemAxis] + item.size[itemAxis] / 2);
+    }
+  }
+  const required = max.map((value, itemAxis) => value - min[itemAxis] + padding * 2);
+  if (assignedSize + 1e-9 < required[axis]) return boundsOf(placements, padding);
+  const center = min.map((value, itemAxis) => (value + max[itemAxis]) / 2);
+  const positions = placements.map(item => ({
+    ...item,
+    position: item.position.map((value, itemAxis) => {
+      const centered = itemAxis === axis ? value : value - center[itemAxis];
+      return Object.is(centered, -0) ? 0 : centered;
+    })
+  }));
+  required[axis] = assignedSize;
+  return { positions, size: required };
+}
+
+function rowLayout(items, spec, diagnostics, availableSize = null) {
   const direction = ["x", "y", "z"].includes(spec.direction) ? spec.direction : "x";
   const axis = { x: 0, y: 1, z: 2 }[direction];
   const gap = Math.max(0, scalar(spec.gap, 1));
   const padding = Math.max(0, scalar(spec.padding, 1));
+  const justify = spec.justify || "center";
+  const validJustify = ["start", "center", "end", "space-between", "space-around", "space-evenly"];
+  if (!validJustify.includes(justify)) diagnostic(diagnostics, "warning", "UNKNOWN_JUSTIFY", `Unknown row justify '${spec.justify}'.`);
+
   const minimumWeight = Math.min(...items.map(item => positiveNumber(item.entity.weight, 1)));
   const lengths = items.map(item => item.size[axis] * Math.max(1, positiveNumber(item.entity.weight, 1) / minimumWeight));
-  const total = lengths.reduce((sum, value) => sum + value, 0) + Math.max(0, items.length - 1) * gap;
+  const contentLength = lengths.reduce((sum, value) => sum + value, 0);
+  const minimumLength = contentLength + Math.max(0, items.length - 1) * gap;
+  const assignedSize = Array.isArray(availableSize) ? Math.max(0, scalar(availableSize[axis], 0)) : 0;
+  const availableLength = Math.max(0, assignedSize - padding * 2);
+  const allocatedLength = Math.max(minimumLength, availableLength || minimumLength);
+  const free = Math.max(0, allocatedLength - minimumLength);
+
+  let leading = justify === "end" ? free : justify === "center" ? free / 2 : 0;
+  let spacing = gap;
+  if (justify === "space-between") {
+    if (items.length > 1) spacing += free / (items.length - 1);
+    else leading = free / 2;
+  } else if (justify === "space-around" && items.length) {
+    spacing += free / items.length;
+    leading = free / (items.length * 2);
+  } else if (justify === "space-evenly") {
+    spacing += free / (items.length + 1);
+    leading = free / (items.length + 1);
+  }
+
   const orderSign = axis === 0 ? 1 : -1;
-  let cursor = -total / 2;
+  let cursor = -allocatedLength / 2 + leading;
   const placements = items.map((item, index) => {
     const length = lengths[index];
     cursor += length / 2;
     const position = [0, 0, 0];
     position[axis] = cursor * orderSign;
-    cursor += length / 2 + gap;
+    cursor += length / 2 + spacing;
     const slotSize = item.size.map((value, itemAxis) => itemAxis === axis ? length : value);
     return { ...item, size: sizeForSlot(item, slotSize), slotSize, position };
   });
-  if (spec.justify === "end") for (const placement of placements) placement.position[axis] += total / 2;
-  if (spec.justify === "start") for (const placement of placements) placement.position[axis] -= total / 2;
-  if (spec.justify && !["start", "center", "end"].includes(spec.justify)) diagnostic(diagnostics, "warning", "UNKNOWN_JUSTIFY", `Unknown row justify '${spec.justify}'.`);
-  return boundsOf(placements, padding);
+  return assignedSize > 0 && availableLength + 1e-9 >= minimumLength
+    ? boundsOfAssignedAxis(placements, padding, axis, assignedSize)
+    : boundsOf(placements, padding);
 }
 
 function gridDimensions(items, spec, dimension) {
@@ -351,6 +849,12 @@ function markOccupied(occupied, start, span, dimension) {
   }
 }
 
+const GRID_PLANES = Object.freeze({
+  xy: [0, 1, 2],
+  xz: [0, 2, 1],
+  yz: [2, 1, 0]
+});
+
 function packedGridLayout(items, spec, diagnostics, dimension = 2) {
   const gap = Math.max(0, scalar(spec.gap, 1));
   const padding = Math.max(0, scalar(spec.padding, 1));
@@ -379,17 +883,23 @@ function packedGridLayout(items, spec, diagnostics, dimension = 2) {
       markOccupied(occupied, start, span, 2);
       placements.push({ ...item, span, cell: start });
     }
-    const cellX = Math.max(...placements.map(item => item.size[0] / item.span[0]), 1);
-    const cellZ = Math.max(...placements.map(item => item.size[2] / item.span[1]), 1);
-    const cellY = Math.max(...placements.map(item => item.size[1]), 1);
+    const [columnAxis, rowAxis, orthogonalAxis] = GRID_PLANES[spec.plane] || GRID_PLANES.xz;
+    const columnCell = Math.max(...placements.map(item => item.size[columnAxis] / item.span[0]), 1);
+    const rowCell = Math.max(...placements.map(item => item.size[rowAxis] / item.span[1]), 1);
+    const orthogonalCell = Math.max(...placements.map(item => item.size[orthogonalAxis]), 1);
     for (const item of placements) {
-      const width = item.span[0] * cellX + (item.span[0] - 1) * gap;
-      const depth = item.span[1] * cellZ + (item.span[1] - 1) * gap;
-      const offset = spec.variant === "masonry" && item.cell[1] % 2 === 1 ? (spec.stagger?.offset === "half-cell" ? (cellX + gap) / 2 : scalar(spec.stagger?.offset, 0)) : 0;
-      const slotSize = [width, cellY, depth];
+      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 slotSize = [0, 0, 0];
+      slotSize[columnAxis] = columnSize;
+      slotSize[rowAxis] = rowSize;
+      slotSize[orthogonalAxis] = orthogonalCell;
       item.size = sizeForSlot(item, slotSize);
       item.slotSize = slotSize;
-      item.position = [item.cell[0] * (cellX + gap) + width / 2 + offset, 0, -(item.cell[1] * (cellZ + gap) + depth / 2)];
+      item.position = [0, 0, 0];
+      item.position[columnAxis] = item.cell[0] * (columnCell + gap) + columnSize / 2 + offset;
+      item.position[rowAxis] = -(item.cell[1] * (rowCell + gap) + rowSize / 2);
     }
     return boundsOf(placements, padding);
   }
@@ -459,6 +969,7 @@ export function compileAtlasModel(input, options = {}) {
   const source = normalizeRoot(input);
   const palette = paletteFrom(source);
   const flat = flattenEntities(source.entities, diagnostics);
+  normalizeEntityTypes(flat, options.geometryCatalog || [], diagnostics);
   if (!flat.entities.length) diagnostic(diagnostics, "fatal", "NO_VALID_ENTITIES", "The model does not contain any valid entities.");
   const validIds = new Set(flat.entities.map(entity => entity.id));
   const relations = normalizeRelations(source.relations, validIds, diagnostics);
@@ -489,17 +1000,19 @@ export function compileAtlasModel(input, options = {}) {
     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 result = algorithm === "row"
-      ? rowLayout(childItems, spec, diagnostics)
-      : algorithm === "volume"
-        ? volumeLayout(childItems, spec, diagnostics)
-        : gridLayout(childItems, spec, diagnostics);
+    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);
     for (const placement of result.positions) {
       const child = byId.get(placement.entity.id);
       child.p = placement.position;
       child.s = placement.size;
     }
-    const declared = Array.isArray(entity.size) && entity.size.length === 3 ? asVector(entity.size) : null;
     entity.s = declared ? [Math.max(declared[0], result.size[0]), Math.max(declared[1], result.size[1]), Math.max(declared[2], result.size[2])] : result.size;
     if (declared && sourceEntity.sizeMode === "fixed" && result.size.some((value, axis) => value > declared[axis])) {
       diagnostic(diagnostics, "error", "FIXED_LAYOUT_OVERFLOW", `Content exceeds fixed container '${entity.id}'.`, { entityId: entity.id, declaredSize: declared, requiredSize: result.size });
@@ -513,11 +1026,12 @@ export function compileAtlasModel(input, options = {}) {
   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 = rootAlgorithm === "row"
-    ? rowLayout(rootItems, rootSpec, diagnostics)
-    : rootAlgorithm === "volume"
-      ? volumeLayout(rootItems, rootSpec, diagnostics)
-      : gridLayout(rootItems, rootSpec, diagnostics);
+  const rootResult = constrainedLayout(rootItems, rootSpec, source, diagnostics, null,
+    rootAlgorithm === "row"
+      ? rowLayout
+      : rootAlgorithm === "volume"
+        ? volumeLayout
+        : gridLayout);
   for (const placement of rootResult.positions) {
     const entity = byId.get(placement.entity.id);
     entity.p = placement.position;
@@ -535,6 +1049,7 @@ export function compileAtlasModel(input, options = {}) {
     }),
     relations,
     layout: source.layout || undefined,
+    constraints: source.constraints || undefined,
     diagnostics
   };
   if (options.throwOnFatal && diagnostics.some(item => item.level === "fatal")) throw new Error(diagnostics.filter(item => item.level === "fatal").map(item => item.message).join("\n"));