spine-rigc 2.45.2 → 2.46.0

package/README.md

@@ -41,7 +41,7 @@ installed.
 | the same, and one texture instead of many | `rigc build --pack` | the parts arranged onto shared atlas pages, written beside the skeleton — losslessly, so the picture is the picture |
 | a pack somebody already made | `rigc build --atlas-in` | the same skeleton, with every part resolved to a region of that atlas — or a named refusal, never a part that silently does not draw |
 | a compiled rig | `rigc render` | every animation as PNG frames, plus one labelled contact sheet of the whole shot |
-| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, mesh edges and hulls, one bone's weights, the draw order, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot, or beside a second build on one transform — and a legend that puts every mark back in world units |
+| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, mesh edges and hulls, one bone's weights, the triangles folded over, the draw order, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot, or beside a second build on one transform — and a legend that puts every mark back in world units |
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
 | a picture of a key pose | `rigc pose` | where each loose part PNG sits in it, in spec coordinates — the movement between two poses is then yours to key ([docs/MOTION.md](docs/MOTION.md)) |
@@ -413,12 +413,13 @@ 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`
+`folds` (each mesh triangle turned over against the setup pose, filled — `render --folds`
+names them per animation and frame), `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, density and number are drawn over the whole painting, and `--compare <dir>` draws a second build beside the first on one
+weights, density, folds 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
@@ -600,7 +601,7 @@ commands take it and what its default is.
 | `repack <dir> --out <dir> --keep-pages` | **`skeleton.model.json` alone, for the pages already in place** — for a player that reads the document beside an atlas and pages that already shipped. The same read and stage rules, then `build --atlas-in` over the input atlas in place of the lift and the pack; it writes the document, and nothing else, only after its `pages` are shown to state the atlas as it stands, the rebuilt skeleton byte-identical to the one on disk (so `spine.sha256` names it — no acceptance flag here) and the gate green. `--out` is usually the build's own directory and must not already hold a `skeleton.model.json`; a page or region line the document has no field for is refused by name ([AUTHORING §0.4](docs/AUTHORING.md)) |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid. `--folds` adds a `folds.json` per set and prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |

package/docs/AUTHORING.md

@@ -245,6 +245,7 @@ What the flags mean:
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone or slot it frames to; §13 says each, with the refusals |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
+| `--folds` | `render` only: also read which mesh triangles **fold** — turn over against the setup pose — and write a `folds.json` into each frame directory: per mesh, the frames with a folded triangle, the worst frame's count and which triangles, by index. One printed line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. A reading, not a gate. Every other file is byte for byte what the render writes without it, `geometry.json` included. Refused with `--slot`/`--hide`, for `--geometry`'s reason — **§8.3** |
 | `--poser` | `render`, `inspect`, `check` and `explain`: `core` or `spine` — on `render`, `inspect` and `check`, which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes; its atlas, when one is named or present, the one beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core, and so is a build rendered with no `--skin` whose default skin names a skin-required bone or constraint, or whose skins name no `default` one — posed as a fresh skeleton is, no skin's bones or constraints applied (the default skin's included) and every slot resolved through the default skin alone, so the second draws nothing and stops at `there is nothing to draw` (exit 2) under either poser (issue #1051). Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. A fallback whose pair the runtime cannot load — another build's `skeleton.json` or atlas beside this build's document, or an export beside an atlas it was not exported with — is not drawn: it is refused `… does not load against <the atlas>: spine-core draws this pair (<why>) and could not resolve it — "<the runtime's own words>"` — or, where the atlas names a page that is not there, `nothing at <the page>: …` — exit 2, nothing written, on `render`, `render --geometry`, `check` and `bench --frames` alike; under `--poser core` the same pair is that flag's refusal, in the words above (`RC18`; the `--candidate` row says what to change). The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`, `RC34`). On the entry that links none of spine-core — the installed `rigc` without the runtime beside it, `bun cli_core.ts` in a clone — that refusal ends on the route to the entry that does (``the entry that links it runs them — installed, the same `rigc` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, `bun cli.ts` ``); a runtime that is installed and fails to load is refused without it, since installing it is not what that reader has to do. On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1), ending on the same route where the entry links none of it |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
@@ -1108,6 +1109,7 @@ bun cli.ts bench    3 --candidate path/to/spine [--frames path/to/frames]
 bun cli.ts render   --candidate path/to/spine [--animation …] [--skin …] [--fps 12] [--max 256]
 bun cli.ts render   --candidate path/to/spine --slot <name,…> | --hide <name,…>   # part of the rig, same grid
 bun cli.ts render   --candidate path/to/spine --geometry   # + geometry.json per set: the numbers the frames were drawn from
+bun cli.ts render   --candidate path/to/spine --folds      # + folds.json per set: which mesh triangles turn over, and when
 bun cli.ts preview  --candidate path/to/spine [--candidate path/to/another …] [--animation …] [--out preview.html]
 bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
 bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
@@ -7285,6 +7287,69 @@ still-in-frame residual over every region of `spineboy-pro` is 4.7e-12 world uni
 Topology and UVs sit in `rest` rather than on every frame because they do not
 change: repeating them per frame would add 35 % to `spineboy-pro`'s files.
 
+### 8.3 Which triangles fold — `render --folds`
+
+A mesh can **fold** — a triangle turning over under a bend — on a build that passes
+every assertion and every check. The art still draws, mirrored, over its neighbour,
+and nothing in a report says so. `--folds` reads it off the frames `render` draws:
+
+```bash
+bun cli.ts render --candidate path/to/spine --folds [--animation …] [--skin …] [--fps 12]
+# rigc render
+#   ..    show             321 frame(s), 16.000s + contact.png + folds.json (2 of 11 mesh(es) fold) -> …/show@20fps
+#   ..    folds    "show": mesh "hair_long" (slot "hair_long") folds on 88 frame(s) [33-54, 113-134, 194-215, 273-294] at 20 fps; worst frame 40 (t=2.0000s): 3 of 459 triangle(s) [137, 139, 140]; 3 triangle(s) fold on some frame [137, 139, 140]
+```
+
+**What folded means.** A mesh triangle is folded at a frame when its orientation
+there — the sign of its signed area in world space — is the opposite of its
+orientation at the setup pose. The setup pose is `rest`'s (§8.2): the setup pose's
+bones with no deform, so an attachment a slot only swaps to later is read too.
+Regions are not read: a region is one quad and cannot fold. A mesh mirrored whole by
+a negative scale reads every triangle as folded — that is what the definition says,
+and the count tells the two apart.
+
+**What is never counted.** A triangle already wrong at the setup pose is said once,
+on a `setup` line the first time a set shows its mesh, and never counted:
+
+- **degenerate** — its height over its longest edge is at most 2⁻³⁰ of the largest
+  coordinate its attachment holds at that pose, in world space or in its UVs. That
+  is eight million ulps above the rounding a chain of bone transforms leaves, and a
+  hundred-thousandth of a pixel on a rig 10⁴ units across drawn at one pixel per
+  unit — thinner than the posed numbers resolve, and thinner than anything drawn.
+  A triangle degenerate *at a frame* is not counted at that frame either: the sign of
+  a zero area is the rounding's;
+- **inverted** — its texture is drawn mirrored against the rest of its mesh: the sign
+  of world area × UV area is the opposite of the mesh's own sense, that product
+  summed over its triangles, weighted by world area. Read through the UVs and not the
+  index order, because the format fixes no winding — a mesh whose triangles are
+  listed in mixed orders draws correctly, and a winding test would call half of it
+  folded.
+
+**The file.** `folds.json`, `rigc-folds/1`, beside each set's frames: `animation`,
+`skin` (absent when none was set), `fps`, `reading` (these definitions, stated in
+the file), and `meshes[]` — every mesh any frame of the set shows, in `rest`'s
+order — each with `slot`, `attachment`, `triangleCount`, `setup` (`degenerate` and
+`inverted`, triangle indices), `frames[]` (only the frames with a folded triangle:
+`index`, `time`, `triangles`), `worst` (the frame with the most, the earliest on a
+tie; `null` when it never folds) and `folded` (every triangle folded on some frame).
+A triangle is named by its index `i` in `rest`'s `triangles`: vertices
+`triangles[3i]`, `triangles[3i+1]`, `triangles[3i+2]`. A mesh that never folds is in
+the file and on no printed line.
+
+**Nothing else moves.** The PNGs, `contact.png`, `frames.json` and, with
+`--geometry` beside it, `geometry.json` are byte for byte what the render writes
+without the flag. The reading is its own file rather than a field of `geometry.json`
+because that file is the pose, read by consumers that have it on disk already; a
+reading derived from it is computed from it — `foldsOf` over `geometry.json`'s
+`rest` and `frames` is `folds.json` exactly (`FO04`). ⛔ **Not with
+`--slot`/`--hide`**, for `--geometry`'s reason: the reading is of every mesh the pose
+shows.
+
+**A reading, not a gate.** Whether a fold is acceptable is yours: a tassel that swings
+past 90° folds honestly. To look at one, draw the worst frame:
+`inspect --show art,folds,mesh --animation <name> --at <worst time>` fills the folded
+triangles at that pose and lists them in its legend (§13).
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -10111,6 +10176,7 @@ pixel (`IN09`).
 | 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 |
+| Does anything fold in this animation? | `render --folds --animation <name>` (§8.3), then `inspect --show art,folds,mesh --dim --animation <name> --at <the worst frame's time>` | `render --folds` prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count and which triangles. The view fills those triangles at the pose drawn — every pixel whose centre a folded triangle holds — in the colour the legend's `folds` states, and the legend's `folds[]` names, per mesh, the folded triangles by index and the setup pose's degenerate and inverted ones, which are never counted. A fold is usually a sliver a few units across: `--viewport` around the vertices the legend's `meshes[]` gives is how it becomes visible. A reading, not a verdict |
 | 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 |
@@ -10167,7 +10233,7 @@ 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>`, `density` and `slots` — only for the slots a pattern matches, and
+  `weights:<bone>`, `density`, `folds` 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
@@ -10207,7 +10273,11 @@ pixel (`IN09`).
   `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`,
+  `why`; it is not painted. With `folds`, `folds[]`: every kept mesh with a
+  triangle folded at this tile's pose or a setup fault, in draw order — `slot`,
+  `attachment`, `triangleCount`, `folded` (the triangles filled, by index),
+  `degenerate` and `inverted` (the setup pose's, never counted); empty when none.
+  With `mesh`, `hull`, `weights`, `density` or `folds`,
   `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
@@ -10224,6 +10294,11 @@ pixel (`IN09`).
 - `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.
+- `folds` — with `folds`: the colour a folded triangle is filled with, as RGBA, and
+  what it means; `degenerateShare` (2⁻³⁰, §8.3); and in words what `folded`,
+  `degenerate` and `inverted` are and how a triangle is named by `index`. Its colour
+  is stated here rather than in `colours`, which every legend lists whole, so a legend
+  drawn without `folds` is the bytes it was before the view existed.
 - `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.45.2",
+  "version": "2.46.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

@@ -31,6 +31,7 @@ import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
 import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
+import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine } from '../folds.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
@@ -488,6 +489,10 @@ export function cmdRender(flags: Record<string, string>): void {
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
+  // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
+  // neither, or for --geometry alone, gets the bytes it always got: geometry.json is the pose, and a reading derived
+  // from it is a second file beside it, written only when asked for.
+  const folds = flags.folds !== undefined;
   // Refused together rather than one of them ignored (issue #864). The export
   // records every slot's whole geometry, because a subset is a statement about
   // which pixels are DRAWN and the pose is the same whatever a picture leaves
@@ -505,6 +510,18 @@ export function cmdRender(flags: Record<string, string>): void {
       }
     }
   }
+  // The same refusal for the same reason: the reading is of every mesh the pose shows, whatever a picture leaves out.
+  if (folds) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--folds takes no --${flag}: it reads every mesh the pose shows, which a subset of the drawn slots does not ` +
+            `change. Run \`rigc render --folds\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --folds for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
 
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
@@ -569,7 +586,7 @@ export function cmdRender(flags: Record<string, string>): void {
     // `--geometry` rides on the SAME call (issue #864): the bones and the whole
     // attachments are read off the skeleton at the step that drew each frame, so
     // the export's grid is this frame set's by construction.
-    const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
+    const sampling = geometry ? { ...pose, bones: true, geometry: true } : folds ? { ...pose, geometry: true } : pose;
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -583,15 +600,28 @@ export function cmdRender(flags: Record<string, string>): void {
         geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin)));
       }
     }
-    return { viewport, sampled, geometryTexts };
+    // The fold reading, off the very attachments the frames were drawn from, against the rest table the geometry
+    // export writes — one per set, every mesh any of its frames shows.
+    const foldReadings = new Map<string, ReturnType<typeof foldsFileOf>>();
+    if (folds) {
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const shown = frames.map((frame) => frame.attachments ?? []);
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, attachments: frame.attachments ?? [] }));
+        foldReadings.set(name, foldsFileOf(animation, fps, skin, foldsOf(poser.rest(skin, shown), read)));
+      }
+    }
+    return { viewport, sampled, geometryTexts, foldReadings };
   });
-  const { viewport, sampled, geometryTexts } = posed.value;
+  const { viewport, sampled, geometryTexts, foldReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
   mkdirSync(outRoot, { recursive: true });
   const sets: FrameSet[] = [];
+  // A mesh's setup faults are a property of the mesh, not of an animation: said once, the first time a set shows it.
+  const faultsSaid = new Set<string>();
   for (const [name, frames] of sampled) {
     // Same naming as a reference render: the protocol rate says nothing, any
     // other rate says itself, so two rates of one animation sit side by side.
@@ -611,6 +641,8 @@ export function cmdRender(flags: Record<string, string>): void {
     if (sheet) contactSheet(frames, pages, viewport, SHEET_TILE).writePng(join(dir, SHEET_FILE));
     const geometryOut = geometryTexts.get(name);
     if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
+    const foldReading = foldReadings.get(name);
+    if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -622,8 +654,18 @@ export function cmdRender(flags: Record<string, string>): void {
       duration,
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}`;
+    const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
+    const foldNote = foldReading === undefined ? '' : ` + ${FOLDS_FILE} (${folding} of ${foldReading.meshes.length} mesh(es) fold)`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
+    for (const mesh of foldReading?.meshes ?? []) {
+      const key = `${mesh.slot}\u0000${mesh.attachment}`;
+      const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
+      faultsSaid.add(key);
+      if (fault !== null) console.log(`  ..    setup    ${fault}`);
+      const line = foldLine(foldReading?.animation ?? null, fps, mesh);
+      if (line !== null) console.log(`  ..    folds    ${line}`);
+    }
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:

package/src/cli/shared.ts

@@ -36,6 +36,7 @@ import { ANCHOR_MAX_RESIDUAL, ANCHOR_MAX_UNEXPLAINED, DEFAULT_HINGE_MAX, DEFAULT
 import { checkAgainstFrames, type CheckOptions, CheckPlates, type CheckReport } from '../check.ts';
 import { compile, CompileError, droppedStateReason, headerBoundsOf, type CompileOptions } from '../compile.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
+import { FOLDS_FILE } from '../folds.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
 import { MODEL_DOCUMENT_FILE, MODEL_DOCUMENT_SPEC, modelDocument, spineFileSha256 } from '../model.ts';
@@ -126,7 +127,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences', 'keep-pages', 'dim']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'folds', 'accept-skeleton-differences', 'keep-pages', 'dim']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -996,6 +997,11 @@ const FLAG_MEANINGS: Record<string, string> = {
     `also write ${GEOMETRY_FILE} into each frame directory: per frame, every bone's world transform and every ` +
     "slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry — on the " +
     'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
+  folds:
+    `also read which mesh triangles fold — turn over against the setup pose — and write ${FOLDS_FILE} into each frame ` +
+    'directory: per mesh, the frames with a folded triangle, the worst frame\'s count and which triangles, by index. ' +
+    'One line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. ' +
+    'A reading, not a gate. Not with --slot/--hide: it reads every mesh the pose shows',
   poser:
     "`render`, `inspect` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
@@ -1067,7 +1073,8 @@ const FLAG_MEANINGS: Record<string, string> = {
     "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; ' +
+    'weight over every region and mesh it moves, as a heat on a ramp the legend states; folds = each mesh triangle turned ' +
+    "over against the setup pose at the pose drawn, filled, and named by index in the legend (render --folds reads the same); 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, " +
     'a bone of length 0 marked as one; axes = each bone\'s world x and y axes; slots = each slot\'s place in the posed ' +
@@ -1577,10 +1584,10 @@ export const COMMANDS: CommandDoc[] = [
     runtime: false,
     spineFormat: false,
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--poser core|spine] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'folds', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -1595,7 +1602,7 @@ 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 … --overlay-slot neck --hide-overlay-slot <glob>   (which slots mesh, hull, weights, density, folds 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', 'overlay-slot', 'hide-overlay-slot', 'compare', 'max', 'poser', 'out'],

package/src/folds.ts

@@ -0,0 +1,354 @@
+/**
+ * Which triangles of a posed mesh are turned over — the fold reading behind
+ * `rigc render --folds` and `rigc inspect --show folds` (issue #1383).
+ *
+ * ⭐ **A reading, not a gate.** A mesh can fold — a triangle flipping over under
+ * a bend — on a build that passes every assertion and every check, and until
+ * this it was found by a person looking at the right frame. Whether a fold is
+ * acceptable is the consumer's: a tassel that swings past 90° folds honestly.
+ * So this names the triangles and the frames and decides nothing.
+ *
+ * ## What "folded" means here
+ *
+ * A triangle is folded at a frame when its orientation there — the sign of its
+ * signed area in world space — is the opposite of its orientation at the setup
+ * pose. The setup pose is the rest table's (`AttachmentRest.vertices`: the setup
+ * pose's bones with no deform, the table `render --geometry` writes as `rest`),
+ * so an attachment a slot only swaps to later has a reference too.
+ *
+ * A triangle that is already wrong at the setup pose is reported once as that
+ * and never counted as folding, because "opposite to the setup pose" says
+ * nothing about it:
+ *
+ * - **degenerate** — thinner than the posed numbers resolve (`DEGENERATE_SHARE`
+ *   below), in world space or in its UVs, so it has no orientation to keep;
+ * - **inverted** — its texture is drawn mirrored against the rest of its mesh:
+ *   the sign of world area × UV area is the opposite of the mesh's own sense,
+ *   which is the sign of that product summed over its triangles, weighted by
+ *   world area. Read through the UVs rather than the index order because the
+ *   format does not fix a winding: a mesh whose triangles are listed in mixed
+ *   orders is drawn correctly, and a winding test would call half of it folded.
+ *
+ * A triangle that is degenerate at a frame — collapsed to a line by the pose —
+ * is not counted at that frame either: the sign of a zero area is the rounding's,
+ * not the pose's.
+ *
+ * A mesh mirrored whole by a negative scale reads every triangle as folded: that
+ * is what "opposite to the setup pose" is, and the count says which it was.
+ *
+ * Pure: no clock, no randomness, no runtime. The posed vertices are handed in by
+ * whichever poser drew the frames (rigc's core for a rigc build).
+ */
+
+/** The fold file's name inside an animation's frame directory, and its format tag. */
+export const FOLDS_FILE = 'folds.json';
+export const FOLDS_SPEC = 'rigc-folds/1';
+
+/**
+ * A triangle is degenerate when its height over its longest edge is at most
+ * this share of the largest coordinate magnitude its attachment holds at that
+ * pose (world units, or UV units for the UV triangle).
+ *
+ * 2⁻³⁰ ≈ 9.3e-10, chosen between two bounds that are both stated rather than
+ * tuned:
+ *
+ * - **above the rounding**: a posed coordinate is a chain of bone transforms in
+ *   doubles, each step rounding by half an ulp (2⁻⁵³) of numbers no larger than
+ *   a few times the coordinate. 2⁻³⁰ is 2²³ ulps — eight million steps of
+ *   headroom — so a sign this flags is never one a different rounding could
+ *   have given the other way;
+ * - **below anything drawn**: on a rig 10⁴ world units across it is 1e-5 world
+ *   units, a hundred-thousandth of a pixel at one pixel per unit, so no triangle
+ *   a picture can show is called degenerate.
+ *
+ * Relative to the attachment's own magnitude because the rounding is: a mesh at
+ * 3,200 units from its origin carries 3,200 times the absolute noise of one at 1.
+ */
+export const DEGENERATE_SHARE = 2 ** -30;
+
+/** The rest geometry the reading needs: the triangles, the UVs and the setup pose's vertices. */
+export interface FoldRest {
+  slot: string;
+  attachment: string;
+  kind: 'region' | 'mesh';
+  vertices: readonly number[];
+  triangles: readonly number[];
+  uvs?: readonly number[];
+}
+
+/** One posed attachment: its slot, its name, its world vertices `x, y` per vertex. */
+export interface FoldPose {
+  slot: string;
+  attachment: string;
+  vertices: readonly number[];
+}
+
+/** One sampled frame: its index on the grid, its time and every attachment it shows. */
+export interface FoldFrame {
+  index: number;
+  time: number;
+  attachments: readonly FoldPose[];
+}
+
+/** A mesh's triangles that are wrong at the setup pose — reported once, never counted. */
+export interface SetupFaults {
+  /** Thinner than the posed numbers resolve, in world space or in the UVs — by triangle index. */
+  degenerate: number[];
+  /** Drawn mirrored against the rest of its mesh at the setup pose — by triangle index. */
+  inverted: number[];
+}
+
+/** One frame on which a mesh has a folded triangle. */
+export interface FoldedFrame {
+  index: number;
+  time: number;
+  /** The folded triangles, by index (`triangles[3i..3i+2]` of the rest table), ascending. */
+  triangles: number[];
+}
+
+/** One mesh's reading over one frame set. */
+export interface MeshFolds {
+  slot: string;
+  attachment: string;
+  /** How many triangles the mesh has. */
+  triangleCount: number;
+  setup: SetupFaults;
+  /** Every frame with a folded triangle, in frame order; empty when the mesh never folds. */
+  frames: FoldedFrame[];
+  /** The frame with the most folded triangles — the earliest, on a tie — or `null` when it never folds. */
+  worst: FoldedFrame | null;
+  /** Every triangle folded on some frame, ascending. */
+  folded: number[];
+}
+
+/** `folds.json`: one frame set's reading, every mesh any frame shows. */
+export interface FoldsFile {
+  spec: typeof FOLDS_SPEC;
+  /** The animation, or `null` for a skeleton with none (its one frame is the setup pose). */
+  animation: string | null;
+  skin?: string;
+  fps: number;
+  /** What the numbers mean, stated in the file so a reader does not need this module. */
+  reading: { folded: string; degenerate: string; inverted: string; index: string };
+  /** Every mesh any frame of the set shows, in the order the rest table lists them. */
+  meshes: MeshFolds[];
+}
+
+/**
+ * A planted defect, for the suite's mutants only (`FO` controls in
+ * `selftest.ts`). Production passes none.
+ */
+export interface FoldPlant {
+  /** Count a triangle whose sign AGREES with the setup pose's, rather than the one opposite it. */
+  signFlipped?: boolean;
+  /** Read each frame against the frame before it — a flip detector — rather than against the setup pose. */
+  againstPreviousFrame?: boolean;
+  /** Count the setup pose's degenerate and inverted triangles like any other. */
+  countSetupFaults?: boolean;
+}
+
+/** Twice the signed area of triangle `t` in `xy` (`x, y` per vertex). */
+function cross2(xy: readonly number[], triangles: readonly number[], t: number): number {
+  const a = triangles[3 * t] * 2;
+  const b = triangles[3 * t + 1] * 2;
+  const c = triangles[3 * t + 2] * 2;
+  return (xy[b] - xy[a]) * (xy[c + 1] - xy[a + 1]) - (xy[c] - xy[a]) * (xy[b + 1] - xy[a + 1]);
+}
+
+/** The longest edge of triangle `t` in `xy`. */
+function longestEdge(xy: readonly number[], triangles: readonly number[], t: number): number {
+  const ids = [triangles[3 * t] * 2, triangles[3 * t + 1] * 2, triangles[3 * t + 2] * 2];
+  let most = 0;
+  for (const [i, j] of [[0, 1], [1, 2], [2, 0]] as const) {
+    const dx = xy[ids[j]] - xy[ids[i]];
+    const dy = xy[ids[j] + 1] - xy[ids[i] + 1];
+    most = Math.max(most, Math.sqrt(dx * dx + dy * dy));
+  }
+  return most;
+}
+
+/** The largest coordinate magnitude in `xy` — what the rounding of every number in it is relative to. */
+function magnitude(xy: readonly number[]): number {
+  let most = 0;
+  for (const v of xy) most = Math.max(most, Math.abs(v));
+  return most;
+}
+
+/**
+ * The sign of triangle `t`'s area in `xy`: +1, −1, or 0 when it is degenerate
+ * — its height over its longest edge at most `DEGENERATE_SHARE` of `scale`.
+ */
+function orientation(xy: readonly number[], triangles: readonly number[], t: number, scale: number): -1 | 0 | 1 {
+  const twice = cross2(xy, triangles, t);
+  const edge = longestEdge(xy, triangles, t);
+  if (edge === 0 || Math.abs(twice) / edge <= DEGENERATE_SHARE * scale) return 0;
+  return twice > 0 ? 1 : -1;
+}
+
+/** A mesh's setup reading: each triangle's world sign at the setup pose, and the triangles reported as setup faults. */
+export interface SetupReading {
+  /** Per triangle: +1 or −1, its world sign at the setup pose; 0 for a setup fault (never counted). */
+  signs: Int8Array;
+  faults: SetupFaults;
+}
+
+/** The setup reading of one mesh — see the module comment for what degenerate and inverted mean. */
+export function setupReading(rest: FoldRest, plant: FoldPlant = {}): SetupReading {
+  const count = Math.floor(rest.triangles.length / 3);
+  const signs = new Int8Array(count);
+  const world: number[] = [];
+  const uvSigns: number[] = [];
+  const worldScale = magnitude(rest.vertices);
+  const uvs = rest.uvs ?? [];
+  const uvScale = magnitude(uvs);
+  let sense = 0;
+  const degenerate: number[] = [];
+  for (let t = 0; t < count; t++) {
+    const w = orientation(rest.vertices, rest.triangles, t, worldScale);
+    const u = uvs.length === rest.vertices.length ? orientation(uvs, rest.triangles, t, uvScale) : 1;
+    world.push(w);
+    uvSigns.push(u);
+    if (w === 0 || u === 0) {
+      degenerate.push(t);
+      continue;
+    }
+    sense += w * u * Math.abs(cross2(rest.vertices, rest.triangles, t));
+  }
+  const inverted: number[] = [];
+  for (let t = 0; t < count; t++) {
+    if (world[t] === 0 || uvSigns[t] === 0) continue;
+    // A mesh whose two senses weigh exactly the same has no rest to be inverted against: none is flagged.
+    if (sense !== 0 && Math.sign(world[t] * uvSigns[t]) !== Math.sign(sense)) {
+      inverted.push(t);
+      continue;
+    }
+    signs[t] = world[t];
+  }
+  if (plant.countSetupFaults) {
+    for (let t = 0; t < count; t++) signs[t] = world[t] === 0 ? 1 : world[t];
+  }
+  return { signs, faults: { degenerate, inverted } };
+}
+
+/** The triangles of one mesh folded at one pose, ascending — `vertices` posed, `setup` its setup reading. */
+export function foldedAt(rest: FoldRest, setup: SetupReading, vertices: readonly number[], plant: FoldPlant = {}): number[] {
+  if (vertices.length !== rest.vertices.length) {
+    throw new Error(
+      `slot "${rest.slot}" mesh "${rest.attachment}": the rest table states ${rest.vertices.length / 2} vertices, the pose ${vertices.length / 2} — the poser disagrees with itself`,
+    );
+  }
+  const scale = magnitude(vertices);
+  const out: number[] = [];
+  for (let t = 0; t < setup.signs.length; t++) {
+    const before = setup.signs[t];
+    if (before === 0) continue;
+    const now = orientation(vertices, rest.triangles, t, scale);
+    if (now === 0) continue;
+    if (plant.signFlipped ? now === before : now === -before) out.push(t);
+  }
+  return out;
+}
+
+const restKey = (slot: string, attachment: string): string => `${slot}\u0000${attachment}`;
+
+/**
+ * Every mesh's reading over one frame set: `rest` the rest table (regions are
+ * skipped — a region is a quad and cannot fold), `frames` the frames as the
+ * sampler returned them. A mesh any frame shows is read; one no frame shows is
+ * not listed. Order is the rest table's, so one build reads in one order.
+ */
+export function foldsOf(rest: readonly FoldRest[], frames: readonly FoldFrame[], plant: FoldPlant = {}): MeshFolds[] {
+  const shown = new Set<string>();
+  for (const frame of frames) for (const a of frame.attachments) shown.add(restKey(a.slot, a.attachment));
+  const out: MeshFolds[] = [];
+  for (const r of rest) {
+    if (r.kind !== 'mesh' || !shown.has(restKey(r.slot, r.attachment))) continue;
+    let setup = setupReading(r, plant);
+    const folded: FoldedFrame[] = [];
+    const union = new Set<number>();
+    for (const frame of frames) {
+      const posed = frame.attachments.find((a) => a.slot === r.slot && a.attachment === r.attachment);
+      if (posed === undefined) continue;
+      const triangles = foldedAt(r, setup, posed.vertices, plant);
+      if (plant.againstPreviousFrame) {
+        const signs = Int8Array.from(setup.signs, (sign, t) => (triangles.includes(t) ? -sign : sign));
+        setup = { ...setup, signs };
+      }
+      if (triangles.length === 0) continue;
+      for (const t of triangles) union.add(t);
+      folded.push({ index: frame.index, time: frame.time, triangles });
+    }
+    let worst: FoldedFrame | null = null;
+    for (const f of folded) if (worst === null || f.triangles.length > worst.triangles.length) worst = f;
+    out.push({
+      slot: r.slot,
+      attachment: r.attachment,
+      triangleCount: setup.signs.length,
+      setup: setup.faults,
+      frames: folded,
+      worst,
+      folded: [...union].sort((a, b) => a - b),
+    });
+  }
+  return out;
+}
+
+/** What `folds.json` states its numbers mean — the one wording the file and the docs share. */
+export const FOLDS_READING: FoldsFile['reading'] = {
+  folded:
+    "a triangle whose world orientation (the sign of its signed area) at the frame is the opposite of its orientation at the setup pose — the rest table's vertices, the setup pose's bones with no deform. A triangle degenerate at the frame is not counted there",
+  degenerate: `a triangle whose height over its longest edge is at most ${DEGENERATE_SHARE} of the largest coordinate magnitude its attachment holds at that pose, in world space or in its UVs — thinner than the posed numbers resolve`,
+  inverted:
+    "a triangle drawn mirrored against the rest of its mesh at the setup pose: the sign of world area x UV area is the opposite of the mesh's own sense (that product summed over its triangles, weighted by world area). Setup faults are listed once and never counted as folds",
+  index: 'a triangle is named by its index i in the rest table: vertices triangles[3i], triangles[3i+1], triangles[3i+2]',
+};
+
+/** The file for one frame set. */
+export function foldsFileOf(animation: string | null, fps: number, skin: string | undefined, meshes: MeshFolds[]): FoldsFile {
+  return { spec: FOLDS_SPEC, animation, ...(skin === undefined ? {} : { skin }), fps, reading: FOLDS_READING, meshes };
+}
+
+/** The file's text: two-space JSON and a newline, so one build and one request are one byte sequence. */
+export function foldsText(file: FoldsFile): string {
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+/** Ascending indices as runs: `[3, 4, 5, 9]` → `3-5, 9`. */
+export function indexRuns(indices: readonly number[]): string {
+  const runs: string[] = [];
+  for (let i = 0; i < indices.length; ) {
+    let j = i;
+    while (j + 1 < indices.length && indices[j + 1] === indices[j] + 1) j++;
+    runs.push(j === i ? String(indices[i]) : `${indices[i]}-${indices[j]}`);
+    i = j + 1;
+  }
+  return runs.join(', ');
+}
+
+/**
+ * The printed line for a mesh that folds, or `null` for one that never does.
+ * It names the animation, the mesh and its slot, the frames, the worst frame's
+ * count and its triangles, and every triangle folded on any frame.
+ */
+export function foldLine(animation: string | null, fps: number, mesh: MeshFolds): string | null {
+  const worst = mesh.worst;
+  if (worst === null) return null;
+  const where = animation === null ? 'the setup pose' : JSON.stringify(animation);
+  const frames = mesh.frames.map((f) => f.index);
+  return (
+    `${where}: mesh "${mesh.attachment}" (slot "${mesh.slot}") folds on ${frames.length} frame(s) [${indexRuns(frames)}] at ${fps} fps; ` +
+    `worst frame ${worst.index} (t=${worst.time.toFixed(4)}s): ${worst.triangles.length} of ${mesh.triangleCount} triangle(s) [${worst.triangles.join(', ')}]; ` +
+    `${mesh.folded.length} triangle(s) fold on some frame [${mesh.folded.join(', ')}]`
+  );
+}
+
+/** The printed line for a mesh with setup faults, or `null` for one with none — printed once per run, not per animation. */
+export function setupFaultLine(mesh: Pick<MeshFolds, 'slot' | 'attachment' | 'setup'>): string | null {
+  const { degenerate, inverted } = mesh.setup;
+  if (degenerate.length === 0 && inverted.length === 0) return null;
+  const parts = [
+    ...(degenerate.length === 0 ? [] : [`${degenerate.length} degenerate [${degenerate.join(', ')}]`]),
+    ...(inverted.length === 0 ? [] : [`${inverted.length} inverted against the rest of the mesh [${inverted.join(', ')}]`]),
+  ];
+  return `mesh "${mesh.attachment}" (slot "${mesh.slot}") at the setup pose: triangle(s) ${parts.join('; ')} — reported here once and never counted as folding`;
+}

package/src/inspect.ts

@@ -42,6 +42,11 @@
  * budget: `A13_MESH_BUDGET` is the one gate on counts, and this only says where
  * the triangles are.
  *
+ * ⭐ **A fold is read, never judged** (issue #1383). `folds` fills each mesh
+ * triangle that is turned over at the pose drawn — its world orientation the
+ * opposite of the setup pose's — by `./folds.ts`, the reading `render --folds`
+ * prints, so the picture and that line name the same triangles.
+ *
  * Links nothing from the runtime: the poser is handed in.
  */
 import { createHash } from 'node:crypto';
@@ -71,12 +76,13 @@ import {
   viewportFor,
 } from './render_shared.ts';
 import { hypot2 } from './numeric.ts';
+import { DEGENERATE_SHARE, foldedAt, FOLDS_READING, setupReading } from './folds.ts';
 
 /** The legend's format tag. */
 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', 'density', 'weights', 'mesh', 'hull', 'declared', 'bones', 'axes', 'slots', 'names'] as const;
+export const SHOW_WORDS = ['art', 'grid', 'density', 'weights', 'folds', '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. */
@@ -183,6 +189,19 @@ export const INSPECT_COLOURS = {
   rule: { rgba: [...SHEET_RULE], meaning: 'the gap between two tiles' },
 } as const satisfies Record<string, { rgba: readonly number[]; meaning: string }>;
 
+/**
+ * The `folds` view's colour (issue #1383). Kept out of `INSPECT_COLOURS`, which
+ * every legend lists whole: a colour added there would move the bytes of every
+ * legend written without `folds`. It is stated in the legend's `folds` block
+ * instead, only when the view is drawn — as the weights and density ramps are.
+ * Pure red at full alpha: neither ramp reaches it (the weights ramp's red end is
+ * `[215, 20, 20]`), and the mesh edges drawn over a fill stay readable.
+ */
+export const FOLD_COLOUR = {
+  rgba: [255, 0, 0, 255],
+  meaning: 'a mesh triangle folded over at this pose — its world orientation the opposite of the setup pose\'s: every pixel whose centre it holds',
+} as const;
+
 type ColourName = keyof typeof INSPECT_COLOURS;
 const colour = (name: ColourName): RGBA => [...INSPECT_COLOURS[name].rgba] as RGBA;
 
@@ -292,6 +311,8 @@ export interface InspectPlant {
   densityLinearRamp?: boolean;
   /** Density: take the figure's totals over the slots the filter keeps, not over every slot. */
   densityTotalsFiltered?: boolean;
+  /** Folds: fill every triangle of every kept mesh, folded or not. */
+  foldsFillAll?: boolean;
 }
 
 /** A point in both spaces. */
@@ -425,6 +446,20 @@ export interface LegendDensity {
   slots: LegendDensitySlot[];
 }
 
+/** One kept mesh with a folded triangle, or a setup fault, at one tile's pose (issue #1383). */
+export interface LegendFold {
+  slot: string;
+  attachment: string;
+  /** How many triangles the mesh has. */
+  triangleCount: number;
+  /** The triangles folded at this pose, by index (`triangles[3i..3i+2]` of the rest table), ascending — the ones filled. */
+  folded: number[];
+  /** Thinner than the posed numbers resolve at the setup pose, never counted — by index. */
+  degenerate: number[];
+  /** Drawn mirrored against the rest of the mesh at the setup pose, never counted — by index. */
+  inverted: number[];
+}
+
 export interface LegendTile {
   /** With `--compare`: which build this tile is — `A` is `--candidate`, `B` is `--compare`. */
   build?: 'A' | 'B';
@@ -445,6 +480,8 @@ export interface LegendTile {
   slots?: LegendSlot[];
   /** With `density`: the figure's totals and every kept slot's row. */
   density?: LegendDensity;
+  /** With `folds`: every kept mesh with a triangle folded at this pose or a setup fault, in draw order; empty when none. */
+  folds?: LegendFold[];
   declared?: LegendDeclared[];
   grid?: { step: number; x: number[]; y: number[] };
 }
@@ -470,6 +507,8 @@ export interface InspectLegend {
   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 `folds`: the colour a folded triangle is filled with, the degenerate share, and what folded, degenerate and inverted mean. */
+  folds?: { rgba: number[]; meaning: string; degenerateShare: number; folded: string; degenerate: string; inverted: string; index: 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 };
@@ -1138,7 +1177,7 @@ interface Gathered {
   sha: string;
 }
 
-const MESH_VIEWS: readonly ShowWord[] = ['mesh', 'hull', 'weights', 'density'];
+const MESH_VIEWS: readonly ShowWord[] = ['mesh', 'hull', 'weights', 'density', 'folds'];
 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. */
@@ -1357,6 +1396,16 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
           },
         }
       : {}),
+    ...(request.show.includes('folds')
+      ? {
+          folds: {
+            rgba: [...FOLD_COLOUR.rgba],
+            meaning: FOLD_COLOUR.meaning,
+            degenerateShare: DEGENERATE_SHARE,
+            ...FOLDS_READING,
+          },
+        }
+      : {}),
     ...(compare ? { builds: builds.map((b) => ({ build: b.tag, poser: b.poser, skeletonSha256: b.sha })) } : {}),
     coordinates: {
       world: 'spine world: y up, world units',
@@ -1521,6 +1570,37 @@ function drawTile(
       }
       legendTile.meshes.push(entry);
     }
+    // ── folds: each kept mesh's turned-over triangles filled, over the heat and under the edges (issue #1383) ──
+    if (request.show.includes('folds')) {
+      legendTile.folds = [];
+      for (const shown of frame.attachments ?? []) {
+        if (slotsOut.has(shown.slot)) continue;
+        const rest = build.rest.get(restKey(shown.slot, shown.attachment));
+        if (rest === undefined || rest.kind !== 'mesh') continue;
+        const setup = setupReading(rest);
+        const folded = foldedAt(rest, setup, shown.vertices);
+        const { degenerate, inverted } = setup.faults;
+        const fill = plant.foldsFillAll ? Array.from({ length: rest.triangles.length / 3 }, (_, i) => i) : folded;
+        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 (const t of fill) fillTriangle(tile, [at(rest.triangles[3 * t]), at(rest.triangles[3 * t + 1]), at(rest.triangles[3 * t + 2])], [...FOLD_COLOUR.rgba] as RGBA);
+        if (folded.length === 0 && degenerate.length === 0 && inverted.length === 0) continue;
+        legendTile.folds.push({ slot: shown.slot, attachment: shown.attachment, triangleCount: rest.triangles.length / 3, folded, degenerate, inverted });
+      }
+      if (first) {
+        const count = legendTile.folds.reduce((n, f) => n + f.folded.length, 0);
+        const meshes = legendTile.folds.filter((f) => f.folded.length > 0);
+        notes.push(
+          count === 0
+            ? `folds: no mesh${request.slotFilter === undefined ? '' : ' the filter keeps'} has a triangle folded over at this pose — nothing filled`
+            : `folds: ${count} triangle(s) folded over across ${meshes.length} mesh(es) — ${meshes.map((f) => `"${f.slot}" [${f.folded.join(', ')}]`).join(', ')} — every one is in the legend`,
+        );
+        const faulted = legendTile.folds.filter((f) => f.degenerate.length > 0 || f.inverted.length > 0);
+        if (faulted.length > 0) notes.push(`folds: setup faults, never counted — ${faulted.map((f) => `"${f.slot}" degenerate [${f.degenerate.join(', ')}] inverted [${f.inverted.join(', ')}]`).join(', ')}`);
+      }
+    }
     for (const entry of legendTile.meshes) {
       if (entry.kind !== 'mesh') continue;
       anyMesh = true;