@es3d/es3d 0.0.0-stage → 1.0.1

package/src/format/ast.js

@@ -0,0 +1,238 @@
+// The ES3D abstract syntax tree.
+//
+// Every surface syntax (markup, compact, JSON, binary) produces the same tree of
+// Element / Comment nodes. Attribute values stay as raw strings in the AST so a
+// document can be round-tripped losslessly; typed values are attached by the
+// validator in `element.values` (keyed by canonical attribute name).
+
+export class Attr {
+  constructor(name, value, nameStart = -1, nameEnd = -1, valueStart = -1, valueEnd = -1, quote = '"') {
+    this.name = name;
+    this.value = value;
+    this.nameStart = nameStart;
+    this.nameEnd = nameEnd;
+    this.valueStart = valueStart;
+    this.valueEnd = valueEnd;
+    this.quote = quote;
+    /** true when the raw value contained entity references (offsets inside the value are approximate) */
+    this.decoded = false;
+    /** pre-parsed typed value supplied by a decoder (the validator then skips parsing the text) */
+    this.typed = undefined;
+  }
+}
+
+/**
+ * Attribute whose typed value is known and whose text is produced on demand
+ * (binary decoding of large arrays: formatting a mesh as text only to parse
+ * it again would dominate the load time). Assigning a new text value drops
+ * the typed value.
+ */
+export class LazyAttr extends Attr {
+  constructor(name, typed, format) {
+    super(name, null);
+    this.typed = typed;
+    this.format = format;
+  }
+
+  get value() {
+    if (this._value === null) this._value = this.format();
+    return this._value;
+  }
+
+  set value(v) {
+    this._value = v;
+    if (v !== null) this.typed = undefined;
+  }
+}
+
+export class Comment {
+  constructor(text, start = -1, end = -1) {
+    this.type = 'comment';
+    this.text = text;
+    this.start = start;
+    this.end = end;
+    this.parent = null;
+  }
+}
+
+export class Element {
+  constructor(name, start = -1) {
+    this.type = 'element';
+    this.name = name;
+    /** @type {Attr[]} */
+    this.attrs = [];
+    /** @type {(Element|Comment)[]} */
+    this.children = [];
+    this.text = null;
+    this.textStart = -1;
+    this.textEnd = -1;
+    this.start = start;
+    this.end = start;
+    this.nameStart = start;
+    this.nameEnd = start;
+    this.openEnd = start;
+    this.closeStart = -1;
+    this.selfClosing = true;
+    this.uid = 0;
+    this.parent = null;
+    /** canonical name -> typed value (set by the validator) */
+    this.values = null;
+    /** canonical name -> Attr (set by the validator) */
+    this.attrIndex = null;
+  }
+
+  attr(name) {
+    for (let i = 0; i < this.attrs.length; i++) if (this.attrs[i].name === name) return this.attrs[i].value;
+    return undefined;
+  }
+
+  attrNode(name) {
+    for (let i = 0; i < this.attrs.length; i++) if (this.attrs[i].name === name) return this.attrs[i];
+    return null;
+  }
+
+  setAttr(name, value) {
+    const a = this.attrNode(name);
+    if (a) a.value = String(value);
+    else this.attrs.push(new Attr(name, String(value)));
+    return this;
+  }
+
+  removeAttr(name) {
+    const i = this.attrs.findIndex((a) => a.name === name);
+    if (i >= 0) this.attrs.splice(i, 1);
+    return this;
+  }
+
+  appendChild(node) {
+    node.parent = this;
+    this.children.push(node);
+    this.selfClosing = false;
+    return node;
+  }
+
+  get elementChildren() {
+    return this.children.filter((c) => c.type === 'element');
+  }
+
+  /** The canonical id of this element, if any. */
+  get id() {
+    return this.values && this.values.id !== undefined ? this.values.id : this.attr('id');
+  }
+}
+
+export class Document {
+  constructor({ root, syntax, source = null, leading = [], trailing = [] }) {
+    /** @type {Element} */
+    this.root = root;
+    /** 'xml' | 'compact' | 'json' | 'binary' */
+    this.syntax = syntax;
+    this.source = source;
+    /** comments before / after the root element */
+    this.leading = leading;
+    this.trailing = trailing;
+    this.lineIndex = null;
+    this.diagnostics = [];
+    /** id -> Element (set by the validator) */
+    this.ids = new Map();
+    /** uid -> Element */
+    this.byUid = new Map();
+    this.elementCount = 0;
+  }
+
+  get errors() {
+    return this.diagnostics.filter((d) => d.severity === 'error');
+  }
+
+  get warnings() {
+    return this.diagnostics.filter((d) => d.severity === 'warning');
+  }
+
+  get ok() {
+    return !this.diagnostics.some((d) => d.severity === 'error');
+  }
+}
+
+/** Depth-first pre-order traversal of elements. Return false from fn to skip children. */
+export function walk(el, fn, parent = null, depth = 0) {
+  if (fn(el, parent, depth) === false) return;
+  const kids = el.children;
+  for (let i = 0; i < kids.length; i++) {
+    const c = kids[i];
+    if (c.type === 'element') walk(c, fn, el, depth + 1);
+  }
+}
+
+/** Assign sequential uids and parent links; returns the number of elements. */
+export function indexTree(doc) {
+  let uid = 0;
+  doc.byUid.clear();
+  const visit = (el, parent) => {
+    el.uid = ++uid;
+    el.parent = parent;
+    doc.byUid.set(el.uid, el);
+    for (const c of el.children) {
+      if (c.type === 'element') visit(c, el);
+      else c.parent = el;
+    }
+  };
+  if (doc.root) visit(doc.root, null);
+  doc.elementCount = uid;
+  return uid;
+}
+
+/** Deep copy of an element subtree without source positions or typed values. */
+export function cloneElement(el, keepPositions = false) {
+  const copy = new Element(el.name, keepPositions ? el.start : -1);
+  for (const a of el.attrs) {
+    copy.attrs.push(keepPositions ? Object.assign(new Attr(a.name, a.value), a) : new Attr(a.name, a.value));
+  }
+  copy.text = el.text;
+  copy.selfClosing = el.selfClosing;
+  for (const c of el.children) {
+    if (c.type === 'element') copy.appendChild(cloneElement(c, keepPositions));
+    else copy.appendChild(new Comment(c.text));
+  }
+  copy.selfClosing = el.children.length === 0;
+  return copy;
+}
+
+/** Convenience constructor: h('box', {size: '2'}, ...children) */
+export function h(name, attrs = {}, ...children) {
+  const el = new Element(name);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null) continue;
+    el.attrs.push(new Attr(k, String(v)));
+  }
+  for (const c of children.flat()) {
+    if (c === null || c === undefined || c === false) continue;
+    if (typeof c === 'string') el.text = (el.text || '') + c;
+    else el.appendChild(c);
+  }
+  el.selfClosing = el.children.length === 0 && el.text === null;
+  return el;
+}
+
+/** Structural equality of two subtrees (names, attributes, text, element children). */
+export function treesEqual(a, b, { ignoreComments = true, attrOrder = false } = {}) {
+  if (a.name !== b.name) return false;
+  if ((a.text || '').trim() !== (b.text || '').trim()) return false;
+  if (a.attrs.length !== b.attrs.length) return false;
+  if (attrOrder) {
+    for (let i = 0; i < a.attrs.length; i++) {
+      if (a.attrs[i].name !== b.attrs[i].name || a.attrs[i].value !== b.attrs[i].value) return false;
+    }
+  } else {
+    for (const at of a.attrs) if (b.attr(at.name) !== at.value) return false;
+  }
+  const ka = ignoreComments ? a.children.filter((c) => c.type === 'element') : a.children;
+  const kb = ignoreComments ? b.children.filter((c) => c.type === 'element') : b.children;
+  if (ka.length !== kb.length) return false;
+  for (let i = 0; i < ka.length; i++) {
+    if (ka[i].type !== kb[i].type) return false;
+    if (ka[i].type === 'comment') {
+      if (ka[i].text !== kb[i].text) return false;
+    } else if (!treesEqual(ka[i], kb[i], { ignoreComments, attrOrder })) return false;
+  }
+  return true;
+}

package/src/format/colors.js

@@ -0,0 +1,93 @@
+// Color parsing. ES3D colors are sRGB like CSS/SVG: #rgb, #rgba, #rrggbb,
+// #rrggbbaa, rgb(r,g,b), rgba(r,g,b,a) and the 148 CSS named colors.
+// Values are returned as [r, g, b, a] in 0..1 (sRGB, not linearized).
+
+const NAMED =
+  'aliceblue:f0f8ff,antiquewhite:faebd7,aqua:00ffff,aquamarine:7fffd4,azure:f0ffff,beige:f5f5dc,bisque:ffe4c4,' +
+  'black:000000,blanchedalmond:ffebcd,blue:0000ff,blueviolet:8a2be2,brown:a52a2a,burlywood:deb887,cadetblue:5f9ea0,' +
+  'chartreuse:7fff00,chocolate:d2691e,coral:ff7f50,cornflowerblue:6495ed,cornsilk:fff8dc,crimson:dc143c,cyan:00ffff,' +
+  'darkblue:00008b,darkcyan:008b8b,darkgoldenrod:b8860b,darkgray:a9a9a9,darkgreen:006400,darkgrey:a9a9a9,' +
+  'darkkhaki:bdb76b,darkmagenta:8b008b,darkolivegreen:556b2f,darkorange:ff8c00,darkorchid:9932cc,darkred:8b0000,' +
+  'darksalmon:e9967a,darkseagreen:8fbc8f,darkslateblue:483d8b,darkslategray:2f4f4f,darkslategrey:2f4f4f,' +
+  'darkturquoise:00ced1,darkviolet:9400d3,deeppink:ff1493,deepskyblue:00bfff,dimgray:696969,dimgrey:696969,' +
+  'dodgerblue:1e90ff,firebrick:b22222,floralwhite:fffaf0,forestgreen:228b22,fuchsia:ff00ff,gainsboro:dcdcdc,' +
+  'ghostwhite:f8f8ff,gold:ffd700,goldenrod:daa520,gray:808080,green:008000,greenyellow:adff2f,grey:808080,' +
+  'honeydew:f0fff0,hotpink:ff69b4,indianred:cd5c5c,indigo:4b0082,ivory:fffff0,khaki:f0e68c,lavender:e6e6fa,' +
+  'lavenderblush:fff0f5,lawngreen:7cfc00,lemonchiffon:fffacd,lightblue:add8e6,lightcoral:f08080,lightcyan:e0ffff,' +
+  'lightgoldenrodyellow:fafad2,lightgray:d3d3d3,lightgreen:90ee90,lightgrey:d3d3d3,lightpink:ffb6c1,' +
+  'lightsalmon:ffa07a,lightseagreen:20b2aa,lightskyblue:87cefa,lightslategray:778899,lightslategrey:778899,' +
+  'lightsteelblue:b0c4de,lightyellow:ffffe0,lime:00ff00,limegreen:32cd32,linen:faf0e6,magenta:ff00ff,maroon:800000,' +
+  'mediumaquamarine:66cdaa,mediumblue:0000cd,mediumorchid:ba55d3,mediumpurple:9370db,mediumseagreen:3cb371,' +
+  'mediumslateblue:7b68ee,mediumspringgreen:00fa9a,mediumturquoise:48d1cc,mediumvioletred:c71585,' +
+  'midnightblue:191970,mintcream:f5fffa,mistyrose:ffe4e1,moccasin:ffe4b5,navajowhite:ffdead,navy:000080,' +
+  'oldlace:fdf5e6,olive:808000,olivedrab:6b8e23,orange:ffa500,orangered:ff4500,orchid:da70d6,palegoldenrod:eee8aa,' +
+  'palegreen:98fb98,paleturquoise:afeeee,palevioletred:db7093,papayawhip:ffefd5,peachpuff:ffdab9,peru:cd853f,' +
+  'pink:ffc0cb,plum:dda0dd,powderblue:b0e0e6,purple:800080,rebeccapurple:663399,red:ff0000,rosybrown:bc8f8f,' +
+  'royalblue:4169e1,saddlebrown:8b4513,salmon:fa8072,sandybrown:f4a460,seagreen:2e8b57,seashell:fff5ee,' +
+  'sienna:a0522d,silver:c0c0c0,skyblue:87ceeb,slateblue:6a5acd,slategray:708090,slategrey:708090,snow:fffafa,' +
+  'springgreen:00ff7f,steelblue:4682b4,tan:d2b48c,teal:008080,thistle:d8bfd8,tomato:ff6347,turquoise:40e0d0,' +
+  'violet:ee82ee,wheat:f5deb3,white:ffffff,whitesmoke:f5f5f5,yellow:ffff00,yellowgreen:9acd32';
+
+export const NAMED_COLORS = new Map(NAMED.split(',').map((kv) => kv.split(':')));
+
+const HEX = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+/** Parse a color; returns [r,g,b,a] (0..1 sRGB) or null when the syntax is invalid. */
+export function parseColor(str) {
+  const s = str.trim();
+  if (s[0] === '#') {
+    if (!HEX.test(s)) return null;
+    let h = s.slice(1);
+    if (h.length <= 4) h = [...h].map((c) => c + c).join('');
+    const n = h.length === 6 ? h + 'ff' : h;
+    return [0, 2, 4, 6].map((i) => parseInt(n.slice(i, i + 2), 16) / 255);
+  }
+  const lower = s.toLowerCase();
+  if (lower === 'transparent') return [0, 0, 0, 0];
+  const named = NAMED_COLORS.get(lower);
+  if (named) return parseColor('#' + named);
+  const m = /^rgba?\(\s*([^)]*)\)$/i.exec(s);
+  if (m) {
+    const parts = m[1].split(/\s*,\s*|\s+/).filter(Boolean);
+    if (parts.length !== 3 && parts.length !== 4) return null;
+    const out = [];
+    for (let i = 0; i < parts.length; i++) {
+      const p = parts[i];
+      let v;
+      if (p.endsWith('%')) v = Number(p.slice(0, -1)) / 100;
+      else v = i < 3 ? Number(p) / 255 : Number(p);
+      if (!Number.isFinite(v) || v < 0 || v > 1) return null;
+      out.push(v);
+    }
+    if (out.length === 3) out.push(1);
+    return out;
+  }
+  return null;
+}
+
+export function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+export function linearToSrgb(c) {
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+/** [r,g,b,a] sRGB -> [r,g,b,a] linear (alpha untouched). */
+export function colorToLinear(c) {
+  return [srgbToLinear(c[0]), srgbToLinear(c[1]), srgbToLinear(c[2]), c[3]];
+}
+
+/** Canonical lowercase hex form (#rrggbb or #rrggbbaa). */
+export function colorToHex(c) {
+  const h = (v) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, '0');
+  const base = '#' + h(c[0]) + h(c[1]) + h(c[2]);
+  return c[3] !== undefined && c[3] < 1 ? base + h(c[3]) : base;
+}
+
+/** Shortest hex form (#rgb when possible). */
+export function colorToShortHex(c) {
+  const hex = colorToHex(c);
+  if (hex.length === 7 && hex[1] === hex[2] && hex[3] === hex[4] && hex[5] === hex[6]) return '#' + hex[1] + hex[3] + hex[5];
+  return hex;
+}

package/src/format/compact-parser.js

@@ -0,0 +1,171 @@
+// Parser for the ES3D compact syntax: tokens -> the same AST as the markup syntax.
+//
+// Grammar (newlines are whitespace):
+//   document  := comment* root
+//   root      := 'es3d' header ( '{' statement* '}' | statement* )
+//   statement := element | comment | ';'
+//   element   := NAME header ( '{' statement* '}' )?
+//   header    := ('#' ID)? ('@' REF)? STRING? (NAME '=' VALUE)*
+
+import { Attr, Comment, Document, Element } from './ast.js';
+import { Diagnostic, ES3DError, LineIndex } from './errors.js';
+import { CTok, CompactTokenizer } from './compact-tokenizer.js';
+
+const ROOT_NAMES = new Set(['es3d', 'v3d']);
+
+export function parseCompact(text, lineIndex = new LineIndex(text)) {
+  const tz = new CompactTokenizer(text, lineIndex);
+  const buf = [];
+  const peek = (k = 0) => {
+    while (buf.length <= k) buf.push(tz.next());
+    return buf[k];
+  };
+  const take = () => (buf.length ? buf.shift() : tz.next());
+  const fail = (code, message, offset, length = 1, extra = {}) => {
+    const d = new Diagnostic({ code, message, offset, length, ...extra });
+    d.locate(lineIndex);
+    throw new ES3DError([d], lineIndex);
+  };
+  const where = (offset) => {
+    const p = lineIndex.position(offset);
+    return `line ${p.line}, column ${p.column}`;
+  };
+
+  function parseHeader(el) {
+    let last = el.nameEnd;
+    for (;;) {
+      const t = peek();
+      if (t.type === CTok.ID || t.type === CTok.REF) {
+        take();
+        const name = t.type === CTok.ID ? 'id' : 'ref';
+        if (el.attrNode(name)) fail('E_DUPLICATE_ATTRIBUTE', `Duplicate attribute '${name}' on ${el.name}.`, t.start, t.end - t.start);
+        el.attrs.push(new Attr(name, t.value, t.start, t.start + 1, t.start + 1, t.end, t.type === CTok.ID ? '#' : '@'));
+        last = t.end;
+      } else if (t.type === CTok.STRING) {
+        take();
+        if (el.text !== null) fail('E_SYNTAX', `${el.name} already has text content.`, t.start, t.end - t.start);
+        el.text = t.value;
+        el.textStart = t.start;
+        el.textEnd = t.end;
+        last = t.end;
+      } else if (t.type === CTok.NAME && peek(1).type === CTok.EQ) {
+        take();
+        take();
+        const v = take();
+        if (v.type !== CTok.VALUE) fail('E_MISSING_VALUE', `Expected a value for attribute '${t.value}'.`, v.start, 1);
+        for (const prev of el.attrs) {
+          if (prev.name === t.value) fail('E_DUPLICATE_ATTRIBUTE', `Duplicate attribute '${t.value}' on ${el.name}.`, t.start, t.end - t.start);
+        }
+        const a = new Attr(t.value, v.value, t.start, t.end, v.valueStart, v.valueEnd, v.quote);
+        a.decoded = !!v.escaped;
+        el.attrs.push(a);
+        last = v.end;
+      } else {
+        break;
+      }
+    }
+    el.openEnd = last;
+  }
+
+  function parseStatements(parent, closeTok) {
+    for (;;) {
+      const t = peek();
+      if (t.type === CTok.EOF) {
+        if (closeTok) {
+          fail('E_UNCLOSED_ELEMENT', `Unclosed block of '${parent.name}' (opened at ${where(closeTok.start)}): missing '}'.`, closeTok.start, 1);
+        }
+        return;
+      }
+      if (t.type === CTok.RBRACE) {
+        if (!closeTok) fail('E_UNEXPECTED_CLOSE', "Unexpected '}': no block is open.", t.start, 1);
+        take();
+        parent.closeStart = t.start;
+        parent.end = t.end;
+        return;
+      }
+      if (t.type === CTok.SEMI) {
+        take();
+        continue;
+      }
+      if (t.type === CTok.COMMENT) {
+        take();
+        parent.appendChild(new Comment(t.text, t.start, t.end));
+        continue;
+      }
+      if (t.type === CTok.NAME) {
+        if (peek(1).type === CTok.EQ) {
+          fail('E_SYNTAX', `Attribute '${t.value}' must follow an element name.`, t.start, t.end - t.start, {
+            hint: 'Attributes belong to the element written before them on the same statement.',
+          });
+        }
+        parent.appendChild(parseElement());
+        continue;
+      }
+      if (t.type === CTok.LBRACE) fail('E_SYNTAX', "Unexpected '{': a block must follow an element name.", t.start, 1);
+      if (t.type === CTok.STRING || t.type === CTok.ID || t.type === CTok.REF) {
+        fail('E_SYNTAX', 'Expected an element name.', t.start, t.end - t.start);
+      }
+      fail('E_SYNTAX', 'Unexpected token.', t.start, Math.max(1, t.end - t.start));
+    }
+  }
+
+  function parseElement() {
+    const t = take();
+    const el = new Element(t.value, t.start);
+    el.nameStart = t.start;
+    el.nameEnd = t.end;
+    parseHeader(el);
+    el.end = el.openEnd;
+    if (peek().type === CTok.LBRACE) {
+      const open = take();
+      el.selfClosing = false;
+      parseStatements(el, open);
+    } else {
+      el.selfClosing = true;
+    }
+    return el;
+  }
+
+  const leading = [];
+  while (peek().type === CTok.COMMENT || peek().type === CTok.SEMI) {
+    const c = take();
+    if (c.type === CTok.COMMENT) leading.push(new Comment(c.text, c.start, c.end));
+  }
+  const first = peek();
+  if (first.type === CTok.EOF) fail('E_EMPTY_DOCUMENT', "Empty document: expected 'es3d version=1'.", first.start, 0);
+  if (first.type !== CTok.NAME || !ROOT_NAMES.has(first.value)) {
+    fail('E_COMPACT_ROOT', "An ES3D compact document must start with the root element 'es3d'.", first.start, Math.max(1, first.end - first.start), {
+      hint: "Begin the file with: es3d version=1",
+    });
+  }
+  const rt = take();
+  const root = new Element(rt.value, rt.start);
+  root.nameStart = rt.start;
+  root.nameEnd = rt.end;
+  parseHeader(root);
+  root.end = root.openEnd;
+  const trailing = [];
+  if (peek().type === CTok.LBRACE) {
+    const open = take();
+    root.selfClosing = false;
+    parseStatements(root, open);
+    for (;;) {
+      const t = peek();
+      if (t.type === CTok.EOF) break;
+      if (t.type === CTok.COMMENT) {
+        take();
+        trailing.push(new Comment(t.text, t.start, t.end));
+      } else if (t.type === CTok.SEMI) take();
+      else fail('E_MULTIPLE_ROOTS', 'Content after the end of the root block.', t.start, Math.max(1, t.end - t.start));
+    }
+  } else {
+    // Header form: everything after the root header belongs to the root.
+    root.headerForm = true;
+    parseStatements(root, null);
+    root.selfClosing = root.children.length === 0;
+    root.end = text.length;
+  }
+  const doc = new Document({ root, syntax: 'compact', source: text, leading, trailing });
+  doc.lineIndex = lineIndex;
+  return doc;
+}

package/src/format/compact-tokenizer.js

@@ -0,0 +1,165 @@
+// Tokenizer for the ES3D compact syntax ("ES3D-C").
+//
+//   es3d version=1
+//   material#red c=#e53935
+//   box s=2 m=red
+//   group p=0,2,0 { sphere r=1 }
+//   use @tree p=10,0,5
+//
+// Newlines are insignificant: an element header ends where the next token is
+// not an attribute (NAME '='), so the grammar is LL(2) and needs no schema.
+
+import { Diagnostic, ES3DError } from './errors.js';
+
+export const CTok = Object.freeze({
+  NAME: 'name',
+  ID: 'id', // #name
+  REF: 'ref', // @name
+  EQ: 'eq',
+  VALUE: 'value', // bare or quoted attribute value
+  STRING: 'string', // quoted text content in header position
+  LBRACE: 'lbrace',
+  RBRACE: 'rbrace',
+  SEMI: 'semi',
+  COMMENT: 'comment',
+  EOF: 'eof',
+});
+
+function isSpace(c) {
+  return c === 32 || c === 10 || c === 9 || c === 13;
+}
+function isNameStart(c) {
+  return (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === 95;
+}
+function isNameChar(c) {
+  return isNameStart(c) || (c >= 48 && c <= 57) || c === 45 || c === 46 || c === 58;
+}
+// characters that terminate a bare value
+function isValueStop(c) {
+  return isSpace(c) || c === 123 || c === 125 || c === 59 || c === 34;
+}
+
+export class CompactTokenizer {
+  constructor(text, lineIndex = null) {
+    this.s = text;
+    this.n = text.length;
+    this.i = text.charCodeAt(0) === 0xfeff ? 1 : 0;
+    this.lineIndex = lineIndex;
+    this.afterEq = false;
+  }
+
+  fail(code, message, offset, length = 1, extra = {}) {
+    const d = new Diagnostic({ code, message, offset, length, ...extra });
+    d.locate(this.lineIndex);
+    throw new ES3DError([d], this.lineIndex);
+  }
+
+  readQuoted(start) {
+    const s = this.s;
+    let i = start + 1;
+    let out = '';
+    let segStart = i;
+    for (;;) {
+      if (i >= this.n) this.fail('E_UNTERMINATED_STRING', 'Unterminated string: missing closing quote.', start, 1);
+      const c = s.charCodeAt(i);
+      if (c === 34) break;
+      if (c === 92) {
+        out += s.slice(segStart, i);
+        const e = s[i + 1];
+        if (e === '"' || e === '\\') out += e;
+        else if (e === 'n') out += '\n';
+        else if (e === 't') out += '\t';
+        else this.fail('E_BAD_ESCAPE', `Unknown escape sequence '\\${e ?? ''}'. Use \\" \\\\ \\n or \\t.`, i, 2);
+        i += 2;
+        segStart = i;
+        continue;
+      }
+      i++;
+    }
+    out += s.slice(segStart, i);
+    return { value: out, end: i + 1, escaped: segStart !== start + 1 };
+  }
+
+  next() {
+    const s = this.s;
+    let i = this.i;
+    while (i < this.n && isSpace(s.charCodeAt(i))) i++;
+    if (i >= this.n) {
+      this.i = i;
+      if (this.afterEq) this.fail('E_MISSING_VALUE', "Expected a value after '='.", i, 0);
+      return { type: CTok.EOF, start: i, end: i };
+    }
+    const c = s.charCodeAt(i);
+    const start = i;
+
+    if (this.afterEq) {
+      this.afterEq = false;
+      if (c === 34) {
+        const q = this.readQuoted(i);
+        this.i = q.end;
+        return { type: CTok.VALUE, value: q.value, start, end: q.end, valueStart: start + 1, valueEnd: q.end - 1, quote: '"', escaped: q.escaped };
+      }
+      if (c === 123 || c === 125 || c === 59) this.fail('E_MISSING_VALUE', "Expected a value after '='.", i, 1);
+      while (i < this.n && !isValueStop(s.charCodeAt(i))) i++;
+      this.i = i;
+      return { type: CTok.VALUE, value: s.slice(start, i), start, end: i, valueStart: start, valueEnd: i, quote: '' };
+    }
+
+    // comments
+    if (c === 47) {
+      const c2 = s.charCodeAt(i + 1);
+      if (c2 === 47) {
+        let end = s.indexOf('\n', i);
+        if (end < 0) end = this.n;
+        this.i = end;
+        return { type: CTok.COMMENT, text: s.slice(i + 2, end).replace(/\r$/, ''), start, end, line: true };
+      }
+      if (c2 === 42) {
+        const end = s.indexOf('*/', i + 2);
+        if (end < 0) this.fail('E_UNTERMINATED_COMMENT', "Unterminated comment: missing '*/'.", i, 2);
+        this.i = end + 2;
+        return { type: CTok.COMMENT, text: s.slice(i + 2, end), start, end: end + 2, line: false };
+      }
+    }
+    switch (c) {
+      case 123:
+        this.i = i + 1;
+        return { type: CTok.LBRACE, start, end: i + 1 };
+      case 125:
+        this.i = i + 1;
+        return { type: CTok.RBRACE, start, end: i + 1 };
+      case 59:
+        this.i = i + 1;
+        return { type: CTok.SEMI, start, end: i + 1 };
+      case 61:
+        this.i = i + 1;
+        this.afterEq = true;
+        return { type: CTok.EQ, start, end: i + 1 };
+      case 34: {
+        const q = this.readQuoted(i);
+        this.i = q.end;
+        return { type: CTok.STRING, value: q.value, start, end: q.end, valueStart: start + 1, valueEnd: q.end - 1 };
+      }
+      case 35: // #id
+      case 64: {
+        // @ref
+        let j = i + 1;
+        if (!isNameStart(s.charCodeAt(j))) {
+          this.fail('E_SYNTAX', c === 35 ? "Expected an id after '#'." : "Expected a reference id after '@'.", i, 1);
+        }
+        while (j < this.n && isNameChar(s.charCodeAt(j))) j++;
+        this.i = j;
+        return { type: c === 35 ? CTok.ID : CTok.REF, value: s.slice(i + 1, j), start, end: j };
+      }
+      default:
+        break;
+    }
+    if (isNameStart(c)) {
+      let j = i + 1;
+      while (j < this.n && isNameChar(s.charCodeAt(j))) j++;
+      this.i = j;
+      return { type: CTok.NAME, value: s.slice(i, j), start, end: j };
+    }
+    this.fail('E_SYNTAX', `Unexpected character '${s[i]}'.`, i, 1);
+  }
+}