@es3d/es3d 0.0.0-stage → 1.0.0

package/src/format/serializer.js

@@ -0,0 +1,333 @@
+// Serialization of the ES3D AST to text.
+//
+//   serialize(doc, { syntax: 'xml' | 'compact' | 'json', pretty, aliases, precision, comments })
+//
+// pretty   : indentation, one element per line, comments kept (default true)
+// aliases  : use the short attribute aliases (p, r, s, m, ...) (default !pretty)
+// precision: quantize numbers to this many decimals (null = keep source values)
+// normalize: re-format typed values canonically (implied by precision / !pretty)
+//
+// Without precision/normalize the original attribute strings are written
+// unchanged, so load -> save is lossless.
+
+import { elementSpec, attrSpec } from './schema.js';
+import { formatNumber, formatNumberList, formatColor, formatTransformOps, formatPathData } from './value-format.js';
+import { toJsonTree } from './json.js';
+
+const PRESETS = {
+  pretty: { pretty: true, aliases: false, precision: null, normalize: false, comments: true },
+  minified: { pretty: false, aliases: true, precision: null, normalize: true, comments: false },
+};
+
+function resolveOptions(opts = {}) {
+  const base = opts.pretty === false ? PRESETS.minified : PRESETS.pretty;
+  const o = { syntax: 'xml', indent: '  ', wrap: 100, ...base, ...opts };
+  if (o.precision !== null && o.precision !== undefined) o.normalize = true;
+  return o;
+}
+
+/** Canonical (or aliased) attribute name for output. */
+function outName(elName, canonical, opts) {
+  if (!opts.aliases) return canonical;
+  const spec = attrSpec(elName, canonical);
+  return spec && spec.alias ? spec.alias : canonical;
+}
+
+function canonicalName(el, a) {
+  if (el.attrIndex) {
+    for (const [k, v] of Object.entries(el.attrIndex)) if (v === a) return k;
+  }
+  const spec = elementSpec(el.name);
+  if (!spec) return a.name;
+  if (spec.attrs[a.name]) return a.name;
+  for (const [k, s] of Object.entries(spec.attrs)) if (s.alias === a.name) return k;
+  return a.name;
+}
+
+const allEqual = (v) => v.every((x) => x === v[0]);
+
+/** Format an attribute value, re-encoding typed values when normalizing. */
+export function formatAttrValue(el, canonical, raw, opts) {
+  if (!opts.normalize) return raw;
+  const spec = attrSpec(el.name, canonical);
+  const v = el.values ? el.values[canonical] : undefined;
+  if (!spec || v === undefined) return raw.trim();
+  const p = opts.precision;
+  const c = !opts.pretty;
+  switch (spec.type) {
+    case 'number':
+    case 'angle':
+      return formatNumber(v, p, c);
+    case 'int':
+      return String(v);
+    case 'vec2':
+    case 'vec3':
+    case 'vec4':
+    case 'numbers':
+    case 'animValue':
+      return formatNumberList(v, { sep: ',', precision: p, compact: c });
+    case 'keyframes':
+      return v.map((k) => formatNumberList(k, { sep: ',', precision: p, compact: c })).join(c ? ';' : '; ');
+    case 'size2':
+    case 'size3':
+    case 'scale3':
+      return allEqual(v) ? formatNumber(v[0], p, c) : formatNumberList(v, { sep: ',', precision: p, compact: c });
+    case 'count2':
+      return v.join(',');
+    case 'points2':
+      return formatNumberList(v, { group: 2, precision: p, compact: c });
+    case 'points3':
+      return formatNumberList(v, { group: 3, precision: p, compact: c });
+    case 'floats':
+      return formatNumberList(v, { sep: ' ', precision: p, compact: c });
+    case 'indices':
+      return Array.from(v).join(' ');
+    case 'color': {
+      const hex = formatColor(v);
+      const r = raw.trim();
+      return r.length < hex.length ? r : hex;
+    }
+    case 'ref':
+    case 'id':
+    case 'enum':
+    case 'string':
+      return String(v);
+    case 'bool':
+      return v ? 'true' : 'false';
+    case 'transform':
+      return formatTransformOps(v.ops, p, c);
+    case 'path2d':
+      return formatPathData(v.segments, { precision: p, minify: c, dim: 2 });
+    case 'spine':
+      if (v.kind === 'path') return formatPathData(v.segments, { precision: p, minify: c, dim: 3 });
+      if (v.kind === 'points') return formatNumberList(v.points, { group: 3, precision: p, compact: c });
+      return `helix(${[v.radius, v.pitch, v.turns, ...(v.segmentsPerTurn ? [v.segmentsPerTurn] : [])].map((x) => formatNumber(x, p, c)).join(',')})`;
+    case 'range': {
+      const [a, b] = v;
+      return a === b ? formatNumber(a, p, c) : `${formatNumber(a, p, c)}..${formatNumber(b, p, c)}`;
+    }
+    case 'range3': {
+      const f = ([a, b]) => (a === b ? formatNumber(a, p, c) : `${formatNumber(a, p, c)}..${formatNumber(b, p, c)}`);
+      return v.ranges.map(f).join(',');
+    }
+    case 'idlist':
+      return v.join(',');
+    case 'duration':
+      return formatNumber(v, p, c) + 's';
+    case 'repeatCount':
+      return v === Infinity ? 'indefinite' : formatNumber(v, p, c);
+    default:
+      return raw.trim();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// markup syntax
+
+function escAttr(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+}
+function escText(s) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function xmlComment(text) {
+  return `<!--${text.replace(/--/g, '- -').replace(/-$/, '- ')}-->`;
+}
+
+function attrPairs(el, opts) {
+  const out = [];
+  for (const a of el.attrs) {
+    const canonical = canonicalName(el, a);
+    out.push([outName(el.name, canonical, opts), formatAttrValue(el, canonical, a.value, opts), canonical]);
+  }
+  return out;
+}
+
+function serializeXml(doc, opts) {
+  const lines = [];
+  const ind = (d) => opts.indent.repeat(d);
+  if (opts.pretty) {
+    if (opts.comments) for (const c of doc.leading) lines.push(xmlComment(c.text));
+    const emit = (el, depth) => {
+      const pairs = attrPairs(el, opts);
+      const attrsInline = pairs.map(([k, v]) => ` ${k}="${escAttr(v)}"`).join('');
+      const kids = el.children.filter((c) => c.type === 'element' || opts.comments);
+      const hasText = el.text !== null && el.text !== undefined && el.text.trim() !== '';
+      let open = `${ind(depth)}<${el.name}${attrsInline}`;
+      if (open.length + 2 > opts.wrap && pairs.length > 1) {
+        open = `${ind(depth)}<${el.name}` + pairs.map(([k, v]) => `\n${ind(depth + 2)}${k}="${escAttr(v)}"`).join('');
+      }
+      if (!kids.length && !hasText) {
+        lines.push(open + '/>');
+        return;
+      }
+      if (hasText && !kids.length) {
+        lines.push(`${open}>${escText(el.text.trim())}</${el.name}>`);
+        return;
+      }
+      lines.push(open + '>');
+      if (hasText) lines.push(ind(depth + 1) + escText(el.text.trim()));
+      for (const c of kids) {
+        if (c.type === 'comment') lines.push(ind(depth + 1) + xmlComment(c.text));
+        else emit(c, depth + 1);
+      }
+      lines.push(`${ind(depth)}</${el.name}>`);
+    };
+    emit(doc.root, 0);
+    if (opts.comments) for (const c of doc.trailing) lines.push(xmlComment(c.text));
+    return lines.join('\n') + '\n';
+  }
+  // minified
+  let out = '';
+  const emit = (el) => {
+    out += '<' + el.name;
+    for (const [k, v] of attrPairs(el, opts)) out += ` ${k}="${escAttr(v)}"`;
+    const kids = el.children.filter((c) => c.type === 'element' || opts.comments);
+    const hasText = el.text !== null && el.text !== undefined && el.text.trim() !== '';
+    if (!kids.length && !hasText) {
+      out += '/>';
+      return;
+    }
+    out += '>';
+    if (hasText) out += escText(el.text.trim());
+    for (const c of kids) {
+      if (c.type === 'comment') out += xmlComment(c.text);
+      else emit(c);
+    }
+    out += `</${el.name}>`;
+  };
+  emit(doc.root);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// compact syntax
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_.:-]*$/;
+
+function quoteCompact(v) {
+  if (v !== '' && !/[\s{};"\\]/.test(v)) return v;
+  return '"' + v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\t/g, '\\t') + '"';
+}
+
+function compactComment(text, pretty) {
+  if (pretty && !text.includes('\n')) return '//' + (text.startsWith(' ') ? '' : ' ') + text.replace(/\s+$/, '');
+  return '/*' + text.replace(/\*\//g, '* /') + '*/';
+}
+
+function compactHeader(el, opts) {
+  let s = el.name;
+  const rest = [];
+  for (const [k, v, canonical] of attrPairs(el, opts)) {
+    if (canonical === 'id' && NAME_RE.test(v)) s += '#' + v;
+    else if (canonical === 'ref' && NAME_RE.test(v)) rest.unshift('@' + v);
+    else rest.push(`${k}=${quoteCompact(v)}`);
+  }
+  const hasText = el.text !== null && el.text !== undefined && el.text.trim() !== '';
+  if (hasText) {
+    const t = el.text.trim();
+    rest.unshift('"' + t.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\t/g, '\\t') + '"');
+  }
+  return rest.length ? s + ' ' + rest.join(' ') : s;
+}
+
+function serializeCompact(doc, opts) {
+  if (opts.pretty) {
+    const lines = [];
+    const ind = (d) => opts.indent.repeat(d);
+    if (opts.comments) for (const c of doc.leading) lines.push(compactComment(c.text, true));
+    const emitChildren = (el, depth) => {
+      for (const c of el.children) {
+        if (c.type === 'comment') {
+          if (opts.comments) lines.push(ind(depth) + compactComment(c.text, true));
+          continue;
+        }
+        const kids = c.children.filter((k) => k.type === 'element' || opts.comments);
+        const head = ind(depth) + compactHeader(c, opts);
+        if (!kids.length) lines.push(head);
+        else {
+          lines.push(head + ' {');
+          emitChildren(c, depth + 1);
+          lines.push(ind(depth) + '}');
+        }
+      }
+    };
+    lines.push(compactHeader(doc.root, opts));
+    emitChildren(doc.root, 0);
+    if (opts.comments) for (const c of doc.trailing) lines.push(compactComment(c.text, true));
+    return lines.join('\n') + '\n';
+  }
+  const parts = [];
+  const emit = (el) => {
+    let s = compactHeader(el, opts);
+    const kids = el.children.filter((k) => k.type === 'element' || opts.comments);
+    if (kids.length) {
+      const inner = [];
+      for (const c of kids) inner.push(c.type === 'comment' ? compactComment(c.text, false) : emit(c));
+      s += '{' + joinStatements(inner) + '}';
+    }
+    return s;
+  };
+  parts.push(compactHeader(doc.root, opts));
+  for (const c of doc.root.children) {
+    if (c.type === 'comment') {
+      if (opts.comments) parts.push(compactComment(c.text, false));
+    } else parts.push(emit(c));
+  }
+  return joinStatements(parts);
+}
+
+/** Join compact statements; a separator is needed only between two plain headers. */
+function joinStatements(items) {
+  let out = '';
+  for (let i = 0; i < items.length; i++) {
+    const s = items[i];
+    if (i > 0) {
+      const prev = items[i - 1];
+      if (!prev.endsWith('}') && !prev.endsWith('*/')) out += ';';
+    }
+    out += s;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a document.
+ * @param {import('./ast.js').Document} doc
+ * @param {object} [options]
+ * @returns {string}
+ */
+export function serialize(doc, options = {}) {
+  const opts = resolveOptions(options);
+  if (!doc.root) throw new Error('Cannot serialize a document without a root element.');
+  if (opts.syntax === 'compact') return serializeCompact(doc, opts);
+  if (opts.syntax === 'json') {
+    const workDoc = opts.normalize ? normalizedCopy(doc, opts) : doc;
+    const tree = toJsonTree(workDoc, { comments: opts.comments });
+    return opts.pretty ? JSON.stringify(tree, null, 1) + '\n' : JSON.stringify(tree);
+  }
+  return serializeXml(doc, opts);
+}
+
+/** Copy of the AST where attribute values are already formatted per opts. */
+function normalizedCopy(doc, opts) {
+  const clone = (el) => {
+    const pairs = attrPairs(el, opts);
+    return {
+      ...el,
+      attrs: pairs.map(([k, v]) => ({ name: k, value: v })),
+      children: el.children.map((c) => (c.type === 'element' ? clone(c) : c)),
+    };
+  };
+  return { ...doc, root: clone(doc.root) };
+}
+
+export const SERIALIZE_PRESETS = {
+  'xml-pretty': { syntax: 'xml', pretty: true },
+  'xml-min': { syntax: 'xml', pretty: false },
+  'compact-pretty': { syntax: 'compact', pretty: true },
+  'compact-min': { syntax: 'compact', pretty: false },
+  'json-min': { syntax: 'json', pretty: false },
+};

package/src/format/validator.js

@@ -0,0 +1,330 @@
+// Schema validation and reference resolution.
+//
+// Converts raw attribute strings into typed values (element.values), checks
+// element nesting, numeric ranges and cross-attribute rules, verifies every id
+// reference and detects circular <use> chains. All problems are collected (not
+// just the first) and reported with exact source positions and suggestions.
+
+import { DiagnosticList, suggest } from './errors.js';
+import { indexTree } from './ast.js';
+import { ELEMENTS, ROOT_ELEMENTS, SHAPES, CONTAINERS, aliasesFor, elementSpec, ALL_ELEMENT_NAMES } from './schema.js';
+import { parseTyped } from './values.js';
+import { ValueError } from './value-error.js';
+
+const USABLE = new Set([...SHAPES, ...CONTAINERS, 'use', 'light']);
+
+function elementPath(el) {
+  const parts = [];
+  for (let e = el; e; e = e.parent) {
+    let label = e.name;
+    if (e.parent) {
+      let index = -1, same = 0;
+      for (const c of e.parent.children) {
+        if (c.type !== 'element' || c.name !== e.name) continue;
+        if (c === e) index = same;
+        same++;
+      }
+      if (same > 1) label += `[${index}]`;
+    }
+    const id = e.attr && e.attr('id');
+    if (id) label += `#${id}`;
+    parts.unshift(label);
+  }
+  return parts.join(' > ');
+}
+
+function describeNumber(spec) {
+  const parts = [];
+  if (spec.exclusiveMin !== undefined) parts.push(`greater than ${spec.exclusiveMin}`);
+  else if (spec.min !== undefined) parts.push(`at least ${spec.min}`);
+  if (spec.max !== undefined) parts.push(`at most ${spec.max}`);
+  return parts.join(' and ');
+}
+
+function checkNumeric(spec, value) {
+  if (typeof value !== 'number') return null;
+  if (spec.exclusiveMin !== undefined && !(value > spec.exclusiveMin)) return describeNumber(spec);
+  if (spec.min !== undefined && value < spec.min) return describeNumber(spec);
+  if (spec.max !== undefined && value > spec.max) return describeNumber(spec);
+  return null;
+}
+
+/**
+ * Validate a parsed document in place.
+ * Sets el.values / el.attrIndex, doc.ids and doc.diagnostics.
+ * @returns {import('./ast.js').Document}
+ */
+const REQUIRED = new WeakMap();
+
+/** Names of an element's required attributes, in schema order (computed once per element type). */
+function requiredAttrs(spec) {
+  let list = REQUIRED.get(spec);
+  if (!list) {
+    list = Object.entries(spec.attrs).filter(([, a]) => a.required).map(([name]) => name);
+    REQUIRED.set(spec, list);
+  }
+  return list;
+}
+
+export function validate(doc) {
+  const diags = new DiagnosticList(doc.lineIndex);
+  indexTree(doc);
+  doc.ids = new Map();
+  const refs = []; // {el, attr, id, kind, list?}
+
+  const locEl = (el) => (el.nameStart >= 0 ? { offset: el.nameStart, length: el.nameEnd - el.nameStart } : { offset: -1, length: 0, path: elementPath(el) });
+  const locAttrName = (el, a) => (a && a.nameStart >= 0 ? { offset: a.nameStart, length: a.nameEnd - a.nameStart } : locEl(el));
+  const locAttrValue = (el, a, e) => {
+    if (!a || a.valueStart < 0) return locEl(el);
+    if (e && !a.decoded && e.offset !== undefined) {
+      const off = Math.min(a.valueStart + e.offset, a.valueEnd);
+      const len = Math.max(1, Math.min(e.length || 1, a.valueEnd - off));
+      return { offset: off, length: len };
+    }
+    return { offset: a.valueStart, length: Math.max(1, a.valueEnd - a.valueStart) };
+  };
+  const report = (severity, code, message, loc, extra = {}, el = null) => {
+    diags.add({ severity, code, message, offset: loc.offset, length: loc.length, path: loc.path || (loc.offset < 0 && el ? elementPath(el) : null), uid: el ? el.uid : 0, ...extra });
+  };
+
+  const root = doc.root;
+  if (!ROOT_ELEMENTS.includes(root.name)) {
+    report('error', 'E_ROOT', `The root element must be <es3d> but found <${root.name}>.`, locEl(root), { suggestion: 'es3d' }, root);
+    doc.diagnostics = diags.sorted();
+    return doc;
+  }
+  if (root.name === 'v3d') {
+    report('warning', 'W_LEGACY_ROOT', 'The root element <v3d> is a legacy alias; write <es3d>.', locEl(root), {}, root);
+  }
+
+  let sceneCount = 0;
+  let envCount = 0;
+  let controlsCount = 0;
+
+  const visit = (el, parentSpec, inDefs) => {
+    const spec = elementSpec(el.name);
+    if (!spec) {
+      if (el.name.startsWith('x-')) {
+        report('warning', 'W_EXTENSION', `Extension element <${el.name}> is not supported by this reader; it and its children are not rendered.`, locEl(el), {}, el);
+      } else {
+        report('error', 'E_UNKNOWN_ELEMENT', `Unknown element: ${el.name}`, locEl(el), { suggestion: suggest(el.name, ALL_ELEMENT_NAMES.concat(['es3d'])) }, el);
+      }
+      el.values = {};
+      el.attrIndex = {};
+      el.unknown = true;
+      return;
+    }
+    el.unknown = false;
+    if (el.name === 'scene' && ++sceneCount > 1) report('error', 'E_MULTIPLE_SCENES', 'Only one <scene> element is allowed.', locEl(el), {}, el);
+    if (el.name === 'environment' && ++envCount > 1) {
+      report('warning', 'W_MULTIPLE_ENVIRONMENTS', 'More than one <environment>: only the first one is used.', locEl(el), {}, el);
+    }
+    if (el.name === 'controls' && ++controlsCount > 1) {
+      report('warning', 'W_MULTIPLE_CONTROLS', 'More than one <controls>: only the first one is used.', locEl(el), {}, el);
+    }
+
+    // attributes
+    const aliases = aliasesFor(el.name);
+    const values = {};
+    const attrIndex = {};
+    for (const a of el.attrs) {
+      const canonical = aliases.get(a.name);
+      if (!canonical) {
+        if (a.name === 'xmlns' || a.name.startsWith('xmlns:')) continue;
+        const candidates = [...aliases.keys()];
+        const sug = suggest(a.name, candidates);
+        let hint = null;
+        if (!sug) {
+          const own = Object.keys(spec.attrs).filter((k) => !['id', 'name', 'transform', 'position', 'rotation', 'scale', 'visible', 'material', 'color'].includes(k));
+          if (own.length) hint = `<${el.name}> accepts: ${own.join(', ')} (plus id, name, transform, position, rotation, scale, material, color).`;
+        }
+        report('error', 'E_UNKNOWN_ATTRIBUTE', `Unknown attribute: ${a.name}`, locAttrName(el, a), { suggestion: sug, hint }, el);
+        continue;
+      }
+      if (attrIndex[canonical]) {
+        report('error', 'E_DUPLICATE_ATTRIBUTE', `Attribute '${canonical}' is given twice (as '${attrIndex[canonical].name}' and '${a.name}').`, locAttrName(el, a), {}, el);
+        continue;
+      }
+      attrIndex[canonical] = a;
+      const aspec = spec.attrs[canonical];
+      let value;
+      try {
+        value = a.typed !== undefined ? a.typed : parseTyped(aspec, a.value);
+      } catch (e) {
+        if (!(e instanceof ValueError)) throw e;
+        report('error', e.code || 'E_INVALID_VALUE', `Invalid value for '${a.name}': ${e.message}`, locAttrValue(el, a, e), { suggestion: e.suggestion, hint: e.hint }, el);
+        continue;
+      }
+      const bad = checkNumeric(aspec, value);
+      if (bad) {
+        report('error', 'E_RANGE', `'${a.name}' must be ${bad}; found ${value}.`, locAttrValue(el, a), {}, el);
+        continue;
+      }
+      values[canonical] = value;
+      if (aspec.type === 'id' && canonical === 'id') {
+        const prev = doc.ids.get(value);
+        if (prev) {
+          let where = '';
+          if (prev.nameStart >= 0 && doc.lineIndex) {
+            const p = doc.lineIndex.position(prev.nameStart);
+            where = ` (first defined at line ${p.line})`;
+          }
+          report('error', 'E_DUPLICATE_ID', `Duplicate id '${value}'${where}.`, locAttrValue(el, a), {}, el);
+        } else {
+          doc.ids.set(value, el);
+        }
+      }
+      if (aspec.type === 'ref') refs.push({ el, attr: a, canonical, id: value, kind: aspec.ref });
+      if (aspec.type === 'idlist' && aspec.ref) for (const id of value) refs.push({ el, attr: a, canonical, id, kind: aspec.ref });
+    }
+    el.values = values;
+    el.attrIndex = attrIndex;
+
+    for (const name of requiredAttrs(spec)) {
+      if (values[name] === undefined && !attrIndex[name]) {
+        report('error', 'E_MISSING_ATTRIBUTE', `<${el.name}> requires the attribute '${name}'.`, locEl(el), { hint: spec.attrs[name].desc }, el);
+      }
+    }
+    if (spec.check) {
+      // attributes that are present but failed to parse count as given, so
+      // cross-attribute rules do not cascade into "missing attribute" errors
+      const given = (k) => values[k] !== undefined || !!attrIndex[k];
+      spec.check(values, (attrName, message, code = 'E_INVALID_VALUE') => {
+        const a = attrName ? attrIndex[attrName] : null;
+        report('error', code, message, a ? locAttrValue(el, a) : locEl(el), {}, el);
+      }, el, given);
+    }
+
+    // text content
+    if (el.text !== null && el.text.trim() !== '' && spec.children !== 'text') {
+      const loc = el.textStart >= 0 ? { offset: el.textStart, length: Math.max(1, Math.min(20, el.textEnd - el.textStart)) } : locEl(el);
+      report('error', 'E_TEXT_NOT_ALLOWED', `Text content is not allowed inside <${el.name}>.`, loc, {}, el);
+    }
+
+    if (inDefs && el.parent && el.parent.name === 'defs' && values.id === undefined && !attrIndex.id) {
+      report('warning', 'W_DEF_WITHOUT_ID', `<${el.name}> inside <defs> has no id, so it can never be used.`, locEl(el), {}, el);
+    }
+    if (el.name === 'material' && values.id === undefined && !attrIndex.id) {
+      report('warning', 'W_MATERIAL_WITHOUT_ID', '<material> without an id can never be referenced.', locEl(el), {}, el);
+    }
+
+    // children
+    const allowed = spec.children;
+    for (const c of el.children) {
+      if (c.type !== 'element') continue;
+      if (allowed === 'text' || !Array.isArray(allowed) || !allowed.includes(c.name)) {
+        const childSpec = elementSpec(c.name);
+        if (childSpec || !c.name.startsWith('x-')) {
+          if (childSpec) {
+            let hint = null;
+            if (c.name === 'animate') hint = '<animate> can only be placed inside an element with a transform (shapes, group, use, repeat, scatter, lod, light, camera).';
+            else if (c.name === 'scene' || c.name === 'defs') hint = `<${c.name}> is only allowed directly inside <es3d>.`;
+            else if (c.name === 'controls') hint = '<controls> is only allowed directly inside <es3d> or <scene>.';
+            else if (spec.category === 'shape') hint = 'Shapes cannot contain other shapes; wrap them in a <group>.';
+            report('error', 'E_MISPLACED_ELEMENT', `<${c.name}> is not allowed inside <${el.name}>.`, locEl(c), { hint }, c);
+          }
+        }
+      }
+      visit(c, spec, inDefs || el.name === 'defs');
+    }
+  };
+  visit(root, null, false);
+
+  // references ---------------------------------------------------------------
+  const kindLabel = { material: 'material', path: 'path', node: 'element' };
+  for (const r of refs) {
+    const target = doc.ids.get(r.id);
+    // computed only when reporting: element paths are expensive for large binary documents
+    const where = () => (r.attr.valueStart >= 0 ? { offset: r.attr.valueStart, length: Math.max(1, r.attr.valueEnd - r.attr.valueStart) } : locEl(r.el));
+    if (!target) {
+      const loc = where();
+      const candidates = [...doc.ids.entries()]
+        .filter(([, t]) => (r.kind === 'material' ? t.name === 'material' : r.kind === 'path' ? t.name === 'path' : USABLE.has(t.name)))
+        .map(([id]) => id);
+      diags.add({
+        phase: 'reference',
+        code: 'E_UNKNOWN_REFERENCE',
+        message: `Unknown ${kindLabel[r.kind]} '${r.id}' referenced by ${r.attr.name}.`,
+        offset: loc.offset,
+        length: loc.length,
+        path: loc.path || null,
+        suggestion: suggest(r.id, candidates),
+        uid: r.el.uid,
+      });
+      continue;
+    }
+    let ok = true;
+    if (r.kind === 'material') ok = target.name === 'material';
+    else if (r.kind === 'path') ok = target.name === 'path';
+    else if (r.kind === 'node') ok = USABLE.has(target.name);
+    if (!ok) {
+      const loc = where();
+      diags.add({
+        phase: 'reference',
+        code: 'E_REFERENCE_KIND',
+        message: `${r.attr.name}="${r.id}" refers to a <${target.name}>, but a ${r.kind === 'node' ? 'shape, group, use, repeat, scatter, lod or light' : `<${r.kind}>`} is required.`,
+        offset: loc.offset,
+        length: loc.length,
+        path: loc.path || null,
+        uid: r.el.uid,
+      });
+      continue;
+    }
+    if (r.canonical === 'ref') r.el.target = target;
+    if (r.kind === 'path') r.el.pathTarget = target;
+  }
+
+  // circular <use> chains ------------------------------------------------------
+  const usesInside = new Map();
+  const collectUses = (el) => {
+    if (usesInside.has(el)) return usesInside.get(el);
+    const list = [];
+    const stack = [el];
+    while (stack.length) {
+      const e = stack.pop();
+      if (e.name === 'use' && e.target) list.push(e);
+      for (const c of e.children) if (c.type === 'element') stack.push(c);
+    }
+    usesInside.set(el, list);
+    return list;
+  };
+  const state = new Map(); // target -> 1 visiting, 2 done
+  const reported = new Set();
+  const dfs = (target, chain) => {
+    state.set(target, 1);
+    for (const u of collectUses(target)) {
+      const t = u.target;
+      const st = state.get(t);
+      if (st === 1) {
+        if (!reported.has(u)) {
+          reported.add(u);
+          const ids = [...chain.map((x) => x.values.id || x.name), t.values.id || t.name];
+          const a = u.attrIndex.ref;
+          diags.add({
+            phase: 'reference',
+            code: 'E_CIRCULAR_REFERENCE',
+            message: `Circular reference: ${ids.join(' → ')}.`,
+            offset: a && a.valueStart >= 0 ? a.valueStart : u.nameStart,
+            length: a && a.valueStart >= 0 ? a.valueEnd - a.valueStart : u.nameEnd - u.nameStart,
+            path: u.nameStart < 0 ? elementPath(u) : null,
+            hint: 'An element cannot (directly or indirectly) contain a <use> of itself.',
+            uid: u.uid,
+          });
+        }
+        u.circular = true;
+      } else if (!st) {
+        dfs(t, [...chain, t]);
+      }
+    }
+    state.set(target, 2);
+  };
+  for (const target of new Set([...doc.ids.values()])) {
+    if (!state.has(target)) dfs(target, [target]);
+  }
+  // uses outside any referenced subtree (e.g. in the scene) that point into a cycle are covered above.
+
+  doc.diagnostics = diags.sorted();
+  return doc;
+}
+
+export { elementPath, ELEMENTS };

package/src/format/value-error.js

@@ -0,0 +1,12 @@
+/** Error raised by attribute value parsers; offsets are relative to the attribute value. */
+export class ValueError extends Error {
+  constructor(message, offset = 0, length = 0, extra = {}) {
+    super(message);
+    this.name = 'ValueError';
+    this.offset = offset;
+    this.length = length;
+    this.hint = extra.hint || null;
+    this.suggestion = extra.suggestion || null;
+    this.code = extra.code || null;
+  }
+}