spine-rigc 2.11.1 → 2.13.0

package/src/compile.ts

@@ -2854,7 +2854,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
       partBySlot.has(rigSlot.name) &&
       (slotAttachments.get(rigSlot.name) ?? rigAttachmentNames.get(rigSlot.name) ?? []).length > 0,
   );
-  if (skinNames.includes(DEFAULT_SKIN) || partsFillDefault) tableFor(DEFAULT_SKIN);
+  // The stage box (issue #1168): resolved before the slots, so every refusal
+  // names the field before any slot is built — and a `default` skin is one it
+  // files the box under, so it is created here with the others.
+  const stageBox = resolveStageBox(rig, { stageWidth, stageHeight, bones, partBySlot, slotAttachments, rigAttachmentNames });
+  if (skinNames.includes(DEFAULT_SKIN) || partsFillDefault || stageBox !== null) tableFor(DEFAULT_SKIN);
   // ...and every skin the rig declares: a skin can carry `bones`/constraint lists
   // with no attachments at all, and a skin that only switches bones on would
   // otherwise never reach the emitted array.
@@ -2867,7 +2871,8 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
 
   for (const rigSlot of rig.slots) {
     const part = partBySlot.get(rigSlot.name);
-    const names = slotAttachments.get(rigSlot.name) ?? rigAttachmentNames.get(rigSlot.name) ?? [];
+    const boxHere = stageBox !== null && stageBox.slot === rigSlot.name;
+    const names = boxHere ? [stageBox.attachment] : (slotAttachments.get(rigSlot.name) ?? rigAttachmentNames.get(rigSlot.name) ?? []);
     // 🔑 A slot nothing fills is EMITTED, empty — it is not dropped (issue #575).
     // A `continue` stood here instead, and what it bought was the format's own
     // silence: the emitted array came back a slot short with no line saying
@@ -2969,6 +2974,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
     // As stated: `parseRigSpec` refused every spelling the runtime would read as no mode (issue #946).
     if (rigSlot.blend !== undefined) slot.blend = rigSlot.blend;
     slots.push(slot);
+    // The stage box is the slot's one attachment, in the `default` skin (issue #1168).
+    if (boxHere) {
+      tableFor(DEFAULT_SKIN)[rigSlot.name] = { [stageBox.attachment]: stageBox.record };
+      continue;
+    }
     // ...and nothing below this line has anything to build. An empty entry in a
     // skin's attachment table would be rigc writing a key the editor does not,
     // so the skins array is left exactly as it was before #575 for every slot
@@ -3625,7 +3635,7 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   // model's value into the header, as it writes `referenceScale`.
   const stage: ModelStage | null =
     stageWidth !== undefined && stageHeight !== undefined
-      ? { x: rig.skeleton?.x ?? 0, y: rig.skeleton?.y ?? 0, width: stageWidth, height: stageHeight }
+      ? { x: rig.skeleton?.x ?? 0, y: rig.skeleton?.y ?? 0, width: stageWidth, height: stageHeight, ...(stageBox === null ? {} : { box: { slot: stageBox.slot, attachment: stageBox.attachment } }) }
       : null;
   // What the skeleton carries that the model does not hold: the rest of the header.
   const header: Omit<SkeletonHeader, 'bounds'> = {
@@ -4448,6 +4458,112 @@ function bindingsOnF32(vertices: Extract<ModelVertices, { weighted: true }>): Ex
   };
 }
 
+/**
+ * The stage box a rig asked for (`skeleton.stageBox`, issue #1168), resolved:
+ * its slot and attachment name, and the bounding box `compile` files under
+ * them — or `null` for a rig that did not ask.
+ *
+ * ⭐ **Its numbers are the stage's and nobody else's.** The four vertices are
+ * the stage's corners in Spine world — `(x, y)`, `(x + w, y)`, `(x + w, y + h)`,
+ * `(x, y + h)`, the bottom-left first and counter-clockwise — the same four
+ * fields `ModelStage` holds and the coordinate transform reads, each written on
+ * the float32 grid every other emitted vertex is on. Nothing in the rig spec
+ * states them, so nothing can disagree with the stage.
+ *
+ * 🔒 **The box hangs on the root, and the root states no setup transform —
+ * or the box is refused.** Two readings were weighed. Computing local vertices
+ * through the inverse of any bone's setup transform would admit every bone,
+ * and the posed box would land on the stage only to within the float32
+ * rounding of those local numbers, a tolerance of the gate's own. Requiring an
+ * unmoved root makes the stored vertices the stage's numbers exactly —
+ * readable straight off the attachment by a consumer that poses nothing — and
+ * the posed box is those numbers through the runtime's frame of an unrotated
+ * root, whose `b` is cos 90° at the runtime's pi (−2.3e-8, measured: the
+ * compiler's own world transform of `gallery/nod`'s root, and the `-0.000016`
+ * of that build's header `x`), which `A50_STAGE_BOX_IS_THE_STAGE` holds on the
+ * header's grid with no new tolerance. A bone below the root is refused even
+ * when it states nothing, because that residue is taken once per level. A
+ * constraint that moves the root at setup is not seen here — the compiler
+ * poses no constraint — and is A50's to name, through the runtime.
+ *
+ * Refused by name: a slot `slots` does not declare; a slot something else
+ * fills (a skin entry, a manifest part); a slot on a bone below the root, or
+ * on a root that states a setup transform; a rig with no stage, which `parseRigSpec` already refuses
+ * for a stated absence and which cannot reach here otherwise.
+ */
+function resolveStageBox(
+  rig: RigSpec,
+  ctx: {
+    stageWidth: number | undefined;
+    stageHeight: number | undefined;
+    bones: readonly ModelBone[];
+    partBySlot: ReadonlyMap<string, unknown>;
+    slotAttachments: ReadonlyMap<string, readonly string[]>;
+    rigAttachmentNames: ReadonlyMap<string, readonly string[]>;
+  },
+): { slot: string; attachment: string; record: ModelBoundingBoxAttachment } | null {
+  const asked = rig.skeleton?.stageBox;
+  if (asked === undefined) return null;
+  const field = `skeleton.stageBox (slot "${asked.slot}", attachment "${asked.attachment}")`;
+  if (ctx.stageWidth === undefined || ctx.stageHeight === undefined) {
+    throw new CompileError(`${field}: the rig declares no stage, so there is no box to write — state skeleton.width and skeleton.height`);
+  }
+  const rigSlot = rig.slots.find((s) => s.name === asked.slot);
+  if (rigSlot === undefined) {
+    throw new CompileError(
+      `${field}: slot "${asked.slot}" is not one the rig declares. Declare it in "slots" — where it stands in the ` +
+        `array is its place in the draw order, and its "bone" is the box's bone — e.g. { "name": "${asked.slot}", "bone": "root", "attachment": "${asked.attachment}" }`,
+    );
+  }
+  const filledBy = [
+    ...(ctx.partBySlot.has(asked.slot) ? ['a cut manifest part'] : []),
+    ...((ctx.slotAttachments.get(asked.slot) ?? ctx.rigAttachmentNames.get(asked.slot) ?? []).length > 0
+      ? [`the attachment(s) [${(ctx.slotAttachments.get(asked.slot) ?? ctx.rigAttachmentNames.get(asked.slot) ?? []).join(', ')}]`]
+      : []),
+  ];
+  if (filledBy.length > 0) {
+    throw new CompileError(
+      `${field}: slot "${asked.slot}" is also filled by ${filledBy.join(' and ')}. The stage box is its slot's one ` +
+        'attachment, so a reader of that slot finds the stage and nothing else: give the box a slot of its own',
+    );
+  }
+  // The box's bone: the root, stating no setup transform — as built, so a root placed `from` the manifest is read as placed.
+  const bone = ctx.bones.find((b) => b.name === rigSlot.bone);
+  if (bone === undefined) {
+    throw new CompileError(`${field}: slot "${asked.slot}" names bone "${rigSlot.bone}", which the rig does not declare`);
+  }
+  if (bone.parent !== undefined) {
+    throw new CompileError(
+      `${field}: slot "${asked.slot}" hangs on bone "${rigSlot.bone}", which is not the root. The box's vertices are ` +
+        "the stage's corners in world space, written as they are, and the gate holds them on the header's grid " +
+        "through the runtime's own frame of an unrotated root; every bone below it adds that frame's residue once " +
+        "more (the runtime spells an unrotated b as cos 90° at its pi, -2.3e-8 per level). Put the slot on the root " +
+        `("${ctx.bones[0]?.name ?? 'root'}")`,
+    );
+  }
+  const stated = [
+    ...(['x', 'y', 'rotation', 'shearX', 'shearY'] as const).filter((key) => (bone[key] ?? 0) !== 0).map((key) => `${key} ${bone[key]}`),
+    ...(['scaleX', 'scaleY'] as const).filter((key) => (bone[key] ?? 1) !== 1).map((key) => `${key} ${bone[key]}`),
+  ];
+  if (stated.length > 0) {
+    throw new CompileError(
+      `${field}: slot "${asked.slot}" hangs on the root "${bone.name}", which states a setup transform (${stated.join(', ')}). ` +
+        "The box's vertices are the stage's corners in world space, written as they are, so the root must not move, " +
+        'turn, scale or shear at setup — move what the root carries onto a bone below it, or drop stageBox',
+    );
+  }
+  const x = rig.skeleton?.x ?? 0;
+  const y = rig.skeleton?.y ?? 0;
+  const right = x + ctx.stageWidth;
+  const top = y + ctx.stageHeight;
+  const record: ModelBoundingBoxAttachment = {
+    kind: 'boundingbox',
+    vertexCount: 4,
+    vertices: { weighted: false, xy: [x, y, right, y, right, top, x, top].map(f32) },
+  };
+  return { slot: asked.slot, attachment: asked.attachment, record };
+}
+
 function buildRigBoundingBox(
   att: RigBoundingBoxAttachment,
   where: string,

package/src/core/index.ts

@@ -243,6 +243,8 @@ export const CORE_PAGE_FIELDS = ['name', 'width', 'height', 'pma', 'scale', 'reg
 export const CORE_PAGE_FIELDS_2: readonly string[] = CORE_PAGE_FIELDS.filter((key) => key !== 'pma' && key !== 'scale');
 /** The stage's fields, as the writer lists them (`MODEL_STAGE_FIELDS` in `src/model.ts`, mirrored). */
 export const CORE_STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
+/** The stage box's fields (issue #1168), as the writer lists them (`MODEL_STAGE_BOX_FIELDS` in `src/model.ts`, mirrored). */
+export const CORE_STAGE_BOX_FIELDS = ['slot', 'attachment'] as const;
 export const CORE_PAGE_REGION_FIELDS = ['name', 'x', 'y', 'width', 'height', 'offsetX', 'offsetY', 'originalWidth', 'originalHeight', 'degrees', 'index'] as const;
 
 /** The fields a bone record may carry, as the writer lists them. A field outside this list is refused. */
@@ -484,12 +486,24 @@ function readStage(value: unknown, problems: string[]): ModelStage | null {
     return null;
   }
   const before = problems.length;
-  unknownFields(value, CORE_STAGE_FIELDS, 'stage', problems);
+  unknownFields(value, [...CORE_STAGE_FIELDS, 'box'], 'stage', problems);
   for (const key of CORE_STAGE_FIELDS) {
     const v = value[key];
     if (typeof v !== 'number' || !Number.isFinite(v)) problems.push(`stage: ${key} is ${JSON.stringify(v) ?? 'absent'}, not a finite number`);
   }
-  return problems.length === before ? { x: value.x as number, y: value.y as number, width: value.width as number, height: value.height as number } : null;
+  // The stage box (issue #1168): written only where the rig asked for one, and then exactly its two names.
+  const box = value.box;
+  if (box !== undefined) {
+    if (!isRecord(box)) problems.push(`stage.box is ${JSON.stringify(box)}, not { slot, attachment }`);
+    else {
+      unknownFields(box, CORE_STAGE_BOX_FIELDS, 'stage.box', problems);
+      for (const key of CORE_STAGE_BOX_FIELDS) if (typeof box[key] !== 'string' || box[key] === '') problems.push(`stage.box: ${key} is ${JSON.stringify(box[key]) ?? 'absent'}, not a non-empty string`);
+    }
+  }
+  if (problems.length !== before) return null;
+  const stage: ModelStage = { x: value.x as number, y: value.y as number, width: value.width as number, height: value.height as number };
+  if (isRecord(box)) stage.box = { slot: box.slot as string, attachment: box.attachment as string };
+  return stage;
 }
 
 /**

package/src/ingest.ts

@@ -221,6 +221,18 @@ export interface IngestOptions {
    * document beside the skeleton, only when its digest is that skeleton's).
    */
   documentStage?: IngestStage | null;
+  /**
+   * The slot whose bounding box carries the stage (issue #1168, `--stage-box
+   * <slot>`): a rig built with `skeleton.stageBox` carries its stage there,
+   * in the files a consumer ships, while the header carries the setup-pose
+   * bounding box. Named, that box is read as the stage — in place of the
+   * header's box, as `documentStage` is — and the rebuilt rig spec asks for
+   * the same box (`skeleton.stageBox`) instead of transcribing it as an
+   * attachment. Every shape `build` could not write back is refused by name
+   * (`readStageBox`). Absent, nothing is read from a slot: no box is the stage
+   * because of its name.
+   */
+  stageBox?: string;
   /** The source file's basename, for the provenance note. No path: no leak. */
   source: string;
   /** rigc's own version, for the provenance note. Passed in — `src/` reads no files. */
@@ -725,7 +737,8 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
   // stage is the only value in this whole module that a skeleton cannot answer
   // for. Since #578 a rig spec can SAY that a skeleton declares no stage, and
   // since #714 this is where a file that declares none is carried as saying so.
-  const rigHeader = ingestHeader(obj(root.skeleton), opts, note);
+  const stageBox = opts.stageBox === undefined ? null : readStageBox(root, opts.stageBox, note);
+  const rigHeader = ingestHeader(obj(root.skeleton), opts, note, stageBox);
 
   // -- physics constraints that drive nothing (issue #731) ------------------
   // Read before the skins, because a skin's `physics` member list is one of the
@@ -785,10 +798,13 @@ export function ingest(skeleton: unknown, opts: IngestOptions): IngestResult {
     for (const [slot, placeholders] of objEntries(entry.attachments)) {
       const perSlot: JsonObject = {};
       for (const [placeholder, att] of Object.entries(placeholders)) {
+        // The stage box is the rebuilt spec's `skeleton.stageBox`, which `build` writes from the stage — not an attachment to transcribe (issue #1168).
+        if (stageBox !== null && nameOf(entry) === 'default' && slot === stageBox.slot && placeholder === stageBox.attachment) continue;
         perSlot[placeholder] = ingestAttachment(obj(att), placeholder, boneNames, opts, note, {
           where: `skin "${nameOf(entry)}" slot "${slot}" attachment "${placeholder}"`,
         });
       }
+      if (stageBox !== null && nameOf(entry) === 'default' && slot === stageBox.slot) continue;
       table[slot] = perSlot;
     }
     const lists: JsonObject = {};
@@ -1158,6 +1174,115 @@ function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): st
   return [x ?? 0, y ?? 0, width, height].map((value) => String(value)).join(',');
 }
 
+/**
+ * The rig spec's header fields a skeleton's own header can state — every one
+ * but `stageBox`, which is the caller's reading of a slot (`--stage-box`,
+ * issue #1168) and never a key of the Spine header: a header that carried a
+ * key of that name would otherwise be copied into the rebuilt spec as a
+ * request for a box nobody named.
+ */
+const HEADER_FIELDS_FROM_FILE: readonly string[] = RIG_KEYS.RigSkeletonHeader.filter((field) => field !== 'stageBox');
+
+/** The stage box `--stage-box` read (`readStageBox`): its slot, its attachment and the stage its four corners are. */
+interface StageBoxRead {
+  slot: string;
+  attachment: string;
+  stage: IngestStage;
+}
+
+/**
+ * Read the stage from the bounding box in `slotName` (issue #1168,
+ * `--stage-box`): the box `build` writes for a rig that asks for one
+ * (`skeleton.stageBox`), read back as the rebuild's stage.
+ *
+ * 🔒 **Only a box `build` could write back is read, and everything else is
+ * refused by name** — the slot is named by the caller, so a shape that is not
+ * the stage is a mistake to report, not a guess to make. Refused: a slot the
+ * skeleton does not have; a slot on a bone other than the root, or on a root
+ * that states a setup transform (the box would not be the stage in world
+ * space, and `build` refuses the same); a slot with no attachment in the
+ * `default` skin, more than one, or one in another skin; an attachment that
+ * is not a bounding box, states a `name` other than its placeholder, or is not
+ * four unweighted vertices; four vertices that are not the corners of one
+ * axis-aligned rectangle of positive size.
+ *
+ * The stage is the rectangle's least corner and its extent. What the rebuild
+ * writes differently is one lossy finding, `STAGE_BOX_REWRITTEN`: `build`
+ * writes the corners bottom-left first and counter-clockwise and states no
+ * `color`, so a box in another order or with the editor's colour comes back as
+ * the same rectangle, spelled `build`'s way.
+ */
+function readStageBox(root: JsonObject, slotName: string, note: Note): StageBoxRead {
+  const flag = `--stage-box ${slotName}`;
+  const slot = arr(root.slots).map(obj).find((s) => s.name === slotName);
+  if (slot === undefined) {
+    throw new IngestError(`${flag}: the skeleton has no slot "${slotName}"; it declares [${arr(root.slots).map(nameOf).join(', ')}]`);
+  }
+  const bones = arr(root.bones).map(obj);
+  const bone = bones.find((b) => b.name === slot.bone);
+  if (bone === undefined || bone.parent !== undefined) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" hangs on bone "${String(slot.bone)}", which is not the root. A stage box is the stage's ` +
+        "corners in world space, and build writes one only on the root — on any other bone the box's numbers are not the stage",
+    );
+  }
+  const moved: string[] = [
+    ...['x', 'y', 'rotation', 'shearX', 'shearY'].filter((key) => bone[key] !== undefined && bone[key] !== 0),
+    ...['scaleX', 'scaleY'].filter((key) => bone[key] !== undefined && bone[key] !== 1),
+  ];
+  if (moved.length > 0) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" hangs on the root "${nameOf(bone)}", which states ${moved.map((key) => `${key} ${JSON.stringify(bone[key])}`).join(', ')}. ` +
+        "A box on a root that moves at setup is not the stage in world space, and build refuses to write one there",
+    );
+  }
+  const elsewhere = arr(root.skins).map(obj).filter((skin) => skin.name !== 'default' && Object.keys(obj(obj(skin.attachments)[slotName])).length > 0);
+  if (elsewhere.length > 0) {
+    throw new IngestError(
+      `${flag}: slot "${slotName}" is also filled by skin(s) ${elsewhere.map((skin) => `"${nameOf(skin)}"`).join(', ')}. A stage box is its ` +
+        "slot's one attachment, in the default skin, so a reader of that slot finds the stage and nothing else",
+    );
+  }
+  const table = obj(obj(arr(root.skins).map(obj).find((skin) => skin.name === 'default')?.attachments)[slotName]);
+  const placeholders = Object.keys(table);
+  if (placeholders.length !== 1) {
+    throw new IngestError(
+      `${flag}: the default skin holds ${placeholders.length === 0 ? 'no attachment' : `${placeholders.length} attachments [${placeholders.join(', ')}]`} on slot "${slotName}"; ` +
+        "a stage box is its slot's one attachment",
+    );
+  }
+  const attachment = placeholders[0];
+  const att = obj(table[attachment]);
+  const where = `${flag}: attachment "${attachment}" on slot "${slotName}"`;
+  if (att.type !== 'boundingbox') throw new IngestError(`${where} is a ${JSON.stringify(att.type ?? 'region')}, not a bounding box`);
+  if (att.name !== undefined && att.name !== attachment) {
+    throw new IngestError(`${where} states the name ${JSON.stringify(att.name)}; a stage box is named by its placeholder, which is what build writes`);
+  }
+  const vertices = Array.isArray(att.vertices) ? att.vertices : [];
+  if (att.vertexCount !== 4 || vertices.length !== 8 || !vertices.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+    throw new IngestError(
+      `${where} states vertexCount ${JSON.stringify(att.vertexCount)} and ${vertices.length} vertex number(s); the stage is four unweighted ` +
+        'corners — vertexCount 4 and eight finite numbers',
+    );
+  }
+  const xy = vertices as number[];
+  const xs = [...new Set([xy[0], xy[2], xy[4], xy[6]])].sort((a, b) => a - b);
+  const ys = [...new Set([xy[1], xy[3], xy[5], xy[7]])].sort((a, b) => a - b);
+  const corners = new Set([0, 2, 4, 6].map((i) => `${xy[i]},${xy[i + 1]}`));
+  if (xs.length !== 2 || ys.length !== 2 || corners.size !== 4) {
+    throw new IngestError(`${where} holds [${xy.join(', ')}], which is not the four corners of one axis-aligned rectangle of positive size`);
+  }
+  const stage: IngestStage = { x: xs[0], y: ys[0], width: xs[1] - xs[0], height: ys[1] - ys[0] };
+  const rewritten: string[] = [];
+  const order = [xs[0], ys[0], xs[1], ys[0], xs[1], ys[1], xs[0], ys[1]];
+  if (order.some((v, i) => v !== xy[i])) rewritten.push(`its corners [${xy.join(', ')}] in build's order [${order.join(', ')}], bottom-left first and counter-clockwise`);
+  if (att.color !== undefined) rewritten.push(`no color (the source states ${JSON.stringify(att.color)}, an editor affordance build does not write on a stage box)`);
+  if (rewritten.length > 0) {
+    note('lossy', 'STAGE_BOX_REWRITTEN', `skin "default" slot "${slotName}" attachment "${attachment}"`, `the rebuild writes the same rectangle with ${rewritten.join(', and ')}`);
+  }
+  return { slot: slotName, attachment, stage };
+}
+
 /**
  * The rig spec's `skeleton` block — and the one judgement in this module.
  *
@@ -1211,10 +1336,29 @@ function spellStage(x: unknown, y: unknown, width: unknown, height: unknown): st
  * a decompiler that is right for a reason it never states is a decompiler nobody
  * can check.
  */
-function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note): JsonObject {
-  // A rigc build's stage is its model document's (issue #907, `IngestOptions.documentStage`): read in place of the header's box.
-  const head: JsonObject = opts.documentStage === undefined ? source : Object.fromEntries(Object.entries(source).filter(([key]) => !(STAGE_FIELDS as readonly string[]).includes(key)));
-  if (opts.documentStage) Object.assign(head, opts.documentStage);
+function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note, box: StageBoxRead | null = null): JsonObject {
+  // The stage box the caller named (issue #1168) is the file's own statement of its stage, so a second source beside it is refused, as `--stage` beside a declared box is.
+  if (box !== null) {
+    const spelled = spellStage(box.stage.x, box.stage.y, box.stage.width, box.stage.height);
+    if (opts.stage !== undefined) {
+      throw new IngestError(
+        `--stage-box ${box.slot} reads a stage of ${spelled} from the skeleton's bounding box "${box.attachment}" and --stage supplied ` +
+          `${spellStage(opts.stage.x, opts.stage.y, opts.stage.width, opts.stage.height)}: two sources for one value. Drop one of the two flags`,
+      );
+    }
+    const doc = opts.documentStage;
+    if (doc !== undefined && (doc === null || spellStage(doc.x, doc.y, doc.width, doc.height) !== spelled)) {
+      throw new IngestError(
+        `--stage-box ${box.slot} reads a stage of ${spelled} from the skeleton's bounding box "${box.attachment}", and the model document ` +
+          `beside it states ${doc === null ? 'no stage' : spellStage(doc.x, doc.y, doc.width, doc.height)}: two statements of one stage that ` +
+          "disagree, about one build. rigc will not choose between them — A50_STAGE_BOX_IS_THE_STAGE refuses such a build, so one of the files was edited after it",
+      );
+    }
+  }
+  // A rigc build's stage is its model document's (issue #907, `IngestOptions.documentStage`) or its stage box's (issue #1168): read in place of the header's box.
+  const replaced = box !== null ? box.stage : opts.documentStage;
+  const head: JsonObject = replaced === undefined ? source : Object.fromEntries(Object.entries(source).filter(([key]) => !(STAGE_FIELDS as readonly string[]).includes(key)));
+  if (replaced) Object.assign(head, replaced);
   // 🚨 Before a line of transcription, because a header the caller contradicted
   // is not a header to start writing a spec from (issue #626).
   if (declaresStage(head) && opts.stage !== undefined) {
@@ -1226,9 +1370,11 @@ function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note): Json
     );
   }
   const out: JsonObject = {};
-  for (const field of RIG_KEYS.RigSkeletonHeader) if (head[field] !== undefined) out[field] = head[field];
+  for (const field of HEADER_FIELDS_FROM_FILE) if (head[field] !== undefined) out[field] = head[field];
+  // The stage box is the caller's reading of a slot, never a header key: a Spine header has no such field (issue #1168).
+  if (box !== null) out.stageBox = { slot: box.slot, attachment: box.attachment };
   for (const key of Object.keys(head)) {
-    if ((RIG_KEYS.RigSkeletonHeader as readonly string[]).includes(key)) continue;
+    if (HEADER_FIELDS_FROM_FILE.includes(key)) continue;
     if (HEADER_REDERIVED.includes(key)) {
       // Two-sided on purpose: the same fact reads as bookkeeping when the two
       // agree and as a warning when they do not, and a reader needs to be told
@@ -1285,7 +1431,7 @@ function ingestHeader(source: JsonObject, opts: IngestOptions, note: Note): Json
       // The absence, carried: the pair goes where `RIG_KEYS` orders it, so the
       // spec reads like one a transcriber would have written by hand.
       const carried: JsonObject = {};
-      for (const field of RIG_KEYS.RigSkeletonHeader) {
+      for (const field of HEADER_FIELDS_FROM_FILE) {
         if (field === 'width' || field === 'height') carried[field] = null;
         else if (out[field] !== undefined) carried[field] = out[field];
       }

package/src/model.ts

@@ -593,6 +593,22 @@ export interface ModelStage {
   y: number;
   width: number;
   height: number;
+  /**
+   * Where the stage also travels in the Spine files, when the rig asked for it
+   * (`skeleton.stageBox`, issue #1168): the slot and the attachment name of the
+   * bounding box `compile` wrote from these four numbers. Absent where the rig
+   * did not ask, so no document written before the field existed moves a byte;
+   * a `/3` reader that predates it refuses the field by name rather than
+   * reading the document without it. `A50_STAGE_BOX_IS_THE_STAGE` reads it on
+   * both suppliers.
+   */
+  box?: ModelStageBox;
+}
+
+/** The stage box a rig asked for (`ModelStage.box`): the slot it is in and its attachment name. */
+export interface ModelStageBox {
+  slot: string;
+  attachment: string;
 }
 
 /**
@@ -883,7 +899,10 @@ function animationOf(animation: CompiledAnimation, where: string): { [key: strin
 
 /** The stage's fields, in the order the Spine header writes them. */
 export const MODEL_STAGE_FIELDS = ['x', 'y', 'width', 'height'] as const;
-const STAGE_FIELDS: readonly string[] = MODEL_STAGE_FIELDS;
+/** The stage box's fields (issue #1168), in `ModelStageBox`'s order. */
+export const MODEL_STAGE_BOX_FIELDS = ['slot', 'attachment'] as const;
+/** What the `stage` section writes: the four numbers, then the box where the rig asked for one. */
+const STAGE_FIELDS: readonly string[] = [...MODEL_STAGE_FIELDS, 'box'];
 
 /**
  * The `editorOrder` section: `{ skins: [{ name, slots }], animations }`,
@@ -1027,7 +1046,7 @@ export function modelDocument(model: CompiledModel, skeletonText: string, atlasT
   const doc: { [key: string]: DocValue } = {
     spec: MODEL_DOCUMENT_SPEC,
     referenceScale: plain(model.referenceScale, 'referenceScale'),
-    stage: model.stage === null ? null : ordered(model.stage, STAGE_FIELDS, 'stage'),
+    stage: model.stage === null ? null : ordered(model.stage, STAGE_FIELDS, 'stage', (key, v) => (key === 'box' ? ordered(v as object, MODEL_STAGE_BOX_FIELDS, 'stage.box') : plain(v, `stage.${key}`))),
     bones: model.bones.map((bone, i) =>
       ordered(bone, BONE_FIELDS, `bones[${i}]`, (key, v) => (key === 'editor' ? ordered(v as object, ['color', 'icon'], `bones[${i}].editor`) : plain(v, `bones[${i}].${key}`))),
     ),