spine-rigc 2.45.2 → 2.47.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, with where and how big), `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
+`--zoom <bone|slot|folds>[: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, their world box and their setup-pose area |
 | `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

@@ -243,8 +243,9 @@ What the flags mean:
 | `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
 | `--candidate` | `check`, `bench`, `render`, `inspect`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--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 |
+| `--show`, `--dim`, `--at`, `--zoom` | `inspect` only — what it draws, whether the art is faded, which times of `--animation` it poses and the bone, slot or folds 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, with their world box and setup-pose area. 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,91 @@ 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] in world box x [112.04, 133.28] y [323.01, 339.19] (21.22 × 16.16), setup-pose area 122.00 units² = 0.0686% of the mesh's; 3 triangle(s) fold on some frame [137, 139, 140]
+```
+
+**Where and how big.** The line says, for the worst frame, where the folded
+triangles are — the **world box** of their vertices as posed at that frame, every
+vertex of each and nothing else, printed rounded *outward* to hundredths so the
+printed box still holds every one (the file states it exactly) — and how big they
+are: their summed **setup-pose area**, each triangle's unsigned area in `rest`, in
+world units², and that as a share of the mesh's own setup-pose area (every
+triangle's, summed). "3 of 459 triangles" reads the same for three slivers at a
+hair tip and three panels of a skirt; the share does not.
+
+⭐ The box is the frame's and the area is the setup pose's, on purpose. The box is
+where to look, so it is where the triangles are drawn. The area is how much of the
+art is turned over, and a folded triangle's *posed* area cannot say that: it passes
+through 0 at the frame the triangle turns, so one triangle reads a different size on
+every frame it is folded — on the film above, `hair_long`'s three range from 0.09 to
+24.2 units² posed across their 88 frames against 122.00 at the setup pose.
+
+**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), `area` (the mesh's setup-pose area, world units²),
+`frames[]` (only the frames with a folded triangle: `index`, `time`, `triangles`,
+and that frame's `box` — `[minX, minY, maxX, maxY]`, world units, y up — `area` and
+`share`, as above), `worst` (the frame with the most, the earliest on a tie, with the
+same fields; `null` when it never folds) and `folded` (every triangle folded on some
+frame). `area`, `box` and `share` arrived in 2.47 (issue #1386) as added fields:
+every field 2.46 wrote means what it meant, so the tag is still `rigc-folds/1`.
+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, and no size is too small to print. To look at one, draw the
+worst frame framed to it:
+`inspect --show art,folds,mesh --animation <name> --at <worst time> --zoom folds`
+fills the folded triangles at that pose, frames the picture to their box, and lists
+them with the same box and area in its legend (§13).
+
 ---
 
 ## 9. Checking against the frames — `rigc check`
@@ -10111,6 +10198,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 --animation <name> --at <the worst frame's time> --zoom folds` | `render --folds` prints one line per mesh with a triangle turned over against the setup pose: the frames, the worst frame's count, which triangles, their world box at that frame and their setup-pose area. 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 with the same box and area, and the setup pose's degenerate and inverted ones, which are never counted. A fold is usually a sliver a few units across, invisible in a picture of the whole mesh: `--zoom folds` frames the picture to the folded triangles' box. A thin sliver still needs pixels — raise `--max` when the fill is a line. 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 |
@@ -10133,7 +10221,16 @@ pixel (`IN09`).
   vertices over every time drawn, padded by `<pad>` world units on every side
   (default a quarter of the box's longer side). A name that is both a bone and a slot
   is refused until it is written `bone:<name>` or `slot:<name>`; a bone of length 0
-  with no pad is one point, and is refused asking for one.
+  with no pad is one point, and is refused asking for one. **The folds** —
+  `--zoom folds[:<pad>]`: the box of every triangle folded over (§8.3) at the times
+  drawn, in every mesh `--overlay-slot`/`--hide-overlay-slot` keep — the union of
+  the legend's `folds[].box` over the tiles — padded as above. With nothing folded at
+  those times it is refused, naming the meshes that fold on the animation's grid and
+  their frames (`--zoom folds: nothing to frame — no mesh has a triangle folded over
+  at t=1s of "turn" — at 12 fps these do: "hair_lock_l" on frame(s) [22-23], worst
+  frame 22 (t=1.8333s); …`); at the setup pose — what a fold is read against —
+  nothing folds, and it says so. A rig with a bone or slot named `folds` is refused
+  until the name is written `bone:folds` or `slot:folds`.
 - **Two builds** — `--compare <dir | skeleton.json>`. The second build is loaded as
   the first is (its own poser, chosen by what it carries, on a `poser    B:` line),
   posed at the same times, and drawn beside it: one time is two halves side by side,
@@ -10167,7 +10264,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 +10304,14 @@ 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), `box` (the folded
+  triangles' world box at this pose, `[minX, minY, maxX, maxY]`; `null` when none is
+  folded), `area` (their setup-pose area, world units²) and `share` (that over the
+  mesh's setup-pose area) — §8.3's numbers; 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
@@ -10217,13 +10321,19 @@ pixel (`IN09`).
   `build` — `A` or `B`.
 - `colours` — every colour the picture draws, as RGBA, with what it means.
 - `poser`, `show`, `dim`, `skin`, `animation`, `fps` and `framing` — what was drawn
-  and how it was framed (`shot`, `zoom` with the bone or slot, the pad and whether it
-  was stated, or `viewport`).
+  and how it was framed (`shot`, `zoom` with the bone or slot — or with `folds`, what
+  the box is of — the pad and whether it 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.
+- `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, how a triangle is named by `index`, and what
+  `box` and `area` are. 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.
@@ -10244,9 +10354,11 @@ beside it whose `spine.sha256` is its own — a Spine export states no rig invar
 `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), an
 `--overlay-slot`/`--hide-overlay-slot` pattern that matches no slot (the slots
-listed), and, with
+listed), `--zoom folds` with no triangle folded over at the times drawn (the meshes
+that fold on the grid and their frames listed), and, with
 `--compare`, any of these that holds of the second build, said as `the --compare
-build: …`.
+build: …` — except `--zoom folds`, which frames to whichever build folds and is
+refused only when neither does, each build's frames named.
 A rig that declares no `invariants.axes` is not refused: the picture draws nothing
 for `declared` and the run says so on a line of its own.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.45.2",
+  "version": "2.47.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,12 @@ 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, ' +
+    'with where they are (the world box of their posed vertices) and how big (their setup-pose area, and its share of the mesh\'s). ' +
+    '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 +1074,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 ' +
@@ -1082,7 +1090,9 @@ const FLAG_MEANINGS: Record<string, string> = {
   zoom:
     'frame the picture to one bone (origin to tip) or one slot (its attachment\'s vertices) over every time drawn, padded ' +
     'by <pad> world units on every side (default: a quarter of the box\'s longer side). A name that is both a bone and a ' +
-    'slot is refused until written bone:<name> or slot:<name>; a name that is neither lists both rosters. Not with --viewport',
+    'slot is refused until written bone:<name> or slot:<name>; a name that is neither lists both rosters. `folds` frames it to ' +
+    'every folded triangle of every mesh --overlay-slot keeps, at the times drawn — refused, naming the frames that do fold, ' +
+    'when none is folded there. Not with --viewport',
   bone:
     "draw only the bones these globs match (`*` any run of characters, `?` one, the whole name; comma-separated) — on `inspect`, " +
     "for bones, axes and names; every bone stays in the legend, a left-out one saying why in `undrawn`. A pattern that matches no " +
@@ -1202,7 +1212,7 @@ const FLAG_VALUES: Record<string, string> = {
   max: '<px>',
   show: '<view[,view…]>',
   at: '<s[,s…]>',
-  zoom: '<name>[:<pad>]',
+  zoom: '<name|folds>[:<pad>]',
   bone: '<glob[,glob…]>',
   'hide-bone': '<glob[,glob…]>',
   'overlay-slot': '<glob[,glob…]>',
@@ -1577,10 +1587,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})` },
@@ -1593,9 +1603,9 @@ export const COMMANDS: CommandDoc[] = [
     usage: [
       'rigc inspect --candidate <dir | skeleton.json> [--show art,bones,…] [--dim] [--max 256] [--poser core|spine] [--out inspect.png]   (the setup pose)',
       '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 … --zoom <bone|slot|folds>[:<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,446 @@
+/**
+ * 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.
+ *
+ * ## Where and how big (issue #1386)
+ *
+ * Each folded frame also carries the world box of its folded triangles' posed
+ * vertices and their summed setup-pose area, alone and as a share of the mesh's
+ * — `foldExtent` says why the box is the frame's and the area the setup pose's.
+ *
+ * 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[];
+}
+
+/** A world box `[minX, minY, maxX, maxY]`, world units, y up. */
+export type FoldBox = [number, number, number, number];
+
+/** Where a set of folded triangles is at one pose, and how big they are (issue #1386). */
+export interface FoldExtent {
+  /** The world box of the folded triangles' vertices as posed at this frame — every vertex of each, nothing else. */
+  box: FoldBox;
+  /** Their summed area at the setup pose, world units² — each triangle's unsigned area in the rest table. */
+  area: number;
+  /** `area` over the mesh's own setup-pose area (every triangle's, unsigned): the share of the mesh's art that is turned over. */
+  share: number;
+}
+
+/** One frame on which a mesh has a folded triangle. */
+export interface FoldedFrame extends FoldExtent {
+  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;
+  /** The mesh's area at the setup pose, world units²: every triangle's unsigned area in the rest table, summed — what `share` is over. */
+  area: 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; box: string; area: 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;
+  /** Box every vertex of the mesh at the frame, rather than the folded triangles' vertices. */
+  boxWholeMesh?: boolean;
+  /** Size the folded triangles by their unsigned area as posed at the frame, rather than at the setup pose. */
+  areaPosed?: 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;
+}
+
+/** A mesh's area at the setup pose: every triangle's unsigned area in the rest table, summed in index order. */
+export function setupArea(rest: FoldRest): number {
+  let area = 0;
+  for (let t = 0; t < Math.floor(rest.triangles.length / 3); t++) area += Math.abs(cross2(rest.vertices, rest.triangles, t)) / 2;
+  return area;
+}
+
+/**
+ * Where `triangles` of one mesh are at one pose and how big they are: the world
+ * box of their posed vertices, and their summed setup-pose area, alone and as a
+ * share of `meshArea` (`setupArea(rest)`). `null` for no triangle.
+ *
+ * ⭐ The box is the pose's and the area is the setup pose's, on purpose. The box
+ * answers "where is it in this frame" — it is what a picture is framed to. The
+ * area answers "how much of the art is turned over", and a folded triangle's
+ * posed area cannot: it passes through 0 at the frame the triangle turns, so one
+ * triangle reads a different size on every frame it is folded and none of them
+ * says how much art it carries.
+ */
+export function foldExtent(
+  rest: FoldRest,
+  vertices: readonly number[],
+  triangles: readonly number[],
+  meshArea: number,
+  plant: FoldPlant = {},
+): FoldExtent | null {
+  if (triangles.length === 0) return null;
+  const box: FoldBox = [Infinity, Infinity, -Infinity, -Infinity];
+  const take = (v: number): void => {
+    box[0] = Math.min(box[0], vertices[2 * v]);
+    box[1] = Math.min(box[1], vertices[2 * v + 1]);
+    box[2] = Math.max(box[2], vertices[2 * v]);
+    box[3] = Math.max(box[3], vertices[2 * v + 1]);
+  };
+  if (plant.boxWholeMesh) for (let v = 0; v < vertices.length / 2; v++) take(v);
+  let area = 0;
+  for (const t of triangles) {
+    if (!plant.boxWholeMesh) for (let k = 0; k < 3; k++) take(rest.triangles[3 * t + k]);
+    area += Math.abs(cross2(plant.areaPosed ? vertices : rest.vertices, rest.triangles, t)) / 2;
+  }
+  return { box, area, share: meshArea > 0 ? area / meshArea : 0 };
+}
+
+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 area = setupArea(r);
+    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 };
+      }
+      const extent = foldExtent(r, posed.vertices, triangles, area, plant);
+      if (extent === null) continue;
+      for (const t of triangles) union.add(t);
+      folded.push({ index: frame.index, time: frame.time, triangles, ...extent });
+    }
+    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,
+      area,
+      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]',
+  box: "a frame's box is [minX, minY, maxX, maxY] in world units (y up) over every vertex of that frame's folded triangles as posed there, and nothing else",
+  area:
+    "a frame's area is its folded triangles' unsigned areas at the setup pose (the rest table), summed, in world units²; share is that over the mesh's area, every triangle's unsigned setup-pose area summed. The setup pose's, not the frame's: a folded triangle's posed area passes through 0 as it turns, so it says how far the turn has gone rather than how much art is turned over",
+};
+
+/** 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(', ');
+}
+
+/** `x` rounded to hundredths away from the box's inside, so the printed box holds every vertex the exact one does. */
+const outward = (x: number, up: boolean): string => ((up ? Math.ceil(x * 100) : Math.floor(x * 100)) / 100).toFixed(2);
+
+/**
+ * Where and how big, as the fold line and the inspect note print it:
+ * `in world box x [x0, x1] y [y0, y1] (w × h), setup-pose area A units² = S% of the mesh's`.
+ * The box is rounded outward to hundredths; the file states it exactly.
+ */
+export function extentText(extent: FoldExtent): string {
+  const [x0, y0, x1, y1] = extent.box;
+  return (
+    `in world box x [${outward(x0, false)}, ${outward(x1, true)}] y [${outward(y0, false)}, ${outward(y1, true)}] ` +
+    `(${(x1 - x0).toFixed(2)} × ${(y1 - y0).toFixed(2)}), setup-pose area ${extent.area.toFixed(2)} units² = ${(100 * extent.share).toPrecision(3)}% of the mesh's`
+  );
+}
+
+/**
+ * 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, its triangles, where they are and how big, 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(', ')}] ` +
+    `${extentText(worst)}; ` +
+    `${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,12 @@
  * 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 — and the same
+ * box and area, which `--zoom folds` frames the picture to (issue #1386).
+ *
  * Links nothing from the runtime: the poser is handed in.
  */
 import { createHash } from 'node:crypto';
@@ -71,12 +77,13 @@ import {
   viewportFor,
 } from './render_shared.ts';
 import { hypot2 } from './numeric.ts';
+import { DEGENERATE_SHARE, extentText, type FoldBox, foldedAt, foldExtent, type FoldPlant, FOLDS_READING, foldsOf, indexRuns, setupArea, 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 +190,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 +312,10 @@ 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;
+  /** Folds: a planted fold reading (`./folds.ts`) for the box and area the legend states and `--zoom folds` frames to. */
+  foldPlant?: FoldPlant;
 }
 
 /** A point in both spaces. */
@@ -425,6 +449,26 @@ 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[];
+  /** The world box of the folded triangles' vertices at this pose, `[minX, minY, maxX, maxY]`; `null` when none is folded (issue #1386). */
+  box: FoldBox | null;
+  /** The folded triangles' summed setup-pose area, world units² — 0 when none is folded. */
+  area: number;
+  /** `area` over the mesh's setup-pose area. */
+  share: number;
+}
+
 export interface LegendTile {
   /** With `--compare`: which build this tile is — `A` is `--candidate`, `B` is `--compare`. */
   build?: 'A' | 'B';
@@ -445,6 +489,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[] };
 }
@@ -460,7 +506,7 @@ export interface InspectLegend {
   fps: number;
   framing:
     | { kind: 'shot'; note: string }
-    | { kind: 'zoom'; bone?: string; slot?: string; pad: number; padFrom: 'stated' | 'default' }
+    | { kind: 'zoom'; bone?: string; slot?: string; folds?: string; pad: number; padFrom: 'stated' | 'default' }
     | { kind: 'viewport' };
   /** `--bone` / `--hide-bone` as given — each bone they leave out says so in its `undrawn`. */
   boneFilter?: { include: string[] | null; exclude: string[] | null };
@@ -470,6 +516,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; box: string; area: 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 };
@@ -559,7 +607,7 @@ export function readTimes(raw: string | undefined): number[] {
   return times;
 }
 
-/** `--zoom <name>[:<pad>]`: the name, and the pad in world units when one is stated. */
+/** `--zoom <name>[:<pad>]`: the name — a bone, a slot or `folds` — and the pad in world units when one is stated. */
 export function readZoom(raw: string): { target: string; pad: number | null } {
   const colon = raw.lastIndexOf(':');
   if (colon > 0) {
@@ -570,7 +618,7 @@ export function readZoom(raw: string): { target: string; pad: number | null } {
       return { target: raw.slice(0, colon), pad };
     }
   }
-  if (raw === '') throw new InspectError('--zoom needs a bone or slot name: --zoom <name>[:<pad>]');
+  if (raw === '') throw new InspectError('--zoom needs a bone or slot name, or folds: --zoom <name|folds>[:<pad>]');
   return { target: raw, pad: null };
 }
 
@@ -1036,10 +1084,17 @@ function slotsLeftOut(slots: ReadonlyArray<{ name: string }>, filter: SlotFilter
 // the view
 // ---------------------------------------------------------------------------
 
-/** The poses one picture is of: the frames, in the order the request named their times. */
-function posesOf(poser: Poser, request: InspectRequest, needAttachments: boolean): Array<{ frame: Frame; index: number }> {
+/**
+ * The poses one picture is of: the frames, in the order the request named their
+ * times — and every frame of the grid they were taken from, which `--zoom folds`
+ * reads when nothing is folded at the times drawn.
+ */
+function posesOf(poser: Poser, request: InspectRequest, needAttachments: boolean): { poses: Array<{ frame: Frame; index: number }>; grid: Frame[] } {
   const opts: PoseOptions = { bones: true, ...(needAttachments ? { geometry: true } : {}), ...(request.skin === undefined ? {} : { skin: request.skin }) };
-  if (request.animation === null) return [{ frame: sampleSetupPose(poser, opts)[0], index: 0 }];
+  if (request.animation === null) {
+    const grid = sampleSetupPose(poser, opts);
+    return { poses: [{ frame: grid[0], index: 0 }], grid };
+  }
   const animation = poser.animations.find((a) => a.name === request.animation);
   if (animation === undefined) {
     throw new InspectError(`no animation ${JSON.stringify(request.animation)} in this skeleton; it has [${poser.animations.map((a) => a.name).join(', ') || 'none'}]`);
@@ -1051,11 +1106,67 @@ function posesOf(poser: Poser, request: InspectRequest, needAttachments: boolean
     seen.add(index);
   }
   const frames = sampleAnimation(poser, animation.name, request.fps, opts);
-  return indices.map((index) => ({ frame: frames[index], index }));
+  return { poses: indices.map((index) => ({ frame: frames[index], index })), grid: frames };
 }
 
 type WorldBox = [number, number, number, number];
 
+/** The word `--zoom` takes for the fold reading's box rather than a bone's or a slot's (issue #1386). */
+export const ZOOM_FOLDS = 'folds';
+
+/**
+ * `--zoom folds`: the world box of every folded triangle of every kept mesh at
+ * the times drawn — the box the legend's `folds[]` states per tile, unioned —
+ * or, when none is folded there, `null` and the sentence that says which frames
+ * of the grid do fold, so the refusal points at them.
+ */
+function foldsZoomBox(
+  poser: Poser,
+  poses: ReadonlyArray<{ frame: Frame }>,
+  grid: readonly Frame[],
+  slotsOut: ReadonlySet<string>,
+  request: InspectRequest,
+  plant: InspectPlant,
+): { box: WorldBox; folds: string } | { miss: string } {
+  const rests = new Map<string, AttachmentRest>();
+  const restOf = (frames: ReadonlyArray<{ frame: Frame }>): void => {
+    for (const r of poser.rest(request.skin, frames.map((p) => p.frame.attachments ?? []))) rests.set(restKey(r.slot, r.attachment), r);
+  };
+  restOf(poses);
+  const box: WorldBox = [Infinity, Infinity, -Infinity, -Infinity];
+  for (const { frame } of poses) {
+    for (const shown of frame.attachments ?? []) {
+      if (slotsOut.has(shown.slot)) continue;
+      const rest = rests.get(restKey(shown.slot, shown.attachment));
+      if (rest === undefined || rest.kind !== 'mesh') continue;
+      const extent = foldExtent(rest, shown.vertices, foldedAt(rest, setupReading(rest), shown.vertices), setupArea(rest), plant.foldPlant);
+      if (extent === null) continue;
+      box[0] = Math.min(box[0], extent.box[0]);
+      box[1] = Math.min(box[1], extent.box[1]);
+      box[2] = Math.max(box[2], extent.box[2]);
+      box[3] = Math.max(box[3], extent.box[3]);
+    }
+  }
+  const kept = request.slotFilter === undefined ? 'mesh' : 'mesh the filter keeps';
+  if (box.every(Number.isFinite)) return { box, folds: `every triangle of every ${kept} folded over at the time(s) drawn` };
+  const at = request.animation === null ? 'the setup pose' : `t=${request.times.map((t) => `${t}s`).join(', ')}`;
+  if (request.animation === null) {
+    return { miss: `no ${kept} has a triangle folded over at ${at} — the setup pose is what a fold is read against, so nothing folds there; name --animation <name> --at <s>` };
+  }
+  // Where the grid does fold: the reading `render --folds` prints, over every frame of it, for the kept meshes.
+  restOf(grid.map((frame) => ({ frame })));
+  const keptRest = [...rests.values()].filter((r) => !slotsOut.has(r.slot));
+  const read = grid.map((frame, index) => ({ index, time: frame.time, attachments: (frame.attachments ?? []).filter((a) => !slotsOut.has(a.slot)) }));
+  const folding = foldsOf(keptRest, read).filter((m) => m.worst !== null);
+  const where =
+    folding.length === 0
+      ? `no ${kept} folds on any frame of ${JSON.stringify(request.animation)} at ${request.fps} fps`
+      : `at ${request.fps} fps these do: ${folding
+          .map((m) => `"${m.slot}" on frame(s) [${indexRuns(m.frames.map((f) => f.index))}], worst frame ${m.worst?.index} (t=${m.worst?.time.toFixed(4)}s)`)
+          .join('; ')}`;
+  return { miss: `no ${kept} has a triangle folded over at ${at} of ${JSON.stringify(request.animation)} — ${where}` };
+}
+
 /** The world box of what `--zoom` names, over every pose of the picture. */
 function zoomBox(
   poser: Poser,
@@ -1128,7 +1239,9 @@ interface Gathered {
   poses: Array<{ frame: Frame; index: number }>;
   /** `render`'s framing of the build — taken only when the picture is framed as a shot. */
   shot: Viewport | null;
-  zoom: { box: WorldBox; bone?: string; slot?: string } | null;
+  zoom: { box: WorldBox; bone?: string; slot?: string; folds?: string } | null;
+  /** `--zoom folds` with nothing folded at the times drawn: which frames do — the refusal's words, when no build has a box. */
+  foldsMiss: string | null;
   /** The rest table's topology for every attachment a pose shows, by `slot\0attachment` — taken only when a mesh view is drawn. */
   rest: Map<string, AttachmentRest> | null;
   pages: Map<string, Plate>;
@@ -1138,7 +1251,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. */
@@ -1163,18 +1276,35 @@ function gather(tag: 'A' | 'B', candidate: Candidate, texts: InspectTexts, reque
     const lengths = boneLengths(texts.skeletonText);
     const meshViews = request.show.some((w) => MESH_VIEWS.includes(w));
     const needAttachments = request.frame.kind === 'zoom' || meshViews || request.show.includes('slots');
+    const zoomFolds = request.frame.kind === 'zoom' && request.frame.target === ZOOM_FOLDS && plant.zoomBone === undefined;
     const posed = throughPoser(candidate.choice, (poser, roster) => {
-      const poses = posesOf(poser, request, needAttachments);
+      if (zoomFolds && (poser.bones.some((b) => b.name === ZOOM_FOLDS) || poser.slots.some((s) => s.name === ZOOM_FOLDS))) {
+        // The word and a name in the rig would mean two boxes; which is meant is the caller's to say, as with a bone and a slot.
+        throw new InspectError(
+          `--zoom ${ZOOM_FOLDS} is the fold reading's box, and this skeleton also has a ${poser.bones.some((b) => b.name === ZOOM_FOLDS) ? 'bone' : 'slot'} named "${ZOOM_FOLDS}"; ` +
+            `for that one write --zoom bone:${ZOOM_FOLDS} or --zoom slot:${ZOOM_FOLDS}, and for the folds a --viewport around the box render --folds prints`,
+        );
+      }
+      const { poses, grid } = posesOf(poser, request, needAttachments);
       const shot =
         request.frame.kind === 'shot' ? framingViewport(poser, request.maxSide, request.skin === undefined ? undefined : { skin: request.skin }, roster) : null;
       if (request.frame.kind === 'shot' && shot === null) {
         throw new InspectError('this skeleton poses no drawable attachment in any animation or in its setup pose — there is nothing to frame; name a box with --viewport');
       }
-      const zoom = request.frame.kind === 'zoom' ? zoomBox(poser, poses, plant.zoomBone ?? request.frame.target, lengths) : null;
+      const folds = zoomFolds ? foldsZoomBox(poser, poses, grid, slotsLeftOut(poser.slots, request.slotFilter, plant.ignoreSlotFilter !== true), request, plant) : null;
+      const zoom =
+        folds !== null
+          ? 'box' in folds
+            ? folds
+            : null
+          : request.frame.kind === 'zoom'
+            ? zoomBox(poser, poses, plant.zoomBone ?? request.frame.target, lengths)
+            : null;
+      const foldsMiss = folds !== null && 'miss' in folds ? folds.miss : null;
       const rest = meshViews
         ? new Map(poser.rest(request.skin, poses.map((p) => p.frame.attachments ?? [])).map((r) => [restKey(r.slot, r.attachment), r]))
         : null;
-      return { poses, shot, zoom, rest, bones: poser.bones, slots: poser.slots };
+      return { poses, shot, zoom, foldsMiss, rest, bones: poser.bones, slots: poser.slots };
     });
     return {
       tag,
@@ -1236,6 +1366,11 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     framing = { kind: 'viewport' };
   } else if (request.frame.kind === 'zoom') {
     const found = builds.map((b) => b.zoom).filter((z): z is NonNullable<Gathered['zoom']> => z !== null);
+    if (found.length === 0) {
+      // Only `--zoom folds` finds nothing without having refused already: a bone or slot that names nothing is refused while posing.
+      const misses = builds.map((b) => (compare ? `${b.tag === 'A' ? 'the --candidate build' : 'the --compare build'}: ${b.foldsMiss ?? ''}` : (b.foldsMiss ?? '')));
+      throw new InspectError(`--zoom ${request.frame.target}: nothing to frame — ${misses.join('; ')}`);
+    }
     const [x0, y0, x1, y1] = found.reduce<WorldBox>(
       (u, z) => [Math.min(u[0], z.box[0]), Math.min(u[1], z.box[1]), Math.max(u[2], z.box[2]), Math.max(u[3], z.box[3])],
       [Infinity, Infinity, -Infinity, -Infinity],
@@ -1250,7 +1385,14 @@ function view(builds: readonly Gathered[], request: InspectRequest, plant: Inspe
     }
     viewport = viewportFor(x0 - pad, y0 - pad, x1 + pad, y1 + pad, request.maxSide);
     const first = found[0];
-    framing = { kind: 'zoom', ...(first?.bone === undefined ? {} : { bone: first.bone }), ...(first?.slot === undefined ? {} : { slot: first.slot }), pad, padFrom: request.frame.pad === null ? 'default' : 'stated' };
+    framing = {
+      kind: 'zoom',
+      ...(first?.bone === undefined ? {} : { bone: first.bone }),
+      ...(first?.slot === undefined ? {} : { slot: first.slot }),
+      ...(first?.folds === undefined ? {} : { folds: first.folds }),
+      pad,
+      padFrom: request.frame.pad === null ? 'default' : 'stated',
+    };
   } else {
     const shots = builds.map((b) => b.shot).filter((v): v is Viewport => v !== null);
     if (!compare) {
@@ -1357,6 +1499,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 +1673,50 @@ 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;
+        const extent = foldExtent(rest, shown.vertices, folded, setupArea(rest), plant.foldPlant);
+        legendTile.folds.push({
+          slot: shown.slot,
+          attachment: shown.attachment,
+          triangleCount: rest.triangles.length / 3,
+          folded,
+          degenerate,
+          inverted,
+          box: extent === null ? null : extent.box,
+          area: extent === null ? 0 : extent.area,
+          share: extent === null ? 0 : extent.share,
+        });
+      }
+      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(', ')}]${f.box === null ? '' : ` ${extentText({ box: f.box, area: f.area, share: f.share })}`}`)
+                .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;