spine-rigc 2.43.0 → 2.45.0

package/README.md

@@ -412,12 +412,13 @@ point*, *is this axis held*. It draws the build's art, framed as `render` frames
 and over it any of `bones` (origin to tip, a bone of length 0 marked as one),
 `names` (one label per pixel), `axes` (each bone's world x and y), `mesh` and `hull`
 (each mesh's edges and outline), `weights:<bone>` (what that bone moves, as a heat),
+`density` (each part's triangles per area against the figure's, on a log ramp),
 `slots` (the draw order at the pose), `grid` (in world units) and `declared`
 (each `invariants.axes` line and the bones held to it), at the setup pose, at
 `--animation <name> --at <s[,s…]>` — one picture, or a sheet — or zoomed with
 `--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`; `--bone`/`--hide-bone` pick the
 bones by glob, `--overlay-slot`/`--hide-overlay-slot` the slots whose mesh, hull,
-weights and number are drawn over the whole painting, and `--compare <dir>` draws a second build beside the first on one
+weights, density and number are drawn over the whole painting, and `--compare <dir>` draws a second build beside the first on one
 transform, to see what a change moved. Beside the PNG it writes a legend:
 the world-to-pixel transform both ways, what each colour means, and every bone's
 origin and tip in world units and in pixels, so a position read off the picture goes

package/docs/AUTHORING.md

@@ -10095,6 +10095,7 @@ pixel (`IN09`).
 | Did it break during the move? | any of the above `--animation <name> --at <s,s,…>` | one tile per time, left to right on one grid, each labelled with its time and frame |
 | What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
 | Does this part's edge follow that bone? | `--show art,weights:<bone>,mesh --overlay-slot <part> --zoom slot:<part>` | the part's own triangles and the bone's weight over them alone, over the whole painting. Where slots stack — a neck under the face, the hair, a collar — every mesh crossing the box is drawn and the heat is the union of every slot the bone moves, so the part's edge has no pixel of its own until the others are left out. The legend's `meshes[]` gives the part's weight for the bone at every vertex, so "does the top row follow the head" is read as numbers as well as colour |
+| Is this rig's density where its motion is? | `--show art,density --dim` | each region and mesh filled by its **ratio** — its triangles per world unit² over the figure's — on one ramp, log-scaled and centred on 1×: grey is as dense as the figure, pink to magenta denser (4×, 16×), light to dark green sparser (1/4×, 1/16×), clamped past the end stops (the stops are in the legend). A part's area is its posed mesh's own, the sum of its triangles' areas at the pose drawn, not the image's box; a region is two triangles over its quad. Where parts overlap the pixel is the part drawn last, as in the art, so a part under others is read with `--overlay-slot <part>`. The figure's totals are always over every slot the pose shows — the filter picks what is drawn and listed, never what the figure is — and the legend's `density` gives each slot's attachment, kind, vertices, triangles, hull, area, triangles per area, ratio and the bones it is weighted to, in draw order. A measurement, not a verdict: no bar is drawn, and `A13_MESH_BUDGET` stays the one gate on counts |
 | How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
 | Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |
 | Did this change move anything? | `--compare <dir>` beside any view | the same view of a second build beside the first, at the same times, on **one** world box and one transform, each half labelled `A`/`B` with the poser that posed it. A mark on a different pixel in the two halves is at a different place in the two rigs |
@@ -10151,11 +10152,12 @@ pixel (`IN09`).
   legend, and a left-out one says which flag left it out in `undrawn`. A pattern
   that matches no bone is refused naming the bones there are.
 - **`--overlay-slot <glob[,glob…]>`** draws the per-slot views — `mesh`, `hull`,
-  `weights:<bone>` and `slots` — only for the slots a pattern matches, and
+  `weights:<bone>`, `density` and `slots` — only for the slots a pattern matches, and
   **`--hide-overlay-slot <glob[,glob…]>`** for none of the ones it matches, applied
   after `--overlay-slot`; the patterns are globs, as `--bone`'s are. The **art is not
   filtered**: the painting is what the edge is read against, and `--dim` already
-  quiets it. A slot left out is absent from `meshes[]` and `slots[]`, and a slot kept
+  quiets it, and neither is the figure a `density` is measured against. A slot left
+  out is absent from `meshes[]`, `slots[]` and the density rows, and a slot kept
   keeps its number — its place in the whole draw order, not among the slots drawn. A
   pattern that matches no slot is refused naming the slots there are. It is not
   `--slot`: on `render` that flag draws a subset of the *art*, by exact name, which is
@@ -10182,7 +10184,15 @@ pixel (`IN09`).
   value; with `declared`, each entry's line in degrees, its two points, and each held
   bone's angle and how far off the line it is. With `names`, `labels[]`: each label's
   `text`, the `bones` it stands for, its `anchor` pixel, the `box` it is drawn in,
-  and whether it was `moved` or `overlaps`. With `mesh`, `hull` or `weights`,
+  and whether it was `moved` or `overlaps`. With `density`, `density`: the
+  `figure` at this tile's pose — `slots`, `triangles`, `area` (world units²) and
+  `trianglesPerArea`, over every slot whose attachment is a region or mesh — and
+  `slots[]`, one row per kept slot in draw order: `order`, `slot`, `attachment`,
+  `kind`, `alpha`, `vertices`, `triangles`, `hull`, `area`, `trianglesPerArea`,
+  `ratio`, the `rgba` it is painted, `bones` (how many bones it is weighted to —
+  a region's or an unweighted mesh's is its slot's one) and `boneNames`. A part
+  whose posed area is 0 has `trianglesPerArea` and `ratio` `null` and says why in
+  `why`; it is not painted. With `mesh`, `hull`, `weights` or `density`,
   `meshes[]`: every region and mesh the pose shows, in draw order, with its `kind`,
   `vertexCount`, `triangleCount`, `hull` (a mesh's hull vertex count), its unique
   triangle `edges` as vertex pairs, every posed vertex in `world` and `pixel`, and
@@ -10196,6 +10206,9 @@ pixel (`IN09`).
   was stated, or `viewport`).
 - `weights` — with `weights:<bone>`: the bone, the ramp's stops as RGBA, the floor
   below which nothing is painted, and how a pixel's weight is read.
+- `density` — with `density`: the ramp's stops (`ratio`, RGBA), the `scale` it is
+  read on (log₂ of the ratio, clamped at the end stops), and in words what `area`,
+  the figure's `totals` and the `ratio` are and how a pixel is painted.
 - `boneFilter` — `--bone` and `--hide-bone` as given.
 - `slotFilter` — `--overlay-slot` and `--hide-overlay-slot` as given; with it,
   `meshes[]` and `slots[]` list only the slots it keeps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/shared.ts

@@ -1064,7 +1064,9 @@ const FLAG_MEANINGS: Record<string, string> = {
   max: 'longest side of a rendered frame, in pixels (default 256)',
   show:
     `what \`inspect\` draws, comma-separated, from [${SHOW_SPELLINGS.join(', ')}] (default \`${DEFAULT_SHOW.join(',')}\`): art = the ` +
-    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; weights:<bone> = that bone's " +
+    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; density = each region and mesh " +
+    "filled by its triangles per world unit² over the figure's, on a log ramp centred on 1x that the legend states, with the " +
+    "figure's totals over every slot and each slot's row in the legend; weights:<bone> = that bone's " +
     'weight over every region and mesh it moves, as a heat on a ramp the legend states; mesh = each mesh\'s triangle edges; ' +
     "hull = each mesh's hull outline; declared = each invariants.axes " +
     "line through its two bones' origins, its held bones drawn in their own colour; bones = each bone from origin to tip, " +
@@ -1089,11 +1091,11 @@ const FLAG_MEANINGS: Record<string, string> = {
     "draw none of the bones these globs match — `--bone` the other way round, applied after it, so `--bone 'bang_*' " +
     "--hide-bone '*_ctl'` is the fringe chains without their control bones",
   'overlay-slot':
-    "draw the per-slot views — mesh, hull, weights:<bone> and slots — only for the slots these globs match (`*` any run of " +
+    "draw the per-slot views — mesh, hull, weights:<bone>, density and slots — only for the slots these globs match (`*` any run of " +
     "characters, `?` one, the whole name; comma-separated); the art is every slot's still, since it is what the geometry is read " +
-    "against. Not `--slot`: that flag draws a subset of the art on `render`, by exact name. The legend's meshes[] and slots[] list " +
-    'only the slots kept, a slot number stays its place in the whole draw order, and a pattern that matches no slot is refused ' +
-    'naming the slots there are',
+    "against. Not `--slot`: that flag draws a subset of the art on `render`, by exact name. The legend's meshes[], slots[] and " +
+    "density rows list only the slots kept — the figure's density totals stay over every slot —, a slot number stays its place in " +
+    'the whole draw order, and a pattern that matches no slot is refused naming the slots there are',
   'hide-overlay-slot':
     "draw none of the per-slot views for the slots these globs match — `--overlay-slot` the other way round, applied after it, " +
     "so `--overlay-slot 'hair_*' --hide-overlay-slot hair_back` is the hair but its back layer",

package/src/inspect.ts

@@ -36,6 +36,12 @@
  * the one a viewport pins), so a mark that sits on a different pixel in the two
  * halves sits at a different place in the two rigs.
  *
+ * ⭐ **Density is a measurement, never a verdict** (issue #1371). A part's
+ * triangles over its posed area, against the figure's — the triangles and area
+ * of every slot the pose shows, whatever a slot filter keeps. No bar, no
+ * budget: `A13_MESH_BUDGET` is the one gate on counts, and this only says where
+ * the triangles are.
+ *
  * Links nothing from the runtime: the poser is handed in.
  */
 import { createHash } from 'node:crypto';
@@ -69,7 +75,7 @@ import {
 export const INSPECT_SPEC = 'rigc-inspect/1';
 
 /** Every word `--show` takes, in the order the picture draws them (bottom first). `weights` is spelled `weights:<bone>`. */
-export const SHOW_WORDS = ['art', 'grid', 'weights', 'mesh', 'hull', 'declared', 'bones', 'axes', 'slots', 'names'] as const;
+export const SHOW_WORDS = ['art', 'grid', 'density', 'weights', 'mesh', 'hull', 'declared', 'bones', 'axes', 'slots', 'names'] as const;
 export type ShowWord = (typeof SHOW_WORDS)[number];
 
 /** The words as a refusal lists them — `weights` with the bone it needs. */
@@ -112,6 +118,32 @@ export const WEIGHT_RAMP: ReadonlyArray<{ weight: number; rgba: readonly [number
   { weight: 1, rgba: [215, 20, 20, 255] },
 ];
 
+/**
+ * The density ramp (issue #1371): a part's ratio — its triangles per world
+ * unit² over the figure's — painted at its colour here, interpolated **in log₂
+ * of the ratio** between the two stops either side, each channel rounded, and
+ * clamped to the end stops outside 1/16..16. Log because the ratio is a
+ * quotient: 4× and 1/4× are the same distance from the figure, and a linear
+ * ramp would spend half its colours between 8× and 16×.
+ *
+ * ⭐ **1× is a mid grey, neither hue, and not the background.** A part as dense
+ * as the figure reads as neutral, and is still visibly a part (the background is
+ * `[232, 232, 232]`, `--dim`'s art is paler still).
+ *
+ * ⭐ **Green to magenta, never blue to red** — ColorBrewer's PiYG ends with
+ * the light stops between them. The weights ramp says blue is 0 and red is 1,
+ * and an agent may read the two pictures side by side; a density ramp that ran
+ * blue to red would put "sparse" and "weight 0" in one colour. Neither end is a
+ * mark colour either: the mesh edge and hull drawn over a fill stay readable.
+ */
+export const DENSITY_RAMP: ReadonlyArray<{ ratio: number; rgba: readonly [number, number, number, number] }> = [
+  { ratio: 1 / 16, rgba: [39, 100, 25, 255] },
+  { ratio: 1 / 4, rgba: [161, 215, 106, 255] },
+  { ratio: 1, rgba: [185, 185, 185, 255] },
+  { ratio: 4, rgba: [233, 163, 201, 255] },
+  { ratio: 16, rgba: [142, 1, 82, 255] },
+];
+
 /** Below this weight a heat pixel is not painted. Not a rounding of any weight: it only keeps a weight of 0 that a barycentric sum spelled as 1e-17 off the picture. */
 export const WEIGHT_FLOOR = 1e-6;
 
@@ -172,8 +204,9 @@ export interface BoneFilter {
 
 /**
  * `--overlay-slot` / `--hide-overlay-slot`: which slots the per-slot views
- * (`mesh`, `hull`, `weights:<bone>`, `slots`) draw, by glob. The art is not
- * filtered — it is what the geometry is read against.
+ * (`mesh`, `hull`, `weights:<bone>`, `density`, `slots`) draw, by glob. The art
+ * is not filtered — it is what the geometry is read against — and neither is the
+ * figure a density is measured against.
  */
 export interface SlotFilter {
   /** Draw only the slots some pattern matches; absent draws every slot. */
@@ -189,7 +222,7 @@ export interface InspectRequest {
   weightsBone?: string;
   /** Which bones `bones`, `axes` and `names` draw; absent is every one. */
   boneFilter?: BoneFilter;
-  /** Which slots `mesh`, `hull`, `weights` and `slots` draw; absent is every one. */
+  /** Which slots `mesh`, `hull`, `weights`, `density` and `slots` draw; absent is every one. */
   slotFilter?: SlotFilter;
   dim: boolean;
   /** `null` is the setup pose. */
@@ -250,6 +283,14 @@ export interface InspectPlant {
   ignoreSlotFilter?: boolean;
   /** Draw the first build in both halves of a `--compare`. */
   compareFirstTwice?: boolean;
+  /** Density: take a part's area as its posed vertices' bounding box — the image's box, for an unrotated region — rather than its triangles'. */
+  densityAreaOfBox?: boolean;
+  /** Density: state and paint the figure's density over the part's, upside down. */
+  densityRatioInverted?: boolean;
+  /** Density: interpolate the ramp linearly in the ratio, not in its log. */
+  densityLinearRamp?: boolean;
+  /** Density: take the figure's totals over the slots the filter keeps, not over every slot. */
+  densityTotalsFiltered?: boolean;
 }
 
 /** A point in both spaces. */
@@ -299,7 +340,7 @@ export interface LegendLabel {
   overlaps: boolean;
 }
 
-/** One region or mesh the frame shows, when `mesh`, `hull` or `weights` is drawn — and, with a slot filter, that it keeps. */
+/** One region or mesh the frame shows, when `mesh`, `hull`, `weights` or `density` is drawn — and, with a slot filter, that it keeps. */
 export interface LegendMesh {
   slot: string;
   attachment: string;
@@ -346,6 +387,43 @@ export interface LegendDeclared {
   bones: Array<{ name: string; degrees: number | null; off: number | null }>;
 }
 
+/** One slot's row of the density table: one region or mesh the pose shows. */
+export interface LegendDensitySlot {
+  /** Its place in the posed draw order (0 is drawn first) — the number `slots` draws, filtered or not. */
+  order: number;
+  slot: string;
+  attachment: string;
+  kind: 'region' | 'mesh';
+  /** The slot colour × attachment colour alpha at this pose: a part at 0 is in the totals and draws nothing. */
+  alpha: number;
+  vertices: number;
+  triangles: number;
+  /** A mesh's hull vertex count; `null` for a region. */
+  hull: number | null;
+  /** The posed area: the sum of its triangles' absolute areas, world units². */
+  area: number;
+  /** `triangles / area`, per world unit²; `null` with `why` when the area is 0. */
+  trianglesPerArea: number | null;
+  /** `trianglesPerArea` over the figure's: the number to read. `null` with `why`. */
+  ratio: number | null;
+  /** The colour the part is painted, or `null` when it is not (no ratio, or a slot filter left it out of the picture — then it is not listed). */
+  rgba: number[] | null;
+  /** How many bones its vertices are weighted to (weight above 0) — a region's or an unweighted mesh's is its slot's one bone. */
+  bones: number;
+  /** Those bones, in the order the skeleton declares them. */
+  boneNames: string[];
+  /** `null`, or why `trianglesPerArea` or `ratio` has no value. */
+  why: string | null;
+}
+
+/** The figure's density at one tile's pose, and each kept slot's row. */
+export interface LegendDensity {
+  /** Over EVERY slot whose attachment at this pose is a region or mesh, whatever a slot filter keeps. */
+  figure: { slots: number; triangles: number; area: number; trianglesPerArea: number | null; why: string | null };
+  /** The slots the filter keeps, in the posed draw order. */
+  slots: LegendDensitySlot[];
+}
+
 export interface LegendTile {
   /** With `--compare`: which build this tile is — `A` is `--candidate`, `B` is `--compare`. */
   build?: 'A' | 'B';
@@ -364,6 +442,8 @@ export interface LegendTile {
   labels?: LegendLabel[];
   meshes?: LegendMesh[];
   slots?: LegendSlot[];
+  /** With `density`: the figure's totals and every kept slot's row. */
+  density?: LegendDensity;
   declared?: LegendDeclared[];
   grid?: { step: number; x: number[]; y: number[] };
 }
@@ -387,6 +467,8 @@ export interface InspectLegend {
   slotFilter?: { include: string[] | null; exclude: string[] | null };
   /** With `weights:<bone>`: the bone, the ramp a weight is painted with, and how a pixel's weight is read. */
   weights?: { bone: string; ramp: Array<{ weight: number; rgba: number[] }>; floor: number; reading: string };
+  /** With `density`: the ramp, its scale, and how area, totals and ratio are read. */
+  density?: { ramp: Array<{ ratio: number; rgba: number[] }>; scale: string; area: string; totals: string; ratio: string; reading: string };
   /** With `--compare`: each build, the poser that posed it and its `skeleton.json`'s sha256; a tile names its own in `build`. */
   builds?: Array<{ build: 'A' | 'B'; poser: 'core' | 'spine'; skeletonSha256: string }>;
   coordinates: { world: string; image: string; toPixel: string; toWorld: string };
@@ -748,6 +830,136 @@ function heatTriangle(plate: Plate, p: ReadonlyArray<[number, number]>, w: reado
   }
 }
 
+/**
+ * The density ramp's colour at `ratio`: interpolated in log₂ of the ratio
+ * between the two stops either side, each channel rounded, clamped to the end
+ * stops. `linear` is the mutant's reading — interpolated in the ratio itself.
+ */
+export function densityColour(ratio: number, linear = false): RGBA {
+  const at = (r: number): number => (linear ? r : Math.log2(r));
+  const first = DENSITY_RAMP[0];
+  const last = DENSITY_RAMP[DENSITY_RAMP.length - 1];
+  if (ratio <= first.ratio) return [...first.rgba] as RGBA;
+  if (ratio >= last.ratio) return [...last.rgba] as RGBA;
+  for (let i = 0; i + 1 < DENSITY_RAMP.length; i++) {
+    const lo = DENSITY_RAMP[i];
+    const hi = DENSITY_RAMP[i + 1];
+    if (ratio > hi.ratio) continue;
+    const t = (at(ratio) - at(lo.ratio)) / (at(hi.ratio) - at(lo.ratio));
+    return [0, 1, 2, 3].map((c) => Math.round(lo.rgba[c] + (hi.rgba[c] - lo.rgba[c]) * t)) as RGBA;
+  }
+  return [...last.rgba] as RGBA;
+}
+
+/** A posed attachment's area: the sum of its triangles' absolute areas, in the units its vertices are in. */
+export function trianglesArea(vertices: readonly number[], triangles: readonly number[]): number {
+  let sum = 0;
+  for (let t = 0; t + 2 < triangles.length; t += 3) {
+    const [a, b, c] = [triangles[t] * 2, triangles[t + 1] * 2, triangles[t + 2] * 2];
+    sum += Math.abs((vertices[b] - vertices[a]) * (vertices[c + 1] - vertices[a + 1]) - (vertices[c] - vertices[a]) * (vertices[b + 1] - vertices[a + 1])) / 2;
+  }
+  return sum;
+}
+
+/** The bounding box of the vertices, as an area — the density mutant's wrong reading of a part's size. */
+function boxArea(vertices: readonly number[]): number {
+  const xs = vertices.filter((_, i) => i % 2 === 0);
+  const ys = vertices.filter((_, i) => i % 2 === 1);
+  return (Math.max(...xs) - Math.min(...xs)) * (Math.max(...ys) - Math.min(...ys));
+}
+
+/** Every pixel whose centre the triangle holds, painted one colour — the heat's inside test. */
+function fillTriangle(plate: Plate, p: ReadonlyArray<[number, number]>, rgba: RGBA): void {
+  const [[x0, y0], [x1, y1], [x2, y2]] = p;
+  const area = (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0);
+  if (area === 0) return;
+  const left = Math.max(0, Math.floor(Math.min(x0, x1, x2)));
+  const right = Math.min(plate.width - 1, Math.floor(Math.max(x0, x1, x2)));
+  const top = Math.max(0, Math.floor(Math.min(y0, y1, y2)));
+  const bottom = Math.min(plate.height - 1, Math.floor(Math.max(y0, y1, y2)));
+  const inside = -1e-6;
+  for (let py = top; py <= bottom; py++) {
+    for (let px = left; px <= right; px++) {
+      const cx = px + 0.5;
+      const cy = py + 0.5;
+      const b0 = ((x1 - cx) * (y2 - cy) - (x2 - cx) * (y1 - cy)) / area;
+      const b1 = ((x2 - cx) * (y0 - cy) - (x0 - cx) * (y2 - cy)) / area;
+      if (b0 < inside || b1 < inside || 1 - b0 - b1 < inside) continue;
+      put(plate, px, py, rgba);
+    }
+  }
+}
+
+/**
+ * The density table at one pose: every region and mesh the pose shows, in the
+ * posed draw order, with the figure's totals over all of them — the slot filter
+ * decides which rows are listed and painted, never what the figure is. Read,
+ * never filled in: a part whose posed area is 0 has no density and says why,
+ * and a figure with no area has none either.
+ */
+function densityAt(
+  attachments: readonly AttachmentPose[],
+  rest: ReadonlyMap<string, AttachmentRest>,
+  weights: (slot: string, attachment: string) => VertexWeights | string,
+  boneOrder: readonly string[],
+  slotsOut: ReadonlySet<string>,
+  plant: InspectPlant,
+): LegendDensity {
+  const rows: Array<LegendDensitySlot & { kept: boolean }> = [];
+  for (const [order, shown] of attachments.entries()) {
+    const r = rest.get(restKey(shown.slot, shown.attachment));
+    if (r === undefined) throw new Error(`slot "${shown.slot}" attachment "${shown.attachment}": the rest table has no entry for it — the poser disagrees with itself`);
+    const read = weights(shown.slot, shown.attachment);
+    if (typeof read === 'string') throw new InspectError(`--show density: ${read}`);
+    const named = new Set<string>();
+    for (const run of read) for (const [bone, w] of run) if (w > 0) named.add(bone);
+    const boneNames = boneOrder.filter((b) => named.has(b));
+    const triangles = r.triangles.length / 3;
+    const area = plant.densityAreaOfBox ? boxArea(shown.vertices) : trianglesArea(shown.vertices, r.triangles);
+    rows.push({
+      order,
+      slot: shown.slot,
+      attachment: shown.attachment,
+      kind: r.kind,
+      alpha: shown.color[3],
+      vertices: shown.vertices.length / 2,
+      triangles,
+      hull: r.kind === 'mesh' ? (r.hull ?? null) : null,
+      area,
+      trianglesPerArea: area > 0 ? triangles / area : null,
+      ratio: null,
+      rgba: null,
+      bones: boneNames.length,
+      boneNames,
+      why: area > 0 ? null : 'its posed area is 0 — every triangle collapsed to a line or a point at this pose (a scale of 0 does), so it covers nothing and has no density',
+      kept: !slotsOut.has(shown.slot),
+    });
+  }
+  const over = plant.densityTotalsFiltered ? rows.filter((r) => r.kept) : rows;
+  const triangles = over.reduce((n, r) => n + r.triangles, 0);
+  const area = over.reduce((n, r) => n + r.area, 0);
+  const figurePerArea = area > 0 ? triangles / area : null;
+  const figure = {
+    slots: over.length,
+    triangles,
+    area,
+    trianglesPerArea: figurePerArea,
+    why: figurePerArea !== null ? null : over.length === 0 ? 'the pose shows no region or mesh' : "every part's posed area is 0, so the figure covers nothing and has no density",
+  };
+  const slots: LegendDensitySlot[] = [];
+  for (const { kept, ...row } of rows) {
+    if (!kept) continue;
+    if (row.trianglesPerArea !== null && figurePerArea !== null) {
+      row.ratio = plant.densityRatioInverted ? figurePerArea / row.trianglesPerArea : row.trianglesPerArea / figurePerArea;
+      row.rgba = [...densityColour(row.ratio, plant.densityLinearRamp === true)];
+    } else if (row.why === null) {
+      row.why = `the figure has no density: ${figure.why ?? ''}`;
+    }
+    slots.push(row);
+  }
+  return { figure, slots };
+}
+
 /** Two pixel boxes overlap, or sit with no clear pixel between them. */
 function crowds(a: PixelBox, b: PixelBox): boolean {
   return a.x < b.x + b.width + 1 && b.x < a.x + a.width + 1 && a.y < b.y + b.height + 1 && b.y < a.y + a.height + 1;
@@ -925,7 +1137,7 @@ interface Gathered {
   sha: string;
 }
 
-const MESH_VIEWS: readonly ShowWord[] = ['mesh', 'hull', 'weights'];
+const MESH_VIEWS: readonly ShowWord[] = ['mesh', 'hull', 'weights', 'density'];
 const restKey = (slot: string, attachment: string): string => `${slot}\u0000${attachment}`;
 
 /** A refusal about the second build says so: the same sentence, under the name of the build it is about. */
@@ -971,7 +1183,7 @@ function gather(tag: 'A' | 'B', candidate: Candidate, texts: InspectTexts, reque
       pages,
       lengths,
       axes,
-      weights: request.show.includes('weights') ? weightsReader(texts.skeletonText, request.skin) : null,
+      weights: request.show.includes('weights') || request.show.includes('density') ? weightsReader(texts.skeletonText, request.skin) : null,
       sha: createHash('sha256').update(texts.skeletonText).digest('hex'),
     };
   });
@@ -1120,6 +1332,30 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
               "Each vertex's weight is in its tile's meshes[].weights, read off skeleton.json",
           },
         }),
+    ...(request.show.includes('density')
+      ? {
+          density: {
+            ramp: DENSITY_RAMP.map((s) => ({ ratio: s.ratio, rgba: [...s.rgba] })),
+            scale:
+              "log2: a ratio's colour is interpolated in log2(ratio) between the two stops either side, each channel rounded; " +
+              `at or below ${DENSITY_RAMP[0].ratio} and at or above ${DENSITY_RAMP[DENSITY_RAMP.length - 1].ratio} it is the end stop's. ` +
+              '1, as dense as the figure, is the neutral grey',
+            area:
+              "a part's area is its posed mesh's own: the sum of its triangles' absolute areas in world units², through the vertices " +
+              "the pose carries — not the image's box and not its alpha. A region is two triangles over its quad",
+            totals:
+              "the figure's are over EVERY slot whose attachment at the pose is a region or mesh — whatever --overlay-slot and " +
+              '--hide-overlay-slot keep, whatever its alpha, wherever it lies against the box drawn',
+            ratio:
+              "a part's triangles per world unit² over the figure's (Σ triangles / Σ area): 2 is twice as dense as the figure, 0.5 " +
+              "half. null where a part's posed area is 0, with why",
+            reading:
+              "each kept part is filled with its ratio's colour — every pixel whose centre lies in one of its triangles — in the " +
+              "posed draw order, so where parts overlap the pixel is the part drawn last, as in the art. Each tile's density " +
+              "states the figure and every kept part's row, in draw order",
+          },
+        }
+      : {}),
     ...(compare ? { builds: builds.map((b) => ({ build: b.tag, poser: b.poser, skeletonSha256: b.sha })) } : {}),
     coordinates: {
       world: 'spine world: y up, world units',
@@ -1209,6 +1445,37 @@ function drawTile(
   // ── what a bone moves: weights under the edges, the edges under the hull ──
   let weighted = false;
   let anyMesh = false;
+  // ── density: each kept part filled with its ratio's colour, under the heat and the edges ──
+  if (build.rest !== null && build.weights !== null && request.show.includes('density')) {
+    const shownAll = frame.attachments ?? [];
+    const density = densityAt(shownAll, build.rest, build.weights, build.bones.map((b) => b.name), slotsOut, plant);
+    legendTile.density = density;
+    for (const row of density.slots) {
+      const shown = shownAll[row.order];
+      const rest = build.rest.get(restKey(shown.slot, shown.attachment));
+      if (rest === undefined || row.rgba === null) continue;
+      const rgba = row.rgba as RGBA;
+      const at = (v: number): [number, number] => {
+        const [px, py] = toPixel(shown.vertices[2 * v], shown.vertices[2 * v + 1]);
+        return [tx(px), ty(py)];
+      };
+      for (let t = 0; t + 2 < rest.triangles.length; t += 3) fillTriangle(tile, [at(rest.triangles[t]), at(rest.triangles[t + 1]), at(rest.triangles[t + 2])], rgba);
+    }
+    if (first) {
+      const f = density.figure;
+      const fmt = (n: number): string => String(Number(n.toPrecision(4)));
+      if (f.trianglesPerArea === null) notes.push(`density: ${f.why ?? ''} — nothing painted`);
+      else {
+        const by = density.slots.filter((r) => r.ratio !== null).sort((p, q) => (q.ratio ?? 0) - (p.ratio ?? 0) || p.order - q.order);
+        const at = (r: LegendDensitySlot): string => `"${r.slot}" at ${fmt(r.ratio ?? 0)}x`;
+        const ends =
+          by.length === 0 ? '' : by.length === 1 ? `; the one listed, ${at(by[0])}` : `; of the ${density.slots.length} listed, the densest ${at(by[0])}, the sparsest ${at(by[by.length - 1])}`;
+        notes.push(`density: the figure is ${f.triangles} triangles over ${Number(f.area.toFixed(2))} world units² across ${f.slots} slots${ends} — every row is in the legend`);
+        const unrated = density.slots.filter((r) => r.ratio === null);
+        if (unrated.length > 0) notes.push(`density: no ratio for ${unrated.map((r) => `"${r.slot}"`).join(', ')} — ${unrated[0].why ?? ''}`);
+      }
+    }
+  }
   if (build.rest !== null) {
     legendTile.meshes = [];
     const [mx, my] = plant.meshShift ?? [0, 0];

package/src/meshquality.ts

@@ -306,6 +306,54 @@ export interface MeshReductionInput {
    * a list. `protect.edges` keeps its meaning: a line held whole is listed there.
    */
   lines?: NamedLine[];
+  /**
+   * What refused each kept source vertex (issue #1374) — opt-in. Left out = the report is the one it was before the
+   * field existed, byte for byte, and no refusal is measured that the run would not measure. Set, `changes` ends in
+   * `kept` (`KeptRefusals`): for the last removal pass, the one that took nothing, each kept source vertex's reason
+   * counted per reason and split boundary / interior — and with `'by-vertex'` also listed vertex by vertex with the
+   * refusal's text. A refusal the deviation floor decided is measured in full to be named, in that pass only, as
+   * `blockingConstraint`'s is. No step, order or mesh reads it. Any other value, `null` included, is refused.
+   */
+  explainKept?: 'by-row' | 'by-vertex';
+}
+
+/**
+ * Issue #1374: why the kept source vertices are kept — `ReductionChanges.kept`, written last in `changes` and only when
+ * the input set `explainKept`. The reasons are read from the last removal pass, the one in which no step was taken, so
+ * every kept vertex not protected was attempted there once as a single removal, on the mesh the result carries (before
+ * any `retriangulate` post-pass). A vertex is boundary when it is a source-hull vertex — a kept source vertex is on the
+ * outline exactly then — and interior otherwise. Vertices the refinement inserted are never candidates and are not
+ * listed.
+ *
+ * A reason is the refusal's constraint without the object an author named: a row's code (`MQ_BOUNDARY_DEVIATION`,
+ * `MQ_SKINNING_RESIDUAL`, …, the region or line it names left in `refusal`), or a structural condition as the refusal
+ * opens — `retriangulation`, `outline`, `protect (a)`, `weightJump (b)`, `line`. A vertex no attempt in such a pass
+ * reached reads why, never an absence: `protected` (`protect`, or a line's end or crossing), and — when the run has no
+ * pass that took nothing — `budget-exhausted`, `replayed-to-accepted-step` or `no-removal-pass` (the refined source
+ * did not meet its targets, so no removal was tried), the termination it ended in.
+ */
+export interface KeptRefusals {
+  /** The 1-based removal pass the reasons were read from; null when the run had no pass that took nothing. */
+  pass: number | null;
+  /** One entry per reason that holds a kept source vertex, ascending by reason. `boundary + interior` over the entries is the kept source vertices. */
+  rows: KeptRow[];
+  /** `explainKept: 'by-vertex'` only: every kept source vertex, ascending by source index. */
+  vertices?: KeptVertex[];
+}
+
+/** Issue #1374: one reason, and the kept source vertices it holds on the outline and inside it. */
+export interface KeptRow {
+  reason: string;
+  boundary: number;
+  interior: number;
+}
+
+/** Issue #1374: one kept source vertex, its reason, and the refusal's text as `blockingConstraint` writes it — null for a reason no attempt gave. */
+export interface KeptVertex {
+  vertex: number;
+  boundary: boolean;
+  reason: string;
+  refusal: string | null;
 }
 
 /**
@@ -687,8 +735,10 @@ export interface ReductionChanges {
    * `stopAfterAccepted: k` replays to the operation at `acceptedAt[k - 1]`.
    */
   acceptedAt: AcceptedOperation[];
-  /** Issue #1283: which triangulation the mesh carries — present only when the input set `retriangulate`, written last. */
+  /** Issue #1283: which triangulation the mesh carries — present only when the input set `retriangulate`. */
   retriangulation?: Retriangulation;
+  /** Issue #1374: what refused each kept source vertex in the last removal pass — present only when the input set `explainKept`, written last. */
+  kept?: KeptRefusals;
 }
 
 export interface MeshQualityReport {
@@ -750,6 +800,8 @@ export interface EffectiveSettings {
   lines?: NamedLine[];
   /** A measurement's `lineSource`, by id and `sourceMeshDigest`, echoed when the input set it (issue #1326); absent otherwise. */
   lineSource?: { id: string; digest: string };
+  /** A reduction's `explainKept`, echoed when the input set it (issue #1374); absent otherwise. */
+  explainKept?: 'by-row' | 'by-vertex';
 }
 
 export interface MeshCounts {
@@ -2805,6 +2857,7 @@ function effectiveJson(e: EffectiveSettings): Json {
     ...(e.overBound === undefined ? {} : { overBound: { maxSamples: e.overBound.maxSamples, triangles: e.overBound.triangles } }),
     ...(e.lines === undefined ? {} : { lines: e.lines.map((l): Json => ({ name: l.name, vertices: [...l.vertices], closed: l.closed, maxDeviation: l.maxDeviation })) }),
     ...(e.lineSource === undefined ? {} : { lineSource: { id: e.lineSource.id, digest: e.lineSource.digest } }),
+    ...(e.explainKept === undefined ? {} : { explainKept: e.explainKept }),
   };
 }
 
@@ -2950,6 +3003,15 @@ function candidateJson(c: CandidateReport): Json {
               monotonicity: k.retriangulation.monotonicity,
             },
           }),
+      ...(k.kept === undefined
+        ? {}
+        : {
+            kept: {
+              pass: k.kept.pass,
+              rows: k.kept.rows.map((r) => ({ reason: r.reason, boundary: r.boundary, interior: r.interior })),
+              ...(k.kept.vertices === undefined ? {} : { vertices: k.kept.vertices.map((v) => ({ vertex: v.vertex, boundary: v.boundary, reason: v.reason, refusal: v.refusal })) }),
+            },
+          }),
     };
   }
   return out;

package/src/meshreduce.ts

@@ -90,6 +90,15 @@
  * of the triangles it changed; the result's own measurement reads the row in
  * full. Left out, nothing here reads it and the call is the one it was.
  *
+ * ## What refused each kept vertex (issue #1374, opt-in)
+ *
+ * With `explainKept`, the pass that ends the reduction having taken nothing
+ * keeps each single removal's refusal and names it once the pass is over — the
+ * working mesh is then the one every attempt in it was tried on, so a refusal
+ * the deviation floor decided is measured as `blockingConstraint`'s is — and the
+ * result's `changes.kept` counts the kept source vertices per reason, boundary
+ * and interior (`keptOf`). No step, order or mesh reads it.
+ *
  * A removal whose deviation floor — the furthest removed source-hull vertex
  * from the candidate's outline, which `MQ_BOUNDARY_DEVIATION` can only exceed —
  * is over the bound is refused without the measurement; its name, when read,
@@ -148,6 +157,8 @@ import {
   type CandidateReport,
   type DeformKeyInput,
   type EffectiveSettings,
+  type KeptRefusals,
+  type KeptVertex,
   type MeasureRow,
   type MeshCounts,
   type MeshMeasureInput,
@@ -344,6 +355,9 @@ function validateReduction(input: MeshReductionInput, plant: ReductionPlant | nu
   if ('removalOrder' in input && input.removalOrder !== undefined && input.removalOrder !== 'deformation-load') {
     refuse('REDUCE_INPUT_MISSING', `${who}: removalOrder is ${JSON.stringify(input.removalOrder)}; required "deformation-load" — single removals in ascending predicted deformation load, ties by source index — or the field left out (issue #1283: ascending source index)`);
   }
+  if ('explainKept' in input && input.explainKept !== undefined && input.explainKept !== 'by-row' && input.explainKept !== 'by-vertex') {
+    refuse('REDUCE_INPUT_MISSING', `${who}: explainKept is ${JSON.stringify(input.explainKept)}; required "by-row" — what refused the kept source vertices in the last removal pass, counted per reason — or "by-vertex" — those counts and every kept source vertex listed — or the field left out (issue #1374: no such block)`);
+  }
   // Issue #1287: refused here, before the admission measurement and any step, in the measurement's own words — the
   // admission does not carry the field, and a call whose source is refused never reaches the one measurement that does.
   if (plant !== 'amplitude-unvalidated') validateMotionAmplitude(who, input.motionAmplitude);
@@ -961,6 +975,18 @@ interface Run {
   hooks: SkinningHooks | null;
   /** Issue #1326: the declared lines, or null when the input left `lines` out. */
   lines: LineRun | null;
+  /** Issue #1374: the refusals of the current pass's single removals, and the last pass's once it took nothing — null when the input left `explainKept` out. */
+  kept: KeptLog | null;
+}
+
+/**
+ * Issue #1374: what `explainKept` reads. `attempts` is the current pass's single removals refused, by source vertex,
+ * as tried — a floor's refusal still a thunk, read only if the pass takes nothing; `final` is that pass's, read in
+ * the state it was tried in, once a pass ends having taken nothing.
+ */
+interface KeptLog {
+  attempts: Map<number, Refusal>;
+  final: { pass: number; refusals: Map<number, string> } | null;
 }
 
 /** Issue #1326: the input's lines as the steps read them. */
@@ -1486,7 +1512,14 @@ export type ReductionPlant =
   | OrderPlant
   | AmplitudePlant
   | RefinementPlant
-  | LinePlant;
+  | LinePlant
+  | KeptPlant;
+
+/**
+ * Issue #1374's fault, for the `mesh-quality` suite's control: each kept vertex named by the refusal of the next
+ * vertex refused in the last pass (the first's for the last) — a reason that did not refuse it.
+ */
+export type KeptPlant = 'kept-reason-shifted';
 
 /**
  * Issue #1326's faults in the line mechanism, for the `mesh-quality` suite's controls: the line rows read by no step
@@ -1909,6 +1942,7 @@ function removeVertices(run: Run): PhaseEnd {
     let taken = 0;
     let tried = 0;
     pass++;
+    if (run.kept !== null) run.kept.attempts = new Map();
     if (runs !== undefined) {
       let walk: number[] | null = null;
       for (let s = 0; s < hull; s++) {
@@ -1990,12 +2024,14 @@ function removeVertices(run: Run): PhaseEnd {
         if (accept(run, 'removal', [v])) return { kind: 'replayed' };
       } else {
         lastBlock = { refusal: block, what: `removing source vertex ${v}` };
+        if (run.kept !== null) run.kept.attempts.set(v, block);
         if (run.hooks?.plant === 'veto-ends-search' && typeof block === 'string' && block.startsWith('MQ_SKINNING_RESIDUAL')) return { kind: 'stuck', constraint: lastName() };
       }
     }
     if (taken === 0) {
       // A pass that took nothing left the working mesh as it found it, so a refusal the floor decided is measured
       // now in the state it was decided in.
+      if (run.kept !== null) run.kept.final = { pass, refusals: new Map([...run.kept.attempts].map(([v, r]) => [v, refusalText(r)])) };
       const kept = run.lines === null ? '' : ", or an open line's end or a vertex two lines list";
       const constraint = tried === 0 ? `protect: every surviving source vertex is protected (protect.hull, protect.vertices, protect.edges, protect.regionBoundaries or a weightJump edge${kept})` : lastName();
       return { kind: 'stuck', constraint };
@@ -2688,6 +2724,7 @@ function reduceValidated(
       skinning: null,
       hooks,
       lines: null,
+      kept: input.explainKept === undefined ? null : { attempts: new Map(), final: null },
     };
     run.skinning = skinningRunOf(run, skinningAdmitted);
     run.lines = lineRunOf(run);
@@ -2880,6 +2917,7 @@ function finish(run: Run, effective: EffectiveSettings, sourceCounts: MeshCounts
     linkedMeshes: input.linkedMeshes,
     acceptedAt: run.acceptedAt.map((a) => ({ step: a.step, kind: a.kind, count: a.count, sourceVertices: [...a.sourceVertices] })),
     ...(retriangulation === undefined ? {} : { retriangulation }),
+    ...(run.kept === null ? {} : { kept: keptOf(run, termination) }),
   };
   const counts = candidate.counts!;
   const mesh: ReducedMesh = {
@@ -2894,6 +2932,62 @@ function finish(run: Run, effective: EffectiveSettings, sourceCounts: MeshCounts
   return { mesh, report: reportOf(effective, sourceCounts, { ...candidate, changes }, termination) };
 }
 
+/**
+ * A refusal's reason (issue #1374, `KeptRefusals`): a row's code, or the structural condition the refusal opens with.
+ * Every refusal a step writes opens with one of them; one that does not is a defect here, thrown rather than named.
+ */
+function refusalReason(text: string): string {
+  const code = /^MQ_[A-Z0-9_]+/.exec(text);
+  if (code !== null) return code[0];
+  if (text.startsWith('line "')) return 'line';
+  for (const condition of ['retriangulation', 'outline', 'protect (a)', 'weightJump (b)']) if (text.startsWith(`${condition}:`)) return condition;
+  throw new Error(`issue #1374: a refusal opens with no reason KeptRefusals names: "${text.slice(0, 120)}"`);
+}
+
+/**
+ * Issue #1374: `ReductionChanges.kept` — every kept source vertex with its reason: `protected`, else its refusal in the
+ * last pass when one took nothing, else the termination that ended the run without one.
+ */
+function keptOf(run: Run, termination: Termination): KeptRefusals {
+  const { work } = run;
+  const hull = run.input.source.hull;
+  const final = run.kept!.final;
+  const unreached = final !== null ? null : termination.reason === 'budget-exhausted' || termination.reason === 'replayed-to-accepted-step' ? termination.reason : 'no-removal-pass';
+  let refusals = final?.refusals ?? null;
+  if (refusals !== null && run.plant === 'kept-reason-shifted') {
+    const order = [...refusals.keys()].sort((a, b) => a - b);
+    refusals = new Map(order.map((v, i) => [v, refusals!.get(order[(i + 1) % order.length])!]));
+  }
+  const vertices: KeptVertex[] = [];
+  for (let v = 0; v < work.nSource; v++) {
+    if (!work.alive[v]) continue;
+    const boundary = v < hull;
+    if (run.protectedVertices.has(v)) {
+      vertices.push({ vertex: v, boundary, reason: 'protected', refusal: null });
+      continue;
+    }
+    if (refusals === null) {
+      vertices.push({ vertex: v, boundary, reason: unreached!, refusal: null });
+      continue;
+    }
+    const refusal = refusals.get(v);
+    if (refusal === undefined) throw new Error(`issue #1374: source vertex ${v} is kept and not protected, yet removal pass ${final!.pass}, which took nothing, did not refuse it`);
+    vertices.push({ vertex: v, boundary, reason: refusalReason(refusal), refusal });
+  }
+  const rows = new Map<string, { boundary: number; interior: number }>();
+  for (const k of vertices) {
+    const row = rows.get(k.reason) ?? { boundary: 0, interior: 0 };
+    if (k.boundary) row.boundary++;
+    else row.interior++;
+    rows.set(k.reason, row);
+  }
+  return {
+    pass: final === null ? null : final.pass,
+    rows: [...rows.keys()].sort().map((reason) => ({ reason, ...rows.get(reason)! })),
+    ...(run.input.explainKept === 'by-vertex' ? { vertices } : {}),
+  };
+}
+
 function reportOf(effective: EffectiveSettings, sourceCounts: MeshCounts | null, candidate: CandidateReport, termination: Termination): MeshQualityReport {
   return {
     spec: 'mesh-quality-report/1',
@@ -2924,6 +3018,7 @@ function effectiveOf(input: MeshReductionInput, measured: EffectiveSettings, sou
     ...(input.retriangulate === undefined ? {} : { retriangulate: input.retriangulate }),
     ...(input.removalOrder === undefined ? {} : { removalOrder: input.removalOrder }),
     ...(input.lines === undefined ? {} : { lines: input.lines }),
+    ...(input.explainKept === undefined ? {} : { explainKept: input.explainKept }),
   };
 }