@liquidcars/atlas-layout 0.1.3 → 0.1.6

package/README.md

@@ -24,6 +24,12 @@ Cada entrada del catálogo puede declarar `id`, `aliases` y `canonicalSize`.
 Una geometría externa desconocida conserva el tamaño de fallback de una caja,
 de modo que la compilación sigue siendo recuperable si falta un pack.
 
+Las entidades con `children` deben declarar `type: container`. Las hojas pueden
+omitir `type` y se normalizan como items. `type: shell` se acepta únicamente
+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.
+
 Para compilar una fuente YAML durante el build:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liquidcars/atlas-layout",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Declarative layout compiler for LiquidCars Atlas models",
   "type": "module",
   "main": "./src/index.js",
@@ -21,12 +21,23 @@
     "./vite": {
       "import": "./src/vite.js",
       "default": "./src/vite.js"
+    },
+    "./spec": {
+      "import": "./src/spec.js",
+      "default": "./src/spec.js"
     }
   },
   "scripts": {
     "test": "node --test test/index.test.mjs"
   },
-  "keywords": ["liquidcars", "atlas", "layout", "3d", "graph", "web-component"],
+  "keywords": [
+    "liquidcars",
+    "atlas",
+    "layout",
+    "3d",
+    "graph",
+    "web-component"
+  ],
   "license": "MIT",
   "dependencies": {
     "yaml": "^2.8.1"

package/packages/atlas-layout/package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "atlas-layout",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

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

@@ -0,0 +1,132 @@
+# ATLAS-LAYOUT-SPEC-v1
+
+This document defines the semantic YAML contract consumed by @liquidcars/atlas-layout.
+The executable projection of this contract is packages/atlas-layout/src/spec.js.
+
+## Root model
+
+A model may contain version, palette, theme, render, layout, entities and relations.
+Entities may be declared at the root or nested under children. The compiler normalizes
+nested entities to a flat list with parent references.
+
+## Model coordinate system
+
+Atlas model space is independent from the camera and from the host application's view.
+The coordinate convention is fixed:
+
+- x: left (-) to right (+)
+- y: bottom (-) to top (+)
+- z: back (-) to front (+)
+
+Positions, sizes, layout directions and future alignment rules are interpreted in this
+model space. Camera rotation, zoom, pan and projection never change the meaning of a
+model coordinate. The default front view places the camera on the positive z side,
+looking toward the origin.
+
+A container's local origin is the reference point for its children. The compiler resolves
+nested positions into model-space output while preserving the authored hierarchy. The
+authoring aliases left, right, bottom, top, back and front may be used for boundary
+terms; they correspond respectively to minX, maxX, minY, maxY, minZ and maxZ.
+
+## Layout units and intrinsic sizing
+
+All dimensions are expressed in Atlas world units: geometry dimensions, positions, layout
+gap, padding and explicit size values use the same unit. There is no universal 1 x 1 x 1
+item size. When a leaf has no explicit size, assisted layout uses the selected geometry's
+canonical size; an aspect style changes proportion, not the geometry's semantic identity.
+
+Containers are sized from their laid-out contents by default: child bounds plus gap and
+padding determine the required extent. padding: 1 reserves one world unit on every
+content-to-boundary side, so it contributes approximately two units to each occupied
+dimension. gap: 1.2 reserves 1.2 world units between adjacent siblings along the
+layout axis. Authored size is the exception: it is an explicit dimension constraint,
+subject to sizeMode and diagnostics.
+
+
+## Entity fields
+
+Required: id.
+
+Common fields: name, sub, text, type, 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`.
+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.
+
+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
+as fatal diagnostics instead of silently rendering a fallback box.
+
+`children` is the nested authoring form. In a flat model, an entity referenced by
+other entities through `parent` is also a container and follows the same rule.
+
+geometry is resolved against built-in primitives and registered geometry packs.
+geometryOptions and geometryPalette are namespaced by the selected geometry definition.
+size is an explicit dimension constraint. p and s are calculated layout output and are
+normally omitted from authored Markdown. sizeMode fixed preserves explicit dimensions;
+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.
+Grid layouts also accept variant uniform or masonry and optional columns, rows and
+layers. gap and padding are absolute numbers. justify accepts start, center or end.
+
+An entity weight influences its relative allocation. span can explicitly occupy
+columns, rows and layers. A semantic style.aspect may be compact, wide, tall, deep or flat.
+
+## Sibling size and alignment constraints
+
+A root model or container may declare `constraints` for its immediate children. Constraint
+references must resolve to siblings in that group; references across parents produce a
+diagnostic and are not applied. Constraints may alternatively be nested under the
+corresponding `layout` object, but sibling-level `constraints` is the canonical form.
+
+An equal-size rule lists entity ids under `equal`. `dimensions` accepts one or more of
+`width`, `height` and `depth`; the compiler uses the largest intrinsic extent in the
+group for each requested dimension. The singular `dimension` form is accepted, and
+`edge: width|height|depth` is a compact alias.
+
+An alignment rule lists entity ids under `align`. `edge` or `edges` accepts
+`left`, `centerX`, `right`, `bottom`, `centerY`, `top`, `back`,
+`centerZ` and `front`. These names always use model coordinates, never camera
+coordinates. Alignment uses the first listed sibling as the reference.
+
+`strength` accepts `preferred` (the default) or `required`. Invalid preferred rules
+produce warnings; invalid required rules produce errors.
+
+```yaml
+constraints:
+  - equal: [layer-top, layer-middle, layer-bottom]
+    dimensions: [width, height, depth]
+    strength: preferred
+  - align: [layer-top, layer-middle, layer-bottom]
+    edges: [left, front]
+    strength: preferred
+```
+
+## Relations
+
+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.
+
+## Rendering
+
+palette maps tokens to CSS colours. style.color or c can reference a token or direct
+CSS colour. render can additionally set relationMode, selectionMode, toolbar and
+shellLabels. theme contains background, lighting and ui settings.
+
+## Markdown blocks
+
+Atlas Markdown accepts a full atlas or atlas overview fenced block, and split
+atlas-model, atlas-layout, atlas-render and atlas-relations blocks. Named blocks
+use the block name as the model identifier. A document may contain more than one model.
+
+## Compatibility
+
+Unknown fields remain available to geometry packs and host applications, but the
+editor only suggests fields defined by this version of the contract.

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,149 @@ 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] });
+        }
+      }
+      item.position = [...item.position];
+      item.position[axis] = Math.max(...placements.slice(0, index).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);
+}
+
+function constrainedLayout(items, spec, source, diagnostics, ownerId, layout) {
+  const constraints = layoutConstraints(source, spec);
+  applyEqualSizeConstraints(items, constraints, diagnostics, ownerId);
+  const result = layout(items, spec, diagnostics);
+  applyAlignmentConstraints(result.positions, constraints, diagnostics, ownerId, spec);
+  return constraints.some(constraint => constraint?.align)
+    ? boundsOf(result.positions, Math.max(0, scalar(spec.padding, 1)))
+    : result;
+}
+
 function boundsOf(placements, padding) {
   if (!placements.length) return { positions: [], size: [padding * 2, padding * 2, padding * 2] };
   const min = [Infinity, Infinity, Infinity];
@@ -459,6 +666,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,11 +697,12 @@ 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 result = constrainedLayout(childItems, spec, sourceEntity, diagnostics, entityId,
+      algorithm === "row"
+        ? rowLayout
+        : algorithm === "volume"
+          ? volumeLayout
+          : gridLayout);
     for (const placement of result.positions) {
       const child = byId.get(placement.entity.id);
       child.p = placement.position;
@@ -513,11 +722,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 +745,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"));

package/src/spec.js

@@ -0,0 +1,204 @@
+const freeze = value => Object.freeze(value);
+
+const field = (description, values = null, extra = {}) => freeze({
+  description,
+  ...(values ? { values: freeze([...values]) } : {}),
+  ...extra
+});
+
+export const ATLAS_LAYOUT_SPEC_V1 = freeze({
+  version: 1,
+  name: "Atlas Layout",
+  contexts: freeze({
+    root: freeze({
+      label: "Atlas model",
+      properties: freeze({
+        version: field("Semantic model version.", [1]),
+        palette: field("Named model colours.", null, { context: "palette" }),
+        theme: field("Renderer theme configuration.", null, { context: "theme" }),
+        render: field("Renderer configuration.", null, { context: "render" }),
+        layout: field("Assisted layout for root entities.", null, { context: "layout" }),
+        constraints: field("Equal-size and edge-alignment rules for root siblings.", null, { context: "constraint", sequence: true }),
+        entities: field("Top-level entities and containers.", null, { context: "entity", sequence: true }),
+        relations: field("Connections between entity ids.", null, { context: "relation", sequence: true })
+      })
+    }),
+    entity: freeze({
+      label: "Entity",
+      properties: freeze({
+        id: field("Stable identifier.", null, { type: "string", required: true }),
+        name: field("Visible title.", null, { type: "string" }),
+        sub: field("Visible subtitle.", null, { type: "string" }),
+        text: field("Description shown by the inspector.", null, { type: "string" }),
+        type: field("Structural role. Use container when declaring children; omit it for a leaf item.", ["container"]),
+        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" }),
+        geometryOptions: field("Typed parameters supplied by the selected geometry.", null, { context: "geometryOptions" }),
+        geometryPalette: field("Local palette overrides supplied by the selected geometry.", null, { context: "geometryPalette" }),
+        style: field("Appearance and semantic proportions.", null, { context: "style" }),
+        layout: field("Assisted layout for this container.", null, { context: "layout" }),
+        constraints: field("Equal-size and edge-alignment rules for this container's children.", null, { context: "constraint", sequence: true }),
+        weight: field("Relative space used by assisted layout.", null, { type: "number" }),
+        span: field("Grid or volume cell span.", null, { context: "span", authoring: "absolute" }),
+        size: field("Explicit [x, y, z] dimensions.", null, { type: "vector", authoring: "absolute" }),
+        sizeMode: field("Whether explicit dimensions are fixed.", ["fit", "fixed"], { authoring: "absolute" }),
+        p: field("Calculated or imported local position.", null, { type: "vector", authoring: "absolute" }),
+        s: field("Calculated final bounding-box size.", null, { type: "vector", authoring: "absolute" }),
+        c: field("Palette token or CSS colour.", null, { valueSource: "palette" }),
+        radius: field("Absolute rounding radius where supported.", null, { type: "number" })
+      })
+    }),
+    relation: freeze({
+      label: "Relation",
+      properties: freeze({
+        id: field("Stable relation identifier.", null, { type: "string" }),
+        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" }),
+        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" }),
+        toAnchor: field("Named target anchor.", null, { type: "string" }),
+        priority: field("Relative routing priority.", null, { type: "number" }),
+        layout: field("Include this relation in assisted routing.", [true, false])
+      })
+    }),
+    layout: freeze({
+      label: "Layout",
+      properties: freeze({
+        algorithm: field("Spatial strategy.", ["row", "grid", "volume", "graph"]),
+        direction: field("Primary semantic axis.", ["x", "y", "z"]),
+        variant: field("Regular or staggered grid cells.", ["uniform", "masonry"]),
+        columns: field("Explicit column count.", null, { type: "integer" }),
+        rows: field("Explicit row count.", null, { type: "integer" }),
+        layers: field("Explicit volume layer count.", null, { type: "integer" }),
+        gap: field("Spacing between children.", null, { type: "number" }),
+        padding: field("Spacing to the container boundary.", null, { type: "number" }),
+        justify: field("Row alignment.", ["start", "center", "end"]),
+        stagger: field("Optional masonry offset.", null, { context: "stagger" }),
+        constraints: field("Equal-size and edge-alignment rules for this layout's siblings.", null, { context: "constraint", sequence: true })
+      })
+    }),
+    constraint: freeze({
+      label: "Sibling constraint",
+      properties: freeze({
+        equal: field("Sibling entity ids that must share dimensions.", null, { type: "string-list" }),
+        align: field("Sibling entity ids whose boundaries or centres must align.", null, { type: "string-list" }),
+        dimensions: field("Dimensions shared by an equal-size group.", ["width", "height", "depth"], { multiple: true }),
+        edge: field("Single dimension or alignment boundary.", ["width", "height", "depth", "left", "centerX", "right", "bottom", "centerY", "top", "back", "centerZ", "front"]),
+        edges: field("Alignment boundaries or centres.", ["left", "centerX", "right", "bottom", "centerY", "top", "back", "centerZ", "front"], { multiple: true }),
+        strength: field("Diagnostic strength when the rule cannot be applied.", ["preferred", "required"])
+      })
+    }),
+    style: freeze({
+      label: "Style",
+      properties: freeze({
+        color: field("Palette token or CSS colour.", null, { valueSource: "palette" }),
+        aspect: field("Semantic proportion.", ["compact", "wide", "tall", "deep", "flat"]),
+        radius: field("Absolute rounding radius.", null, { type: "number" }),
+        label: field("Label appearance.", null, { context: "label" }),
+        edges: field("Edge appearance.", null, { context: "edges" })
+      })
+    }),
+    palette: freeze({
+      label: "Palette",
+      properties: freeze({
+        default_color: field("Fallback CSS colour.", null, { type: "color" })
+      })
+    }),
+    theme: freeze({
+      label: "Theme",
+      properties: freeze({
+        background: field("Background configuration.", null, { context: "background" }),
+        lighting: field("Lighting configuration.", null, { context: "lighting" }),
+        ui: field("Built-in component UI visibility.", null, { context: "ui" })
+      })
+    }),
+    render: freeze({
+      label: "Render",
+      properties: freeze({
+        palette: field("Renderer palette overrides.", null, { context: "palette" }),
+        theme: field("Renderer theme overrides.", null, { context: "theme" }),
+        ui: field("Renderer UI visibility.", null, { context: "ui" }),
+        relationMode: field("Visible relation set.", ["all", "selected", "none"]),
+        selectionMode: field("Selection ownership.", ["internal", "event"]),
+        toolbar: field("Built-in toolbar visibility.", [true, false]),
+        shellLabels: field("Container label visibility.", [true, false])
+      })
+    }),
+    span: freeze({
+      label: "Span",
+      properties: freeze({
+        columns: field("Number of columns occupied.", null, { type: "integer" }),
+        rows: field("Number of rows occupied.", null, { type: "integer" }),
+        layers: field("Number of layers occupied.", null, { type: "integer" })
+      })
+    }),
+    stagger: freeze({
+      label: "Stagger",
+      properties: freeze({
+        offset: field("Masonry row offset.", ["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" }) }) }),
+    edges: freeze({ label: "Edge appearance", properties: freeze({ color: field("Edge colour.", null, { valueSource: "palette" }), opacity: field("Edge opacity.", null, { type: "number" }) }) }),
+    background: freeze({ label: "Background", properties: freeze({ color: field("Background colour.", null, { type: "color" }), glow: field("Background glow colour.", null, { type: "color" }) }) }),
+    lighting: freeze({ label: "Lighting", properties: freeze({ ambient: field("Ambient intensity.", null, { type: "number" }), directional: field("Directional intensity.", null, { type: "number" }) }) }),
+    ui: freeze({ label: "Component UI", properties: freeze({ panel: field("Show information panel.", [true, false]), toolbar: field("Show camera toolbar.", [true, false]), breadcrumbs: field("Show breadcrumbs.", [true, false]), hint: field("Show interaction hint.", [true, false]) }) }),
+    geometryOptions: freeze({ label: "Geometry parameters", properties: freeze({}) }),
+    geometryPalette: freeze({ label: "Geometry palette", properties: freeze({}) })
+  })
+});
+
+export function atlasLayoutContextForPath(path = []) {
+  const names = Array.isArray(path) ? path : [];
+  const aliases = new Map([
+    ["models", "root"],
+    ["entities", "entity"],
+    ["children", "entity"],
+    ["relations", "relation"],
+    ["layout", "layout"],
+    ["constraints", "constraint"],
+    ["style", "style"],
+    ["palette", "palette"],
+    ["theme", "theme"],
+    ["render", "render"],
+    ["span", "span"],
+    ["stagger", "stagger"],
+    ["label", "label"],
+    ["edges", "edges"],
+    ["background", "background"],
+    ["lighting", "lighting"],
+    ["ui", "ui"],
+    ["geometryOptions", "geometryOptions"],
+    ["geometryPalette", "geometryPalette"]
+  ]);
+  for (let index = names.length - 1; index >= 0; index -= 1) {
+    const context = aliases.get(names[index]);
+    if (context && ATLAS_LAYOUT_SPEC_V1.contexts[context]) return ATLAS_LAYOUT_SPEC_V1.contexts[context];
+  }
+  return ATLAS_LAYOUT_SPEC_V1.contexts.root;
+}
+
+export function atlasLayoutProperty(context, name) {
+  return context?.properties?.[name] || null;
+}
+
+const ABSOLUTE_ENTITY_PROPERTIES = new Set(["parent", "span", "size", "sizeMode", "p", "s"]);
+
+export function atlasLayoutPropertyKind(context, name) {
+  const definition = atlasLayoutProperty(context, name);
+  return definition?.authoring || (ABSOLUTE_ENTITY_PROPERTIES.has(name) ? "absolute" : "markup");
+}
+
+export function atlasLayoutValues(definition, options = {}) {
+  if (!definition) return [];
+  if (definition.valueSource === "geometryCatalog") {
+    return (options.geometryCatalog || []).map(item => item.id).filter(Boolean);
+  }
+  if (definition.valueSource === "palette") {
+    return Object.keys(options.palette || {}).filter(Boolean);
+  }
+  return Array.isArray(definition.values) ? [...definition.values] : [];
+}

package/test/index.test.mjs

@@ -11,10 +11,17 @@ function ids(model) {
   return new Map(model.entities.map(entity => [entity.id, entity]));
 }
 
+function entitiesOverlap(a, b) {
+  return [0, 1, 2].every(axis =>
+    Math.abs(a.p[axis] - b.p[axis]) < (a.s[axis] + b.s[axis]) / 2 - 1e-9
+  );
+}
+
 test("normalizes nested entities and inherits colors", () => {
   const model = compileAtlasModel({
     entities: [{
       id: "container",
+      type: "container",
       style: { color: "top" },
       layout: { algorithm: "grid", columns: 2 },
       children: [{ id: "a", geometry: "box" }, { id: "b", geometry: "sphere", style: { color: "warm" } }]
@@ -22,6 +29,8 @@ test("normalizes nested entities and inherits colors", () => {
     render: { palette: { top: "#00f", warm: "#f80", default_color: "#ccc" } }
   });
   const byId = ids(model);
+  assert.equal(byId.get("container").type, "container");
+  assert.equal(byId.get("a").type, "item");
   assert.equal(byId.get("a").parent, "container");
   assert.equal(byId.get("a").c, "top");
   assert.equal(byId.get("b").c, "warm");
@@ -32,17 +41,74 @@ test("normalizes nested entities and inherits colors", () => {
 test("accepts flat parent references as well as nested children", () => {
   const model = compileAtlasModel({
     entities: [
-      { id: "parent", style: { color: "top" }, layout: { algorithm: "row", direction: "x" } },
+      { id: "parent", type: "container", style: { color: "top" }, layout: { algorithm: "row", direction: "x" } },
       { id: "child", parent: "parent", geometry: "box" }
     ],
     render: { palette: { top: "#00f" } }
   });
   const byId = ids(model);
+  assert.equal(byId.get("parent").type, "container");
+  assert.equal(byId.get("child").type, "item");
   assert.equal(byId.get("child").parent, "parent");
   assert.equal(byId.get("child").c, "top");
   assert.equal(model.diagnostics.length, 0);
 });
 
+
+test("requires an explicit container type for nested children", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "root",
+      children: [{ id: "child", geometry: "box" }]
+    }]
+  });
+  assert.equal(model.diagnostics[0].code, "CONTAINER_TYPE_REQUIRED_FOR_CHILDREN");
+  assert.equal(model.diagnostics[0].level, "fatal");
+  assert.equal(ids(model).get("root").type, "container");
+});
+
+test("rejects custom geometry on containers", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "root",
+      type: "container",
+      geometry: "infra.cloud",
+      children: [{ id: "child", geometry: "box" }]
+    }]
+  }, {
+    geometryCatalog: [{ id: "infra.cloud", canonicalSize: [3, 2, 3] }]
+  });
+  assert.equal(model.diagnostics[0].code, "CUSTOM_GEOMETRY_ON_CONTAINER");
+  assert.equal(model.diagnostics[0].level, "fatal");
+});
+
+test("accepts primitive geometry on explicit containers", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "root",
+      type: "container",
+      geometry: "geo.box",
+      children: [{ id: "child", geometry: "sphere" }]
+    }]
+  });
+  assert.equal(ids(model).get("root").type, "container");
+  assert.equal(model.diagnostics.length, 0);
+});
+
+test("normalizes shell as a compatible container alias and infers leaf items", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "root",
+      type: "shell",
+      children: [{ id: "leaf", geometry: "infra.cloud" }]
+    }]
+  }, {
+    geometryCatalog: [{ id: "infra.cloud", canonicalSize: [3, 2, 3] }]
+  });
+  assert.equal(ids(model).get("root").type, "container");
+  assert.equal(ids(model).get("leaf").type, "item");
+  assert.equal(model.diagnostics.length, 0);
+});
 test("row y places the first item above the next item", () => {
   const model = compileAtlasModel({
     layout: { algorithm: "row", direction: "y", gap: 1 },
@@ -126,6 +192,7 @@ test("fixed containers report overflow without hiding children", () => {
   const model = compileAtlasModel({
     entities: [{
       id: "fixed",
+      type: "container",
       size: [1, 1, 1],
       sizeMode: "fixed",
       layout: { algorithm: "row", gap: 1, padding: 1 },
@@ -137,6 +204,90 @@ test("fixed containers report overflow without hiding children", () => {
   assert.equal(ids(model).get("fixed").layoutError, "overflow");
 });
 
+test("equal-size constraints use the largest intrinsic sibling dimensions", () => {
+  const model = compileAtlasModel({
+    constraints: [{
+      equal: ["wide", "small", "deep"],
+      dimensions: ["width", "height", "depth"],
+      strength: "preferred"
+    }],
+    layout: { algorithm: "row", direction: "y", gap: 1 },
+    entities: [
+      { id: "wide", type: "container", layout: { algorithm: "row" }, children: [{ id: "a", geometry: "box" }, { id: "b", geometry: "sphere" }] },
+      { id: "small", type: "container", children: [{ id: "c", geometry: "box" }] },
+      { id: "deep", type: "container", children: [{ id: "d", geometry: "pyramid-square" }] }
+    ]
+  });
+  const byId = ids(model);
+  assert.deepEqual(byId.get("wide").s, byId.get("small").s);
+  assert.deepEqual(byId.get("small").s, byId.get("deep").s);
+  assert.equal(model.diagnostics.length, 0);
+});
+
+test("alignment constraints use stable model-space boundary aliases", () => {
+  const model = compileAtlasModel({
+    constraints: [{
+      align: ["a", "b"],
+      edges: ["left", "front"],
+      strength: "required"
+    }],
+    layout: { algorithm: "row", direction: "y", gap: 1 },
+    entities: [
+      { id: "a", geometry: "box", size: [4, 1, 2] },
+      { id: "b", geometry: "box", size: [2, 1, 4] }
+    ]
+  });
+  const byId = ids(model);
+  assert.equal(byId.get("a").p[0] - byId.get("a").s[0] / 2, byId.get("b").p[0] - byId.get("b").s[0] / 2);
+  assert.equal(byId.get("a").p[2] + byId.get("a").s[2] / 2, byId.get("b").p[2] + byId.get("b").s[2] / 2);
+});
+
+test("alignment preserves non-overlap when it targets the layout axis", () => {
+  const model = compileAtlasModel({
+    constraints: [{ align: ["a", "b", "c"], edges: ["centerY"], strength: "preferred" }],
+    layout: { algorithm: "row", direction: "y", gap: 1 },
+    entities: [
+      { id: "a", geometry: "box", size: [4, 2, 2] },
+      { id: "b", geometry: "sphere", size: [3, 3, 3] },
+      { id: "c", geometry: "box", size: [2, 4, 2] }
+    ]
+  });
+  const byId = ids(model);
+  assert.equal(byId.get("a").p[1], byId.get("b").p[1]);
+  assert.equal(byId.get("b").p[1], byId.get("c").p[1]);
+  assert.equal(entitiesOverlap(byId.get("a"), byId.get("b")), false);
+  assert.equal(entitiesOverlap(byId.get("a"), byId.get("c")), false);
+  assert.equal(entitiesOverlap(byId.get("b"), byId.get("c")), false);
+});
+
+test("changing alignment recompiles from a clean packed layout", () => {
+  const source = {
+    constraints: [{ align: ["a", "b"], edges: ["centerY"], strength: "preferred" }],
+    layout: { algorithm: "row", direction: "y", gap: 1 },
+    entities: [
+      { id: "a", geometry: "box", size: [4, 2, 2] },
+      { id: "b", geometry: "box", size: [2, 2, 2] }
+    ]
+  };
+  const first = compileAtlasModel(source);
+  const second = compileAtlasModel({
+    ...first,
+    constraints: [{ align: ["a", "b"], edges: ["centerX"], strength: "preferred" }]
+  });
+  const byId = ids(second);
+  assert.equal(byId.get("a").p[0], byId.get("b").p[0]);
+  assert.equal(entitiesOverlap(byId.get("a"), byId.get("b")), false);
+});
+
+test("constraints reject references outside their sibling group", () => {
+  const model = compileAtlasModel({
+    constraints: [{ equal: ["a", "missing"], edge: "width", strength: "required" }],
+    entities: [{ id: "a", geometry: "box" }]
+  });
+  assert.equal(model.diagnostics[0].code, "UNKNOWN_CONSTRAINT_ENTITY");
+  assert.equal(model.diagnostics[0].level, "error");
+});
+
 test("graph layout is reported as a recoverable fallback", () => {
   const model = compileAtlasModel({
     entities: [{ id: "a", geometry: "box" }, { id: "b", geometry: "box" }],
@@ -154,6 +305,7 @@ render:
     top: "#00f"
 entities:
   - id: root
+    type: container
     layout:
       algorithm: row
       direction: x