spine-rigc 1.2.2 → 1.3.0

package/src/atlas.ts

@@ -51,7 +51,10 @@
  *     `regionWidth` and `pageWidth` are integers and the page is a power of two,
  *     so `u · pageWidth` recovers `regionX + localTexel` with nothing lost —
  *     which is why the eleven region-only rigs are already byte-identical, and
- *     why `PK18` can assert exactness rather than a bound;
+ *     why `PK18` can assert exactness rather than a bound. That holds for the
+ *     default power-of-two page only: `pageEdges: 'free'` gives it up, and the
+ *     region attachments of a free page sit at the mesh's bound of 1 (`PK72`,
+ *     and `packAtlas`, *free*);
  *   * on a **mesh** it is **not** 0 — 88 of 88 coordinates on `gallery/squash`'s
  *     ball, worst 3.15e-5 texels — because `spine-core` stores mesh page UVs in a
  *     **`Float32Array`**. `MeshAttachment.updateRegion` computes `u +
@@ -503,6 +506,18 @@ export interface EmitPage {
  * Rotation buys page area on a set of parts whose aspect ratios differ a lot. It
  * is not free and it is not implemented; a page that runs out of room spills to a
  * second page instead.
+ *
+ * 🔬 **Measured for issue #860, and held back on the measurement.** A pack that
+ * turned regions `rotate: 90` lifted every one of them back byte for byte through
+ * `extractRegion` (22 of 22 and 20 of 20 on two painting rigs, 12 turned on each),
+ * and rigc's renderer drew the turned region attachments with 0 differing pixels
+ * against the unturned pack. But on neither rig did a turn shrink the page: both
+ * were already on the smallest power-of-two page their area allows, and a turn
+ * that buys no area only moves bytes. Shipping it would also need two clauses
+ * changed that say rigc never turns a region — `A06`'s under `spine-html`
+ * ([`src/validate.ts`](validate.ts)) and `artUvsOf`
+ * ([`src/render.ts`](render.ts)), which returns no art UVs for a turned region
+ * attachment, so `check`'s texture substitution would report it unmatched.
  */
 export const PACK_NO_ROTATE = 0;
 
@@ -578,6 +593,21 @@ export const DEFAULT_PAGE_SIZE = 2048;
 /** What `--padding` defaults to. See `extrudeCell` for why it is not 0 and not 1. */
 export const DEFAULT_PADDING = 2;
 
+/**
+ * What a packed page's edges may be — `--page-edges`. See `packAtlas`, *Page size*.
+ *
+ * `pot` is the default and the only value until issue #860: both edges are powers
+ * of two. `free` lets the width be any multiple of `FREE_EDGE_STEP` and the height
+ * whatever the placement needs. What `free` costs is measured rather than
+ * conceded: a region attachment's sampling coordinate stops being exact and moves
+ * to `PK05`'s bound of one least significant bit, the bound a mesh already had.
+ */
+export const PAGE_EDGES = ['pot', 'free'] as const;
+export type PageEdges = (typeof PAGE_EDGES)[number];
+export const DEFAULT_PAGE_EDGES: PageEdges = 'pot';
+/** The step a `free` page's width is tried on. See `packAtlas`, *Page size*. */
+export const FREE_EDGE_STEP = 32;
+
 /** The part a page is packed from: its region name and its pixels. */
 export interface PackInput {
   region: string;
@@ -594,6 +624,8 @@ export interface PackOptions {
   padding?: number;
   /** Page filenames are `<stem>.png`, `<stem>2.png`, … — libgdx's own numbering. */
   pageStem?: string;
+  /** What the page's edges may be (default `pot`). See `PAGE_EDGES`. */
+  pageEdges?: PageEdges;
 }
 
 /** Where one region landed. `x`/`y` are the REGION's own corner, not its cell's. */
@@ -666,7 +698,9 @@ function floorPowerOfTwo(n: number): number {
 function smallestPageFor(
   cells: Array<{ w: number; h: number }>,
   maxEdge: number,
+  pageEdges: PageEdges,
 ): { width: number; height: number; rects: Rect[] } | null {
+  if (pageEdges === 'free') return smallestFreePageFor(cells, maxEdge);
   const edges: number[] = [];
   for (let e = 1; e <= maxEdge; e *= 2) edges.push(e);
   const candidates: Array<{ w: number; h: number }> = [];
@@ -680,6 +714,60 @@ function smallestPageFor(
   return null;
 }
 
+/**
+ * The smallest `free` page that holds these cells, and where they land on it —
+ * or `null` when they do not fit `maxEdge x maxEdge` at all.
+ *
+ * The rule, which `docs/AUTHORING.md` §0.1 states in the same words:
+ *
+ *   * the candidate WIDTHS are the multiples of `FREE_EDGE_STEP` from the widest
+ *     cell up to `maxEdge`, plus `maxEdge` itself (it is a power of two, so this
+ *     only adds anything when it is smaller than the step);
+ *   * at each width the cells are placed by the same MaxRects pass as a `pot`
+ *     page, on a page `maxEdge` tall, and the HEIGHT is the bottom edge of the
+ *     lowest cell — what that placement needs, not rounded;
+ *   * the page with the least area wins, then the squarer (smaller |width −
+ *     height|), then the narrower. Every candidate has a distinct width, so that
+ *     last key makes the order total and the answer a function of the cells.
+ *
+ * ⚠️ The height is read off one placement rather than searched for, and that is
+ * a definition, not an approximation of one: MaxRects' success is not monotonic
+ * in the page height (a shorter page changes which free rectangle scores best),
+ * so "the least height that fits" is not a quantity a bisection could find, and a
+ * definition that could not be computed exactly would not be deterministic.
+ */
+function smallestFreePageFor(
+  cells: Array<{ w: number; h: number }>,
+  maxEdge: number,
+): { width: number; height: number; rects: Rect[] } | null {
+  let widest = 0;
+  for (const cell of cells) widest = Math.max(widest, cell.w);
+  const widths: number[] = [];
+  for (let w = Math.ceil(widest / FREE_EDGE_STEP) * FREE_EDGE_STEP; w <= maxEdge; w += FREE_EDGE_STEP) widths.push(w);
+  if (widths[widths.length - 1] !== maxEdge && widest <= maxEdge) widths.push(maxEdge);
+  let best: { width: number; height: number; rects: Rect[] } | null = null;
+  for (const width of widths) {
+    const attempt = packOnePage(cells, width, maxEdge);
+    if (attempt.some((r) => r === null)) continue;
+    const rects = attempt as Rect[];
+    let height = 0;
+    for (const r of rects) height = Math.max(height, r.y + r.h);
+    if (best !== null) {
+      const area = width * height;
+      const bestArea = best.width * best.height;
+      if (area > bestArea) continue;
+      if (area === bestArea) {
+        const square = Math.abs(width - height);
+        const bestSquare = Math.abs(best.width - best.height);
+        if (square > bestSquare) continue;
+        if (square === bestSquare && width >= best.width) continue;
+      }
+    }
+    best = { width, height, rects };
+  }
+  return best;
+}
+
 /**
  * MaxRects with Best Short Side Fit, no rotation.
  *
@@ -856,11 +944,40 @@ function extrudeCell(page: Plate, source: Plate, cellX: number, cellY: number, p
  * transparency — 4 MiB of decoded RAM at the 2048 default. A single part whose
  * cell is bigger than the maximum is refused by name — silently splitting one
  * drawing across two pages is not a thing the format can express.
+ *
+ * ## `pageEdges: 'free'` — a page sized to the parts rather than to a power of two (issue #860)
+ *
+ * Opt-in, and the default stays `pot`: every runtime accepts a power-of-two page
+ * and the editor's own packer writes one by default — 9 of the 10 atlases in the
+ * fetched `examples/` corpus are power-of-two on both edges. Under `free` the
+ * search is `smallestFreePageFor`: widths on a `FREE_EDGE_STEP` grid, the height
+ * the placement needs, least area first, then squarer, then narrower. Everything
+ * else is shared — the MaxRects pass, the packing order, the spill rule (which
+ * parts share a page is still decided at `maxEdge x maxEdge`) and `--page-size`
+ * as the ceiling on both edges, floored to a power of two exactly as under `pot`.
+ *
+ * What it buys and what it costs, observed on two 20- and 22-part painting rigs:
+ * the page went from 1024x2048 to 1888x697 (2,097,152 to 1,315,936 texels,
+ * -37.3 %) and from 512x2048 to 480x1166 (1,048,576 to 559,680, -46.6 %). The cost is the exactness the paragraph above describes:
+ * `x / pageWidth` is no longer exact, so a REGION attachment's sampling
+ * coordinate joins a mesh's at `PK05`'s bound of one least significant bit
+ * against the loose build. It does not go past it, and no region's bytes change
+ * (`PK02`'s lift-back holds under both).
+ *
+ * ⚠️ `pot` is not the smaller answer's poor relation, and its search was never
+ * "double until it fits": it tries every power-of-two pair in order of area.
+ * On both rigs above the cells' own area (1,206,755 and 540,793 texels at
+ * padding 2) already exceeds the next power-of-two page down, so no `pot`
+ * packer could do better; the only lever left was the power of two itself.
  */
 export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResult {
   const pageSize = opts.pageSize ?? DEFAULT_PAGE_SIZE;
   const padding = opts.padding ?? DEFAULT_PADDING;
   const stem = opts.pageStem ?? 'skeleton';
+  const pageEdges = opts.pageEdges ?? DEFAULT_PAGE_EDGES;
+  if (!PAGE_EDGES.includes(pageEdges)) {
+    throw new CompileError(`--page-edges ${JSON.stringify(String(opts.pageEdges))}; known values: ${PAGE_EDGES.join(', ')}`);
+  }
   if (!Number.isInteger(pageSize) || pageSize < 1) {
     throw new CompileError(`--page-size must be a positive integer, got ${String(opts.pageSize)}`);
   }
@@ -884,7 +1001,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
     );
   }
 
-  const single = smallestPageFor(cells, maxEdge);
+  const single = smallestPageFor(cells, maxEdge, pageEdges);
 
   /** page index -> the placements on it, in packing order. */
   const perPage: Placement[][] = [];
@@ -943,6 +1060,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
       const shrunk = smallestPageFor(
         onPage.map((r) => r.cell),
         maxEdge,
+        pageEdges,
       );
       if (shrunk === null) {
         // Unreachable for the same reason as the stall above: these cells were

package/src/compile.ts

@@ -83,8 +83,11 @@ import {
   meshEdges,
   MeshError,
   ringControlAngles,
+  buildSegmentsLattice,
+  segmentShares,
   traceOutline,
   type MeshBoneRef,
+  type WorldSegment,
   type MeshFitReport,
   type MeshGeometry,
   type MeshVertexWeight,
@@ -5047,6 +5050,7 @@ function buildGeneratedMesh(
 ): SpineMeshAttachment {
   if (generator.kind === 'contour') return buildContourAttachment(att, generator, placeholder, where, ctx);
   if (generator.kind === 'grid') return buildGridAttachment(att, generator, placeholder, where, ctx);
+  if (generator.kind === 'segments') return buildSegmentsAttachment(att, generator, placeholder, where, ctx);
   const controls = generator.kind === 'ring' ? generator.controls : generator.chain;
   // Resolving the bone list and the setup transform is one step with two named
   // refusals, because the ring's control angles need the transform and the encode
@@ -5690,6 +5694,335 @@ function buildGridAttachment(
   return out;
 }
 
+/**
+ * Defaults for the `segments` generator's optional parameters, stated once.
+ *
+ * `power`, `maxBones` and `minWeight` are the constants the algorithm was
+ * ported with, and `alpha` is `contour`'s own. `cell` and `falloff.radius` have
+ * none: both are lengths on this part's art, and a length rigc chose would be a
+ * judgement about a drawing it has not been told anything about.
+ */
+const SEGMENTS_DEFAULTS = { power: 2, maxBones: 4, minWeight: 0.03, alpha: 1 } as const;
+
+/** The smallest share a `minWeight` may keep: one step of the 6-decimal grid weights are written on. */
+const SEGMENTS_WEIGHT_STEP = 0.000001;
+
+/** `[x, y]` as two finite numbers, or null. */
+function finitePair(v: unknown): [number, number] | null {
+  return Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && Number.isFinite(n))
+    ? [v[0] as number, v[1] as number]
+    : null;
+}
+
+/**
+ * Build a `segments` mesh: a lattice over the part's alpha, weighted by distance
+ * to the bone segments `bones` names.
+ *
+ * ⭐ `bones` is the one decision the author makes, and everything else is read
+ * off something already in front of the compiler: the lattice off the image's
+ * alpha, each segment off the skeleton's setup pose (a bone's origin, the next
+ * chain link's origin, a bone's `length` tip) or off the two points a span
+ * states, and every weight off the distance between a vertex and those
+ * segments. No segment is invented — a bone with no `length` and no next link
+ * has an origin and no segment, and is refused by name.
+ *
+ * The placement is the one every generator on this route uses — the slot bone
+ * at the window's centre — unless `anchor` says where in the part's pixels the
+ * slot bone sits, which is what a part drawn somewhere other than centred on
+ * its bone needs, because unlike a pinned generator this one's weights depend
+ * on where the art is relative to the bones.
+ */
+function buildSegmentsAttachment(
+  att: RigMeshAttachment,
+  generator: Extract<NonNullable<RigMeshAttachment['generator']>, { kind: 'segments' }>,
+  placeholder: string,
+  where: string,
+  ctx: AttachmentContext,
+): SpineMeshAttachment {
+  if (att.image === undefined) {
+    throw new CompileError(
+      `${where}: a "segments" generator lays its lattice over the part's own alpha, so the attachment needs an ` +
+        '"image" — there is nothing else here that says which pixels are art',
+    );
+  }
+  const img = atlasedImage(att.image, where, ctx);
+  if (img.pageGrid !== undefined) {
+    throw new CompileError(
+      `${where}: a "segments" generator lays its lattice over 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 art here to cover, only another part of the page. ${img.pageGrid.sentence}`,
+    );
+  }
+  if (img.atlasScale !== undefined) {
+    throw new CompileError(
+      `${where}: a "segments" generator measures its "cell" and its falloff "radius" in the part's pixels, and ` +
+        `"${att.image}" sits on a page that declares scale: ${img.atlasScale}, where a pixel of the drawing is not a ` +
+        'texel of the page. This generator does not convert between the two; build it from the loose part, or ' +
+        'from a pack at scale 1',
+    );
+  }
+
+  // -- the falloff -----------------------------------------------------------
+  const falloffSpec: unknown = generator.falloff;
+  if (typeof falloffSpec !== 'object' || falloffSpec === null || Array.isArray(falloffSpec)) {
+    throw new CompileError(
+      `${where}: the "segments" generator states no "falloff" block. Its "radius" — added to every distance, in ` +
+        "the part's pixels — has no default, because it is a length on this art: " +
+        '"falloff": { "radius": <pixels> } is the least it takes',
+    );
+  }
+  const f = generator.falloff;
+  if (typeof f.radius !== 'number' || !Number.isFinite(f.radius) || !(f.radius > 0)) {
+    throw new CompileError(
+      `${where}: "falloff.radius" is ${JSON.stringify(f.radius)}; it is added to every distance before the power is ` +
+        "taken, a positive number of the part's pixels — at 0 a vertex on a segment would carry an infinite pull",
+    );
+  }
+  const power = f.power ?? SEGMENTS_DEFAULTS.power;
+  if (typeof power !== 'number' || !Number.isFinite(power) || !(power > 0)) {
+    throw new CompileError(
+      `${where}: "falloff.power" is ${JSON.stringify(power)}; it is the exponent a pull falls off with distance by, ` +
+        'a positive number — at 0 or below the far segment pulls as hard as the near one, or harder',
+    );
+  }
+  const maxBones = f.maxBones ?? SEGMENTS_DEFAULTS.maxBones;
+  if (typeof maxBones !== 'number' || !Number.isInteger(maxBones) || maxBones < 1) {
+    throw new CompileError(
+      `${where}: "falloff.maxBones" is ${JSON.stringify(maxBones)}; it is how many bones may pull one vertex, a ` +
+        'whole number of at least 1',
+    );
+  }
+  const minWeight = f.minWeight ?? SEGMENTS_DEFAULTS.minWeight;
+  if (typeof minWeight !== 'number' || !Number.isFinite(minWeight) || minWeight < SEGMENTS_WEIGHT_STEP || minWeight >= 1) {
+    throw new CompileError(
+      `${where}: "falloff.minWeight" is ${JSON.stringify(minWeight)}; it is the share under which a bone's pull ` +
+        `is dropped, so it lies in ${SEGMENTS_WEIGHT_STEP}..1 with 1 excluded — at 1 or above every share is dropped, ` +
+        `and under ${SEGMENTS_WEIGHT_STEP}, one step of the 6-decimal grid weights are written on, a kept binding ` +
+        'could be written as 0',
+    );
+  }
+  const threshold = generator.alpha ?? SEGMENTS_DEFAULTS.alpha;
+
+  // -- the lattice -----------------------------------------------------------
+  const plate = partPlate(img);
+  let lattice;
+  try {
+    lattice = buildSegmentsLattice({
+      mask: { width: plate.width, height: plate.height, alpha: plateAlpha(plate) },
+      threshold,
+      cell: generator.cell,
+    });
+  } catch (err) {
+    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}`);
+    throw err;
+  }
+  const w = img.width;
+  const h = img.height;
+  if (att.width !== undefined && att.width !== w) {
+    throw new CompileError(`${where}: the spec says width ${att.width} and "${att.image}" measures ${w}`);
+  }
+  if (att.height !== undefined && att.height !== h) {
+    throw new CompileError(`${where}: the spec says height ${att.height} and "${att.image}" measures ${h}`);
+  }
+
+  // -- the placement ---------------------------------------------------------
+  const slotBone = ctx.transforms.get(ctx.anchorBone);
+  if (!slotBone) throw new CompileError(`${where}: slot bone "${ctx.anchorBone}" has no setup transform`);
+  let anchorAt: [number, number] = [w / 2, h / 2];
+  if (generator.anchor !== undefined) {
+    const stated = finitePair(generator.anchor);
+    if (stated === null) {
+      throw new CompileError(
+        `${where}: "anchor" is ${JSON.stringify(generator.anchor)}; it is where the slot bone sits in the part's ` +
+          'pixels, y down, as [x, y] — two finite numbers',
+      );
+    }
+    anchorAt = stated;
+  }
+  const [ax, ay] = anchorAt;
+  const place = (px: number, py: number): [number, number] => [
+    slotBone.worldX + (px - ax),
+    slotBone.worldY + (cropToSpineY(py, h) - cropToSpineY(ay, h)),
+  ];
+
+  // -- the segments ----------------------------------------------------------
+  if (!Array.isArray(generator.bones) || generator.bones.length === 0) {
+    throw new CompileError(
+      `${where}: the "segments" generator names no bones. "bones" is the one decision this generator takes — which ` +
+        'segments may pull the part — so it lists at least one: a bone name, a chain as a list of bone names, or ' +
+        '{ "bone", "from", "to" }',
+    );
+  }
+  const parentOf = new Map(ctx.bones.map((b) => [b.name, b.parent ?? null]));
+  const named: string[] = [];
+  const refs: MeshBoneRef[] = [];
+  const segments: WorldSegment[] = [];
+  const boneOf = (name: unknown, at: string): { index: number; transform: BoneTransform } => {
+    if (typeof name !== 'string' || !parentOf.has(name)) {
+      throw new CompileError(`${where}: ${at} names mesh bone ${JSON.stringify(name)}, which is not in the rig's bone list`);
+    }
+    let index = named.indexOf(name);
+    if (index < 0) {
+      index = named.length;
+      named.push(name);
+      refs.push(meshBoneRef(name, where, ctx));
+    }
+    return { index, transform: ctx.transforms.get(name)! };
+  };
+  const tipOf = (name: string, transform: BoneTransform, at: string, chained: boolean): [number, number] => {
+    const length = ctx.bones.find((b) => b.name === name)?.length ?? 0;
+    if (!(length > 0)) {
+      throw new CompileError(
+        `${where}: ${at} names bone "${name}", which has no "length"${chained ? ' and is the last link of its chain' : ''}, ` +
+          'so it has an origin and no segment. Give the bone a "length" (its segment runs from its origin to that ' +
+          'tip, along its setup rotation), ' +
+          (chained ? 'end the chain on a bone that has one, ' : 'name it inside a chain whose next link says where it ends, ') +
+          'or state the segment outright as { "bone", "from", "to" }',
+      );
+    }
+    return toWorld(transform, length, 0);
+  };
+  generator.bones.forEach((entry: unknown, i: number) => {
+    const at = `"bones"[${i}]`;
+    if (typeof entry === 'string') {
+      const { index, transform } = boneOf(entry, at);
+      segments.push({ bone: index, a: [transform.worldX, transform.worldY], b: tipOf(entry, transform, at, false) });
+      return;
+    }
+    if (Array.isArray(entry)) {
+      if (entry.length === 0) {
+        throw new CompileError(`${where}: ${at} is an empty chain; a chain lists its bones root first, at least one`);
+      }
+      const links = entry.map((name: unknown, k: number) => ({ name, ...boneOf(name, `${at}[${k}]`) }));
+      links.forEach((link, k) => {
+        const name = link.name as string;
+        const origin: [number, number] = [link.transform.worldX, link.transform.worldY];
+        if (k === links.length - 1) {
+          segments.push({ bone: link.index, a: origin, b: tipOf(name, link.transform, `${at}[${k}]`, true) });
+          return;
+        }
+        const next = links[k + 1];
+        const nextName = next.name as string;
+        let cursor = parentOf.get(nextName) ?? null;
+        while (cursor !== null && cursor !== name) cursor = parentOf.get(cursor) ?? null;
+        if (cursor === null) {
+          throw new CompileError(
+            `${where}: ${at} chains "${name}" to "${nextName}", and "${nextName}" is not under "${name}" in the bone ` +
+              `tree — a chain runs down the skeleton, each link a descendant of the one before it. List the chain ` +
+              'root first, or name the two bones as separate entries',
+          );
+        }
+        const b: [number, number] = [next.transform.worldX, next.transform.worldY];
+        if (b[0] === origin[0] && b[1] === origin[1]) {
+          throw new CompileError(
+            `${where}: ${at} chains "${name}" to "${nextName}", and the two bones share their setup origin ` +
+              `(${origin[0]}, ${origin[1]}), so the link has no length and no direction to weight along. Give ` +
+              `"${nextName}" its own position, or name "${name}" alone with a "length"`,
+          );
+        }
+        segments.push({ bone: link.index, a: origin, b });
+      });
+      return;
+    }
+    if (typeof entry === 'object' && entry !== null) {
+      const span = entry as { bone?: unknown; from?: unknown; to?: unknown };
+      const { index } = boneOf(span.bone, `${at}.bone`);
+      const from = finitePair(span.from);
+      const to = finitePair(span.to);
+      if (from === null || to === null) {
+        throw new CompileError(
+          `${where}: ${at} states a segment whose ${from === null ? '"from"' : '"to"'} is ` +
+            `${JSON.stringify(from === null ? span.from : span.to)}; both ends are [x, y] in the part's pixels, y down`,
+        );
+      }
+      segments.push({ bone: index, a: place(from[0], from[1]), b: place(to[0], to[1]) });
+      return;
+    }
+    throw new CompileError(
+      `${where}: ${at} is ${JSON.stringify(entry)}; an entry is a bone name, a chain as a list of bone names, or ` +
+        '{ "bone", "from", "to" }',
+    );
+  });
+
+  // -- the weights -----------------------------------------------------------
+  const falloff = { power, radius: f.radius, maxBones, minWeight };
+  const weights: MeshVertexWeight[][] = lattice.points.map(([px, py], v) => {
+    const got = segmentShares(place(px, py), segments, falloff);
+    if ('weights' in got) return got.weights;
+    throw new CompileError(
+      `${where}: vertex ${v}, at (${px}, ${py}) in the part's pixels, keeps no bone — the ${got.dropped.length} ` +
+        `strongest pull(s) share it as ${got.dropped.map((d) => `"${named[d.bone]}" ${d.share.toFixed(4)}`).join(', ')}, ` +
+        `and every one is under "minWeight" ${minWeight}. A vertex needs a bone, and rigc will not pick one the ` +
+        `falloff dropped: lower "minWeight" to ${(1 / maxBones).toFixed(4)} or under (1 / "maxBones", which the ` +
+        'strongest share can never fall below), or name a segment nearer this part of the art',
+    );
+  });
+  const geometry: MeshGeometry = {
+    kind: 'segments',
+    points: lattice.points,
+    uvs: lattice.uvs,
+    triangles: lattice.triangles,
+    weights,
+    hullVertices: lattice.hullVertices,
+  };
+  const vertices = encodeWeightedVertices(geometry, place, {
+    anchor: meshBoneRef(ctx.anchorBone, where, ctx),
+    controls: refs,
+  });
+
+  // -- the report ------------------------------------------------------------
+  let maxInfluence = 0;
+  let totalInfluence = 0;
+  let singleBone = 0;
+  const bound = new Set<number>();
+  for (const vertex of weights) {
+    maxInfluence = Math.max(maxInfluence, vertex.length);
+    totalInfluence += vertex.length;
+    if (vertex.length === 1) singleBone++;
+    for (const e of vertex) bound.add(e.control ?? 0);
+  }
+  const fit = measureAuthoredMeshFit(
+    { width: plate.width, height: plate.height, alpha: plateAlpha(plate) },
+    threshold,
+    lattice.points,
+    lattice.triangles,
+  );
+  ctx.meshBones.add(ctx.anchorBone);
+  for (const k of [...bound].sort((a, b) => a - b)) ctx.meshBones.add(named[k]);
+  ctx.meshes.push({
+    slot: ctx.slotName,
+    kind: 'segments',
+    attachments: [placeholder],
+    vertices: lattice.points.length,
+    triangles: lattice.triangles.length / 3,
+    bones: [...named],
+    coverage: f32(fit.coverage),
+    overshoot: fit.overshoot,
+    influence: {
+      maxBones: maxInfluence,
+      meanBones: f32(totalInfluence / weights.length),
+      singleBone,
+      bound: named.filter((_, k) => bound.has(k)),
+      cell: generator.cell,
+      cols: lattice.report.cols,
+      rows: lattice.report.rows,
+      artCells: lattice.report.artCells,
+      keptCells: lattice.report.keptCells,
+      islands: lattice.report.islands,
+    },
+  });
+  return {
+    type: 'mesh',
+    ...meshTextureKeys(att, placeholder),
+    uvs: geometry.uvs.map(f32),
+    triangles: geometry.triangles,
+    vertices: vertices.map(f32),
+    ...generatedHullAndEdges(geometry, where),
+    width: f32(w),
+    height: f32(h),
+  };
+}
+
 /** Defaults for the `contour` generator's optional parameters, stated once. */
 const CONTOUR_DEFAULTS = { margin: 1, maxVertices: 64, alpha: 1 } as const;
 
@@ -6548,6 +6881,8 @@ function buildRigInfo(
     editorRoundTrip: rig.invariants?.editorRoundTrip === true,
     // `parseRigSpec` resolved every entry against the rig's own constraints.
     consumerDrivenMix: (rig.invariants?.consumerDrivenMix ?? []).map((e) => ({ type: e.type, constraint: e.constraint, why: e.why })),
+    // `parseRigSpec` refused every shape but a non-blank `why`.
+    idleDrivesMeshes: rig.invariants?.idleDrivesMeshes?.why ?? null,
     // `isBase` is set on the manifest route only; every other image says false.
     basePlates: images.filter((img) => img.isBase).map((img) => img.region),
     meshSlotBudget: rig.invariants?.meshSlots ?? null,