@liquidcars/atlas-layout 0.1.3

package/README.md

@@ -0,0 +1,150 @@
+# `@liquidcars/atlas-layout`
+
+Compilador inicial para modelos declarativos de LiquidCars Atlas. Convierte entidades anidadas con layouts `row`, `grid`, `masonry` y `volume` en el modelo plano que consume `@liquidcars/atlas`.
+
+```js
+import { compileAtlasModel } from "@liquidcars/atlas-layout";
+
+const resolved = compileAtlasModel(authorModel);
+atlas.model = resolved;
+
+console.table(resolved.diagnostics);
+```
+
+Las librerías de geometrías pueden aportar sus proporciones canónicas sin
+acoplar el compilador al renderer:
+
+```js
+const resolved = compileAtlasModel(authorModel, {
+  geometryCatalog: getGeometryCatalog()
+});
+```
+
+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.
+
+Para compilar una fuente YAML durante el build:
+
+```js
+import { compileAtlasFileToJson } from "@liquidcars/atlas-layout/build";
+
+await compileAtlasFileToJson(
+  "layers-model.atlas.yaml",
+  "public/layers-model.resolved.json"
+);
+```
+
+En Vite (y también en Astro mediante `vite.plugins`) se pueden importar las fuentes directamente:
+
+```js
+// vite.config.js
+import atlasLayout from "@liquidcars/atlas-layout/vite";
+
+export default {
+  plugins: [atlasLayout()]
+};
+```
+
+```js
+// src/main.js
+import "@liquidcars/atlas";
+import atlasModel from "../layers-model.atlas.yaml";
+
+document.querySelector("liquidcars-atlas").model = atlasModel;
+```
+
+El plugin transforma `.atlas.yaml`, `.atlas.yml`, `.atlas.md` y `.atlas.markdown` en módulos ESM durante el build y reenvía sus warnings al diagnóstico del bundler. Un diagnóstico `fatal` detiene el build.
+
+También se puede compilar texto YAML directamente:
+
+```js
+import { compileAtlasYaml } from "@liquidcars/atlas-layout/yaml";
+
+const resolved = compileAtlasYaml(yamlText);
+```
+
+La API principal recibe un objeto JavaScript ya parseado. Se aceptan entidades anidadas mediante `children` o entidades planas con referencias `parent`; internamente ambas formas se normalizan al contrato plano. Las entradas de texto se manejan mediante los subpaths `/yaml` y `/build` durante el build.
+
+En Markdown se acepta front matter YAML, un bloque completo ` ```atlas ` o bloques separados ` ```atlas-model `, ` ```atlas-layout `, ` ```atlas-render ` y ` ```atlas-relations `. Por ejemplo:
+
+````markdown
+```atlas
+version: 1
+entities:
+  - id: source
+    geometry: sphere
+layout:
+  algorithm: row
+```
+````
+
+Las relaciones admiten el modo visual canónico `directed`, `bidirectional` o `broken`:
+
+```yaml
+relations:
+  - id: source-to-rules
+    from: source
+    to: rules
+    label: feeds
+    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`.
+
+En un documento Markdown dividido, el bloque de relaciones contiene una lista YAML:
+
+````markdown
+```atlas-relations
+- from: source
+  to: rules
+  mode: bidirectional
+```
+````
+
+Un mismo documento puede contener varios modelos nombrados. El nombre se añade
+al identificador del bloque, separado por espacio o por `:`:
+
+````markdown
+```atlas overview
+entities:
+  - id: source
+    geometry: sphere
+```
+
+```atlas process
+entities:
+  - id: rules
+    geometry: prism
+```
+````
+
+Los bloques divididos usan el mismo nombre (`atlas-model overview`,
+`atlas-relations overview`, etc.). Para estos documentos se utiliza la API
+`compileAtlasMarkdownDocument`, que devuelve `{ models, defaultModel }`:
+
+```js
+import { compileAtlasMarkdownDocument } from "@liquidcars/atlas-layout/yaml";
+
+const document = compileAtlasMarkdownDocument(markdown);
+document.models.overview; // modelo normalizado listo para Atlas
+document.models.process;  // segundo modelo normalizado
+```
+
+`parseAtlasMarkdown` y `compileAtlasMarkdown` mantienen el contrato anterior
+para un único modelo y emiten un error explícito si reciben varios. El plugin
+de Vite conserva ese comportamiento para un solo modelo; con varios bloques
+exporta el documento nombrado completo. También se puede declarar un conjunto
+de modelos en front matter mediante `models:` y seleccionar el predeterminado
+con `defaultModel:`.
+
+El parser Markdown/YAML sólo se ejecuta en build time. El bundle del componente visual no incorpora este parser.
+
+El resultado mantiene `palette`, `theme`, `entities` y `relations`, con `p` y `s` resueltos para todas las entidades. `diagnostics` contiene warnings, errores recuperables y errores fatales; los contenedores fijos que no pueden contener su contenido conservan `layoutError: "overflow"` para que el renderer pueda señalarlos visualmente.
+
+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.
+
+Esta es una primera implementación del motor. `row`, `grid`/`masonry` y `volume` ya producen posiciones deterministas. El algoritmo `graph` está reservado en el contrato y, por ahora, emite `GRAPH_LAYOUT_FALLBACK` y usa `grid`; las restricciones espaciales y la proyección de relaciones entre contenedores se incorporarán en iteraciones posteriores.

package/package.json

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

package/src/build.js

@@ -0,0 +1,20 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { compileAtlasYaml, compileAtlasMarkdown, compileAtlasMarkdownDocument } from "./yaml.js";
+
+export async function compileAtlasFile(filePath, options = {}) {
+  const source = await readFile(filePath, "utf8");
+  const extension = extname(filePath).toLowerCase();
+  if (extension === ".yaml" || extension === ".yml") return compileAtlasYaml(source, { ...options, sourceName: filePath });
+  if (extension === ".md" || extension === ".markdown") {
+    const markdownOptions = { ...options, sourceName: filePath };
+    return options.document ? compileAtlasMarkdownDocument(source, markdownOptions) : compileAtlasMarkdown(source, markdownOptions);
+  }
+  throw new TypeError(`Unsupported Atlas source extension '${extension}'. Use .yaml, .yml, .md or .markdown.`);
+}
+
+export async function compileAtlasFileToJson(inputPath, outputPath, options = {}) {
+  const model = await compileAtlasFile(inputPath, options);
+  await writeFile(outputPath, `${JSON.stringify(model, null, 2)}\n`, "utf8");
+  return model;
+}

package/src/index.js

@@ -0,0 +1,549 @@
+const DEFAULT_COLOR = "#b9d8eb";
+
+const DEFAULT_SIZES = Object.freeze({
+  box: [2.5, 1.2, 2.2],
+  cylinder: [2.5, 1.2, 2.2],
+  sphere: [2.2, 2.2, 2.2],
+  cone: [2.5, 1.4, 2.2],
+  "frustum-cone": [2.5, 1.4, 2.5],
+  "frustum-pyramid": [3.4, 2.1, 3.4],
+  "frustum-triangle": [3.4, 2.1, 3.4],
+  prism: [2.5, 1.4, 2.5],
+  "pyramid-square": [3.4, 2.1, 3.4],
+  "pyramid-triangle": [3.4, 2.1, 3.4],
+  octahedron: [2.3, 2.3, 2.3],
+  dodecahedron: [2.3, 2.3, 2.3],
+  icosahedron: [2.3, 2.3, 2.3]
+});
+
+const ASPECT_FACTORS = Object.freeze({
+  compact: [1, 1, 1],
+  wide: [1.35, 0.86, 0.86],
+  tall: [0.86, 1.35, 0.86],
+  deep: [0.86, 0.86, 1.35],
+  flat: [1.08, 0.56, 1.08]
+});
+
+const ALGORITHMS = new Set(["row", "grid", "volume", "graph"]);
+
+// Relation modes are part of the declarative model contract. The renderer
+// accepts a few historical aliases, but the build-time compiler always emits
+// one of these canonical values so downstream consumers can rely on a stable
+// shape.
+export const RELATION_MODES = Object.freeze(["directed", "bidirectional", "broken"]);
+
+const RELATION_MODE_ALIASES = new Map([
+  ["directed", "directed"],
+  ["one-way", "directed"],
+  ["oneway", "directed"],
+  ["unidirectional", "directed"],
+  ["arrow", "directed"],
+  ["single", "directed"],
+  ["bidirectional", "bidirectional"],
+  ["bi-directional", "bidirectional"],
+  ["two-way", "bidirectional"],
+  ["twoway", "bidirectional"],
+  ["duplex", "bidirectional"],
+  ["both", "bidirectional"],
+  ["broken", "broken"],
+  ["interrupted", "broken"],
+  ["disconnected", "broken"],
+  ["failed", "broken"],
+  ["cut", "broken"]
+]);
+
+function asVector(value, fallback = [0, 0, 0]) {
+  if (Array.isArray(value) && value.length === 3 && value.every(Number.isFinite)) return value.map(Number);
+  return [...fallback];
+}
+
+function positiveNumber(value, fallback) {
+  return Number.isFinite(Number(value)) && Number(value) > 0 ? Number(value) : fallback;
+}
+
+function scalar(value, fallback = 0) {
+  return Number.isFinite(Number(value)) ? Number(value) : fallback;
+}
+
+function multiply(a, b) {
+  return [a[0] * b[0], a[1] * b[1], a[2] * b[2]];
+}
+
+function add(a, b) {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+
+function mergeStyle(parent = {}, own = {}) {
+  return {
+    ...parent,
+    ...own,
+    label: { ...(parent.label || {}), ...(own.label || {}) },
+    edges: { ...(parent.edges || {}), ...(own.edges || {}) }
+  };
+}
+
+function diagnostic(diagnostics, level, code, message, extra = {}) {
+  diagnostics.push({ level, code, message, ...extra, recoverable: level !== "fatal" });
+}
+
+function flattenEntities(input, diagnostics) {
+  const entities = [];
+  const childrenById = new Map();
+  const sourceById = new Map();
+  const seen = new Set();
+
+  function visit(items, parent = null) {
+    if (!Array.isArray(items)) return;
+    for (const raw of items) {
+      if (!raw || typeof raw !== "object" || !raw.id) {
+        diagnostic(diagnostics, "warning", "INVALID_ENTITY", "An entity without a valid id was ignored.");
+        continue;
+      }
+      if (seen.has(raw.id)) {
+        diagnostic(diagnostics, "warning", "DUPLICATE_ENTITY_ID", `Duplicate entity id '${raw.id}' was ignored.`, { entityId: raw.id });
+        continue;
+      }
+      seen.add(raw.id);
+      const children = Array.isArray(raw.children) ? raw.children : [];
+      const entity = { ...raw };
+      delete entity.children;
+      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;
+      entities.push(entity);
+      sourceById.set(entity.id, raw);
+      childrenById.set(entity.id, children.map(child => child && child.id).filter(Boolean));
+      visit(children, entity.id);
+    }
+  }
+
+  visit(input);
+  const ids = new Set(entities.map(entity => entity.id));
+  for (const entity of entities) {
+    if (entity.parent && !ids.has(entity.parent)) {
+      diagnostic(diagnostics, "warning", "UNKNOWN_PARENT", `Entity '${entity.id}' references missing parent '${entity.parent}' and was promoted to root.`, { entityId: entity.id, parentId: entity.parent });
+      entity.parent = null;
+    }
+    if (entity.parent && !childrenById.has(entity.parent)) childrenById.set(entity.parent, []);
+    if (entity.parent) {
+      const siblings = childrenById.get(entity.parent);
+      if (!siblings.includes(entity.id)) siblings.push(entity.id);
+    }
+  }
+  return { entities, childrenById, sourceById };
+}
+
+function normalizeRelationMode(relation, diagnostics, index, shorthandMode) {
+  let candidate;
+  for (const value of [relation.mode, relation.visual, relation.render, relation.type, relation.direction, shorthandMode]) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      candidate = value;
+      break;
+    }
+  }
+  if (candidate == null && relation.bidirectional === true) candidate = "bidirectional";
+  if (candidate == null && relation.broken === true) candidate = "broken";
+  if (candidate == null || candidate === "") return "directed";
+
+  const key = String(candidate).trim().toLowerCase().replace(/[_ ]+/g, "-");
+  const mode = RELATION_MODE_ALIASES.get(key);
+  if (mode) return mode;
+
+  diagnostic(diagnostics, "warning", "UNKNOWN_RELATION_MODE", `Unknown relation mode '${candidate}' on relation ${index}; using directed.`, {
+    relationIndex: index,
+    mode: candidate,
+    fallback: "directed"
+  });
+  return "directed";
+}
+
+function normalizeRelations(input, validIds, diagnostics) {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((raw, index) => {
+    const relation = Array.isArray(raw)
+      ? { from: raw[0], to: raw[1], label: raw[2] || "", mode: raw[3] }
+      : { ...raw };
+    if (!validIds.has(relation.from) || !validIds.has(relation.to)) {
+      diagnostic(diagnostics, "warning", "UNKNOWN_RELATION_ENDPOINT", `Relation ${index} was ignored because one endpoint does not exist.`, { relationIndex: index, relation });
+      return [];
+    }
+    const normalized = {
+      from: relation.from,
+      to: relation.to,
+      label: relation.label || "",
+      mode: normalizeRelationMode(relation, diagnostics, index, Array.isArray(raw) ? raw[3] : undefined),
+      layout: relation.layout !== false,
+      priority: positiveNumber(relation.priority, 1),
+      index
+    };
+    if (relation.id != null) normalized.id = String(relation.id);
+    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];
+  });
+}
+
+function paletteFrom(source) {
+  return {
+    ...(source.palette || {}),
+    ...((source.render && source.render.palette) || {}),
+    default_color: (source.render && source.render.palette && source.render.palette.default_color) || source.palette?.default_color || DEFAULT_COLOR
+  };
+}
+
+function resolveColor(value, inherited, palette, diagnostics, entityId) {
+  const candidate = value ?? inherited ?? "default_color";
+  if (typeof candidate !== "string") return palette.default_color;
+  if (palette[candidate]) return candidate;
+  if (/^(#|rgb|hsl|oklch|color\()/i.test(candidate)) return candidate;
+  diagnostic(diagnostics, "warning", "UNKNOWN_COLOR_TOKEN", `Unknown color token '${candidate}' on '${entityId}'.`, { entityId, token: candidate, fallback: "default_color" });
+  return palette.default_color;
+}
+
+function resolveStyles(entities, sourceById, childrenById, palette, diagnostics) {
+  const byId = new Map(entities.map(entity => [entity.id, entity]));
+  const resolved = new Map();
+
+  function visit(id, parentStyle = {}) {
+    const entity = byId.get(id);
+    if (!entity) return;
+    const source = sourceById.get(id) || {};
+    const style = mergeStyle(parentStyle, source.style || {});
+    style.color = resolveColor(style.color, parentStyle.color, palette, diagnostics, id);
+    entity.style = style;
+    entity.c = style.color;
+    if (style.radius != null && entity.radius == null) entity.radius = scalar(style.radius, 0);
+    resolved.set(id, style);
+    for (const childId of childrenById.get(id) || []) visit(childId, style);
+  }
+
+  for (const entity of entities) if (!entity.parent) visit(entity.id);
+  return resolved;
+}
+
+function intrinsicSize(entity, algorithm = "grid", geometrySizes = DEFAULT_SIZES) {
+  if (Array.isArray(entity.size) && entity.size.length === 3) return asVector(entity.size, [1, 1, 1]);
+  const base = geometrySizes[entity.geometry] || DEFAULT_SIZES[entity.geometry] || DEFAULT_SIZES.box;
+  const aspectName = entity.style?.aspect || "compact";
+  const aspect = ASPECT_FACTORS[aspectName] || ASPECT_FACTORS.compact;
+  const weight = positiveNumber(entity.weight, 1);
+  const volumeScale = algorithm === "row" ? Math.cbrt(weight) : 1;
+  return multiply(base, aspect).map(value => value * volumeScale);
+}
+
+function sizeForSlot(item, slotSize) {
+  const base = item.size;
+  if (item.entity.type === "shell" || 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),
+    slotSize[2] / Math.max(base[2], 0.0001)
+  );
+  return base.map(value => value * Math.max(0, scale));
+}
+
+function spanFor(entity, dimension, minimumWeight) {
+  const explicit = entity.span || {};
+  if (dimension === 2 && (explicit.columns || explicit.rows)) {
+    return [Math.max(1, Math.round(scalar(explicit.columns, 1))), Math.max(1, Math.round(scalar(explicit.rows, 1)))];
+  }
+  if (dimension === 3 && (explicit.columns || explicit.rows || explicit.layers)) {
+    return [
+      Math.max(1, Math.round(scalar(explicit.columns, 1))),
+      Math.max(1, Math.round(scalar(explicit.rows, 1))),
+      Math.max(1, Math.round(scalar(explicit.layers, 1)))
+    ];
+  }
+  const target = Math.max(1, Math.ceil(positiveNumber(entity.weight, 1) / minimumWeight));
+  if (dimension === 2) {
+    const columns = Math.max(1, Math.ceil(Math.sqrt(target)));
+    return [columns, Math.max(1, Math.ceil(target / columns))];
+  }
+  const columns = Math.max(1, Math.ceil(Math.cbrt(target)));
+  const rows = Math.max(1, Math.ceil(Math.sqrt(target / columns)));
+  return [columns, rows, Math.max(1, Math.ceil(target / (columns * rows)))];
+}
+
+function boundsOf(placements, padding) {
+  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 axis = 0; axis < 3; axis++) {
+      min[axis] = Math.min(min[axis], item.position[axis] - item.size[axis] / 2);
+      max[axis] = Math.max(max[axis], item.position[axis] + item.size[axis] / 2);
+    }
+  }
+  const center = min.map((value, axis) => (value + max[axis]) / 2);
+  const positions = placements.map(item => ({ ...item, position: item.position.map((value, axis) => {
+    const centered = value - center[axis];
+    return Object.is(centered, -0) ? 0 : centered;
+  }) }));
+  return { positions, size: max.map((value, axis) => value - min[axis] + padding * 2) };
+}
+
+function rowLayout(items, spec, diagnostics) {
+  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 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 orderSign = axis === 0 ? 1 : -1;
+  let cursor = -total / 2;
+  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;
+    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);
+}
+
+function gridDimensions(items, spec, dimension) {
+  const weights = items.map(item => positiveNumber(item.entity.weight, 1));
+  const minimumWeight = Math.min(...weights);
+  const spans = items.map(item => spanFor(item.entity, dimension, minimumWeight));
+  const weightedCells = spans.reduce((sum, span) => sum + span.reduce((product, value) => product * value, 1), 0);
+  if (dimension === 2) {
+    const columns = Math.max(1, Math.round(scalar(spec.columns, Math.ceil(Math.sqrt(weightedCells)))));
+    return { spans, minimumWeight, columns, rows: Math.max(1, Math.ceil(weightedCells / columns)) };
+  }
+  const columns = Math.max(1, Math.round(scalar(spec.columns, Math.ceil(Math.cbrt(weightedCells)))));
+  const rows = Math.max(1, Math.round(scalar(spec.rows, Math.ceil(Math.sqrt(weightedCells / columns)))));
+  return { spans, minimumWeight, columns, rows, layers: Math.max(1, Math.round(scalar(spec.layers, Math.ceil(weightedCells / (columns * rows))))) };
+}
+
+function occupiedKey(coords) {
+  return coords.join(":");
+}
+
+function canOccupy(occupied, start, span, limits) {
+  for (let z = 0; z < span[1]; z++) for (let x = 0; x < span[0]; x++) {
+    const column = start[0] + x;
+    const row = start[1] + z;
+    if (column >= limits.columns || row >= limits.rows || occupied.has(occupiedKey([column, row]))) return false;
+  }
+  return true;
+}
+
+function canOccupyVolume(occupied, start, span, limits) {
+  for (let y = 0; y < span[2]; y++) for (let z = 0; z < span[1]; z++) for (let x = 0; x < span[0]; x++) {
+    const coords = [start[0] + x, start[1] + z, start[2] + y];
+    if (coords[0] >= limits.columns || coords[1] >= limits.rows || coords[2] >= limits.layers || occupied.has(occupiedKey(coords))) return false;
+  }
+  return true;
+}
+
+function markOccupied(occupied, start, span, dimension) {
+  if (dimension === 2) {
+    for (let z = 0; z < span[1]; z++) for (let x = 0; x < span[0]; x++) occupied.add(occupiedKey([start[0] + x, start[1] + z]));
+  } else {
+    for (let y = 0; y < span[2]; y++) for (let z = 0; z < span[1]; z++) for (let x = 0; x < span[0]; x++) occupied.add(occupiedKey([start[0] + x, start[1] + z, start[2] + y]));
+  }
+}
+
+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));
+  const dims = gridDimensions(items, spec, dimension);
+  const limits = { columns: dims.columns, rows: dims.rows, layers: dims.layers || 1 };
+  const occupied = new Set();
+  const placements = [];
+  const base = dimension === 2 ? [0, 0] : [0, 0, 0];
+
+  if (dimension === 2) {
+    for (const item of items) {
+      const span = dims.spans[placements.length];
+      if (span[0] > limits.columns) {
+        diagnostic(diagnostics, "warning", "SPAN_EXCEEDS_COLUMNS", `Span for '${item.entity.id}' exceeds the declared columns.`, { entityId: item.entity.id });
+        limits.columns = span[0];
+      }
+      let start = null;
+      for (let row = 0; !start && row < limits.rows + items.length + 1; row++) for (let column = 0; column < limits.columns; column++) if (canOccupy(occupied, [column, row], span, limits)) {
+        start = [column, row];
+        break;
+      }
+      if (!start) {
+        start = [0, limits.rows];
+        limits.rows += span[1];
+      }
+      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);
+    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];
+      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)];
+    }
+    return boundsOf(placements, padding);
+  }
+
+  for (const item of items) {
+    const span = dims.spans[placements.length];
+    if (span[0] > limits.columns) limits.columns = span[0];
+    if (span[1] > limits.rows) limits.rows = span[1];
+    if (span[2] > limits.layers) limits.layers = span[2];
+    let start = null;
+    for (let layer = 0; !start && layer < limits.layers + items.length + 1; layer++) for (let row = 0; !start && row < limits.rows; row++) for (let column = 0; column < limits.columns; column++) if (canOccupyVolume(occupied, [column, row, layer], span, limits)) {
+      start = [column, row, layer];
+      break;
+    }
+    if (!start) {
+      start = [0, 0, limits.layers];
+      limits.layers += span[2];
+    }
+    markOccupied(occupied, start, span, 3);
+    placements.push({ ...item, span, cell: start });
+  }
+  const cellX = Math.max(...placements.map(item => item.size[0] / item.span[0]), 1);
+  const cellY = Math.max(...placements.map(item => item.size[1] / item.span[2]), 1);
+  const cellZ = Math.max(...placements.map(item => item.size[2] / item.span[1]), 1);
+  for (const item of placements) {
+    const width = item.span[0] * cellX + (item.span[0] - 1) * gap;
+    const height = item.span[2] * cellY + (item.span[2] - 1) * gap;
+    const depth = item.span[1] * cellZ + (item.span[1] - 1) * gap;
+    const slotSize = [width, height, depth];
+    item.size = sizeForSlot(item, slotSize);
+    item.slotSize = slotSize;
+    item.position = [
+      item.cell[0] * (cellX + gap) + width / 2,
+      item.cell[2] * (cellY + gap) + height / 2,
+      -(item.cell[1] * (cellZ + gap) + depth / 2)
+    ];
+  }
+  return boundsOf(placements, padding);
+}
+
+function gridLayout(items, spec, diagnostics) {
+  const hasSpans = items.some(item => item.entity.span || positiveNumber(item.entity.weight, 1) > 1);
+  return hasSpans || spec.variant === "masonry" ? packedGridLayout(items, spec, diagnostics, 2) : packedGridLayout(items, { ...spec, columns: spec.columns || Math.ceil(Math.sqrt(items.length)) }, diagnostics, 2);
+}
+
+function volumeLayout(items, spec, diagnostics) {
+  return packedGridLayout(items, spec, diagnostics, 3);
+}
+
+function resolveTheme(source) {
+  const theme = source.theme || source.styles || {};
+  const render = source.render || {};
+  return {
+    ...theme,
+    ...(render.theme || {}),
+    ui: { ...(theme.ui || {}), ...(render.ui || {}) }
+  };
+}
+
+function normalizeRoot(input) {
+  if (input && input.model && !input.entities && !input.relations) return { ...input.model, layout: input.layout, render: input.render };
+  return input || {};
+}
+
+export function compileAtlasModel(input, options = {}) {
+  const diagnostics = [];
+  const source = normalizeRoot(input);
+  const palette = paletteFrom(source);
+  const flat = flattenEntities(source.entities, 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);
+  resolveStyles(flat.entities, flat.sourceById, flat.childrenById, palette, diagnostics);
+  const byId = new Map(flat.entities.map(entity => [entity.id, entity]));
+  const geometrySizes = { ...DEFAULT_SIZES };
+  for (const definition of options.geometryCatalog || []) {
+    if (!definition?.id || !Array.isArray(definition.canonicalSize) || definition.canonicalSize.length !== 3) continue;
+    geometrySizes[definition.id] = asVector(definition.canonicalSize, DEFAULT_SIZES.box);
+    for (const alias of definition.aliases || []) geometrySizes[alias] = geometrySizes[definition.id];
+  }
+
+  function layoutEntity(entityId) {
+    const entity = byId.get(entityId);
+    if (!entity) return [1, 1, 1];
+    const childIds = flat.childrenById.get(entityId) || [];
+    if (!childIds.length) {
+      entity.s = intrinsicSize(entity, "grid", geometrySizes);
+      entity.p = asVector(entity.p);
+      return entity.s;
+    }
+    const childItems = childIds.map(childId => {
+      const child = byId.get(childId);
+      return { entity: child, size: layoutEntity(childId) };
+    });
+    const sourceEntity = flat.sourceById.get(entityId) || {};
+    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 result = algorithm === "row"
+      ? rowLayout(childItems, spec, diagnostics)
+      : algorithm === "volume"
+        ? volumeLayout(childItems, spec, diagnostics)
+        : gridLayout(childItems, spec, diagnostics);
+    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 });
+      entity.layoutError = "overflow";
+    }
+    entity.p = asVector(entity.p);
+    return entity.s;
+  }
+
+  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 = rootAlgorithm === "row"
+    ? rowLayout(rootItems, rootSpec, diagnostics)
+    : rootAlgorithm === "volume"
+      ? volumeLayout(rootItems, rootSpec, diagnostics)
+      : gridLayout(rootItems, rootSpec, diagnostics);
+  for (const placement of rootResult.positions) {
+    const entity = byId.get(placement.entity.id);
+    entity.p = placement.position;
+    entity.s = placement.size;
+  }
+
+  const output = {
+    palette,
+    theme: resolveTheme(source),
+    entities: flat.entities.map(entity => {
+      const copy = { ...entity };
+      delete copy.style;
+      delete copy.__atlasExplicitSize;
+      return copy;
+    }),
+    relations,
+    layout: source.layout || 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"));
+  return output;
+}
+
+export function compileAtlasModelWithDiagnostics(input, options = {}) {
+  const model = compileAtlasModel(input, options);
+  return { model, diagnostics: model.diagnostics || [] };
+}
+
+export const layoutDefaults = Object.freeze({ defaultColor: DEFAULT_COLOR, sizes: DEFAULT_SIZES, aspectFactors: ASPECT_FACTORS });

package/src/vite.js

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { compileAtlasMarkdownDocument, compileAtlasYaml } from "./yaml.js";
+
+const DEFAULT_EXTENSIONS = Object.freeze([".atlas.yaml", ".atlas.yml", ".atlas.md", ".atlas.markdown"]);
+
+function stripQuery(id) {
+  return id.split("?", 1)[0];
+}
+
+function isAtlasSource(id, extensions) {
+  const path = stripQuery(id).toLowerCase();
+  return extensions.some(extension => path.endsWith(extension));
+}
+
+function messageForDiagnostic(item) {
+  const location = item.entityId ? ` [${item.entityId}]` : "";
+  return `${item.code}${location}: ${item.message}`;
+}
+
+export default function atlasLayout(options = {}) {
+  const extensions = Array.isArray(options.extensions) && options.extensions.length
+    ? options.extensions.map(extension => extension.startsWith(".") ? extension.toLowerCase() : `.${extension.toLowerCase()}`)
+    : DEFAULT_EXTENSIONS;
+
+  return {
+    name: "liquidcars-atlas-layout",
+    enforce: "pre",
+
+    resolveId(source, importer) {
+      if (!isAtlasSource(source, extensions)) return null;
+      return source.startsWith("/") ? source : resolve(importer ? importer.replace(/[^/]+$/, "") : process.cwd(), source);
+    },
+
+    async load(id) {
+      const filePath = stripQuery(id);
+      if (!isAtlasSource(filePath, extensions)) return null;
+      const source = await readFile(filePath, "utf8");
+      const extension = extname(filePath).toLowerCase();
+      const model = extension === ".md" || extension === ".markdown"
+        ? compileAtlasMarkdownDocument(source, { sourceName: filePath })
+        : compileAtlasYaml(source, { sourceName: filePath });
+      const output = extension === ".md" || extension === ".markdown"
+        ? Object.keys(model.models).length === 1 ? model.models[model.defaultModel] : model
+        : model;
+      const diagnostics = extension === ".md" || extension === ".markdown"
+        ? Object.values(model.models).flatMap(value => value.diagnostics || [])
+        : model.diagnostics || [];
+      for (const item of diagnostics) {
+        const message = messageForDiagnostic(item);
+        if (item.level === "fatal") {
+          if (typeof this.error === "function") this.error(message);
+          throw new Error(message);
+        }
+        if (typeof this.warn === "function") this.warn(message);
+      }
+      return `export default ${JSON.stringify(output)};\nexport const diagnostics = ${JSON.stringify(diagnostics)};\n`;
+    }
+  };
+}
+
+export { DEFAULT_EXTENSIONS };

package/src/yaml.js

@@ -0,0 +1,142 @@
+import { parse } from "yaml";
+import { compileAtlasModel } from "./index.js";
+
+function parseValue(text, sourceName = "Atlas YAML") {
+  if (typeof text !== "string" || !text.trim()) throw new TypeError(`${sourceName} must contain YAML text.`);
+  const value = parse(text);
+  return value;
+}
+
+function parseDocument(text, sourceName = "Atlas YAML") {
+  const value = parseValue(text, sourceName);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new SyntaxError(`${sourceName} must contain an Atlas object.`);
+  }
+  return value;
+}
+
+export function parseAtlasYaml(text, options = {}) {
+  return parseDocument(text, options.sourceName || "Atlas YAML");
+}
+
+export function compileAtlasYaml(text, options = {}) {
+  return compileAtlasModel(parseAtlasYaml(text, options), options);
+}
+
+function markdownBlocks(markdown) {
+  const blocks = [];
+  const expression = /```([^\r\n`]*)\r?\n([\s\S]*?)```/gi;
+  for (const match of markdown.matchAll(expression)) {
+    const info = match[1].trim();
+    const tokens = info.split(/\s+/).filter(Boolean);
+    const opener = tokens.shift()?.toLowerCase() || "";
+    const inlineName = opener.match(/^(atlas(?:-yaml|-model|-layout|-render|-relations)?|yaml):(.+)$/i);
+    const kind = (inlineName ? inlineName[1] : opener).toLowerCase();
+    const name = (inlineName ? [inlineName[2], ...tokens] : tokens).join(" ").trim() || null;
+    if (["atlas", "atlas-yaml", "yaml", "atlas-model", "atlas-layout", "atlas-render", "atlas-relations"].includes(kind)) {
+      blocks.push({ kind, name, text: match[2] });
+    }
+  }
+  return blocks;
+}
+
+function modelName(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "default";
+}
+
+function addModelGroup(groups, name) {
+  const id = modelName(name);
+  if (!groups.has(id)) groups.set(id, { full: null, model: null, layout: null, render: null, relations: null });
+  return groups.get(id);
+}
+
+function assignBlock(group, block, field, sourceName) {
+  if (group[field]) throw new SyntaxError(`${sourceName} contains more than one '${block.kind}' block for model '${modelName(block.name)}'.`);
+  group[field] = block;
+}
+
+/**
+ * Parses a Markdown document into one or more named Atlas model sources.
+ *
+ * Named fenced blocks use `atlas <name>` (or `atlas:<name>`). Split blocks
+ * use the same suffix, for example `atlas-model overview` and
+ * `atlas-relations overview`. Unnamed documents retain the historical
+ * `default` model name.
+ */
+export function parseAtlasMarkdownDocument(markdown, options = {}) {
+  if (typeof markdown !== "string" || !markdown.trim()) throw new TypeError("Atlas Markdown must contain text.");
+  const frontmatter = markdown.match(/^---\s*\n([\s\S]*?)\n---(?:\s*\n|$)/);
+  if (frontmatter) {
+    const value = parseDocument(frontmatter[1], options.sourceName || "Atlas Markdown front matter");
+    if (value.models && typeof value.models === "object" && !Array.isArray(value.models)) {
+      const models = { ...value.models };
+      const names = Object.keys(models);
+      if (!names.length) throw new SyntaxError("Atlas Markdown front matter models must contain at least one named model.");
+      const defaultModel = modelName(value.defaultModel || options.defaultModel || names[0]);
+      if (!Object.hasOwn(models, defaultModel)) throw new SyntaxError(`Atlas Markdown default model '${defaultModel}' does not exist.`);
+      return { models, defaultModel };
+    }
+    return { models: { default: value }, defaultModel: "default" };
+  }
+
+  const blocks = markdownBlocks(markdown);
+  if (!blocks.length) {
+    throw new SyntaxError("Atlas Markdown must contain front matter or an ```atlas``` YAML block.");
+  }
+
+  const groups = new Map();
+  for (const block of blocks) {
+    const group = addModelGroup(groups, block.name);
+    if (["atlas", "atlas-yaml", "yaml"].includes(block.kind)) assignBlock(group, block, "full", "Atlas Markdown");
+    if (block.kind === "atlas-model") assignBlock(group, block, "model", "Atlas Markdown");
+    if (block.kind === "atlas-layout") assignBlock(group, block, "layout", "Atlas Markdown");
+    if (block.kind === "atlas-render") assignBlock(group, block, "render", "Atlas Markdown");
+    if (block.kind === "atlas-relations") assignBlock(group, block, "relations", "Atlas Markdown");
+  }
+
+  const models = {};
+  for (const [name, group] of groups) {
+    if (group.full && (group.model || group.layout || group.render || group.relations)) {
+      throw new SyntaxError(`Atlas Markdown model '${name}' mixes a full block with split model blocks.`);
+    }
+    if (group.full) {
+      models[name] = parseDocument(group.full.text, `Atlas Markdown model '${name}'`);
+      continue;
+    }
+    const value = group.model ? parseDocument(group.model.text, `Atlas Markdown model block '${name}'`) : {};
+    if (group.layout) value.layout = parseDocument(group.layout.text, `Atlas Markdown layout block '${name}'`);
+    if (group.render) value.render = parseDocument(group.render.text, `Atlas Markdown render block '${name}'`);
+    if (group.relations) {
+      const parsed = parseValue(group.relations.text, `Atlas Markdown relations block '${name}'`);
+      const relationList = Array.isArray(parsed) ? parsed : parsed?.relations;
+      if (!Array.isArray(relationList)) throw new SyntaxError(`Atlas Markdown relations block '${name}' must contain a YAML list (or an object with relations).`);
+      value.relations = relationList;
+    }
+    models[name] = value;
+  }
+
+  const names = Object.keys(models);
+  const defaultModel = modelName(options.defaultModel || (Object.hasOwn(models, "default") ? "default" : names[0]));
+  if (!Object.hasOwn(models, defaultModel)) throw new SyntaxError(`Atlas Markdown default model '${defaultModel}' does not exist.`);
+  return { models, defaultModel };
+}
+
+export function parseAtlasMarkdown(markdown, options = {}) {
+  const document = parseAtlasMarkdownDocument(markdown, options);
+  const names = Object.keys(document.models);
+  if (names.length !== 1) throw new SyntaxError("Atlas Markdown contains multiple models; use parseAtlasMarkdownDocument() instead.");
+  return document.models[names[0]];
+}
+
+export function compileAtlasMarkdown(markdown, options = {}) {
+  const document = compileAtlasMarkdownDocument(markdown, options);
+  const names = Object.keys(document.models);
+  if (names.length !== 1) throw new SyntaxError("Atlas Markdown contains multiple models; use compileAtlasMarkdownDocument() instead.");
+  return document.models[names[0]];
+}
+
+export function compileAtlasMarkdownDocument(markdown, options = {}) {
+  const source = parseAtlasMarkdownDocument(markdown, options);
+  const models = Object.fromEntries(Object.entries(source.models).map(([name, value]) => [name, compileAtlasModel(value, options)]));
+  return { models, defaultModel: source.defaultModel };
+}

package/test/index.test.mjs

@@ -0,0 +1,326 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { compileAtlasMarkdown, compileAtlasMarkdownDocument, compileAtlasYaml, parseAtlasMarkdown, parseAtlasMarkdownDocument } from "../src/yaml.js";
+import { compileAtlasModel } from "../src/index.js";
+import atlasLayout from "../src/vite.js";
+
+function ids(model) {
+  return new Map(model.entities.map(entity => [entity.id, entity]));
+}
+
+test("normalizes nested entities and inherits colors", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "container",
+      style: { color: "top" },
+      layout: { algorithm: "grid", columns: 2 },
+      children: [{ id: "a", geometry: "box" }, { id: "b", geometry: "sphere", style: { color: "warm" } }]
+    }],
+    render: { palette: { top: "#00f", warm: "#f80", default_color: "#ccc" } }
+  });
+  const byId = ids(model);
+  assert.equal(byId.get("a").parent, "container");
+  assert.equal(byId.get("a").c, "top");
+  assert.equal(byId.get("b").c, "warm");
+  assert.deepEqual(byId.get("container").p, [0, 0, 0]);
+  assert.equal(model.diagnostics.length, 0);
+});
+
+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: "child", parent: "parent", geometry: "box" }
+    ],
+    render: { palette: { top: "#00f" } }
+  });
+  const byId = ids(model);
+  assert.equal(byId.get("child").parent, "parent");
+  assert.equal(byId.get("child").c, "top");
+  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 },
+    entities: [{ id: "top", geometry: "box" }, { id: "bottom", geometry: "box" }]
+  });
+  const byId = ids(model);
+  assert.ok(byId.get("top").p[1] > byId.get("bottom").p[1]);
+});
+
+test("grid starts at the front and advances toward the back", () => {
+  const model = compileAtlasModel({
+    layout: { algorithm: "grid", columns: 1, gap: 1 },
+    entities: [{ id: "front", geometry: "box" }, { id: "back", geometry: "box" }]
+  });
+  const byId = ids(model);
+  assert.ok(byId.get("front").p[2] > byId.get("back").p[2]);
+});
+
+test("grid preserves canonical proportions inside non-cubic cells", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "sphere", geometry: "sphere" }, { id: "wide", geometry: "box", weight: 2 }],
+    layout: { algorithm: "grid", columns: 2, gap: 1 }
+  });
+  const sphere = ids(model).get("sphere");
+  assert.ok(Math.abs(sphere.s[0] - sphere.s[1]) < 1e-9);
+  assert.ok(Math.abs(sphere.s[1] - sphere.s[2]) < 1e-9);
+});
+
+test("masonry offsets alternate rows", () => {
+  const model = compileAtlasModel({
+    layout: { algorithm: "grid", variant: "masonry", columns: 2, stagger: { mode: "alternate", offset: "half-cell" } },
+    entities: ["a", "b", "c", "d"].map(id => ({ id, geometry: "box" }))
+  });
+  const byId = ids(model);
+  assert.notEqual(byId.get("a").p[0], byId.get("c").p[0]);
+});
+
+test("volume distributes elements from bottom to top", () => {
+  const model = compileAtlasModel({
+    layout: { algorithm: "volume", columns: 1, rows: 1, layers: 2, gap: 1 },
+    entities: [{ id: "bottom", geometry: "box" }, { id: "top", geometry: "box" }]
+  });
+  const byId = ids(model);
+  assert.ok(byId.get("top").p[1] > byId.get("bottom").p[1]);
+});
+
+test("invalid relation endpoints produce recoverable diagnostics", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "a", geometry: "box" }],
+    relations: [{ from: "a", to: "missing", label: "broken" }]
+  });
+  assert.equal(model.relations.length, 0);
+  assert.equal(model.diagnostics[0].code, "UNKNOWN_RELATION_ENDPOINT");
+});
+
+test("normalizes relation modes and keeps optional relation ids", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "a", geometry: "box" }, { id: "b", geometry: "box" }, { id: "c", geometry: "box" }, { id: "d", geometry: "box" }],
+    relations: [
+      { id: "feed", from: "a", to: "b", mode: "bidirectional" },
+      { from: "b", to: "c", visual: "interrupted" },
+      ["c", "d", "legacy shorthand", "two-way"]
+    ]
+  });
+  assert.deepEqual(model.relations.map(relation => relation.mode), ["bidirectional", "broken", "bidirectional"]);
+  assert.equal(model.relations[0].id, "feed");
+  assert.equal(model.diagnostics.length, 0);
+});
+
+test("invalid relation modes fall back to directed with a warning", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "a", geometry: "box" }, { id: "b", geometry: "box" }],
+    relations: [{ from: "a", to: "b", mode: "sideways" }]
+  });
+  assert.equal(model.relations[0].mode, "directed");
+  assert.equal(model.diagnostics[0].code, "UNKNOWN_RELATION_MODE");
+  assert.equal(model.diagnostics[0].fallback, "directed");
+});
+
+test("fixed containers report overflow without hiding children", () => {
+  const model = compileAtlasModel({
+    entities: [{
+      id: "fixed",
+      size: [1, 1, 1],
+      sizeMode: "fixed",
+      layout: { algorithm: "row", gap: 1, padding: 1 },
+      children: [{ id: "a", geometry: "box" }, { id: "b", geometry: "box" }]
+    }]
+  });
+  assert.equal(model.diagnostics[0].code, "FIXED_LAYOUT_OVERFLOW");
+  assert.equal(model.entities.length, 3);
+  assert.equal(ids(model).get("fixed").layoutError, "overflow");
+});
+
+test("graph layout is reported as a recoverable fallback", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "a", geometry: "box" }, { id: "b", geometry: "box" }],
+    layout: { algorithm: "graph" },
+    relations: [{ from: "a", to: "b" }]
+  });
+  assert.equal(model.diagnostics[0].code, "GRAPH_LAYOUT_FALLBACK");
+});
+
+test("compiles an Atlas YAML document at build time", () => {
+  const model = compileAtlasYaml(`
+version: 1
+render:
+  palette:
+    top: "#00f"
+entities:
+  - id: root
+    layout:
+      algorithm: row
+      direction: x
+    children:
+      - id: child
+        geometry: sphere
+        style:
+          color: top
+relations: []
+`);
+  const child = ids(model).get("child");
+  assert.deepEqual(child.s, [2.2, 2.2, 2.2]);
+  assert.equal(child.c, "top");
+});
+
+test("extracts a full Atlas block or split model/layout/render/relations blocks from Markdown", () => {
+  const full = parseAtlasMarkdown("# Demo\n\n```atlas\nentities:\n  - id: a\n    geometry: box\n```\n");
+  assert.equal(full.entities[0].id, "a");
+
+  const markdown = [
+    "# Layered model",
+    "",
+    "```atlas-model",
+    "entities:",
+    "  - id: a",
+    "    geometry: box",
+    "```",
+    "",
+    "```atlas-layout",
+    "algorithm: row",
+    "direction: x",
+    "```",
+    "",
+    "```atlas-render",
+    "palette:",
+    "  default_color: \"#abc\"",
+    "```",
+    "",
+    "```atlas-relations",
+    "- from: a",
+    "  to: missing",
+    "  mode: broken",
+    "```",
+    ""
+  ].join("\n");
+  const model = compileAtlasMarkdown(markdown);
+  assert.equal(model.entities.length, 1);
+  assert.deepEqual(model.entities[0].p, [0, 0, 0]);
+  assert.equal(model.palette.default_color, "#abc");
+  assert.equal(model.relations.length, 0);
+  assert.equal(model.diagnostics[0].code, "UNKNOWN_RELATION_ENDPOINT");
+});
+
+test("parses and compiles multiple named Atlas models in one Markdown document", () => {
+  const markdown = [
+    "# Two diagrams",
+    "",
+    "```atlas overview",
+    "entities:",
+    "  - id: source",
+    "    geometry: sphere",
+    "```",
+    "",
+    "Some explanatory text.",
+    "",
+    "```atlas process",
+    "entities:",
+    "  - id: rules",
+    "    geometry: prism",
+    "```",
+    ""
+  ].join("\n");
+
+  const parsed = parseAtlasMarkdownDocument(markdown);
+  assert.deepEqual(Object.keys(parsed.models), ["overview", "process"]);
+  assert.equal(parsed.defaultModel, "overview");
+  assert.equal(parsed.models.process.entities[0].id, "rules");
+
+  const compiled = compileAtlasMarkdownDocument(markdown);
+  assert.deepEqual(Object.keys(compiled.models), ["overview", "process"]);
+  assert.equal(compiled.models.overview.entities[0].s[0], 2.2);
+  assert.throws(() => parseAtlasMarkdown(markdown), /multiple models/);
+  assert.throws(() => compileAtlasMarkdown(markdown), /multiple models/);
+});
+
+test("associates named split Markdown blocks with the same model", () => {
+  const markdown = [
+    "```atlas-model overview",
+    "entities:",
+    "  - id: a",
+    "    geometry: box",
+    "  - id: b",
+    "    geometry: sphere",
+    "```",
+    "",
+    "```atlas-relations overview",
+    "- from: a",
+    "  to: b",
+    "  mode: bidirectional",
+    "```",
+    "",
+    "```atlas-model details",
+    "entities:",
+    "  - id: c",
+    "    geometry: cone",
+    "```",
+    ""
+  ].join("\n");
+  const document = compileAtlasMarkdownDocument(markdown, { defaultModel: "details" });
+  assert.equal(document.defaultModel, "details");
+  assert.equal(document.models.overview.relations[0].mode, "bidirectional");
+  assert.equal(document.models.details.entities[0].id, "c");
+});
+
+test("uses canonical sizes supplied by external geometry catalogs", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "server", geometry: "infra.server" }]
+  }, {
+    geometryCatalog: [{ id: "infra.server", aliases: ["server-rack"], canonicalSize: [3, 2, 4] }]
+  });
+  assert.deepEqual(model.entities[0].s, [3, 2, 4]);
+});
+
+test("preserves named geometry anchors on relations", () => {
+  const model = compileAtlasModel({
+    entities: [{ id: "a" }, { id: "b" }],
+    relations: [{ from: "a", to: "b", fromAnchor: "network", to_anchor: "input" }]
+  });
+  assert.equal(model.relations[0].fromAnchor, "network");
+  assert.equal(model.relations[0].toAnchor, "input");
+});
+
+test("Vite plugin turns an Atlas YAML import into a JS module", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "atlas-layout-vite-"));
+  const sourcePath = join(directory, "model.atlas.yaml");
+  await writeFile(sourcePath, "entities:\n  - id: source\n    geometry: sphere\n", "utf8");
+  const plugin = atlasLayout();
+  const resolved = plugin.resolveId("./model.atlas.yaml", join(directory, "main.js"));
+  const warnings = [];
+  const code = await plugin.load.call({ warn: message => warnings.push(message) }, resolved);
+  assert.match(code, /export default/);
+  assert.match(code, /source/);
+  assert.equal(warnings.length, 0);
+  assert.equal((await readFile(sourcePath, "utf8")).includes("entities:"), true);
+});
+
+test("Vite plugin exposes multiple named Markdown models as a document", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "atlas-layout-vite-multi-"));
+  const sourcePath = join(directory, "models.atlas.md");
+  await writeFile(sourcePath, [
+    "```atlas first",
+    "entities:",
+    "  - id: first",
+    "    geometry: box",
+    "```",
+    "",
+    "```atlas second",
+    "entities:",
+    "  - id: second",
+    "    geometry: sphere",
+    "```",
+    ""
+  ].join("\n"), "utf8");
+  const plugin = atlasLayout();
+  const resolved = plugin.resolveId("./models.atlas.md", join(directory, "main.js"));
+  const code = await plugin.load.call({ warn() {} }, resolved);
+  assert.match(code, /models/);
+  assert.match(code, /first/);
+  assert.match(code, /second/);
+});