spine-rigc 0.30.0 → 0.32.0

package/src/compile.ts

@@ -39,8 +39,9 @@ import { parseJsonWithPosition } from './json-position.ts';
 // of it — the same search serves `refuseUnknownKeys`, and a second copy here with
 // a threshold edited is how such a pair drifts apart.
 import { nearMisses } from './keys.ts';
-import { parseMotionSpec } from './motion.ts';
+import { EVERY_GLOBAL_PHYSICS, parseMotionSpec } from './motion.ts';
 import {
+  BONE_INHERIT_KNOWN,
   constraintAt,
   declaresNoStage,
   parseRigSpec,
@@ -50,6 +51,7 @@ import {
   RIG_PATH_SPACING_MODES,
   RIG_SCALE_Y_MODES,
   RIG_SKIN_CONSTRAINT_KEYS,
+  resolveBoneInherit,
   splitRigSkin,
   type RigAttachment,
   type RigBone,
@@ -61,6 +63,7 @@ import {
   type RigMeshBinding,
   type RigPathAttachment,
   type RigRegionAttachment,
+  type RigSequence,
   type RigSkinParts,
   type RigSpec,
   type RigVertexGeometry,
@@ -89,6 +92,8 @@ import { Plate, readPlate } from '../tools/plate.ts';
 import {
   extractRegion,
   pageFootprint,
+  pageGridSaid,
+  pageGridSentence,
   parseAtlasText,
   rewritePageNames,
   writeAtlasText,
@@ -128,6 +133,7 @@ import type {
   MotionEventKey,
   MotionIkTrack,
   MotionMemberValues,
+  MotionSequenceTrack,
   MotionSpec,
   MotionTrack,
   MotionTransformTrack,
@@ -144,6 +150,7 @@ import type {
   SpineMeshAttachment,
   SpinePathAttachment,
   SpineRegionAttachment,
+  SpineSequence,
   SpineSkeletonJson,
   SpineSlot,
   SpineTimelineKey,
@@ -310,8 +317,14 @@ export function editorNamesInOrder(names: readonly string[], collection: 'animat
   return [...names].sort((a, b) => verdicts.get(a)?.get(b) ?? 0);
 }
 
-/** The skin the editor keeps at index 0 whatever its name sorts as. */
-const DEFAULT_SKIN = 'default';
+/**
+ * The skin the editor keeps at index 0 whatever its name sorts as.
+ *
+ * Exported for `ingest`, which has to know that a contested placeholder the
+ * default skin fills is refused rather than named (`refuseDefaultSkinContest`),
+ * and has no business spelling the name a second time (issue #746).
+ */
+export const DEFAULT_SKIN = 'default';
 
 /**
  * The order the emitted `skins` array is written in: **`default` first, then the
@@ -864,6 +877,17 @@ interface ValueTrackShape {
   fields: string[];
   identity: number[];
   bounds?: Array<PhysicsPoseRule | null>;
+  /**
+   * A timeline whose key holds one NAMED value instead of numbers — the JSON
+   * field it is written as, and the resolver that turns a spelling into the
+   * name the file carries (or `undefined` for one the runtime cannot resolve).
+   *
+   * ⚠️ Such a timeline is stepped by the format rather than by choice: its
+   * reader builds no curve at all, so an `ease` or a `curve` on its key would be
+   * accepted by the parser and never read. `compileValueTrack` refuses both.
+   * One entry has it — the bone's `inherit` (issue #733).
+   */
+  named?: { field: string; resolve: (value: unknown) => string | undefined; known: string };
 }
 
 /**
@@ -898,6 +922,12 @@ const BONE_TRACKS: Record<string, ValueTrackShape> = {
   shearx: { fields: ['value'], identity: [0] },
   sheary: { fields: ['value'], identity: [0] },
   rotate: { fields: ['value'], identity: [0] },
+  // The eleventh case of the runtime's bone switch, and the one that keys no
+  // number: `InheritTimeline` sets `pose.inherit` at the key and
+  // `updateWorldTransform` reads it that frame. Resolved by the SAME call the
+  // setup field is (`resolveBoneInherit`), so the five a key may name are the
+  // five a bone may rest in and a refusal prints the one list (issue #733).
+  inherit: { fields: [], identity: [], named: { field: 'inherit', resolve: resolveBoneInherit, known: BONE_INHERIT_KNOWN } },
 };
 
 /**
@@ -1505,6 +1535,11 @@ interface AtlasSource {
   parsed: ParsedAtlas;
   /** Trimmed region name -> the region, first occurrence wins (as `findRegion` does). */
   byName: Map<string, { region: AtlasRegion; page: ParsedAtlas['pages'][number] }>;
+  /**
+   * Page name -> what its file is against what the atlas declares, for every
+   * page on disk whose PNG is not the declared size, in page order (issue #750).
+   */
+  grids: Map<string, NonNullable<CompiledImage['pageGrid']>>;
 }
 
 function readAtlasIn(path: string): AtlasSource {
@@ -1527,12 +1562,28 @@ function readAtlasIn(path: string): AtlasSource {
   // one sentence, rather than one region at a time or at `A06` after the whole
   // compile. A page that is not on disk is left to the region that sits on it,
   // which already names it; saying so twice would be two refusals of one fact.
+  //
+  // 📐 **What each page MEASURES, read in the same pass and not refused here**
+  // (issue #750). A page whose PNG is not the size the atlas declares is a
+  // file every runtime still draws — the region mapping is a fraction of the
+  // declared size — and the only readers it breaks are the ones that address
+  // it in texels. Refusing it here would refuse every pack that has one,
+  // including a pack of region attachments nothing reads a texel of, and on
+  // `build` it would replace `A06`'s verdict with a compile error for the same
+  // fact: `A06` already refuses the pack, names the ratio and prints the
+  // `scale:` repair, before anything is written. So the page is RECORDED, as
+  // `pageGridSentence` states it, and the readers that would take a figure off
+  // its texels decline to on the part that asks (`partTexels` below).
   const unread: string[] = [];
+  const grids: AtlasSource['grids'] = new Map();
   for (const page of parsed.pages) {
     const abs = resolve(dirname(path), page.name);
     if (!existsSync(abs)) continue;
-    const { problem } = readPngHeader(abs);
+    const { info, problem } = readPngHeader(abs);
     if (problem !== null) unread.push(`page "${page.name}": ${problem}`);
+    if (info === null) continue;
+    const sentence = pageGridSentence(page, info, page.regions);
+    if (sentence !== null) grids.set(page.name, { said: pageGridSaid(page, info), sentence });
   }
   if (unread.length > 0) {
     throw new CompileError(
@@ -1540,7 +1591,7 @@ function readAtlasIn(path: string): AtlasSource {
         `nothing was compiled against the pack — ${unread.join('; ')}`,
     );
   }
-  return { path, dir: dirname(path), parsed, byName };
+  return { path, dir: dirname(path), parsed, byName, grids };
 }
 
 /**
@@ -1634,6 +1685,7 @@ function resolveFromAtlas(
   const info = readPngInfo(absPath);
   const page = relative(outDir, absPath).split('\\').join('/');
   const scale = found.page.scale;
+  const grid = atlas.grids.get(found.page.name);
   return {
     region,
     page,
@@ -1647,6 +1699,7 @@ function resolveFromAtlas(
     isBase,
     atlas: found.region,
     ...(scale === 1 ? {} : { atlasScale: scale }),
+    ...(grid === undefined ? {} : { pageGrid: grid }),
   };
 }
 
@@ -1827,8 +1880,17 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   /** The pre-packed atlas `--atlas-in` named, parsed once, or null. */
   const atlasIn = opts.atlasInPath === undefined ? null : readAtlasIn(resolve(opts.atlasInPath));
 
-  const addImage = (relPath: string, baseDir: string, isBase: boolean): CompiledImage => {
-    const region = basename(relPath, '.png');
+  const addImage = (
+    relPath: string,
+    baseDir: string,
+    isBase: boolean,
+    region: string = basename(relPath, '.png'),
+    /**
+     * The directory this part counts as named in, for `skeletonImagesPath`, or
+     * `null` for none. Default: the file's own directory, as it always was.
+     */
+    partDir: string | null = dirname(resolve(baseDir, relPath)),
+  ): CompiledImage => {
     if (seenRegions.has(region)) {
       throw new CompileError(`duplicate region name "${region}" (${relPath})`);
     }
@@ -1839,7 +1901,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         : resolveFromAtlas(relPath, region, isBase, outDir, atlasIn);
     seenRegions.add(region);
     regionSource.set(region, loosePath);
-    partDirs.add(dirname(loosePath));
+    if (partDir !== null) partDirs.add(partDir);
     images.push(img);
     return img;
   };
@@ -1885,6 +1947,63 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     );
   };
 
+  /**
+   * Measure and atlas every frame of one attachment's `sequence` — by NAME, the
+   * way the loader will ask for them (issue #729).
+   *
+   * Frame `i` is the region `sequenceFrameRegion(stem, …, i)`; on the loose
+   * route its pixels are the PNG of that name under the images directory, and
+   * under `--atlas-in` they are the pack's region of that name. A frame that is
+   * not there is refused with its number and the name looked for: the loader's
+   * own miss is `Region not found in atlas: <name> (attachment: <name>)`, which
+   * says neither that the region was frame 3 of a series nor which series.
+   *
+   * ⚠️ The region is the frame's FULL name, not a basename — an editor names a
+   * series in an images subfolder `fx/flame_0001`, and that string is what the
+   * loader looks up. A frame another attachment already atlased from the same
+   * file is the same region on purpose, as `addSkinImage` allows for one PNG.
+   */
+  const addSequenceFrames = (stem: string, seq: RigSequence, where: string): void => {
+    for (let i = 0; i < seq.count; i++) {
+      const region = sequenceFrameRegion(stem, seq, i);
+      const relPath = `${region}.png`;
+      const wanted = resolve(imagesDir, relPath);
+      const frame = `frame ${i} of ${seq.count} (number ${(seq.start ?? 1) + i})`;
+      if (atlasIn === null && !existsSync(wanted)) {
+        throw new CompileError(
+          `${where}: sequence ${frame} is the region "${region}", and there is no PNG for it at ${wanted}. A ` +
+            `sequence's frames are the regions "<stem><start + i>", zero-padded to "digits" — here stem ` +
+            `${JSON.stringify(stem)}, start ${seq.start ?? 1}, digits ${seq.digits ?? 0} — and the compiler draws ` +
+            'no frame in place of another. Add the file, or state the "count" the series really has.',
+        );
+      }
+      if (atlasIn !== null && !atlasIn.byName.has(region)) {
+        const near = nearMisses(region, atlasIn.byName.keys());
+        throw new CompileError(
+          `${where}: sequence ${frame} is the region "${region}", which the atlas at ${atlasIn.path} does not have. ` +
+            (near.length ? `Did you mean ${near.map((n) => JSON.stringify(n)).join(', ')}? ` : '') +
+            `A sequence's frames are the regions "<stem><start + i>", zero-padded to "digits" — here stem ` +
+            `${JSON.stringify(stem)}, start ${seq.start ?? 1}, digits ${seq.digits ?? 0} — and the compiler draws ` +
+            'no frame in place of another.',
+        );
+      }
+      const already = regionSource.get(region);
+      if (already === wanted) continue;
+      if (already !== undefined) {
+        throw new CompileError(
+          `${where}: sequence ${frame} is the region "${region}", and the art already atlased under that name is ` +
+            `${already}, not ${wanted}. One region name is one set of pixels, so this frame would draw the other ` +
+            "file's. Rename one of them.",
+        );
+      }
+      // The directory the frame NAMES are relative to — the images root, not
+      // the frame's own subfolder, because the region name carries the folder —
+      // and only on the loose route: under `--atlas-in` the spec names no file
+      // for a frame, where an `image` is still a file the spec names.
+      addImage(relPath, imagesDir, false, region, atlasIn === null ? imagesDir : null);
+    }
+  };
+
   // A manifest may name a part the cut does not carry. A formation can declare
   // more slots than any one cut fills, and a cut that shares a sprite with the
   // scene around it has no plate of its own to point at — the manifest then
@@ -2072,6 +2191,19 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         if (typeof image === 'string') {
           addSkinImage(image, `skin "${skinName}" slot "${slotName}" attachment "${placeholder}"`);
         }
+        // `parseRigSpec` has refused a sequence on any kind but these three and
+        // proved its shape, so what is left is whether its frames exist. The stem
+        // is the region `path` the attachment resolves through, which with no
+        // `path` stated is the placeholder (`nameSkinAttachment` pins exactly that
+        // where a placeholder is contested).
+        const sequence = (att as RigRegionAttachment).sequence;
+        if (sequence !== undefined) {
+          addSequenceFrames(
+            (att as RigRegionAttachment).path ?? placeholder,
+            sequence,
+            `skin "${skinName}" slot "${slotName}" attachment "${placeholder}"`,
+          );
+        }
       }
       rigAttachmentNames.set(slotName, names);
     }
@@ -2395,6 +2527,16 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   /** kind -> the names it declares, for the "the rig declares: …" half of one. */
   const constraintNamesOfKind = new Map<string, string[]>();
   const declareConstraint = (name: string, type: string): void => {
+    // Reserved, because a track's `"physics": "*"` is the timeline that names no
+    // constraint (issue #726): a physics constraint of that name is one no track
+    // could key by name without meaning every global one instead.
+    if (type === 'physics' && name === EVERY_GLOBAL_PHYSICS) {
+      throw new CompileError(
+        `physics constraint "${EVERY_GLOBAL_PHYSICS}": the name is reserved — a motion spec's \`"physics": ` +
+          `"${EVERY_GLOBAL_PHYSICS}"\` is the timeline that names no constraint and drives every physics constraint ` +
+          'declaring the keyed property global, so a constraint called that could not be keyed by name. Rename it',
+      );
+    }
     constraintDeclared.add(constraintAt(type, name));
     constraintKinds.set(name, [...(constraintKinds.get(name) ?? []), type]);
     constraintNamesOfKind.set(type, [...(constraintNamesOfKind.get(type) ?? []), name]);
@@ -2568,7 +2710,40 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         const perMember = resolveMemberTrack(track, animName, targets, bones, trackDerivations);
         targets.forEach((target, index) => {
           const resolved = perMember.get(target)!;
-          if (family !== null) {
+          // The timeline that names no constraint (issue #726). Resolved against
+          // the constraints' own `…Global` flags rather than a name, and refused
+          // when it reaches none — the runtime would walk every physics
+          // constraint, skip each one, and the file would parse and do nothing.
+          const everyGlobal = family === 'physics' && target === EVERY_GLOBAL_PHYSICS;
+          if (everyGlobal && track.physics === undefined) {
+            throw new CompileError(
+              `animation "${animName}": group "${String(track.group)}" lists "${EVERY_GLOBAL_PHYSICS}", which is not a ` +
+                `constraint but the target that names none — write it as the track's \`"physics": "${EVERY_GLOBAL_PHYSICS}"\``,
+            );
+          }
+          if (everyGlobal) {
+            const physics = constraints.filter((one) => one.type === 'physics');
+            const flag = `${track.property}Global`;
+            const reached =
+              track.property === 'reset'
+                ? physics
+                : physics.filter((one) => one[flag] === true);
+            if (reached.length === 0) {
+              throw new CompileError(
+                `animation "${animName}" keys physics "${EVERY_GLOBAL_PHYSICS}" ${track.property}, the timeline that ` +
+                  `names no constraint and drives every physics constraint ` +
+                  (track.property === 'reset' ? 'the rig has' : `declaring "${flag}": true`) +
+                  ', and ' +
+                  (physics.length === 0
+                    ? 'the rig declares no physics constraint'
+                    : `none of ${physics.map((one) => `"${one.name}"`).join(', ')} does`) +
+                  ' — it would parse and move nothing. ' +
+                  (track.property === 'reset'
+                    ? 'Declare a physics constraint, or remove the track'
+                    : `Set "${flag}": true on the constraints it is for, or key one by name`),
+              );
+            }
+          } else if (family !== null) {
             const label = CONSTRAINT_TRACK_FAMILIES[family].label;
             // Resolved by name AND by type in the parser
             // (`findConstraint(name, PathConstraintData)`), which returns null on
@@ -2650,7 +2825,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
                 ? compileValueTrack(resolved, motion, animName, anim.duration, target, shift, BONE_TRACKS, 'bone')
                 : compileTrack(resolved, motion, animName, anim.duration, target, shift, attachmentIndex, darkSlots);
           for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
-          if (family !== null) (familyTimelines[family][target] ??= {})[track.property] = keys;
+          // Under the empty name, which is the file's own spelling of it.
+          if (family !== null) (familyTimelines[family][everyGlobal ? '' : target] ??= {})[track.property] = keys;
           else if (isBoneTrack) (boneTimelines[target] ??= {})[track.property] = keys;
           else (slotTimelines[target] ??= {})[track.property] = keys;
         });
@@ -2759,6 +2935,43 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
         ((deformTimelines[skinName] ??= {})[track.slot] ??= {})[track.attachment] = { deform: keys };
       }
 
+      // -- sequence timelines: the other attachment timeline (issue #729) -----
+      // Same triple, same table: `readAnimation` reads both names out of one
+      // attachment map, and one attachment may carry both. `deform` is written
+      // first where both exist, which is the order the parser tests them in.
+      const sequenceTracks: MotionSequenceTrack[] = anim.sequence ?? [];
+      for (const track of sequenceTracks) {
+        const skinName = track.skin ?? 'default';
+        const at = `animation "${animName}" sequence ${skinName}/${String(track.slot)}/${String(track.attachment)}`;
+        const table = skinTables.get(skinName);
+        if (!table) {
+          throw new CompileError(
+            `${at}: this rig emits no skin called "${skinName}" (it emits: ${[...skinTables.keys()].join(', ')})`,
+          );
+        }
+        const perSlot = table[track.slot];
+        if (!perSlot) {
+          throw new CompileError(
+            `${at}: skin "${skinName}" gives slot "${String(track.slot)}" no attachments` +
+              (slotNames.has(track.slot) ? '' : ', and this rig does not declare that slot at all'),
+          );
+        }
+        const attachment = perSlot[track.attachment];
+        if (!attachment) {
+          throw new CompileError(
+            `${at}: slot "${track.slot}" in skin "${skinName}" has no attachment "${String(track.attachment)}" ` +
+              `(it has: ${Object.keys(perSlot).join(', ')})`,
+          );
+        }
+        const keys = compileSequenceTrack(track, anim.duration, attachment, at);
+        for (const key of keys) compiledDuration = Math.max(compiledDuration, key.time as number);
+        const slot = ((deformTimelines[skinName] ??= {})[track.slot] ??= {});
+        if (slot[track.attachment]?.sequence) {
+          throw new CompileError(`${at}: two sequence timelines on one attachment; merge them into one`);
+        }
+        slot[track.attachment] = { ...(slot[track.attachment] ?? {}), sequence: keys };
+      }
+
       const drawOrder = anim.drawOrder ? compileDrawOrder(anim.drawOrder, animName, anim.duration, slots) : null;
       if (drawOrder) for (const key of drawOrder) compiledDuration = Math.max(compiledDuration, key.time as number);
 
@@ -2887,6 +3100,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     skeletonText: `${JSON.stringify(skeleton, null, 2)}\n`,
     atlasText,
     images,
+    pageGrids: atlasIn === null ? [] : [...atlasIn.grids].map(([page, grid]) => ({ page, said: grid.said })),
     droppedStates,
     absentParts,
     declaredDurations,
@@ -3060,8 +3274,14 @@ function skinAttachmentName(skinName: string, placeholder: string): string {
  * By the time either caller runs, a contested placeholder the **default** skin
  * fills has already been refused — see `refuseDefaultSkinContest` — so every
  * entry this composes for is a named skin's.
+ *
+ * 🔒 A third caller reads it from outside: `ingest` compares the name a source
+ * states against the one this returns, and reports the rename where the two
+ * differ (issue #746). It calls this rather than `skinAttachmentName` so that
+ * WHETHER a name is composed is read off the same line as WHAT it is — the
+ * separator and the contest test are each stated once, here.
  */
-function composeSkinAttachmentName(skinName: string, placeholder: string, contested: boolean): string | null {
+export function composeSkinAttachmentName(skinName: string, placeholder: string, contested: boolean): string | null {
   return contested ? skinAttachmentName(skinName, placeholder) : null;
 }
 
@@ -3867,12 +4087,120 @@ function attachmentPath(att: { path?: string; image?: string }, placeholder: str
   return region === placeholder ? undefined : region;
 }
 
+/**
+ * The atlas region frame `i` of a sequence resolves to — `Sequence.getPath`
+ * (`Sequence.js:124-132`) transcribed: the stem, then `start + i` left-padded
+ * with zeros to `digits`. `start` and `digits` take the parser's own defaults
+ * (`readSequence`: 1 and 0), which are the format's, not a guess.
+ *
+ * ⚠️ A second transcription of the rule exists in `validate.ts`
+ * (`attachmentRegionLookups`, the walk `A08` joins the atlas with), and that is
+ * deliberate: this module links no runtime, and the two are held to the loader
+ * independently — the one by `A08`, both by `A00`'s round trip, which asks the
+ * runtime's own `getPath` for every frame.
+ */
+function sequenceFrameRegion(stem: string, seq: RigSequence, i: number): string {
+  const frame = String((seq.start ?? 1) + i);
+  return `${stem}${'0'.repeat(Math.max(0, (seq.digits ?? 0) - frame.length))}${frame}`;
+}
+
+/** The emitted `sequence` block: the four fields exactly as the spec stated them. */
+function emitSequence(seq: RigSequence): SpineSequence {
+  const out: SpineSequence = { count: seq.count };
+  if (seq.start !== undefined) out.start = seq.start;
+  if (seq.digits !== undefined) out.digits = seq.digits;
+  if (seq.setup !== undefined) out.setup = seq.setup;
+  return out;
+}
+
+/**
+ * What a sequence attachment's frames measure, for the `width`/`height` a spec
+ * leaves out — or the refusal when they do not agree.
+ *
+ * An attachment has ONE size and every frame is mapped into it
+ * (`RegionAttachment.computeUVs(regions[i], … width, height …)` for each `i` in
+ * `Sequence.update`), so an omitted size is derivable only when every frame
+ * measures the same: that is the one number the frames state. Frames of
+ * different sizes state several, and picking one — the first, the setup frame,
+ * the largest — would be the compiler choosing a value the spec did not.
+ * Under `--atlas-in` a stated size that disagrees with a frame is refused as it
+ * is for a single region, for the same reason: the pack's rectangle is fixed.
+ */
+function sequenceFrameSize(
+  frames: readonly CompiledImage[],
+  stated: { width?: number; height?: number },
+  where: string,
+): { width?: number; height?: number } {
+  const out: { width?: number; height?: number } = {};
+  for (const field of ['width', 'height'] as const) {
+    const sizes = [...new Set(frames.map((img) => img[field]))];
+    if (stated[field] !== undefined) {
+      const packed = frames.find((img) => img.atlas !== undefined && img[field] !== stated[field]);
+      if (packed !== undefined) {
+        throw new CompileError(
+          `${where}: the spec says ${field} ${stated[field]} and sequence frame "${packed.region}" of the imported ` +
+            `atlas is ${packed[field]}; a packed frame's rectangle is fixed, so the two would produce a quad the ` +
+            'pack cannot fill',
+        );
+      }
+      out[field] = stated[field];
+    } else if (sizes.length === 1) {
+      out[field] = sizes[0];
+    } else {
+      throw new CompileError(
+        `${where}: the ${frames.length} frames of this sequence measure ${sizes.join(', ')} in ${field} ` +
+          `(${frames.map((img) => `"${img.region}" ${img[field]}`).join(', ')}), and an attachment has one ` +
+          `${field} every frame is drawn into. State "${field}" — the frames do not agree on one`,
+      );
+    }
+  }
+  return out;
+}
+
+/** Every frame of `att`'s sequence, already atlased by the gather pass. */
+function sequenceFrames(att: { path?: string; sequence?: RigSequence }, placeholder: string, where: string, ctx: AttachmentContext): CompiledImage[] {
+  const seq = att.sequence!;
+  const stem = att.path ?? placeholder;
+  const frames: CompiledImage[] = [];
+  for (let i = 0; i < seq.count; i++) {
+    // By the frame's FULL region name — `atlasedImage` takes a basename, and a
+    // series in an images subfolder is named `fx/flame_0001`.
+    const region = sequenceFrameRegion(stem, seq, i);
+    const img = ctx.images.find((im) => im.region === region);
+    if (img === undefined) {
+      // Unreachable while the gather pass atlases every frame of every sequence
+      // or refuses the missing one by name; stated so that a gather that stops
+      // doing so is a sentence rather than a quad with no region.
+      throw new CompileError(
+        `${where}: sequence frame ${i} is the region "${region}", which was never added to the atlas — every frame ` +
+          'of a sequence is atlased or refused by name before any attachment is built, so reaching this means rigc ' +
+          'skipped one',
+      );
+    }
+    frames.push(img);
+  }
+  return frames;
+}
+
 function buildRigRegion(
   att: RigRegionAttachment,
   placeholder: string,
   where: string,
   ctx: AttachmentContext,
 ): SpineRegionAttachment {
+  if (att.sequence !== undefined) {
+    const size = sequenceFrameSize(sequenceFrames(att, placeholder, where, ctx), att, where);
+    const out: SpineRegionAttachment = { width: r6(size.width!), height: r6(size.height!) };
+    if (att.path !== undefined) out.path = att.path;
+    if (att.x !== undefined) out.x = r6(att.x);
+    if (att.y !== undefined) out.y = r6(att.y);
+    if (att.rotation !== undefined) out.rotation = r6(att.rotation);
+    if (att.scaleX !== undefined) out.scaleX = r6(att.scaleX);
+    if (att.scaleY !== undefined) out.scaleY = r6(att.scaleY);
+    if (att.color !== undefined) out.color = att.color;
+    out.sequence = emitSequence(att.sequence);
+    return out;
+  }
   const img = att.image === undefined ? null : atlasedImage(att.image, where, ctx);
   // ⭐ An IMPORTED region's size is not a default the spec may override. On the
   // loose path `att.width` and the PNG's width are two legitimate numbers — "draw
@@ -3986,11 +4314,20 @@ function encodeNamedWeights(weights: RigMeshBinding[][], where: string, ctx: Att
  * what `extractRegion` does, so there is no unmeasurable case left for this
  * function to report and no catch here to keep reachable.
  */
-function measureAuthoredFit(att: RigMeshAttachment, ctx: AttachmentContext): MeshFitReport | null {
+function measureAuthoredFit(
+  att: RigMeshAttachment,
+  ctx: AttachmentContext,
+): MeshFitReport | { withheld: string } | null {
   if (att.image === undefined || att.uvs === undefined || att.triangles === undefined) return null;
   const region = basename(att.image, '.png');
   const img = ctx.images.find((im) => im.region === region);
   if (!img) return null;
+  // A third case, and neither of the two above (issue #750): there IS art to
+  // compare against, and its texels cannot be located, because its page's file
+  // is not the size the atlas declares. Withheld and said, rather than measured
+  // over whatever the declared coordinates land on — on a half-resolution pack
+  // that read 68.49% where the page it was packed from reads 100.00%.
+  if (img.pageGrid !== undefined) return { withheld: img.pageGrid.said };
   const plate = partPlate(img);
   const alpha = new Uint8Array(plate.width * plate.height);
   for (let i = 0; i < alpha.length; i++) alpha[i] = plate.data[i * 4 + 3];
@@ -4134,8 +4471,9 @@ function buildRigMesh(
   // spec stated, and the editor shows whatever is written here as the image's
   // dimensions (it showed 32x32, its missing-image placeholder, for a 0x0 mesh).
   const img = att.image === undefined ? undefined : atlasedImage(att.image, where, ctx);
-  const width = att.width ?? img?.width;
-  const height = att.height ?? img?.height;
+  const seqSize = att.sequence === undefined ? null : sequenceFrameSize(sequenceFrames(att, placeholder, where, ctx), att, where);
+  const width = seqSize !== null ? seqSize.width : (att.width ?? img?.width);
+  const height = seqSize !== null ? seqSize.height : (att.height ?? img?.height);
   if (width === undefined || height === undefined) {
     throw new CompileError(
       `${where}: a mesh needs width and height — give them, or give an "image" and rigc will measure the PNG`,
@@ -4154,12 +4492,14 @@ function buildRigMesh(
   const path = attachmentPath(att, placeholder);
   if (path !== undefined) out.path = path;
   if (att.color !== undefined) out.color = att.color;
+  if (att.sequence !== undefined) out.sequence = emitSequence(att.sequence);
   // Register it as `authored`: geometry rigc did not build and whose topology it
   // therefore gets to assume nothing about. The generator-topology assertions
   // read this and skip rather than measuring a ring that was never a ring.
   ctx.meshBones.add(ctx.anchorBone);
   for (const name of boundBones) ctx.meshBones.add(name);
-  const fit = measureAuthoredFit(att, ctx);
+  const measured = measureAuthoredFit(att, ctx);
+  const fit = measured === null || 'withheld' in measured ? null : measured;
   ctx.meshes.push({
     slot: ctx.slotName,
     kind: 'authored',
@@ -4169,6 +4509,7 @@ function buildRigMesh(
     bones: boundBones.length ? boundBones : [ctx.anchorBone],
     coverage: fit === null ? undefined : r6(fit.coverage),
     overshoot: fit?.overshoot,
+    ...(measured !== null && 'withheld' in measured ? { fitWithheld: measured.withheld } : {}),
   });
   return out;
 }
@@ -4248,8 +4589,9 @@ function buildRigLinkedMesh(
   // The art side is a mesh's, unchanged: a link draws its OWN region, which is
   // the reason the type exists — one triangulation, one outfit's pixels each.
   const img = att.image === undefined ? undefined : atlasedImage(att.image, where, ctx);
-  const width = att.width ?? img?.width;
-  const height = att.height ?? img?.height;
+  const seqSize = att.sequence === undefined ? null : sequenceFrameSize(sequenceFrames(att, placeholder, where, ctx), att, where);
+  const width = seqSize !== null ? seqSize.width : (att.width ?? img?.width);
+  const height = seqSize !== null ? seqSize.height : (att.height ?? img?.height);
   if (width === undefined || height === undefined) {
     throw new CompileError(
       `${where}: a linked mesh needs width and height — give them, or give an "image" and rigc will measure the PNG`,
@@ -4265,6 +4607,7 @@ function buildRigLinkedMesh(
   if (att.skin !== undefined && att.skin !== 'default') out.skin = att.skin;
   if (att.timelines === false) out.timelines = false;
   if (att.color !== undefined) out.color = att.color;
+  if (att.sequence !== undefined) out.sequence = emitSequence(att.sequence);
   // 🚫 NOT registered in `ctx.meshes`, and that is a decision rather than an
   // omission. `meshKinds` is keyed by SLOT and the commonest linked mesh shares
   // its source's slot from another skin, so an entry here would overwrite the
@@ -4526,8 +4869,13 @@ function sampleMeshDepth(
    *
    * The two are different questions and the header says why. This one has no
    * refusal behind it: it is counted, reported, and left to the author.
+   *
+   * `unlocated` in its place when the part's texels cannot be located — a
+   * region lifted off a page whose file is not its declared size (issue #750),
+   * carrying `pageGridSaid`'s clause — and the count is then `null` with that
+   * clause beside it: withheld, rather than taken off another part of the page.
    */
-  partAlpha: Uint8Array,
+  partAlpha: Uint8Array | { unlocated: string },
   partWidth: number,
   partHeight: number,
   where: string,
@@ -4587,7 +4935,7 @@ function sampleMeshDepth(
       // Zero, not a threshold: "the part image draws nothing here" is a fact
       // about the file, and any other cut-off would be rigc deciding how faint
       // a texel has to be before it stops counting as art.
-      if (partAlpha[at] === 0) drawn = false;
+      if (partAlpha instanceof Uint8Array && partAlpha[at] === 0) drawn = false;
     }
     if (!opaqueEverywhere && !covered) uncovered.push(v);
     if (!drawn) undrawn++;
@@ -4632,7 +4980,7 @@ function sampleMeshDepth(
       zScale: spec.zScale,
       tone,
       range: [r6(lo), r6(hi)],
-      undrawn,
+      ...(partAlpha instanceof Uint8Array ? { undrawn } : { undrawn: null, unlocated: partAlpha.unlocated }),
       ceiling: turnCeiling(
         points.map(([px, py]) => toBind(px, py)),
         z,
@@ -4870,7 +5218,11 @@ function buildGridAttachment(
           geometry.points,
           geometry.triangles,
           (px, py) => toBoneLocal(anchor, anchor.worldX + px * toArt - w / 2, anchor.worldY + h / 2 - py * toArt),
-          plateAlpha(plate),
+          // The lattice's geometry takes nothing off the texels — its window is
+          // the plate's size, which is the atlas's own `offsets` — so a page
+          // whose file is not its declared size costs a grid only this one
+          // count, and the count is what is withheld (issue #750).
+          img.pageGrid === undefined ? plateAlpha(plate) : { unlocated: img.pageGrid.said },
           plate.width,
           plate.height,
           where,
@@ -4959,6 +5311,24 @@ function buildContourAttachment(
     );
   }
   const img = atlasedImage(att.image, where, ctx);
+  // 🔒 **A trace needs the part's texels, and on a page that is not its
+  // declared size the lift does not have them** (issue #750). `extractRegion`
+  // addresses the page at the coordinates the atlas states; on a file of any
+  // other size those are a different part of the picture — measured on a
+  // half-resolution pack, the lift came back with no pixel above alpha 0 and
+  // the build refused with "there is no silhouette to trace", a true sentence
+  // about the wrong texels. Unlike an authored mesh's fit, which is a
+  // measurement and is withheld, this outline IS the geometry: there is no mesh
+  // to build without it, and the compiler invents none. So it is refused, with
+  // `A06`'s own sentence, which names the ratio and the repair — on `build`
+  // this refusal arrives before the gate, where `A06` would have said it.
+  if (img.pageGrid !== undefined) {
+    throw new CompileError(
+      `${where}: a "contour" generator traces the part's own alpha, and "${att.image}" is lifted off a packed ` +
+        'page at the coordinates the atlas states, which on this file are not where its texels are — so there is ' +
+        `no silhouette here to trace, only another part of the page. ${img.pageGrid.sentence}`,
+    );
+  }
   // ⚠️ Nothing here reads the PNG's colour type. `hasAlpha` answers "where does
   // this file keep its alpha", not "is any pixel of it transparent" — a tRNS
   // chunk is real transparency (issue #215) and an all-255 alpha channel is
@@ -5968,6 +6338,26 @@ function compileValueTrack(
       throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`);
     }
     checkKeyTime(where, time, key.t, duration);
+    // A named-value timeline (`inherit`): the key's `v` is one name, stepped by
+    // the format. The name is resolved rather than copied, and what is WRITTEN
+    // is the resolver's spelling — so `NoScale`, which the runtime also reads,
+    // emits as the `noScale` an editor writes, and a spelling the runtime
+    // cannot resolve never reaches the file at all.
+    if (shape.named !== undefined) {
+      if (key.ease !== undefined || key.curve !== undefined) {
+        throw new CompileError(
+          `${where} key at t=${key.t} carries ${key.ease !== undefined ? `an easing ("${key.ease}")` : 'a curve'}, and ` +
+            `this timeline is stepped by the format — its reader builds no curve, so the mode changes AT the key and ` +
+            'holds until the next one. Remove it',
+        );
+      }
+      const mode = shape.named.resolve(key.v);
+      if (mode === undefined) {
+        throw new CompileError(`${where} key at t=${key.t} names mode ${JSON.stringify(key.v)}; ${shape.named.known}`);
+      }
+      out.push({ time, [shape.named.field]: mode });
+      continue;
+    }
     // A no-field timeline (`reset`) is an event: the key IS the value, so it
     // carries none. Anything else must match the field count exactly.
     if (shape.fields.length === 0) {
@@ -6674,6 +7064,81 @@ function deformGeometryOf(
  * nothing guessed. What survives is the one case the identity does not cover: a
  * vertex whose weights do not close at 1.
  */
+/**
+ * One sequence timeline — `animations.<a>.attachments.<skin>.<slot>.<attachment>.sequence`
+ * — keyed on an attachment that carries a numbered series (issue #729).
+ *
+ * The key's own shape (`mode` among the seven, a whole `index`, a delay the
+ * parser will not divide by zero) is `parseMotionSpec`'s; what is refused here
+ * needs the emitted attachment:
+ *
+ *   - an attachment with no `sequence` block. The parser gives every region and
+ *     mesh a one-region series (`readSequence(null)` is `new Sequence(1,
+ *     false)`), so the timeline loads and every mode shows that one region —
+ *     measured: a `loop` key on a plain region showed it at every time.
+ *   - an `index` at or past the series' `count`. `Sequence.resolveIndex` clamps
+ *     it to the last frame (measured: `hold` at index 5 of 4 showed frame 4).
+ *   - a linked mesh that plays its source's timelines (`timelines` absent or
+ *     true). Its `timelineAttachment` is the SOURCE (`SkeletonJson.js:437-448`),
+ *     and `SequenceTimeline.applyToSlot` returns unless the slot's attachment's
+ *     `timelineAttachment` is the one the timeline was built for — so a key
+ *     aimed at the link itself is applied to nothing.
+ *
+ * Fields are emitted exactly as stated: an omitted `mode` is the parser's
+ * `"hold"`, an omitted `index` its 0, an omitted `delay` the previous key's —
+ * none of which the compiler writes for the spec.
+ */
+function compileSequenceTrack(
+  track: MotionSequenceTrack,
+  duration: number,
+  attachment: SpineAttachment,
+  where: string,
+): SpineTimelineKey[] {
+  const type = (attachment as { type?: string }).type ?? 'region';
+  const series = (attachment as { sequence?: SpineSequence }).sequence;
+  if (series === undefined) {
+    throw new CompileError(
+      `${where}: attachment "${track.attachment}" carries no "sequence" block, so there is no series to step. The ` +
+        'parser gives every region and mesh a series of ONE region (`readSequence(null)` is `new Sequence(1, ' +
+        'false)`), so this timeline would load and show that region under every mode at every time. Give the ' +
+        'attachment a "sequence" in the rig spec, or remove the track.',
+    );
+  }
+  if (type === 'linkedmesh' && (attachment as SpineLinkedMeshAttachment).timelines !== false) {
+    const source = (attachment as SpineLinkedMeshAttachment).source;
+    throw new CompileError(
+      `${where}: attachment "${track.attachment}" is a linked mesh that plays its source's timelines ("timelines" ` +
+        `is not false), so its \`timelineAttachment\` is "${source}" (\`SkeletonJson.js:437-448\`) and ` +
+        '`SequenceTimeline` applies only where the slot\'s attachment\'s `timelineAttachment` is the one it was ' +
+        `built for — a key aimed at the link is applied to nothing. Key "${source}" instead (the link steps its own ` +
+        'series by it), or set "timelines": false on the link.',
+    );
+  }
+  if (track.keys.length === 0) throw new CompileError(`${where}: no keys`);
+  const out: SpineTimelineKey[] = [];
+  for (let i = 0; i < track.keys.length; i++) {
+    const key = track.keys[i];
+    const time = keyTime(key.t);
+    if (i > 0 && time <= (out[i - 1].time as number)) {
+      throw new CompileError(`${where}: key times must strictly increase (at t=${key.t})`);
+    }
+    checkKeyTime(where, time, key.t, duration);
+    if (key.index !== undefined && key.index >= series.count) {
+      throw new CompileError(
+        `${where} (t=${key.t}): index ${key.index} is past the end of a ${series.count}-frame series (frames 0 to ` +
+          `${series.count - 1}). \`Sequence.resolveIndex\` clamps it to the last frame, so the key would start on a ` +
+          'frame it does not name. `index` is 0-based.',
+      );
+    }
+    const entry: SpineTimelineKey = { time };
+    if (key.mode !== undefined) entry.mode = key.mode;
+    if (key.index !== undefined) entry.index = key.index;
+    if (key.delay !== undefined) entry.delay = r6(key.delay);
+    out.push(entry);
+  }
+  return out;
+}
+
 function compileDeformTrack(
   track: MotionDeformTrack,
   motion: MotionSpec,