spine-rigc 2.57.0 → 2.58.0

package/src/deformgen.ts

@@ -377,13 +377,13 @@ export function evaluateDeformTransform(
   soft: DeformSoftMask | null = null,
 ): DeformTransformReport {
   if (transform === null || typeof transform !== 'object' || Array.isArray(transform)) {
-    throw new CompileError(`${where}: "transform" is ${JSON.stringify(transform)}; it is an object with a "kind"`);
+    throw new CompileError(`${where}: "transform" is ${JSON.stringify(transform)}; it is an object with a "kind"`, 'CE_DEFORM_TRANSFORM_OBJECT');
   }
   const kind = (transform as { kind?: unknown }).kind;
   if (typeof kind !== 'string' || !(DEFORM_TRANSFORM_KINDS as readonly string[]).includes(kind)) {
     throw new CompileError(
       `${where}: "transform" has kind ${JSON.stringify(kind)}; this spec evaluates ${DEFORM_TRANSFORM_KINDS.join(', ')}. ` +
-        'A model that is none of those is still authorable as a "vertices" run.',
+        'A model that is none of those is still authorable as a "vertices" run.', 'CE_DEFORM_TRANSFORM_KIND',
     );
   }
   const count = setup.length / 2;
@@ -432,14 +432,14 @@ export function evaluateDeformTransform(
         throw new CompileError(
           `${where}: transform ${kind} states both "depth": true and a radius ${JSON.stringify(t.radius)}. They are ` +
             'two answers to how far forward each vertex sits — a cylinder derives it, a map states it — and a key ' +
-            'carrying both leaves a reader unable to say which one the output came from. Drop one.',
+            'carrying both leaves a reader unable to say which one the output came from. Drop one.', 'CE_DEFORM_DEPTH_RADIUS_CONFLICT',
         );
       }
       if (fromDepth && depth === null) {
         throw new CompileError(
           `${where}: transform ${kind} says "depth": true and this attachment has no depth map. The map is named on ` +
             'the attachment\'s generator, as `"depth": { "image": …, "near": …, "zScale": … }`, because it describes ' +
-            'the art rather than this key. Name it there, or give this key a radius.',
+            'the art rather than this key. Name it there, or give this key a radius.', 'CE_DEFORM_DEPTH_MAP_REQUIRED',
         );
       }
       if (fromDepth && depth !== null && depth.length !== count) {
@@ -447,12 +447,12 @@ export function evaluateDeformTransform(
         // emitted; stated because a silent mismatch here would turn into a turn
         // evaluated against another vertex's depth.
         throw new CompileError(
-          `${where}: transform ${kind} has ${depth.length} sampled depths for ${count} vertices`,
+          `${where}: transform ${kind} has ${depth.length} sampled depths for ${count} vertices`, 'CE_DEFORM_DEPTH_SAMPLE_COUNT',
         );
       }
       const radius = fromDepth ? 0 : num(t.radius, 'radius', where);
       if (!fromDepth && radius <= 0) {
-        throw new CompileError(`${where}: transform ${kind} has radius ${radius}; it is the radius of the cylinder the part is painted on, so a positive number`);
+        throw new CompileError(`${where}: transform ${kind} has radius ${radius}; it is the radius of the cylinder the part is painted on, so a positive number`, 'CE_DEFORM_RADIUS_POSITIVE');
       }
       const rad = (degrees * Math.PI) / 180;
       const cosMinus1 = Math.cos(rad) - 1;
@@ -473,7 +473,7 @@ export function evaluateDeformTransform(
             `${where}: transform ${kind} has radius ${radius}, and vertex ${v} sits at ${kind === 'yaw' ? 'x' : 'y'}=` +
               `${setup[2 * v + along]}, which is ${round(Math.abs(u) - radius)} past it (about=${about}). The cylinder has no ` +
               'surface there, so its depth would be 0 and the projection would be a different model at that vertex. ' +
-              'Raise the radius to where the part actually sits, or move the vertex.',
+              'Raise the radius to where the part actually sits, or move the vertex.', 'CE_DEFORM_VERTEX_OUTSIDE_CYLINDER',
           );
         }
         // A depth map needs no such check: it states a surface everywhere it
@@ -533,7 +533,7 @@ export function evaluateDeformTransform(
           `${where}: transform affine has scale [${scale[0]}, ${scale[1]}], whose determinant is ${round(det)}. ` +
             'At or below zero the map mirrors or collapses the geometry and EVERY triangle reverses its winding, ' +
             'which is the fold A39_DEFORM_KEEPS_TRIANGLE_WINDING refuses. A positive determinant is what makes this ' +
-            'kind incapable of folding a mesh.',
+            'kind incapable of folding a mesh.', 'CE_DEFORM_AFFINE_DETERMINANT',
         );
       }
       for (let v = 0; v < count; v++) {
@@ -563,7 +563,7 @@ export function evaluateDeformTransform(
       const wavelength = num(w.wavelength, 'wavelength', where);
       const phase = w.phase === undefined ? 0 : num(w.phase, 'phase', where);
       if (wavelength === 0) {
-        throw new CompileError(`${where}: transform wave has wavelength 0; one period cannot be zero long`);
+        throw new CompileError(`${where}: transform wave has wavelength 0; one period cannot be zero long`, 'CE_DEFORM_WAVELENGTH_ZERO');
       }
       const [along, axis] = axes(w.along, w.axis, 'wave', where);
       const phaseRad = (phase * Math.PI) / 180;
@@ -609,11 +609,11 @@ export function evaluateDeformTransform(
         throw new CompileError(
           `${where}: transform bend has power ${power}; it is a whole number ≥ 1 (1 is an affine shear, 2 a cantilever ` +
             'that is flat at "from"). A fractional power is not evaluated because it has no value on the side of "from" ' +
-            'the part does not reach.',
+            'the part does not reach.', 'CE_DEFORM_BEND_POWER_WHOLE',
         );
       }
       if (to === from) {
-        throw new CompileError(`${where}: transform bend has from ${from} and to ${to}; they are the two ends of the bend, so they differ`);
+        throw new CompileError(`${where}: transform bend has from ${from} and to ${to}; they are the two ends of the bend, so they differ`, 'CE_DEFORM_BEND_ENDS_EQUAL');
       }
       const [along, axis] = axes(b.along, b.axis, 'bend', where);
       const span = to - from;
@@ -679,7 +679,7 @@ export function evaluateDeformTransform(
         'which quantises to 0 on the 1e-6 grid a model is evaluated on. So the key states a deformation and ' +
         `emits the identity, and nothing downstream can tell it apart from a key that meant the setup pose. ` +
         `${sampledTo}. A key that MEANS the identity states it in its own parameters (${identitySpelling}) or carries ` +
-        'no run at all.',
+        'no run at all.', 'CE_DEFORM_TRANSFORM_QUANTISED_IDENTITY',
     );
   }
 
@@ -712,7 +712,7 @@ export function evaluateDeformTransform(
       throw new CompileError(
         `${where}: transform ${kind} states ${stated} and moves ${plain.filter((d, i) => i % 2 === 0 && (d !== 0 || plain[i + 1] !== 0)).length} ` +
           `of ${count} vertices, and envelope ${weighed.stated} weighs every one of them 0 — so the key states a ` +
-          `deformation and emits the identity. ${weighed.reach}`,
+          `deformation and emits the identity. ${weighed.reach}`, 'CE_DEFORM_ENVELOPE_ZERO_WEIGHT',
       );
     }
     if (count > 0 && !identity && moving && offsets.every((d, i) => d === plain[i])) {
@@ -720,7 +720,7 @@ export function evaluateDeformTransform(
         `${where}: transform ${kind} states envelope ${weighed.stated}, and it changes no emitted number: every vertex ` +
           `the model moves takes weight 1 (${weighed.full} of ${count} vertices at 1, ${weighed.zero} at 0), so the run ` +
           `is the un-enveloped one and the envelope is a field a reader would credit for an output it did not shape. ` +
-          `${weighed.reach}`,
+          `${weighed.reach}`, 'CE_DEFORM_ENVELOPE_NO_EFFECT',
       );
     }
     stated = `${stated} envelope(${weighed.stated})`;
@@ -781,7 +781,7 @@ export function evaluateDeformEnvelope(
   if (envelope === null || typeof envelope !== 'object' || Array.isArray(envelope)) {
     throw new CompileError(
       `${where}: transform field "envelope" is ${JSON.stringify(envelope)}; it is an object — a ramp ` +
-        '`{ "axis", "from", "to", "shape" }` or a mask `{ "mask" }`',
+        '`{ "axis", "from", "to", "shape" }` or a mask `{ "mask" }`', 'CE_DEFORM_ENVELOPE_OBJECT',
     );
   }
   const e = envelope as DeformEnvelope;
@@ -791,13 +791,13 @@ export function evaluateDeformEnvelope(
     throw new CompileError(
       `${where}: transform field "envelope" states "mask" ${JSON.stringify(e.mask)} beside the ramp's ` +
         `${rampStated.map((f) => `"${f}"`).join(', ')}. They are two answers to one question — what weight each vertex ` +
-        'takes — and a key carrying both leaves a reader unable to say which one the output came from. Drop one.',
+        'takes — and a key carrying both leaves a reader unable to say which one the output came from. Drop one.', 'CE_DEFORM_ENVELOPE_MASK_RAMP_CONFLICT',
     );
   }
   if (e.mask === undefined && rampStated.length === 0) {
     throw new CompileError(
       `${where}: transform field "envelope" is ${JSON.stringify(envelope)}, which states no weight at all. It is a ramp ` +
-        '`{ "axis", "from", "to", "shape" }` or a mask `{ "mask" }`; a key that weighs every vertex 1 carries no envelope.',
+        '`{ "axis", "from", "to", "shape" }` or a mask `{ "mask" }`; a key that weighs every vertex 1 carries no envelope.', 'CE_DEFORM_ENVELOPE_WEIGHT_UNSTATED',
     );
   }
 
@@ -812,21 +812,21 @@ export function evaluateDeformEnvelope(
         `${where}: transform field "envelope.mask" is ${JSON.stringify(mask)}, and this attachment has no "soft" block, ` +
           'so the mask names nothing. An envelope\'s mask is the attachment\'s own soft mask (AUTHORING §3.4.6), the ' +
           'one its generator sampled at every vertex when the mesh was built; give the generator a "soft" block, or ' +
-          'state a ramp instead.',
+          'state a ramp instead.', 'CE_DEFORM_ENVELOPE_SOFT_REQUIRED',
       );
     }
     if (soft.mask !== mask) {
       throw new CompileError(
         `${where}: transform field "envelope.mask" is ${JSON.stringify(mask)}, and this attachment's soft mask is ` +
           `${JSON.stringify(soft.mask)}, so the mask names nothing it was built with. An envelope reads the mask the ` +
-          'generator sampled at every vertex, and only that one.',
+          'generator sampled at every vertex, and only that one.', 'CE_DEFORM_ENVELOPE_MASK_MISMATCH',
       );
     }
     if (soft.levels.length !== count) {
       // Unreachable while the sampler walks the same vertex list the mesh
       // emitted, as for a depth map; stated because a silent mismatch would
       // weigh one vertex by another's level.
-      throw new CompileError(`${where}: the soft mask "${mask}" has ${soft.levels.length} sampled levels for ${count} vertices`);
+      throw new CompileError(`${where}: the soft mask "${mask}" has ${soft.levels.length} sampled levels for ${count} vertices`, 'CE_DEFORM_SOFT_SAMPLE_COUNT');
     }
     weights = soft.levels.map((level) => round(level));
     stated = `mask=${mask}`;
@@ -842,7 +842,7 @@ export function evaluateDeformEnvelope(
       throw new CompileError(
         `${where}: transform field "envelope.shape" is ${JSON.stringify(e.shape)}; it is one of ` +
           `${DEFORM_ENVELOPE_SHAPES.map((name) => JSON.stringify(name)).join(', ')} — how the weight rises from 0 at ` +
-          '"from" to 1 at "to": "linear" is u, "smooth" is u²(3 − 2u)',
+          '"from" to 1 at "to": "linear" is u, "smooth" is u²(3 − 2u)', 'CE_DEFORM_ENVELOPE_SHAPE',
       );
     }
     const length = hypot2(axis[0], axis[1]);
@@ -855,13 +855,13 @@ export function evaluateDeformEnvelope(
       throw new CompileError(
         `${where}: transform field "envelope.axis" is [${axis[0]}, ${axis[1]}], whose length is ${round(length)}; it is a ` +
           'unit direction, length 1 on the model\'s 1e-6 grid. A longer or shorter one would scale every position the ' +
-          'ramp compares with "from" and "to" — divide it by its length, and state "from" and "to" along the unit one.',
+          'ramp compares with "from" and "to" — divide it by its length, and state "from" and "to" along the unit one.', 'CE_DEFORM_ENVELOPE_AXIS_UNIT',
       );
     }
     if (from === to) {
       throw new CompileError(
         `${where}: transform fields "envelope.from" and "envelope.to" are both ${from}; they are where the weight is 0 ` +
-          'and where it is 1, so they differ — a ramp of no length is a step, and a step is the edge a model exists not to leave.',
+          'and where it is 1, so they differ — a ramp of no length is a step, and a step is the edge a model exists not to leave.', 'CE_DEFORM_ENVELOPE_ENDS_EQUAL',
       );
     }
     const span = to - from;
@@ -913,7 +913,7 @@ export function checkEnvelopeWeights(weights: readonly number[], field: string,
     if (!(w >= 0 && w <= 1)) {
       throw new CompileError(
         `${where}: transform field "${field}" weighs vertex ${v} at ${w}; an envelope's weight is in [0, 1] — 0 leaves ` +
-          'the vertex where it is and 1 moves it the whole way the model says, and nothing past either end is a weight.',
+          'the vertex where it is and 1 moves it the whole way the model says, and nothing past either end is a weight.', 'CE_DEFORM_ENVELOPE_WEIGHT_RANGE',
       );
     }
   }
@@ -922,7 +922,7 @@ export function checkEnvelopeWeights(weights: readonly number[], field: string,
 /** One required finite number, refused by field name rather than compiled as a NaN. */
 function num(value: unknown, field: string, where: string): number {
   if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw new CompileError(`${where}: transform field "${field}" is ${JSON.stringify(value)}; it is a finite number the spec has to state`);
+    throw new CompileError(`${where}: transform field "${field}" is ${JSON.stringify(value)}; it is a finite number the spec has to state`, 'CE_DEFORM_FIELD_NUMBER_FINITE');
   }
   return value;
 }
@@ -930,7 +930,7 @@ function num(value: unknown, field: string, where: string): number {
 /** One required `[a, b]`. */
 function pair(value: unknown, field: string, where: string): [number, number] {
   if (!Array.isArray(value) || value.length !== 2) {
-    throw new CompileError(`${where}: transform field "${field}" is ${JSON.stringify(value)}; it is a pair, [x, y]`);
+    throw new CompileError(`${where}: transform field "${field}" is ${JSON.stringify(value)}; it is a pair, [x, y]`, 'CE_DEFORM_FIELD_PAIR');
   }
   return [num(value[0], `${field}[0]`, where), num(value[1], `${field}[1]`, where)];
 }
@@ -948,14 +948,14 @@ function axes(along: unknown, axis: unknown, kind: string, where: string): [0 |
     ['axis', axis],
   ] as const) {
     if (value !== 'x' && value !== 'y') {
-      throw new CompileError(`${where}: transform ${kind} has ${name}=${JSON.stringify(value)}; it is "x" or "y"`);
+      throw new CompileError(`${where}: transform ${kind} has ${name}=${JSON.stringify(value)}; it is "x" or "y"`, 'CE_DEFORM_COORDINATE_NAME');
     }
   }
   if (along === axis) {
     throw new CompileError(
       `${where}: transform ${kind} reads ${String(along)} and displaces ${String(axis)} — the same coordinate, which is a ` +
         'stretch rather than a bend or a wave. An affine scale states that, and states the determinant that proves it ' +
-        'keeps every triangle\'s winding.',
+        'keeps every triangle\'s winding.', 'CE_DEFORM_SAME_READ_DISPLACE_AXIS',
     );
   }
   return [along === 'x' ? 0 : 1, axis === 'x' ? 0 : 1];

package/src/emit_spine.ts

@@ -137,7 +137,7 @@ export function boneIndexOf(bones: readonly ModelBone[]): (bone: string) => numb
   const index = new Map(bones.map((bone, i) => [bone.name, i] as const));
   return (bone) => {
     const at = index.get(bone);
-    if (at === undefined) throw new CompileError(`internal: a weighted vertex binds bone "${bone}", which is not in the model's bone list`);
+    if (at === undefined) throw new CompileError(`internal: a weighted vertex binds bone "${bone}", which is not in the model's bone list`, 'CE_EMIT_INTERNAL_WEIGHT_BONE_UNKNOWN');
     return at;
   };
 }
@@ -492,7 +492,7 @@ export function emitConstraint(model: ModelConstraint): SpineConstraint {
   const out: SpineConstraint = { name: model.name, type: model.kind };
   const stray = Object.keys(model).filter((key) => key !== 'kind' && key !== 'name' && key !== 'declaredIn' && !order.includes(key));
   if (stray.length > 0) {
-    throw new CompileError(`internal: ${model.kind} constraint "${model.name}" carries ${stray.join(', ')}, which the emitter has no place for`);
+    throw new CompileError(`internal: ${model.kind} constraint "${model.name}" carries ${stray.join(', ')}, which the emitter has no place for`, 'CE_EMIT_INTERNAL_CONSTRAINT_FIELDS');
   }
   for (const field of order) {
     const value = model[field];
@@ -641,11 +641,11 @@ function emitDrawOrderKey(key: ModelKey, slotIndex: ReadonlyMap<string, number>)
   const out = emitKey(key);
   if (key.offsets === undefined) return out;
   if (!isDrawOrderMoves(key.offsets)) {
-    throw new CompileError(`internal: a draw-order key at t=${key.time} carries offsets that are not slot/offset moves`);
+    throw new CompileError(`internal: a draw-order key at t=${key.time} carries offsets that are not slot/offset moves`, 'CE_EMIT_INTERNAL_DRAW_ORDER_SHAPE');
   }
   const indexOf = (slot: string): number => {
     const at = slotIndex.get(slot);
-    if (at === undefined) throw new CompileError(`internal: a draw-order key at t=${key.time} moves slot "${slot}", which is not in the model's slot list`);
+    if (at === undefined) throw new CompileError(`internal: a draw-order key at t=${key.time} moves slot "${slot}", which is not in the model's slot list`, 'CE_EMIT_INTERNAL_DRAW_ORDER_SLOT_UNKNOWN');
     return at;
   };
   out.offsets = key.offsets
@@ -734,7 +734,7 @@ export function emitAnimations(
   const out: Record<string, SpineAnimation> = {};
   for (const name of names) {
     const animation = animations.get(name);
-    if (animation === undefined) throw new CompileError(`internal: the animation order named "${name}", which is not in the model`);
+    if (animation === undefined) throw new CompileError(`internal: the animation order named "${name}", which is not in the model`, 'CE_EMIT_INTERNAL_ANIMATION_UNKNOWN');
     out[name] = emitAnimation(animation, slotIndex);
   }
   return out;

package/src/errors.ts

@@ -17,6 +17,14 @@
 import type { DroppedState } from './types.ts';
 
 export class CompileError extends Error {
+  /** Stable guide row identity; absent on legacy one-argument library errors. */
+  declare readonly code?: string;
+
+  constructor(message?: string, codeOrOptions?: string | ErrorOptions, options?: ErrorOptions) {
+    super(message, typeof codeOrOptions === 'string' ? options : codeOrOptions);
+    if (typeof codeOrOptions === 'string') this.code = codeOrOptions;
+  }
+
   /**
    * States the manifest listed whose art was not found, recorded before this
    * refusal was raised (issue #671).

package/src/guide.ts

@@ -54,17 +54,12 @@ export function guidePointer(rule: string): string {
   return ` (see ${GUIDE_BIN} guide ${rule})`;
 }
 
-/**
- * The section a compile error points at (HQ's ruling on rig-c/parts#343): no compile error names a rule — 0 of
- * the 463 throw sites carry a code, and §5.1's tables are keyed on the message — and §5.1 has no #### a thrower
- * could name, so every one points at the section its row is in. When §5.1 grows #### families a thrower can
- * name, this is where `§5.1.<k>` goes.
- */
+/** Legacy library callers may construct an uncoded error; their pointer remains the compile section. */
 export const COMPILE_ERROR_SECTION = '§5.1';
 
-/** A compile error as the CLI prints it: the prefix, the message, and the pointer to §5.1. */
-export function compileErrorLine(message: string): string {
-  return `rigc compile error: ${message}${guidePointer(COMPILE_ERROR_SECTION)}`;
+/** The original prefix and message, followed by this site's stable code (or the legacy section). */
+export function compileErrorLine(message: string, code?: string): string {
+  return `rigc compile error: ${message}${guidePointer(code ?? COMPILE_ERROR_SECTION)}`;
 }
 
 /** A refusal naming its rule, unindented, as `guide` prints its own: `FAIL  <RULE>: <detail> (see rigc guide <RULE>)`. */

package/src/keys.ts

@@ -112,7 +112,7 @@ export function refuseUnknownKeys(
     `${where}: ${what} has ${strays.length === 1 ? 'a key' : `${strays.length} keys`} this compiler does not read: ` +
       `${named.join(', ')}. Nothing reads such a key, so it would be dropped from the emitted skeleton in silence — ` +
       'fix the spelling or remove it. ' +
-      (known.length === 0 ? 'This shape has no fields at all.' : `Known here: ${[...known].sort().join(', ')}.`),
+      (known.length === 0 ? 'This shape has no fields at all.' : `Known here: ${[...known].sort().join(', ')}.`), 'CE_KEYS_UNKNOWN_FIELD',
   );
 }
 
@@ -182,7 +182,7 @@ export function refuseNumbersTheFileCannotCarry(
       throw new CompileError(
         `${where}: ${place(path)} is ${String(node)}; a number in this file is finite at float32 precision, at most ` +
           `±${String(FLOAT32_MAX)}, because the skeleton is written as float32 — past that it would be emitted as ` +
-          `Infinity, which JSON writes as null, a value the file never stated.${why}`,
+          `Infinity, which JSON writes as null, a value the file never stated.${why}`, 'CE_KEYS_NUMBER_FLOAT32_FINITE',
       );
     }
     if (Array.isArray(node)) {
@@ -409,7 +409,7 @@ export function refuseValuesOfTheWrongType(
       const wrong = wrongTypeAt(visit.node[key], type);
       if (wrong === null) continue;
       throw new CompileError(
-        `${where}: ${visit.name([key, ...wrong.tail])} is ${typeFound(wrong.value)}; ${wrong.required} is required`,
+        `${where}: ${visit.name([key, ...wrong.tail])} is ${typeFound(wrong.value)}; ${wrong.required} is required`, 'CE_KEYS_FIELD_VALUE_TYPE',
       );
     }
   }
@@ -479,7 +479,7 @@ export function refuseValuesOutsideTheirSet(
       if (typeof value === 'string' && rule.set.includes(value)) continue;
       throw new CompileError(
         `${where}: ${visit.name([key])} is ${JSON.stringify(value) ?? String(value)}; one of ` +
-          `${rule.set.map((name) => JSON.stringify(name)).join(', ')} — ${rule.readAs}`,
+          `${rule.set.map((name) => JSON.stringify(name)).join(', ')} — ${rule.readAs}`, 'CE_KEYS_ENUM_VALUE',
       );
     }
   }

package/src/model.ts

@@ -733,7 +733,7 @@ function ordered(record: object, keys: readonly string[], where: string, value:
   const own = record as Record<string, unknown>;
   for (const key of Object.keys(own)) {
     if (!keys.includes(key)) {
-      throw new CompileError(`internal: the model document has no place for field "${key}" of ${where}; it writes [${keys.join(', ')}]`);
+      throw new CompileError(`internal: the model document has no place for field "${key}" of ${where}; it writes [${keys.join(', ')}]`, 'CE_MODEL_INTERNAL_FIELD_UNREPRESENTABLE');
     }
   }
   const out: { [key: string]: DocValue } = {};
@@ -752,13 +752,13 @@ function ordered(record: object, keys: readonly string[], where: string, value:
 function plain(value: unknown, where: string): DocValue {
   if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
   if (typeof value === 'number') {
-    if (!Number.isFinite(value)) throw new CompileError(`internal: the model document cannot carry ${value} at ${where}; JSON writes it as null`);
-    if (Object.is(value, -0)) throw new CompileError(`internal: the model document cannot carry -0 at ${where}; JSON writes it as 0`);
+    if (!Number.isFinite(value)) throw new CompileError(`internal: the model document cannot carry ${value} at ${where}; JSON writes it as null`, 'CE_MODEL_INTERNAL_NONFINITE_NUMBER');
+    if (Object.is(value, -0)) throw new CompileError(`internal: the model document cannot carry -0 at ${where}; JSON writes it as 0`, 'CE_MODEL_INTERNAL_NEGATIVE_ZERO');
     return value;
   }
   if (Array.isArray(value)) {
     return value.map((item, i) => {
-      if (item === undefined) throw new CompileError(`internal: the model document cannot carry undefined at ${where}[${i}]; JSON writes it as null`);
+      if (item === undefined) throw new CompileError(`internal: the model document cannot carry undefined at ${where}[${i}]; JSON writes it as null`, 'CE_MODEL_INTERNAL_UNDEFINED_ELEMENT');
       return plain(item, `${where}[${i}]`);
     });
   }
@@ -767,7 +767,7 @@ function plain(value: unknown, where: string): DocValue {
     for (const [key, item] of Object.entries(value)) if (item !== undefined) out[key] = plain(item, `${where}.${key}`);
     return out;
   }
-  throw new CompileError(`internal: the model document cannot carry ${Object.prototype.toString.call(value)} at ${where}; it writes plain data only`);
+  throw new CompileError(`internal: the model document cannot carry ${Object.prototype.toString.call(value)} at ${where}; it writes plain data only`, 'CE_MODEL_INTERNAL_NONPLAIN_VALUE');
 }
 
 /** A `Map` as the array of its entries in the map's order, each `{ name, … }`. */
@@ -818,11 +818,11 @@ function verticesOf(vertices: ModelVertices, where: string): DocValue {
 
 function attachmentOf(entry: SkinTableEntry, where: string): DocValue {
   const fields = ATTACHMENT_FIELDS[entry.kind];
-  if (fields === undefined) throw new CompileError(`internal: the model document knows no attachment kind "${String(entry.kind)}" at ${where}`);
+  if (fields === undefined) throw new CompileError(`internal: the model document knows no attachment kind "${String(entry.kind)}" at ${where}`, 'CE_MODEL_INTERNAL_ATTACHMENT_KIND');
   if (entry.kind === 'region' && (entry.atlas === undefined) === (entry.sequence === undefined)) {
     throw new CompileError(
       `internal: the region at ${where} carries ${entry.atlas === undefined ? 'neither an atlas rectangle nor a sequence' : 'both an atlas rectangle and a sequence'}; ` +
-        'a region states exactly one of the two, and a sequence holds a rectangle per frame (issue #935)',
+        'a region states exactly one of the two, and a sequence holds a rectangle per frame (issue #935)', 'CE_MODEL_INTERNAL_REGION_SOURCE',
     );
   }
   return ordered(entry, fields, where, (key, v) => {
@@ -840,7 +840,7 @@ function attachmentOf(entry: SkinTableEntry, where: string): DocValue {
 /** One rectangle, in `ModelAtlasRect`'s order, every field required. */
 function atlasRectOf(rect: ModelAtlasRect, where: string): DocValue {
   for (const key of ATLAS_RECT_FIELDS) {
-    if (rect[key] === undefined) throw new CompileError(`internal: the atlas rectangle at ${where} has no ${key}; it states all of [${ATLAS_RECT_FIELDS.join(', ')}]`);
+    if (rect[key] === undefined) throw new CompileError(`internal: the atlas rectangle at ${where} has no ${key}; it states all of [${ATLAS_RECT_FIELDS.join(', ')}]`, 'CE_MODEL_INTERNAL_ATLAS_FIELD_REQUIRED');
   }
   return ordered(rect, ATLAS_RECT_FIELDS, where);
 }
@@ -922,7 +922,7 @@ function editorOrderOf(model: CompiledModel): DocValue {
     if (skin !== undefined) same(`editorOrder.skins[${i}] "${entry.name}".slots`, entry.slots, Object.keys(skin.attachments));
   }
   same('editorOrder.animations', order.animations, [...model.animations.keys()]);
-  if (problems.length > 0) throw new CompileError(`internal: the model's editor order is not its own: ${problems.join('; ')}`);
+  if (problems.length > 0) throw new CompileError(`internal: the model's editor order is not its own: ${problems.join('; ')}`, 'CE_MODEL_INTERNAL_EDITOR_ORDER');
   return {
     skins: order.skins.map((entry, i) => ordered(entry, ['name', 'slots'], `editorOrder.skins[${i}]`)),
     animations: plain(order.animations, 'editorOrder.animations'),
@@ -1040,7 +1040,7 @@ const MODEL_DOCUMENT_LEFT_OUT: readonly string[] = ['setupWorld'];
 export function modelDocument(model: CompiledModel, skeletonText: string, atlasText: string): string {
   for (const key of Object.keys(model)) {
     if (!MODEL_DOCUMENT_FIELDS.includes(key) && !MODEL_DOCUMENT_LEFT_OUT.includes(key)) {
-      throw new CompileError(`internal: the model document has no place for the model's field "${key}"; it writes [${MODEL_DOCUMENT_FIELDS.join(', ')}] and leaves out [${MODEL_DOCUMENT_LEFT_OUT.join(', ')}]`);
+      throw new CompileError(`internal: the model document has no place for the model's field "${key}"; it writes [${MODEL_DOCUMENT_FIELDS.join(', ')}] and leaves out [${MODEL_DOCUMENT_LEFT_OUT.join(', ')}]`, 'CE_MODEL_INTERNAL_DOCUMENT_FIELD');
     }
   }
   const doc: { [key: string]: DocValue } = {

package/src/motion.ts

@@ -289,7 +289,7 @@ function describe(v: unknown): string {
  * has seen one has seen the format.
  */
 function refuse(where: string, key: string, is: unknown, hint: string): never {
-  throw new CompileError(`${where}: \`${key}\` is ${describe(is)}; ${hint}`);
+  throw new CompileError(`${where}: \`${key}\` is ${describe(is)}; ${hint}`, 'CE_MOTION_FIELD_SHAPE');
 }
 
 /**
@@ -436,7 +436,7 @@ function parsePhysics(raw: unknown, where: string): void {
         `${where}: \`${key}\` names a physics constraint "${EVERY_GLOBAL_PHYSICS}", and that name is reserved: a ` +
           `track's \`"physics": "${EVERY_GLOBAL_PHYSICS}"\` is the timeline that names no constraint and drives ` +
           'every one declaring the keyed property global, so a constraint called ' +
-          `"${EVERY_GLOBAL_PHYSICS}" could not be keyed by name. Give it another name`,
+          `"${EVERY_GLOBAL_PHYSICS}" could not be keyed by name. Give it another name`, 'CE_MOTION_PHYSICS_NAME_RESERVED',
       );
     }
     const spec = needObj(entry, where, key,'a physics constraint is an object naming the bone it drives and the components it drives it in');
@@ -674,7 +674,7 @@ function parseSequence(raw: unknown, where: string, at: string): void {
               : '') +
             '. The runtime advances the frame by `(time - keyTime) / delay`, which is Infinity at 0, and ' +
             '`Infinity | 0` is 0 — so the key shows its first frame for as long as it lasts, which is "hold" spelt ' +
-            `as "${mode}". State the seconds per frame, or write "hold"`,
+            `as "${mode}". State the seconds per frame, or write "hold"`, 'CE_MOTION_SEQUENCE_ADVANCE_ZERO_DELAY',
         );
       }
     }
@@ -766,10 +766,10 @@ export function parseMotionSpec(raw: unknown, where: string): MotionSpec {
 
 function parseMotionSpecInto(raw: unknown, where: string, visits: readonly ShapeVisit[]): MotionSpec {
   if (!isObj(raw)) {
-    throw new CompileError(`${where}: a motion spec must be a JSON object, and this file holds ${describe(raw)}`);
+    throw new CompileError(`${where}: a motion spec must be a JSON object, and this file holds ${describe(raw)}`, 'CE_MOTION_SPEC_OBJECT');
   }
   if (raw.spec !== MOTION_SPEC_VERSION) {
-    throw new CompileError(`${where}: unknown motion spec version: ${String(raw.spec)}, expected "${MOTION_SPEC_VERSION}"`);
+    throw new CompileError(`${where}: unknown motion spec version: ${String(raw.spec)}, expected "${MOTION_SPEC_VERSION}"`, 'CE_MOTION_SPEC_VERSION');
   }
   // Before the field checks, for the reason `parseRigSpec` puts its own first: a
   // key nothing reads is often the CAUSE of the field that is missing, and
@@ -793,7 +793,7 @@ function parseMotionSpecInto(raw: unknown, where: string, visits: readonly Shape
 
   const animations = needObj(raw.animations, where, 'animations', 'it is a table keyed by animation name, `{ "<name>": { "duration": …, "tracks": [...] } }` (write `{}` for a static rig)');
   for (const [name, anim] of Object.entries(animations)) {
-    if (name.length === 0) throw new CompileError(`${where}: an animation has an empty name`);
+    if (name.length === 0) throw new CompileError(`${where}: an animation has an empty name`, 'CE_MOTION_ANIMATION_NAME_EMPTY');
     parseAnimation(anim, where, name);
   }