spine-rigc 2.42.0 → 2.44.0

package/README.md

@@ -412,11 +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, and `--compare <dir>` draws a second build beside the first on one
+bones by glob, `--overlay-slot`/`--hide-overlay-slot` the slots whose mesh, hull,
+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

@@ -10094,6 +10094,8 @@ pixel (`IN09`).
 | Is this axis declared, and held? | `--show art,declared,bones` | each `invariants.axes` line (§3.7) through its two bones' origins, drawn across the whole tile, and the bones it holds drawn in their own colour; the legend states each held bone's world x axis and how far off the line it lies, as `A51` measures it, at the pose drawn |
 | 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 |
@@ -10128,7 +10130,7 @@ pixel (`IN09`).
 - `--dim` fades the art toward white (each channel keeps 0.4 of its distance from
   white) so what is drawn over it reads.
 
-### 13.3 Labels, and which bones are drawn
+### 13.3 Labels, and which bones and slots are drawn
 
 - **One label per pixel.** Bones whose origins land on one pixel — a `_ctl` bone and
   its identity child, a chain's joint — are one label: the first by declaration
@@ -10149,6 +10151,17 @@ pixel (`IN09`).
   the shell. The filter is on `bones`, `axes` and `names`; every bone stays in the
   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>`, `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, 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
+  the opposite of what this keeps whole.
 
 ### 13.4 The legend
 
@@ -10171,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
@@ -10185,7 +10206,12 @@ 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.
 - `builds` — with `--compare`: each build (`A`, `B`), the poser that posed it, and
   its `skeleton.json`'s sha256. `poser` is build `A`'s.
 
@@ -10201,7 +10227,9 @@ or past the end, `--at` without `--animation` and the reverse, `--zoom` beside
 `--viewport`, `--show declared` on a skeleton with no `skeleton.model.json`
 beside it whose `spine.sha256` is its own — a Spine export states no rig invariants —
 `weights` with no bone or with a bone the build lacks (the bones listed), a
-`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), and, with
+`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), an
+`--overlay-slot`/`--hide-overlay-slot` pattern that matches no slot (the slots
+listed), and, with
 `--compare`, any of these that holds of the second build, said as `the --compare
 build: …`.
 A rig that declares no `invariants.axes` is not refused: the picture draws nothing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.42.0",
+  "version": "2.44.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/core_commands.ts

@@ -680,6 +680,12 @@ export function cmdInspect(flags: Record<string, string>): void {
   const include = readBonePatterns('bone', flags.bone);
   const exclude = readBonePatterns('hide-bone', flags['hide-bone']);
   const boneFilter = include === undefined && exclude === undefined ? undefined : { ...(include === undefined ? {} : { include }), ...(exclude === undefined ? {} : { exclude }) };
+  const slotInclude = readBonePatterns('overlay-slot', flags['overlay-slot'], 'neck,hair_*');
+  const slotExclude = readBonePatterns('hide-overlay-slot', flags['hide-overlay-slot'], 'neck,hair_*');
+  const slotFilter =
+    slotInclude === undefined && slotExclude === undefined
+      ? undefined
+      : { ...(slotInclude === undefined ? {} : { include: slotInclude }), ...(slotExclude === undefined ? {} : { exclude: slotExclude }) };
   const times = readTimes(flags.at);
   const fps = readPositiveNumber(flags, 'fps', INSPECT_DEFAULT_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
@@ -733,6 +739,7 @@ export function cmdInspect(flags: Record<string, string>): void {
       show,
       ...(weightsBone === undefined ? {} : { weightsBone }),
       ...(boneFilter === undefined ? {} : { boneFilter }),
+      ...(slotFilter === undefined ? {} : { slotFilter }),
       dim: flags.dim !== undefined,
       animation,
       times,

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, " +
@@ -1088,6 +1090,15 @@ const FLAG_MEANINGS: Record<string, string> = {
   'hide-bone':
     "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>, 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[], 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",
   compare:
     'a second build to draw beside --candidate, the same view at the same times on one world box and one transform — the union ' +
     'of both framings unless --zoom or --viewport pins it — each half labelled with its build and the poser that posed it. A ' +
@@ -1194,6 +1205,8 @@ const FLAG_VALUES: Record<string, string> = {
   zoom: '<name>[:<pad>]',
   bone: '<glob[,glob…]>',
   'hide-bone': '<glob[,glob…]>',
+  'overlay-slot': '<glob[,glob…]>',
+  'hide-overlay-slot': '<glob[,glob…]>',
   compare: '<dir|skeleton.json>',
   record: '<result.json>',
   ballot: '<ballot.html>',
@@ -1582,9 +1595,10 @@ export const COMMANDS: CommandDoc[] = [
       'rigc inspect … --animation <name> --at <s[,s…]> [--fps 12] [--skin <name>]   (one time, or a sheet of several on one grid)',
       'rigc inspect … --zoom <bone|slot>[:<pad>] | --viewport <x,y,w,h>   (a box, in world units)',
       "rigc inspect … --bone 'bang_*' --hide-bone '*_ctl'   (which bones bones, axes and names draw)",
+      'rigc inspect … --overlay-slot neck --hide-overlay-slot <glob>   (which slots mesh, hull, weights and slots draw; the art stays whole)',
       'rigc inspect … --compare <dir | skeleton.json>   (a second build beside the first, on one transform)',
     ],
-    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'compare', 'max', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'overlay-slot', 'hide-overlay-slot', 'compare', 'max', 'poser', 'out'],
     overrides: {
       animation: { meaning: 'the animation --at reads its times from (default: the setup pose, with no --at)' },
       fps: { meaning: `the frame grid --at is read on, which is the grid \`render --fps\` draws (default ${INSPECT_DEFAULT_FPS})` },

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;
 
@@ -170,6 +202,19 @@ export interface BoneFilter {
   exclude?: readonly string[];
 }
 
+/**
+ * `--overlay-slot` / `--hide-overlay-slot`: which slots the per-slot views
+ * (`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. */
+  include?: readonly string[];
+  /** Draw none of the slots a pattern matches — applied after `include`. */
+  exclude?: readonly string[];
+}
+
 /** One `rigc inspect` invocation, its flags read but not yet checked against the build. */
 export interface InspectRequest {
   show: readonly ShowWord[];
@@ -177,6 +222,8 @@ export interface InspectRequest {
   weightsBone?: string;
   /** Which bones `bones`, `axes` and `names` draw; absent is every one. */
   boneFilter?: BoneFilter;
+  /** Which slots `mesh`, `hull`, `weights`, `density` and `slots` draw; absent is every one. */
+  slotFilter?: SlotFilter;
   dim: boolean;
   /** `null` is the setup pose. */
   animation: string | null;
@@ -232,8 +279,18 @@ export interface InspectPlant {
   noAvoid?: boolean;
   /** Draw every bone whatever `--bone`/`--hide-bone` say. */
   ignoreFilter?: boolean;
+  /** Draw every slot's geometry whatever `--overlay-slot`/`--hide-overlay-slot` say. */
+  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. */
@@ -283,7 +340,7 @@ export interface LegendLabel {
   overlaps: boolean;
 }
 
-/** One region or mesh the frame shows, when `mesh`, `hull` or `weights` is drawn. */
+/** 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;
@@ -330,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';
@@ -348,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[] };
 }
@@ -367,8 +463,12 @@ export interface InspectLegend {
     | { kind: 'viewport' };
   /** `--bone` / `--hide-bone` as given — each bone they leave out says so in its `undrawn`. */
   boneFilter?: { include: string[] | null; exclude: string[] | null };
+  /** `--overlay-slot` / `--hide-overlay-slot` as given — `meshes[]` and `slots[]` then list only the slots they keep. */
+  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 };
@@ -434,10 +534,10 @@ function showSpelled(request: InspectRequest, weightsBone: string | undefined):
  * characters and `?` one, matched against a bone's whole name. Checked against
  * the build later, where a pattern that matches no bone is refused.
  */
-export function readBonePatterns(flag: string, raw: string | undefined): string[] | undefined {
+export function readBonePatterns(flag: string, raw: string | undefined, example = 'bang_*,*_ctl'): string[] | undefined {
   if (raw === undefined) return undefined;
   const patterns = raw.split(',').map((p) => p.trim());
-  if (patterns.some((p) => p === '')) throw new InspectError(`--${flag} ${JSON.stringify(raw)}: an empty pattern; it takes globs, comma-separated, e.g. --${flag} 'bang_*,*_ctl'`);
+  if (patterns.some((p) => p === '')) throw new InspectError(`--${flag} ${JSON.stringify(raw)}: an empty pattern; it takes globs, comma-separated, e.g. --${flag} '${example}'`);
   return patterns;
 }
 
@@ -730,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;
@@ -776,6 +1006,31 @@ function filterOut(bones: ReadonlyArray<{ name: string }>, filter: BoneFilter |
   return out;
 }
 
+/**
+ * `--overlay-slot` / `--hide-overlay-slot` against one build's slots: the slots
+ * whose geometry is not drawn. A pattern matching no slot is refused naming the
+ * slots there are — checked even when `apply` is off, so a mutant that ignores
+ * the filter still refuses a typo.
+ */
+function slotsLeftOut(slots: ReadonlyArray<{ name: string }>, filter: SlotFilter | undefined, apply: boolean): Set<string> {
+  const out = new Set<string>();
+  if (filter === undefined) return out;
+  const names = slots.map((s) => s.name);
+  const matchers = (flag: string, patterns: readonly string[]): Array<(name: string) => boolean> =>
+    patterns.map((p) => {
+      const m = globMatcher(p);
+      if (!names.some(m)) throw new InspectError(`--${flag} ${JSON.stringify(p)} matches no slot; the slots are [${names.join(', ')}]`);
+      return m;
+    });
+  const include = filter.include === undefined ? null : matchers('overlay-slot', filter.include);
+  const exclude = filter.exclude === undefined ? null : matchers('hide-overlay-slot', filter.exclude);
+  if (!apply) return out;
+  for (const name of names) {
+    if ((include !== null && !include.some((m) => m(name))) || (exclude !== null && exclude.some((m) => m(name)))) out.add(name);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // the view
 // ---------------------------------------------------------------------------
@@ -882,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. */
@@ -928,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'),
     };
   });
@@ -970,6 +1225,7 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     }
   }
   const filtered = builds.map((b) => aboutBuild(b.tag, () => filterOut(b.bones, request.boneFilter, plant.ignoreFilter !== true)));
+  const slotsOut = builds.map((b) => aboutBuild(b.tag, () => slotsLeftOut(b.slots, request.slotFilter, plant.ignoreSlotFilter !== true)));
   // The world box and its pixels: one for every tile of both builds, so a sheet's tiles and a compare's halves overlay.
   let viewport: Viewport;
   let framing: InspectLegend['framing'];
@@ -1034,19 +1290,20 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
       const row = compare ? Math.floor(k / pairs) : Math.floor(k / columns);
       const x0 = gap + column * (width + gap);
       const y0 = gap + row * (height + gap);
-      const drawnTile = drawTile(build, build.poses[k], filtered[bi], { x0, y0, viewport, sheet, compare, weightsBone, first: k === 0 && bi === 0 }, request, plant, notes);
+      const drawnTile = drawTile(build, build.poses[k], filtered[bi], slotsOut[bi], { x0, y0, viewport, sheet, compare, weightsBone, first: k === 0 && bi === 0 }, request, plant, notes);
       if (drawnTile.weighted) weighted[bi] = true;
       if (drawnTile.anyMesh) anyMesh = true;
       for (let y = 0; y < height; y++) plate.data.set(drawnTile.tile.data.subarray(y * width * 4, (y + 1) * width * 4), ((y0 + y) * plate.width + x0) * 4);
       tiles.push(drawnTile.legend);
     }
   }
+  // With a slot filter the sentence says the filter is part of why: the same build unfiltered may paint.
   if (weightsBone !== undefined) {
     for (const [bi, b] of builds.entries()) {
-      if (!weighted[bi]) notes.push(`weights: bone "${weightsBone}" weights no vertex of any region or mesh ${compare ? `build ${b.tag} ` : ''}shows here — nothing painted`);
+      if (!weighted[bi]) notes.push(`weights: bone "${weightsBone}" weights no vertex of any region or mesh${request.slotFilter === undefined ? '' : ' of the slots the filter keeps'} ${compare ? `build ${b.tag} ` : ''}shows here — nothing painted`);
     }
   }
-  if ((request.show.includes('mesh') || request.show.includes('hull')) && !anyMesh) notes.push('mesh/hull: no slot shows a mesh here — nothing drawn for it');
+  if ((request.show.includes('mesh') || request.show.includes('hull')) && !anyMesh) notes.push(`mesh/hull: no slot${request.slotFilter === undefined ? '' : ' the filter keeps'} shows a mesh here — nothing drawn for it`);
   const legend: InspectLegend = {
     spec: INSPECT_SPEC,
     poser: builds[0].poser,
@@ -1059,6 +1316,9 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     ...(request.boneFilter === undefined
       ? {}
       : { boneFilter: { include: request.boneFilter.include === undefined ? null : [...request.boneFilter.include], exclude: request.boneFilter.exclude === undefined ? null : [...request.boneFilter.exclude] } }),
+    ...(request.slotFilter === undefined
+      ? {}
+      : { slotFilter: { include: request.slotFilter.include === undefined ? null : [...request.slotFilter.include], exclude: request.slotFilter.exclude === undefined ? null : [...request.slotFilter.exclude] } }),
     ...(weightsBone === undefined
       ? {}
       : {
@@ -1072,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',
@@ -1103,6 +1387,7 @@ function drawTile(
   build: Gathered,
   pose: { frame: Frame; index: number },
   filtered: Map<string, string>,
+  slotsOut: ReadonlySet<string>,
   place: TilePlace,
   request: InspectRequest,
   plant: InspectPlant,
@@ -1160,10 +1445,42 @@ 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];
     for (const shown of frame.attachments ?? []) {
+      if (slotsOut.has(shown.slot)) continue;
       const rest = build.rest.get(restKey(shown.slot, shown.attachment));
       const vertexCount = shown.vertices.length / 2;
       if (rest === undefined || rest.vertices.length !== shown.vertices.length) {
@@ -1314,6 +1631,8 @@ function drawTile(
     legendTile.slots = [];
     const shown = frame.attachments ?? [];
     for (const [i, att] of shown.entries()) {
+      // A left-out slot keeps its place: a number is the slot's place in the whole draw order, filtered or not.
+      if (slotsOut.has(att.slot)) continue;
       const order = plant.slotsReversed ? shown.length - 1 - i : i;
       let minX = Infinity;
       let minY = Infinity;