spine-rigc 2.56.0 → 2.57.0

package/README.md

@@ -587,7 +587,8 @@ material, like the gallery: a clone runs them.
 
 ## Commands
 
-Every command takes its paths explicitly. `rigc <command> --help` prints its flags, and
+Every command takes its paths explicitly. `rigc <command> --help` prints its flags —
+`rigc help <command>` prints the same page — and
 [AUTHORING.md §0](docs/AUTHORING.md) is the same list with what each flag means, which
 commands take it and what its default is.
 
@@ -600,6 +601,7 @@ commands take it and what its default is.
 | `repack <dir> --out <dir>` | a packed build **repacked from its own output** — `skeleton.json`, `skeleton.atlas` and the pages, with no parts kept — under the packing flags `build --pack` takes, so a packer improvement reaches a build whose parts are gone. Every region is lifted off its page, the skeleton read back with `ingest`, and `build --pack` run over the lifted parts with the same gate; it writes only after every region is shown pixel-identical to the input's, the skeleton byte-identical and the gate green, and refuses by name an atlas it cannot lift exactly. A skeleton the rebuild does not reproduce byte for byte — a build written before 2.2.0, whose header box was its stage — is refused naming every differing path, and written, every path printed, only under `--accept-skeleton-differences`. `--stage-box <slot>` reads the stage from the box a build carries for it (`skeleton.stageBox`), the one way the three files alone carry the stage exactly ([AUTHORING §0.4](docs/AUTHORING.md)) |
 | `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 |
+| `split --rig … --motion … --slot <name> --out <dir>` | the answer to a mesh refused because its triangles are **several pieces that share no vertex** — two legs after the triangles bridging them were deleted. It reads the two specs and writes them back into an absent or empty `--out` with one mesh per piece: piece 1 stays in the slot, piece k gets a new slot `<slot>_<k>` after it, each with the original's uvs and weights unchanged, its triangles renumbered outline first where the hull rule needs it, and every deform key re-sliced to the new indices — plus `split.json`, where every original vertex and triangle went. One piece is said so and nothing is written; what it cannot carry is refused by name ([AUTHORING §3.4.11](docs/AUTHORING.md)) |
 | `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. `--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. `--pass-through <cloth>:<leg>` adds a `pass-through.json` per set and prints the frames where a cloth drawn over a leg has its side inside the leg's drawn outline, with the depth and the world box — a reading, not a gate. `--angle-range <bone>:<relative-to>` prints how far one bone turns against another over each set: the lowest and highest angle and the frames they fall on — a reading, not a gate. `--viewport <x,y,w,h>` or `--viewport-from <frames.json>` draws over a given box instead of a fitted one, so two builds land on one pixel grid; a slot that reaches past it is named by set and frame, and `frames.json` records it. `--environment <schedule.json>` draws the rig under the wind and gravity its physics answers, in time — the same frames on the core and on spine-core; an inspection of the response the rig states, not a scene |
 | `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` |

package/docs/AUTHORING.md

@@ -156,6 +156,9 @@ name the commands that need the runtime (its `--help` lists the ones it runs).
 gate before it wrote, and which rules that gate is on this entry, before the install
 route; on a Spine export it says what it always said (`RC36`).
 `rigc --version` names the entry that ran.
+`rigc help <command>` prints what `rigc <command> --help` prints and exits the same
+way, on either entry, and `rigc help` alone is `rigc --help`; a name that is no
+command is refused naming the nearest one, exit 2, as an unknown command is.
 
 That entry's `build` takes the same flags and writes the same files, byte for byte:
 `skeleton.json`, `skeleton.atlas`, `skeleton.model.json`, and the pages `--pack` or
@@ -2304,7 +2307,7 @@ these messages prints the outline walk, because the walk is the fix:
 | a stated `hull` that disagrees | `hull 25 disagrees with the triangles, whose outline has 16 vertices (0 → 1 → 2 → …). Delete "hull" and rigc derives it, or state 16` |
 | outline vertices that are not the first `hull` of the list | `hull vertices must come first; vertex 19 is on the boundary and vertex 6 is not. The triangles' outline runs 0 → 1 → 2 → 3 → 4 → 9 → 14 → 19 → 24 → 23 → 22 → 21 → 20 → 15 → 10 → 5: list those 16 vertices first, in that order, then the 9 interior vertices` |
 | outline vertices that are first but zigzag | `hull vertices must trace the outline in order; the triangles' outline runs 0 → 1 → 3 → 5 → … → 4 → 2, so vertex 3 has to follow vertex 1 in the list, and vertex 2 does. Renumber the vertices along that walk` |
-| triangles with no single outline | `the triangles do not tile the outline: 25 vertices with a 16-vertex outline tile as 32 triangles and there are 33` — an unused vertex or a doubled interior triangle; or `the triangles' outline is not one closed loop: vertex 4 has 4 boundary edges` — a pinch, a hole, or a doubled triangle on the perimeter |
+| triangles with no single outline | `the triangles do not tile the outline: 25 vertices with a 16-vertex outline tile as 32 triangles and there are 33` — an unused vertex or a doubled interior triangle; or `the triangles' outline is not one closed loop: vertex 4 has 4 boundary edges` — a pinch, a hole, or a doubled triangle on the perimeter. Triangles in pieces that share no vertex get the same sentence and then `— the triangles are 2 pieces that share no vertex …` naming `rigc split`, which writes one mesh per piece (§3.4.11) |
 
 🚨 **A row-major grid is the case this catches**: a 5×5 grid's perimeter is 16 of
 its 25 vertices, interleaved with the interior, so no `hull` can describe that
@@ -3552,6 +3555,104 @@ packed region is still refused.
 `A46_SEQUENCE_ATTACHMENTS_SHOW_THE_FRAME_THE_FILE_STATES` (§5.2) holds the block and
 every frame the timelines show against the file.
 
+#### 3.4.11 `split` — one mesh per piece, when the triangles are several
+
+One mesh is one outline (the `hull` rule above), so a mesh whose triangles fall into
+pieces that share no vertex is refused at compile — typically after the transparent
+triangles that bridged two legs were deleted:
+
+```
+rigc compile error: skin "default" slot "legs" attachment "legs": the triangles' outline is not one closed
+  loop: the walk from vertex 0 closes after 8 of 16 boundary vertices — the triangles are 2 pieces that share no
+  vertex, and one mesh is one outline: `rigc split --rig <rig> --motion <motion> --slot legs --attachment legs
+  --out <dir>` writes one mesh per piece, its deform keys renumbered (AUTHORING §3.4.11) (see rigc guide §5.1)
+```
+
+Each name in that command is one shell word: a slot, placeholder or skin whose name
+holds a space or a character a shell reads (`'`, `$`, `;`, …) is printed
+single-quoted, a `'` inside it as `'\''` — `--slot 'left legs'` — and a plain name
+is printed as it is. So the command copies into a shell as printed, with only
+`<rig>`, `<motion>` and `<dir>` to fill in.
+
+The fix is one mesh per piece, and every number in it is a renumbering: each piece's
+`uvs`, its `weights` (or `vertices`), its `triangles`, and every `deform` key that
+moved it (§4.11). `rigc split` writes that proposal from the two spec files — not from
+a build, because a mesh of several pieces has none:
+
+```bash
+rigc split --rig rig.json --motion motion.json --slot legs --out split/
+# rigc split /abs/rig.json
+#   ..    motion   /abs/motion.json
+#   ..    mesh     skin "default" slot "legs" attachment "legs": 18 vertices, 16 triangles, 2 pieces (triangles that share a vertex are one piece)
+#   ..    piece 1  slot "legs" (the original slot): 9 vertices, 8 triangles, hull 8 — original order kept: [3, 4, 5, 6, 7, 8, 9, 16, 17]
+#   ..    piece 2  slot "legs_2" (new, drawn after "legs"): 9 vertices, 8 triangles, hull 8 — renumbered outline first, as the hull rule needs: piece vertex 0.. is original 0 → 1 → 2 → 15 → 10 → 11 → 12 → 13, then the interior [14]
+#   ..    deform   animation "walk": 5 key(s) re-sliced into 2 timelines — "legs" 3 with a run, "legs_2" 2 with a run
+#   ..    track    animation "walk": slot "legs" "rgba" copied to "legs_2"
+#   ..    images   ../  (the rig spec's own, restated from /abs/split — it resolves to /abs)
+# rigc: wrote /abs/split/rig.json
+# rigc: wrote /abs/split/motion.json
+# rigc: wrote /abs/split/split.json
+# rigc: build it with  rigc build --rig /abs/split/rig.json --motion /abs/split/motion.json --out <dir>
+```
+
+What it decides, and the one reason for each:
+
+| | |
+| --- | --- |
+| a piece | triangles that share a vertex — nothing else: no distance, no art, no threshold. Two triangles touching at one vertex are one piece, and that piece is refused for its pinch as the compiler would refuse it |
+| which piece is 1 | the one whose first triangle is listed first. Spine draws a mesh's triangles in list order, so that is the piece the original drew first; when the pieces' triangles interleave in the list, an `order` line says the split draws each piece whole and where they overlap the stacking can differ |
+| where the pieces go | piece 1 stays in the slot under its placeholder, so everything naming the slot keeps its meaning; piece k gets a new slot **`<slot>_<k>`** on the same bone with the same colour, dark colour and blend, directly after the original in `slots` — the draw order — filled under the **same placeholder**, so `name`, `path` and `image` resolve as before. A derived name the rig already declares is refused by name |
+| a piece's vertex order | the original's relative order when it already lists the piece's outline first and in order; otherwise the outline walk, then the interior in original order — the order the `hull` refusals ask for, so the piece builds without a second edit |
+| `hull`, `edges` | `hull` is left out (rigc derives it); stated `edges` are split with their vertices, and an edge joining two pieces is refused — so is one from a piece to a vertex no triangle names, the refusal saying `(in no piece: no triangle names it)` for that end. An edge whose **two** vertices no triangle names has no piece to go in: it is dropped, and named on a `dropped` line — `dropped  1 stated edge(s) between vertices no triangle names, edge 2 (vertex 18 to vertex 19): …` — so the pieces' `edges` are the original's minus exactly the ones that line names |
+| a deform key | its run re-sliced: each number goes to its vertex's piece at the vertex's new index, written as `offset` + `vertices`, and an index inside a piece's new run that the original run did not cover is written **`0`** — what the parser held there, because a key is a sparse edit and both encodings are offsets from setup. A piece the run did not reach gets the key with no `vertices`, the setup pose, which is what the original did to it. Every piece keeps the key's time and curve |
+| colour and attachment tracks on the slot | copied to every new slot; an `attachment` key showing the split placeholder shows each piece, any other shows nothing in the new slots. `setup` (or the slot's `attachment`) the same way |
+| `invariants.deformMayFold` naming the slot | its entry copied to the new slots |
+| `invariants.meshSlots` | left as stated, and the line does the arithmetic: the mesh slots the split adds, the mesh attachments the proposal's skins then hold (every `type: "mesh"` without a `source`, as the compile counts them), and — when that is over the budget — the figure to raise it by: `invariant invariants.meshSlots states 1, and the split adds 1 mesh slot(s): the proposal's skins hold 2 mesh attachment(s), 1 over the budget, so its build is refused at compile ("2 mesh slot(s) emitted") unless the rig spec raises invariants.meshSlots by 1, to 2; …`. Within the budget it says so. The refusal it predicts is the compile's (§3.7), which stops before `A13_MESH_BUDGET` runs |
+| a vertex no triangle names | no piece can hold it and still build, and it draws nothing in either rig: dropped, and named on a `dropped` line and in `split.json` |
+| `images` | restated from `--out`, so every `image` resolves to the file it resolved to before |
+
+It writes three files into an `--out` that is **absent or empty** — `rig.json` and
+`motion.json`, your two specs with the mesh split and nothing else changed but
+`images`, and `split.json` (`rigc-split/1`): for each piece its slot, placeholder,
+`vertices` (piece vertex `j` is original vertex `vertices[j]`), `triangles` (original
+triangle indices) and `hull`, and the `dropped` vertices. There is no in-place flag:
+your specs are the only statement of what the proposal must reproduce, so it is
+written beside them, never over them. Build it and look before adopting it.
+
+A mesh of one piece is said so on one line — `rigc split: skin "default" slot "legs"
+attachment "legs" is one piece — …; nothing to split, and nothing written` — exit 0.
+A slot, attachment or skin the specs do not have is refused with the names they do,
+exit 2. What the split cannot carry is refused by name, exit 1, because each needs a
+decision the specs do not state:
+
+| Refused | Why |
+| --- | --- |
+| a `generator` mesh | a generator builds one outline by construction; there are no authored triangles |
+| a `sequence` on the mesh, or a sequence timeline on it | which frames each piece shows is not stated |
+| `"boneIndexing": "raw"` | write the weights by name (`weights`) and split that |
+| a deform key stated as a `transform` (§4.11.1) | the model is evaluated over the whole attachment's geometry, and splitting changes the geometry it reads; state it as a `vertices` run |
+| a `fromVertex` key over a vertex with two or more bones, a run past the array | the compiler refuses the key; so does the split |
+| the slot filled in another skin | the new slots would show this skin's pieces under that skin too |
+| a linked mesh borrowing the mesh | its geometry would have to be one of the pieces |
+| a clip whose range ends at the slot | the new slots would fall outside it |
+| a draw-order key, or a slot-property track on a `group`, naming the slot | where the new slots go then is not stated |
+| a piece that is not one mesh either (a pinch, a hole) | splitting does not fix it; the message is the outline refusal for that piece |
+
+⭐ **What makes the proposal exact rather than plausible**: a piece's vertices carry
+the original's entries unchanged, so posing the split rig puts every piece vertex where
+the original put its vertex. The selftest holds that at tolerance 0 — the setup pose and
+every frame of every animation, deform keys, colour and attachment keys included, on
+the core and on spine-core — on a public probe of two legs, against the same mesh with
+its bridge still in (deleting triangles moves no vertex, so that mesh is the original
+every frame is held to), and plants a renumbering off by one and a deform key left
+un-renumbered to see each go red (`SPL01`–`SPL11`). The three lines above are held
+the same way: the printed command on a slot, placeholder and skin named with spaces
+and shell characters runs in `/bin/sh` and splits that mesh, and printed bare it does
+not (`SPL12`); the proposal's edges map back to the original's minus the named one
+(`SPL13`); and at an exact `meshSlots` budget the raise the line states is the build
+refusal's own count minus its budget, raised by it the proposal builds green, and one
+more slot of budget prints no raise (`SPL14`).
+
 ### 3.5 `constraints` — 4.3's single typed array
 
 Spine 4.3 folds every constraint into one `constraints` array with a `type`
@@ -6892,7 +6993,7 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `hull N disagrees with the triangles, whose outline has K vertices (0 → …)` | §3.4 — delete `hull`, or state K |
 | `hull vertices must come first; vertex i is on the boundary and vertex j is not. The triangles' outline runs …: list those K vertices first, in that order, then the M interior vertices` | §3.4 — renumber the vertices: the printed walk first, then the interior |
 | `hull vertices must trace the outline in order; the triangles' outline runs …, so vertex a has to follow vertex b in the list, and vertex c does` | §3.4 — renumber along the printed walk |
-| `the triangles do not tile the outline: …` / `the triangles' outline is not one closed loop: …` | §3.4 — a doubled triangle, an unused vertex, a pinch or a hole in `triangles` |
+| `the triangles do not tile the outline: …` / `the triangles' outline is not one closed loop: …` | §3.4 — a doubled triangle, an unused vertex, a pinch or a hole in `triangles`. When the message goes on `— the triangles are N pieces that share no vertex …`, the mesh is several meshes: `rigc split` writes one per piece (§3.4.11) |
 | `vertex N binds bone "X", which the rig does not declare as a bone` | §3.4 — an authored mesh's `weights` bind by NAME, like everything else in a rig spec. Fix the spelling, or declare the bone. The message names the skin, the slot, the placeholder and the vertex, because an index would name none of them |
 | `vertex N binds bone index I, which is not in the bone list` | §3.4 — a `"boneIndexing": "raw"` run on a mesh, bounding box, clipping polygon or path names a bone by its place in the bone array, and I is no place in it: past the end, negative or not a whole number. Count the rig's `bones` from 0, or give the bindings by name as `weights`, which cannot miss this way. ⚠️ **Refused earlier, not newly** (issue #917): the run is decoded to bone names once, when the attachment is built, and this is where an index that names no bone stops. Before that a mesh compiled and `A20` named the index at the gate, a bounding box, clipping polygon or path with its `lengths` stated compiled and `A33` named it, and only a path whose `lengths` rigc measures refused here, in this sentence. `MV04` plants it on each of the four kinds |
 | `the raw weighted run has a bone count of C at index I` / `the raw weighted run is truncated — vertex N claims C bone(s) and the array ends first` / `the raw weighted run decodes to N vertices but there are M uv pairs` | §3.4 — a mesh's `"boneIndexing": "raw"` run is not `boneCount, (index, x, y, weight) × boneCount` per vertex, one vertex per uv pair. These are the polygon's three sentences (whose last clause there reads `but vertexCount is M`), now asked of a mesh as well. Fix the run, or give the bindings by name as `weights`. ⚠️ **Refused earlier, not newly** (issue #917): the mesh run is decoded to bone names when the mesh is built, and a run that does not decode cannot be. Before that it compiled and `A20` named it at the gate (`has weights for 5 vertices but 4 uv pairs`, `vertex 3 has weight NaN`). `MV04` plants each |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.56.0",
+  "version": "2.57.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/skills/rigc/SKILL.md

@@ -100,7 +100,10 @@ row for each.
    parts were not kept, and writes only after every region and the skeleton are
    shown unchanged (`--accept-skeleton-differences` writes a rebuild whose skeleton
    differs, every difference printed; `--stage-box <slot>` reads a build's stage box)
-   — AUTHORING §0.4.
+   — AUTHORING §0.4. A mesh refused because its triangles are several pieces that
+   share no vertex: `rigc split --rig … --motion … --slot <slot> --out <dir>` writes
+   both specs back with one mesh per piece and every deform key renumbered — build
+   that — AUTHORING §3.4.11.
 7. Every finished unit ends with `rigc preview --candidate <out>`, and the report
    names the `.html` it wrote. The hand-off to a person is part of the work.
 

package/src/cli/core_commands.ts

@@ -31,6 +31,8 @@ import { findingLine, ingest, type IngestFinding, IngestSpecRefused, type Ingest
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
+import { splitMesh, SplitError } from '../meshsplit.ts';
+import { parseRigSpec } from '../rig.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 { AngleRangeError, angleRangeLine, type AngleRangeReading, angleRangesOf, type BonePair, readBonePairs } from '../anglerange.ts';
@@ -2100,6 +2102,55 @@ export const MODEL_AND_TEXT_GATE: BuildGate = {
   look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
 };
 
+/**
+ * split — one authored mesh's pieces, proposed as one mesh each (issue #1414).
+ *
+ * Reads the two spec files and nothing else: a mesh of several pieces does not
+ * compile, so there is no build to read. Writes the proposal — both specs and
+ * `split.json` — into an `--out` that is absent or empty, which is the whole of
+ * how it never overwrites anything: there is no in-place flag, because the
+ * specs it read are the only statement of what the proposal must reproduce,
+ * and a proposal nobody has built yet is not something to put over them.
+ */
+function cmdSplit(flags: Record<string, string>): void {
+  for (const flag of ['rig', 'motion', 'slot', 'out'] as const) {
+    if (flags[flag] === undefined) throw new UsageError(`split needs --${flag}`);
+  }
+  const rigPath = resolve(flags.rig);
+  const motionPath = resolve(flags.motion);
+  const outDir = resolve(flags.out);
+  for (const [flag, path] of [['rig', rigPath], ['motion', motionPath]] as const) {
+    if (!existsSync(path) || !statSync(path).isFile()) throw new SplitError(`--${flag} ${path}: no file there`, 2);
+  }
+  if (existsSync(outDir) && (!statSync(outDir).isDirectory() || readdirSync(outDir).length > 0)) {
+    throw new SplitError(
+      `--out ${outDir} ${statSync(outDir).isDirectory() ? `holds ${readdirSync(outDir).length} entr${readdirSync(outDir).length === 1 ? 'y' : 'ies'}` : 'is a file'}; ` +
+        'the proposal is written into an absent or empty directory only, so it never lands on top of a file — the specs it read included',
+      2,
+    );
+  }
+  const rig = parseRigSpec(readJsonFile(rigPath), rigPath);
+  const motion = parseMotionSpec(readJsonFile(motionPath), motionPath);
+  // The rig spec's `images` is relative to the rig file, and the proposal is written somewhere else: restate it from
+  // there, so every `image` resolves to the file it resolved to before.
+  const imagesDir = resolve(dirname(rigPath), rig.images ?? '.');
+  const images = relativeImagesPath(outDir, imagesDir);
+  console.log(`rigc split ${rigPath}`);
+  console.log(`  ..    motion   ${motionPath}`);
+  const result = splitMesh({ rig, motion, slot: flags.slot, ...(flags.attachment === undefined ? {} : { attachment: flags.attachment }), ...(flags.skin === undefined ? {} : { skin: flags.skin }), images });
+  if (result.kind === 'whole') {
+    console.log(`rigc split: ${result.line}`);
+    return;
+  }
+  for (const line of result.lines) console.log(`  ..    ${line}`);
+  console.log(`  ..    images   ${images}  (the rig spec's own, restated from ${outDir} — it resolves to ${imagesDir})`);
+  mkdirSync(outDir, { recursive: true });
+  writeJson(join(outDir, 'rig.json'), result.rig);
+  writeJson(join(outDir, 'motion.json'), result.motion);
+  writeJson(join(outDir, 'split.json'), result.record);
+  console.log(`rigc: build it with  rigc build --rig ${join(outDir, 'rig.json')} --motion ${join(outDir, 'motion.json')} --out <dir>`);
+}
+
 /**
  * The bodies the second entry runs under a name whose full-entry body is the
  * runtime's (`runtime.core` in `COMMANDS`, issue #1060) — registered by
@@ -2121,6 +2172,7 @@ export const CORE_ENTRY_RUNS: Readonly<Record<string, CommandRun>> = {
 export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   explain: ({ flags }) => cmdExplain(flags),
   ingest: ({ flags, positional }) => cmdIngest(flags, positional),
+  split: ({ flags }) => cmdSplit(flags),
   diff: ({ flags, lists, positional }) => cmdDiff(flags, lists, positional),
   check: ({ flags }) => cmdCheck(flags),
   render: ({ flags }) => cmdRender(flags),

package/src/cli/shared.ts

@@ -43,7 +43,7 @@ import { readViewportBox, ViewportError } from '../viewportpin.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';
-import { compileErrorLine } from '../guide.ts';
+import { compileErrorLine, nearestNames } from '../guide.ts';
 import { PACKAGE_ROOT, readPackageMeta, readVersion } from '../package_meta.ts';
 import { DEFAULT_MAX_RESIDUAL, DEFAULT_SCALE_MAX, DEFAULT_SCALE_MIN } from '../pose.ts';
 import {
@@ -65,6 +65,7 @@ import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAM
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
+import { SplitError } from '../meshsplit.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -1098,6 +1099,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     `printed (default ${DEFAULT_MIN_LEVER_PX}); below it the bone is refused \`no-bracket\` naming the measured ` +
     'lever, because an angle read across a short lever turns a half-pixel anchor error into several degrees',
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
+  attachment:
+    "the placeholder the mesh is filed under in its slot, as the rig spec's skin names it. Absent, the slot's one " +
+    'authored mesh in that skin; a slot holding none or several is refused naming them',
   skin:
     'pose under this skin, by the name the skeleton declares. Without it NO skin is set — every slot resolves ' +
     'through the default skin alone, so a slot whose art lives only in a named skin draws nothing. A name the ' +
@@ -1254,6 +1258,7 @@ const FLAG_VALUES: Record<string, string> = {
   'anchor-residual': '<0..1>',
   'inward-lever': '<px>',
   animation: '<name>',
+  attachment: '<name>',
   skin: '<name>',
   slot: '<name[,name…]>',
   hide: '<name[,name…]>',
@@ -1540,6 +1545,46 @@ export const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'split',
+    runtime: false,
+    spineFormat: false,
+    usage: ['rigc split --rig <path> --motion <path> --slot <name> [--attachment <name>] [--skin <name>] --out <dir>'],
+    flags: ['rig', 'motion', 'slot', 'attachment', 'skin', 'out'],
+    overrides: {
+      out: {
+        value: '<dir>',
+        meaning:
+          'directory to write the proposal into — rig.json and motion.json, the two specs with the mesh split, and ' +
+          'split.json, where every original vertex and triangle went. Absent or empty, and refused otherwise: the ' +
+          "proposal never lands on top of a file, the author's own specs included",
+      },
+      slot: {
+        value: '<name>',
+        meaning: 'the slot whose mesh to split, as the rig spec declares it. A name it does not declare is refused with every one it does',
+      },
+      skin: {
+        meaning:
+          'the skin the mesh is filed under in the rig spec (default: default). A name the rig spec does not declare ' +
+          'is refused with the ones it does',
+      },
+    },
+    notes: [
+      'split reads the two specs — not a build: a mesh of several pieces does not build —',
+      'and finds the pieces of one authored mesh: triangles that share a vertex are one piece.',
+      'A mesh of one piece is said so on one line, exit 0, and nothing is written. Otherwise it',
+      'writes one mesh per piece: piece 1 (the piece whose first triangle is listed first) stays',
+      'in the slot, piece k gets a new slot <slot>_<k> on the same bone, after it in the draw',
+      "order, under the same placeholder. Each piece carries the original's uvs and weights (or",
+      'vertices) unchanged and its triangles renumbered — outline first where the hull rule',
+      'needs it — and every deform key is re-sliced to the new indices; colour and attachment',
+      'tracks on the slot are copied to the new slots. Nothing is invented: a deform index the',
+      'original run did not cover is written 0, which is what the parser held there. What the',
+      'split cannot carry is refused by name, exit 1 (docs/AUTHORING.md §3.4.11 lists it); a',
+      'name the specs do not have is refused with the names they do, exit 2. Nothing is ever',
+      'written over the specs it read: build the proposal, look at it, then adopt it.',
+    ],
+  },
   {
     name: 'diff',
     runtime: false,
@@ -1945,6 +1990,16 @@ const USAGE_PARAGRAPHS: ReadonlyArray<{ about: readonly string[] | { flag: strin
       'is missing from it beats no spec at all.',
     ],
   },
+  {
+    about: ['split'],
+    lines: () => [
+      "split answers the refusal a mesh of several pieces meets at compile — the triangles'",
+      'outline is not one closed loop — with one mesh per piece, its uvs, weights, triangles',
+      'and deform keys renumbered, written beside the specs and never over them:',
+      '  rigc split --rig rig.json --motion motion.json --slot legs --out split/',
+      'Build what it wrote. See `rigc split --help`.',
+    ],
+  },
   {
     about: ['pose'],
     lines: () => [
@@ -2030,6 +2085,7 @@ export function usageText(docs: readonly CommandDoc[], checkout: string, rules:
     ...docs.flatMap((c) => c.usage.map((u) => `  ${u}`)),
     '',
     '  rigc <command> --help    that command\'s own flag table',
+    ...HELP_DOC.usage.map((u) => `  ${u}`),
     '  rigc --version           print the installed version (-v works too)',
   ];
   // Read only by the --profile paragraph, which only an entry running a command that takes --profile prints.
@@ -2783,6 +2839,46 @@ function commandNeedsRuntime(doc: CommandDoc, runs: readonly string[], args: rea
   );
 }
 
+/**
+ * `rigc help` documented as a command is (issue #1440): on the usage of both
+ * entries, and its own page for `rigc help --help` and `rigc help help`, as
+ * every listed command answers `--help`. Not a row of `COMMANDS`, because it
+ * has no body of its own: it is the dispatch reading another spelling of
+ * `--help` (`helpArgv`), on every entry alike.
+ */
+const HELP_DOC: CommandDoc = {
+  name: 'help',
+  usage: ['rigc help [<command>]    the same page as rigc [<command>] --help, and the same exit'],
+  flags: [],
+  runtime: false,
+  spineFormat: false,
+};
+
+/**
+ * `rigc help [<command>]` (issue #1440): the command line it stands for, which
+ * the dispatch then runs in its place — `rigc --help` for `help` alone,
+ * `rigc <command> --help` for a command the table documents — or `null` for
+ * `help`'s own page (`help --help`, `help help`). Rewritten rather than
+ * printed here, so the page and the exit code are the ones that spelling gets
+ * on this entry and cannot come apart from them: a command this entry does not
+ * run is refused as `<command> --help` is.
+ *
+ * ⚠️ A name the table does not document is refused by name with the nearest
+ * one, as a `UsageError` — printed and exited as an unknown command is, exit 2
+ * — and so is more than one name, rather than a guess at which was meant.
+ */
+export function helpArgv(rest: readonly string[]): string[] | null {
+  if (rest.length === 0) return ['--help'];
+  if (rest.length > 1) {
+    throw new UsageError(`help takes one command name and was given ${rest.length}: ${rest.join(' ')} — \`rigc help <command>\` is \`rigc <command> --help\``);
+  }
+  const [name] = rest;
+  if (name === HELP_DOC.name || name === '--help' || name === '-h') return null;
+  if (KNOWN_COMMANDS.includes(name)) return [name, '--help'];
+  const [nearest] = nearestNames(name, [...KNOWN_COMMANDS, HELP_DOC.name], 1);
+  throw new UsageError(`unknown command: ${name} — the nearest command is ${nearest} (\`rigc help ${nearest}\`)`);
+}
+
 /**
  * Run `argv` (`process.argv` without the runtime and the script) through
  * `entry`: the usage, `--version`, a command's `--help`, the command, and
@@ -2797,6 +2893,20 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
     throw new Error(`internal: this entry runs [${known.join(', ')}] by the command table and registers [${registered.join(', ')}]`);
   }
   const USAGE = usageText(docs, entry.checkout, entry.profileRules);
+  if (argv[0] === 'help') {
+    let target: string[] | null;
+    try {
+      target = helpArgv(argv.slice(1));
+    } catch (err) {
+      refuse(err, 'help', USAGE, entry);
+    }
+    if (target === null) {
+      console.log(commandHelp(HELP_DOC.name, [HELP_DOC]));
+      process.exit(0);
+    }
+    runCli(entry, target);
+    return;
+  }
   const [command, ...rest] = argv;
   try {
     if (command === undefined) {
@@ -2913,6 +3023,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(`rigc repack: ${err.message}`);
     process.exit(err.status);
   }
+  // A split refused (issue #1414): a name the specs do not have (2 — the invocation has to change), or something
+  // the specs hold that the split cannot carry (1). The message names it, and the usage under it would bury that.
+  if (err instanceof SplitError) {
+    console.error(`rigc split: ${err.message}`);
+    process.exit(err.status);
+  }
   // A page or frame that is not a PNG rigc can read, from any command that
   // opens one (`render`, `check`, `preview`, …) — issue #732. The sentence is
   // the one reader's and already names the file, what it is and what rigc

package/src/compile.ts

@@ -99,6 +99,7 @@ import {
   type MeshGeometry,
   type MeshVertexWeight,
 } from './mesh.ts';
+import { meshPieces, shellWord } from './meshsplit.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
 import {
   extractRegion,
@@ -5499,6 +5500,7 @@ function authoredHullAndEdges(
   vertexCount: number,
   triangles: number[],
   where: string,
+  named: { skin: string; slot: string; placeholder: string },
 ): { hull: number; edges: number[] } {
   try {
     const outline = traceOutline(vertexCount, triangles);
@@ -5511,11 +5513,31 @@ function authoredHullAndEdges(
     checkHullOrder(outline, vertexCount);
     return { hull: outline.hull, edges: att.edges ?? meshEdges(vertexCount, triangles, outline.hull) };
   } catch (err) {
-    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}`);
+    if (err instanceof MeshError) throw new CompileError(`${where}: ${err.message}${splitPointer(vertexCount, triangles, named)}`);
     throw err;
   }
 }
 
+/**
+ * The command that answers an outline refusal whose cause is pieces that share
+ * no vertex (issue #1414): one mesh is one outline, so the fix is one mesh per
+ * piece, and `rigc split` writes that proposal. Empty for every other cause —
+ * a pinch, a hole, a doubled triangle — whose fix is the triangles, and for a
+ * list the refusal is about because its indices are not vertices at all.
+ */
+function splitPointer(vertexCount: number, triangles: readonly number[], named: { skin: string; slot: string; placeholder: string }): string {
+  if (triangles.length % 3 !== 0 || triangles.some((v) => !Number.isInteger(v) || v < 0 || v >= vertexCount)) return '';
+  const count = meshPieces(vertexCount, triangles).pieces.length;
+  if (count < 2) return '';
+  // Each name one shell word (issue #1442): the command is copied into a shell, and a bare `left legs` is two arguments.
+  const skin = named.skin === 'default' ? '' : ` --skin ${shellWord(named.skin)}`;
+  return (
+    ` — the triangles are ${count} pieces that share no vertex, and one mesh is one outline: ` +
+    `\`rigc split --rig <rig> --motion <motion> --slot ${shellWord(named.slot)} --attachment ${shellWord(named.placeholder)}${skin} --out <dir>\` ` +
+    'writes one mesh per piece, its deform keys renumbered (AUTHORING §3.4.11)'
+  );
+}
+
 /**
  * The same two fields for geometry rigc built. The generators already put the
  * outline first and in order — a contour is all outline, a ring's outer ring
@@ -5599,7 +5621,7 @@ function buildRigMesh(
       vertices = { weighted: false, xy: raw.map(f32) };
     }
   }
-  const { hull, edges } = authoredHullAndEdges(att, uvCount / 2, att.triangles, where);
+  const { hull, edges } = authoredHullAndEdges(att, uvCount / 2, att.triangles, where, { skin: ctx.skinName, slot: ctx.slotName, placeholder });
   // `width`/`height` are the size of the image the mesh is drawn on. Stated
   // wins; otherwise the PNG the attachment names, already measured for the
   // atlas — the same `CompiledImage.width` a region reads, so a page with a

package/src/meshsplit.ts

@@ -0,0 +1,683 @@
+/**
+ * Splitting an authored mesh into its pieces (issue #1414, item 2).
+ *
+ * One mesh is one outline: `hull` is read off the triangles, and a triangle list
+ * whose outline is not one closed loop is refused at compile (`traceOutline`). So
+ * an author who deletes the triangles that bridged two islands — two legs joined
+ * by transparent cells, say — is left with a mesh no build accepts, and the only
+ * way forward is one mesh per island: its UVs, its weights, its triangles and
+ * every deform key that moved it, renumbered. This module writes that proposal
+ * from the two spec files, and nothing else.
+ *
+ * ⭐ **A piece is a set of triangles connected through shared vertices**, and
+ * nothing else decides it: no distance, no art, no threshold. Two triangles that
+ * touch at one vertex are one piece (and that piece is then refused for its pinch
+ * by the outline rule, exactly as the compiler would refuse it); two that share
+ * nothing are two. A vertex no triangle names draws nothing in either rig, so it
+ * belongs to no piece and is dropped, by name.
+ *
+ * 🔒 **Nothing in the proposal is a value the spec did not state.** Every piece's
+ * vertices carry the original's `uvs` and `weights` (or `vertices`) entries
+ * unchanged; its triangles are the original's, renumbered; its deform runs are the
+ * original's numbers at their new indices, with a `0` wherever the new array has
+ * a slot the original run did not cover — which is what the original array held
+ * there, because the parser fills everything outside a run with zero (AUTHORING
+ * §4.11: a key is a sparse edit, and both encodings are offsets from setup). So a
+ * piece poses exactly as its vertices did inside the original mesh; the selftest
+ * holds that at tolerance 0, frame by frame, on both posers.
+ *
+ * Where the pieces go, and why there:
+ *
+ *   - **The first piece stays in the original slot, under the original
+ *     placeholder.** Everything that names the slot — its setup attachment, its
+ *     colour and attachment timelines, a clip's range, a stage box — keeps
+ *     meaning what it meant, so the proposal edits the fewest lines it can.
+ *   - **Piece k (k ≥ 2) gets a new slot `<slot>_<k>`** (`pieceSlotName`), on the
+ *     same bone with the same colour, dark colour and blend, placed directly after
+ *     the original in the slot list — which is the draw order — and filled under
+ *     the SAME placeholder, so the attachment's `name`, `path` and `image` resolve
+ *     exactly as before. A derived name that is already a slot is refused by name;
+ *     the compiler would refuse the duplicate, and a different spelling would be a
+ *     name this module made up.
+ *   - **Pieces are numbered by their first triangle in the list**, which is the
+ *     order the original drew them in: Spine draws a mesh's triangles in list
+ *     order, so piece 1 is under piece 2 wherever they overlap. When the pieces'
+ *     triangles interleave in the list that is not the whole truth, and the
+ *     proposal says so rather than staying silent about it.
+ *
+ * A piece's vertices keep their original relative order when that order already
+ * lists the piece's outline first and in order; otherwise they are renumbered the
+ * way the hull refusal asks — the outline walk first, then the interior in
+ * original order — so every piece builds without a second hand edit.
+ *
+ * ⛔ What the proposal refuses rather than guesses, each by name: a generated
+ * mesh (its generator builds one outline by construction), a `sequence`, a raw
+ * `boneIndexing` run, a deform key stated as a `transform` model (it is evaluated
+ * over the attachment's whole geometry, and splitting changes the geometry it
+ * reads), the slot filled in another skin, a linked mesh borrowing this one, a
+ * clip whose range ends at this slot, a draw-order key or a slot-property group
+ * track naming the slot, and a sequence timeline on the attachment. Each would
+ * need a decision the spec does not state.
+ *
+ * Pure: no clock, no randomness, no file system. The CLI (`rigc split`) reads and
+ * writes the files; this module maps one pair of parsed specs to another.
+ */
+import { checkHullOrder, formatWalk, MeshError, traceOutline } from './mesh.ts';
+import { splitRigSkin, type RigAttachment, type RigMeshAttachment, type RigMeshBinding, type RigSlot, type RigSpec } from './rig.ts';
+import type { MotionDeformKey, MotionDeformTrack, MotionSetupSlot, MotionSpec, MotionTrack } from './types.ts';
+
+/** A split refused: `status` 2 when the invocation names something the specs do not have, 1 when the specs hold something the split cannot carry. */
+export class SplitError extends Error {
+  constructor(
+    message: string,
+    readonly status: 1 | 2,
+  ) {
+    super(message);
+  }
+}
+
+/** The record `rigc split` writes beside the two proposed specs. */
+export const SPLIT_SPEC = 'rigc-split/1';
+
+/** The slot piece `k` (1-based) of a split of `slot` is filed under. Piece 1 keeps the slot itself. */
+export function pieceSlotName(slot: string, k: number): string {
+  return k === 1 ? slot : `${slot}_${k}`;
+}
+
+/**
+ * A name as one POSIX shell word (issue #1442): unchanged when every character
+ * is one no shell treats specially, otherwise single-quoted with each `'`
+ * written `'\''`. A command line a refusal prints is copied into a shell, and
+ * a slot named `left legs` printed bare is two arguments there — the second
+ * refusal would then be about a slot nobody named.
+ */
+export function shellWord(name: string): string {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(name) ? name : `'${name.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * The mesh attachments a build of `rig` (with no manifest beside it) counts
+ * against `invariants.meshSlots`: every `type: "mesh"` in every skin that does
+ * not borrow its geometry through `source` — a linked mesh is not counted — the
+ * authored ones included, because a stated budget counts them. The selftest
+ * holds this to the compile refusal's own count (SPL14).
+ */
+function budgetedMeshCount(rig: RigSpec): number {
+  let count = 0;
+  for (const [name, skin] of Object.entries(rig.skins ?? {})) {
+    for (const map of Object.values(splitRigSkin(skin, `skin "${name}"`).attachments)) {
+      for (const entry of Object.values(map)) {
+        const att: unknown = entry;
+        if (isRecord(att) && att.type === 'mesh' && att.source === undefined) count++;
+      }
+    }
+  }
+  return count;
+}
+
+/** The properties a track keys on a slot, as opposed to a bone or a constraint. */
+const SLOT_PROPERTIES = new Set<string>(['rgba', 'rgb', 'alpha', 'rgba2', 'rgb2', 'attachment']);
+
+/**
+ * The connected pieces of a triangulation: triangles that share a vertex are one
+ * piece. Each piece lists its triangles (indices into the triangle list, in list
+ * order) and its vertices (ascending); pieces are ordered by their first
+ * triangle. `orphans` are the vertices no triangle names, ascending.
+ */
+export interface MeshPieces {
+  pieces: Array<{ triangles: number[]; vertices: number[] }>;
+  orphans: number[];
+}
+
+/** Read the pieces off a triangle list over `vertexCount` vertices. Indices are assumed in range (the caller checks). */
+export function meshPieces(vertexCount: number, triangles: readonly number[]): MeshPieces {
+  const parent = Array.from({ length: vertexCount }, (_v, i) => i);
+  const find = (v: number): number => {
+    let root = v;
+    while (parent[root] !== root) root = parent[root];
+    while (parent[v] !== root) {
+      const next = parent[v];
+      parent[v] = root;
+      v = next;
+    }
+    return root;
+  };
+  const used = new Array<boolean>(vertexCount).fill(false);
+  for (let i = 0; i + 2 < triangles.length; i += 3) {
+    const [a, b, c] = [triangles[i], triangles[i + 1], triangles[i + 2]];
+    used[a] = used[b] = used[c] = true;
+    // Union toward the smaller root, so the root is a deterministic function of the list.
+    for (const [p, q] of [[a, b], [b, c]]) {
+      const rp = find(p);
+      const rq = find(q);
+      if (rp !== rq) parent[Math.max(rp, rq)] = Math.min(rp, rq);
+    }
+  }
+  const byRoot = new Map<number, { triangles: number[]; vertices: number[] }>();
+  for (let t = 0; 3 * t + 2 < triangles.length; t++) {
+    const root = find(triangles[3 * t]);
+    let piece = byRoot.get(root);
+    if (piece === undefined) {
+      piece = { triangles: [], vertices: [] };
+      byRoot.set(root, piece);
+    }
+    piece.triangles.push(t);
+  }
+  for (let v = 0; v < vertexCount; v++) if (used[v]) byRoot.get(find(v))?.vertices.push(v);
+  // Map insertion order is first-triangle order, because triangles were visited in list order.
+  return { pieces: [...byRoot.values()], orphans: [...Array(vertexCount).keys()].filter((v) => !used[v]) };
+}
+
+/** What the caller asks to split. */
+export interface SplitRequest {
+  rig: RigSpec;
+  motion: MotionSpec;
+  slot: string;
+  /** The placeholder; absent, the slot's one authored mesh in the skin. */
+  attachment?: string;
+  /** The skin the attachment is filed under. Absent: `default`. */
+  skin?: string;
+  /** The rig spec's `images` as the proposal must state it (it is written somewhere else); absent, the field is left as it is. */
+  images?: string;
+}
+
+/**
+ * Two plausible wrong renumberings, planted by the selftest's controls and by
+ * nothing else: the vertex data placed one position along from where the record
+ * says it is, and every deform key copied to every piece as it stood — its start
+ * and its numbers unmoved, cut where the piece's shorter array ends, which is
+ * what a hand split that copied the keys and trimmed them until the build
+ * passed would hold (untrimmed, the compiler refuses the overrun first, and the
+ * pose reading this plant exists to test never runs).
+ */
+export interface SplitPlant {
+  offByOne?: boolean;
+  deformUnrenumbered?: boolean;
+}
+
+/** One proposed piece, as the record states it. */
+export interface SplitPieceRecord {
+  slot: string;
+  attachment: string;
+  /** The original vertex index of each of this piece's vertices, in the piece's order: piece vertex `j` is original vertex `vertices[j]`. */
+  vertices: number[];
+  /** The original triangle index of each of this piece's triangles, in the piece's order. */
+  triangles: number[];
+  /** The piece's outline vertex count — the `hull` its build derives. */
+  hull: number;
+  /** Whether the piece's vertices had to be renumbered outline first, rather than kept in original order. */
+  renumbered: boolean;
+}
+
+/** `split.json`: what was split and where each original vertex and triangle went. */
+export interface SplitRecord {
+  spec: typeof SPLIT_SPEC;
+  skin: string;
+  slot: string;
+  attachment: string;
+  vertices: number;
+  triangles: number;
+  pieces: SplitPieceRecord[];
+  /** Original vertices no triangle names: in no piece, and drawn by neither rig. */
+  dropped: number[];
+}
+
+/** The answer: a proposal, or the statement that the mesh is one piece. */
+export type SplitResult =
+  | { kind: 'split'; rig: RigSpec; motion: MotionSpec; record: SplitRecord; lines: string[] }
+  | { kind: 'whole'; line: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function quoteList(names: readonly string[]): string {
+  return names.length === 0 ? 'none' : names.map((n) => `"${n}"`).join(', ');
+}
+
+/** `[0, 1, 2, …, 9]` with the tail elided past `max` entries — a vertex list as a line prints it. */
+function shortList(values: readonly number[], max = 12): string {
+  return values.length <= max ? `[${values.join(', ')}]` : `[${values.slice(0, max).join(', ')}, … ${values.length - max} more]`;
+}
+
+/** Rebuild `record` with `entries` inserted directly after `after`'s key, preserving every other key's order. */
+function insertAfter<T>(record: Record<string, T>, after: string, entries: ReadonlyArray<[string, T]>): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] = value;
+    if (key === after) for (const [k, v] of entries) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Propose the split of one authored mesh into its pieces.
+ *
+ * The specs are not edited: the proposal is built on copies. A mesh of one piece
+ * answers `whole` with the line that says so; anything the split cannot carry
+ * throws `SplitError` naming it.
+ */
+export function splitMesh(request: SplitRequest, plant: SplitPlant = {}): SplitResult {
+  const rig = structuredClone(request.rig);
+  const motion = structuredClone(request.motion);
+  const skinName = request.skin ?? 'default';
+  const slotName = request.slot;
+  const where = (placeholder: string): string => `skin "${skinName}" slot "${slotName}" attachment "${placeholder}"`;
+
+  // --- what the invocation names ----------------------------------------------------------------------------
+  const slotNames = rig.slots.map((s) => s.name);
+  const slotIndex = slotNames.indexOf(slotName);
+  if (slotIndex < 0) throw new SplitError(`the rig spec declares no slot "${slotName}"; it declares ${quoteList(slotNames)}`, 2);
+  const skins = rig.skins ?? {};
+  const skin = skins[skinName];
+  if (skin === undefined) throw new SplitError(`the rig spec declares no skin "${skinName}"; it declares ${quoteList(Object.keys(skins))}`, 2);
+  const attachments = splitRigSkin(skin, `skin "${skinName}"`).attachments;
+  const filled = attachments[slotName];
+  if (filled === undefined) {
+    const fillers = Object.keys(skins).filter((name) => splitRigSkin(skins[name], `skin "${name}"`).attachments[slotName] !== undefined);
+    throw new SplitError(`skin "${skinName}" fills nothing in slot "${slotName}"; the skins that fill it: ${quoteList(fillers)}`, 2);
+  }
+  // Any mesh, generated ones included, so that the one mesh a slot holds is named — and refused for its generator by
+  // name below — rather than reported missing.
+  const isMesh = (att: unknown): boolean => isRecord(att) && att.type === 'mesh';
+  let placeholder = request.attachment;
+  if (placeholder === undefined) {
+    const meshes = Object.keys(filled).filter((p) => isMesh(filled[p]));
+    if (meshes.length !== 1) {
+      throw new SplitError(
+        `slot "${slotName}" in skin "${skinName}" holds ${meshes.length} mesh(es) (${quoteList(meshes)}) among ${quoteList(Object.keys(filled))}; name the one to split with --attachment`,
+        2,
+      );
+    }
+    placeholder = meshes[0];
+  }
+  const original = filled[placeholder];
+  if (original === undefined) {
+    throw new SplitError(`slot "${slotName}" in skin "${skinName}" has no attachment "${placeholder}"; it has ${quoteList(Object.keys(filled))}`, 2);
+  }
+
+  // --- what the attachment is --------------------------------------------------------------------------------
+  const at = where(placeholder);
+  const fields: unknown = original;
+  const type = isRecord(fields) && typeof fields.type === 'string' ? fields.type : 'region';
+  if (type !== 'mesh') throw new SplitError(`${at} is a "${type}" attachment; only a mesh has triangles to split`, 1);
+  const mesh = original as RigMeshAttachment;
+  if (mesh.generator !== undefined) {
+    throw new SplitError(`${at} is built by a "${mesh.generator.kind}" generator, which builds one outline by construction; there are no authored triangles to split`, 1);
+  }
+  if (mesh.sequence !== undefined) {
+    throw new SplitError(`${at} carries a "sequence"; a numbered series over one triangulation would have to become one per piece, and which frames each piece shows is not something the spec states`, 1);
+  }
+  if (mesh.boneIndexing === 'raw') {
+    throw new SplitError(`${at} states its weights as a raw index run ("boneIndexing": "raw"); write them as "weights", by name, and split that`, 1);
+  }
+  if (mesh.uvs === undefined || mesh.triangles === undefined || (mesh.vertices === undefined) === (mesh.weights === undefined)) {
+    throw new SplitError(`${at} needs uvs, triangles and exactly one of vertices or weights to be split`, 1);
+  }
+  const uvs = mesh.uvs;
+  const triangles = mesh.triangles;
+  if (uvs.length % 2 !== 0) throw new SplitError(`${at} has ${uvs.length} uv numbers, which is not a whole number of pairs`, 1);
+  const vertexCount = uvs.length / 2;
+  if (triangles.length % 3 !== 0) throw new SplitError(`${at} has ${triangles.length} triangle indices, which is not a whole number of triangles`, 1);
+  for (let i = 0; i < triangles.length; i++) {
+    const v = triangles[i];
+    if (!Number.isInteger(v) || v < 0 || v >= vertexCount) {
+      throw new SplitError(`${at}: triangle ${Math.floor(i / 3)} names vertex ${v}, and the mesh has vertices 0..${vertexCount - 1}`, 1);
+    }
+  }
+  const weights = mesh.weights;
+  const unweighted = mesh.vertices;
+  if (weights !== undefined && weights.length !== vertexCount) {
+    throw new SplitError(`${at}: weights cover ${weights.length} vertices but there are ${vertexCount} uv pairs`, 1);
+  }
+  if (unweighted !== undefined && unweighted.length !== uvs.length) {
+    throw new SplitError(`${at}: "vertices" is ${unweighted.length} numbers and the ${vertexCount} uv pairs need ${uvs.length}; a weighted run is written as "weights"`, 1);
+  }
+
+  // --- the pieces ------------------------------------------------------------------------------------------
+  const { pieces, orphans } = meshPieces(vertexCount, triangles);
+  if (pieces.length === 0) throw new SplitError(`${at} has no triangles`, 1);
+  if (pieces.length === 1) {
+    return {
+      kind: 'whole',
+      line:
+        `${at} is one piece — its ${triangles.length / 3} triangle(s) over ${vertexCount - orphans.length} vertices each reach every other through shared vertices` +
+        `${orphans.length === 0 ? '' : ` (and ${orphans.length} vertex(es) no triangle names: ${shortList(orphans)})`}; nothing to split, and nothing written`,
+    };
+  }
+  const names = pieces.map((_p, i) => pieceSlotName(slotName, i + 1));
+  for (const name of names.slice(1)) {
+    if (slotNames.includes(name)) {
+      throw new SplitError(`${at} is ${pieces.length} pieces, and piece ${names.indexOf(name) + 1}'s slot would be "${name}", which the rig spec already declares; rename that slot and split again`, 1);
+    }
+  }
+
+  // --- what the rest of the two specs says about the slot ---------------------------------------------------
+  const refusals: string[] = [];
+  for (const [name, other] of Object.entries(skins)) {
+    if (name === skinName) continue;
+    if (splitRigSkin(other, `skin "${name}"`).attachments[slotName] !== undefined) {
+      refusals.push(`skin "${name}" also fills slot "${slotName}", so the new slots would show this skin's pieces under that skin too`);
+    }
+  }
+  for (const [name, other] of Object.entries(skins)) {
+    for (const [ownSlot, map] of Object.entries(splitRigSkin(other, `skin "${name}"`).attachments)) {
+      for (const [ph, entry] of Object.entries(map)) {
+        const att: unknown = entry;
+        if (!isRecord(att)) continue;
+        if (att.type === 'linkedmesh' && att.source === placeholder && (att.slot ?? ownSlot) === slotName && (att.skin ?? 'default') === skinName) {
+          refusals.push(`skin "${name}" slot "${ownSlot}" attachment "${ph}" is a linked mesh borrowing this mesh's geometry`);
+        }
+        if (att.type === 'clipping' && att.end === slotName) {
+          refusals.push(`skin "${name}" slot "${ownSlot}" attachment "${ph}" is a clip whose range ends at slot "${slotName}", and the new slots would fall outside it`);
+        }
+      }
+    }
+  }
+  const groups = motion.groups ?? {};
+  for (const [animation, anim] of Object.entries(motion.animations)) {
+    for (const track of anim.tracks) {
+      if (track.group !== undefined && SLOT_PROPERTIES.has(track.property) && (groups[track.group] ?? []).includes(slotName)) {
+        refusals.push(`animation "${animation}" keys "${track.property}" on group "${track.group}", which holds slot "${slotName}"; the new slots are in no group`);
+      }
+    }
+    for (const key of anim.drawOrder ?? []) {
+      if ((key.offsets ?? []).some((o) => o.slot === slotName)) {
+        refusals.push(`animation "${animation}" moves slot "${slotName}" in its draw order at t=${key.t}; where the new slots go then is not stated`);
+        break;
+      }
+    }
+    for (const track of anim.sequence ?? []) {
+      if ((track.skin ?? 'default') === skinName && track.slot === slotName && track.attachment === placeholder) {
+        refusals.push(`animation "${animation}" keys a sequence on ${at}`);
+      }
+    }
+    for (const track of anim.deform ?? []) {
+      if ((track.skin ?? 'default') !== skinName || track.slot !== slotName || track.attachment !== placeholder) continue;
+      track.keys.forEach((key, i) => {
+        if (key.transform !== undefined) {
+          refusals.push(`animation "${animation}" deform key ${i} (t=${key.t}) states a "${key.transform.kind}" transform, which is evaluated over the whole attachment's geometry; state it as a "vertices" run to split it`);
+        }
+      });
+    }
+  }
+  if (refusals.length > 0) throw new SplitError(`${at} is ${pieces.length} pieces, and the split cannot carry what else names it: ${refusals.join('; ')}`, 1);
+
+  // --- each piece's vertex order ------------------------------------------------------------------------------
+  const orders: number[][] = [];
+  const hulls: number[] = [];
+  const renumbered: boolean[] = [];
+  pieces.forEach((piece, p) => {
+    const ascending = piece.vertices;
+    const localOf = new Map(ascending.map((v, j) => [v, j]));
+    const local = piece.triangles.flatMap((t) => [triangles[3 * t], triangles[3 * t + 1], triangles[3 * t + 2]].map((v) => localOf.get(v) as number));
+    let outline;
+    try {
+      outline = traceOutline(ascending.length, local);
+    } catch (err) {
+      if (err instanceof MeshError) {
+        throw new SplitError(`${at}: piece ${p + 1} (vertices ${shortList(ascending)}) is not one mesh either: ${err.message}`, 1);
+      }
+      throw err;
+    }
+    let order = ascending;
+    let moved = false;
+    try {
+      checkHullOrder(outline, ascending.length);
+    } catch (err) {
+      if (!(err instanceof MeshError)) throw err;
+      const onOutline = new Set(outline.walk);
+      order = [...outline.walk.map((j) => ascending[j]), ...ascending.filter((_v, j) => !onOutline.has(j))];
+      moved = true;
+    }
+    orders.push(order);
+    hulls.push(outline.hull);
+    renumbered.push(moved);
+  });
+
+  // --- the deform array's layout: influences per vertex, and where each vertex starts --------------------------
+  const influences = (v: number): number => (weights === undefined ? 1 : weights[v].length);
+  const base: number[] = [];
+  let length = 0;
+  for (let v = 0; v < vertexCount; v++) {
+    base.push(length);
+    length += 2 * influences(v);
+  }
+  const pieceOf = new Array<number>(vertexCount).fill(-1);
+  const positionOf = new Array<number>(vertexCount).fill(-1);
+  const pieceBase: number[][] = [];
+  const pieceLength: number[] = [];
+  orders.forEach((order, p) => {
+    let at2 = 0;
+    const bases: number[] = [];
+    order.forEach((v, j) => {
+      pieceOf[v] = p;
+      positionOf[v] = j;
+      bases.push(at2);
+      at2 += 2 * influences(v);
+    });
+    pieceBase.push(bases);
+    pieceLength.push(at2);
+  });
+  /** The vertex that owns original deform index `x`. */
+  const ownerOf: number[] = [];
+  for (let v = 0; v < vertexCount; v++) for (let k = 0; k < 2 * influences(v); k++) ownerOf.push(v);
+
+  // --- stated edges between two dropped vertices: no piece holds them, so they are dropped too, by name -----------
+  const droppedEdges: string[] = [];
+  if (Array.isArray(mesh.edges)) {
+    for (let i = 0; i + 1 < mesh.edges.length; i += 2) {
+      const [a, b] = [mesh.edges[i] / 2, mesh.edges[i + 1] / 2];
+      if (pieceOf[a] < 0 && pieceOf[b] < 0) droppedEdges.push(`edge ${i / 2} (vertex ${a} to vertex ${b})`);
+    }
+  }
+  /** Where a stated edge's vertex went, as a refusal names it. */
+  const pieceLabel = (v: number): string => (pieceOf[v] < 0 ? 'in no piece: no triangle names it' : `piece ${pieceOf[v] + 1}`);
+
+  // --- the pieces' attachments ---------------------------------------------------------------------------------
+  const pieceAttachments: RigMeshAttachment[] = orders.map((order, p) => {
+    // The plant: the data one position along from where the record says it is.
+    const source = plant.offByOne === true ? order.map((_v, j) => order[(j + 1) % order.length]) : order;
+    const local = new Map(order.map((v, j) => [v, j]));
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(mesh)) {
+      if (key === 'hull') continue;
+      if (key === 'uvs') out.uvs = source.flatMap((v) => [uvs[2 * v], uvs[2 * v + 1]]);
+      else if (key === 'triangles') out.triangles = pieces[p].triangles.flatMap((t) => [0, 1, 2].map((c) => local.get(triangles[3 * t + c]) as number));
+      else if (key === 'weights' && weights !== undefined) out.weights = source.map((v) => weights[v].map((b: RigMeshBinding) => ({ ...b })));
+      else if (key === 'vertices' && unweighted !== undefined) out.vertices = source.flatMap((v) => [unweighted[2 * v], unweighted[2 * v + 1]]);
+      else if (key === 'edges' && Array.isArray(value)) {
+        const edges: number[] = [];
+        for (let i = 0; i + 1 < value.length; i += 2) {
+          const [a, b] = [value[i] / 2, value[i + 1] / 2];
+          if (pieceOf[a] !== pieceOf[b]) throw new SplitError(`${at}: stated edge ${i / 2} joins vertex ${a} (${pieceLabel(a)}) to vertex ${b} (${pieceLabel(b)}); delete it, or delete "edges" and rigc derives them`, 1);
+          if (pieceOf[a] === p) edges.push(2 * (local.get(a) as number), 2 * (local.get(b) as number));
+        }
+        out.edges = edges;
+      } else out[key] = structuredClone(value);
+    }
+    return out as unknown as RigMeshAttachment;
+  });
+
+  // --- the deform keys -----------------------------------------------------------------------------------------
+  const splitKey = (key: MotionDeformKey, animation: string, i: number): MotionDeformKey[] => {
+    const timing = (k: MotionDeformKey): MotionDeformKey => ({ t: k.t, ...(k.ease === undefined ? {} : { ease: k.ease }), ...(k.curve === undefined ? {} : { curve: k.curve }) });
+    if (plant.deformUnrenumbered === true) {
+      return pieces.map((_piece, p) => {
+        const copy = structuredClone(key);
+        if (copy.vertices === undefined || copy.vertices === null || copy.fromVertex !== undefined) return copy;
+        const from = copy.offset ?? 0;
+        if (from >= pieceLength[p]) return timing(key);
+        copy.vertices = copy.vertices.slice(0, pieceLength[p] - from);
+        return copy;
+      });
+    }
+    const run = key.vertices;
+    if (run === undefined || run === null) return pieces.map(() => timing(key));
+    let start = key.offset ?? 0;
+    if (key.fromVertex !== undefined) {
+      const fv = key.fromVertex;
+      if (!Number.isInteger(fv) || fv < 0 || fv >= vertexCount) throw new SplitError(`animation "${animation}" deform key ${i} (t=${key.t}): "fromVertex" ${fv} is not a vertex of ${at} (0..${vertexCount - 1})`, 1);
+      start = base[fv];
+      if (weights !== undefined) {
+        for (let x = start; x < start + run.length && x < length; x++) {
+          if (influences(ownerOf[x]) > 1) {
+            throw new SplitError(
+              `animation "${animation}" deform key ${i} (t=${key.t}): "fromVertex" counts VERTICES, and this attachment is weighted — vertex ${ownerOf[x]} has ${influences(ownerOf[x])} of them; the compiler refuses this key, so the split does too`,
+              1,
+            );
+          }
+        }
+      }
+    }
+    if (start < 0 || start + run.length > length) {
+      throw new SplitError(`animation "${animation}" deform key ${i} (t=${key.t}): the run starts at deform index ${start} and is ${run.length} long, which ends at ${start + run.length}; ${at}'s deform array is ${length} long`, 1);
+    }
+    const runs = pieces.map(() => new Map<number, number>());
+    run.forEach((value, k) => {
+      const x = start + k;
+      const v = ownerOf[x];
+      const p = pieceOf[v];
+      if (p < 0) return; // a dropped vertex: no triangle draws it in either rig
+      runs[p].set(pieceBase[p][positionOf[v]] + (x - base[v]), value);
+    });
+    return runs.map((entries) => {
+      if (entries.size === 0) return timing(key);
+      const indices = [...entries.keys()];
+      const lo = Math.min(...indices);
+      const hi = Math.max(...indices);
+      // A gap is an index the original run did not cover, and the parser left it at zero there too.
+      const vertices = Array.from({ length: hi - lo + 1 }, (_v, k) => entries.get(lo + k) ?? 0);
+      return { t: key.t, offset: lo, vertices, ...(key.ease === undefined ? {} : { ease: key.ease }), ...(key.curve === undefined ? {} : { curve: key.curve }) };
+    });
+  };
+  const deformLines: string[] = [];
+  for (const [animation, anim] of Object.entries(motion.animations)) {
+    if (anim.deform === undefined) continue;
+    const next: MotionDeformTrack[] = [];
+    for (const track of anim.deform) {
+      if ((track.skin ?? 'default') !== skinName || track.slot !== slotName || track.attachment !== placeholder) {
+        next.push(track);
+        continue;
+      }
+      const perKey = track.keys.map((key, i) => splitKey(key, animation, i));
+      names.forEach((name, p) => next.push({ ...track, slot: name, keys: perKey.map((keys) => keys[p]) }));
+      const moving = names.map((_n, p) => perKey.filter((keys) => keys[p].vertices !== undefined).length);
+      deformLines.push(`deform   animation "${animation}": ${track.keys.length} key(s) re-sliced into ${names.length} timelines — ${names.map((n, p) => `"${n}" ${moving[p]} with a run`).join(', ')}`);
+    }
+    anim.deform = next;
+  }
+
+  // --- the slot tracks the new slots copy --------------------------------------------------------------------
+  const trackLines: string[] = [];
+  for (const [animation, anim] of Object.entries(motion.animations)) {
+    const next: MotionTrack[] = [];
+    for (const track of anim.tracks) {
+      next.push(track);
+      if (track.slot !== slotName || !SLOT_PROPERTIES.has(track.property)) continue;
+      for (const name of names.slice(1)) {
+        const copy = structuredClone(track);
+        copy.slot = name;
+        if (track.property === 'attachment') copy.keys = copy.keys.map((key) => ({ ...key, v: key.v === placeholder ? placeholder : null }));
+        next.push(copy);
+      }
+      trackLines.push(
+        `track    animation "${animation}": slot "${slotName}" "${track.property}" copied to ${quoteList(names.slice(1))}` +
+          (track.property === 'attachment' ? ` — a key showing "${placeholder}" shows its piece there, any other key shows nothing there` : ''),
+      );
+    }
+    anim.tracks = next;
+  }
+
+  // --- the rig spec ------------------------------------------------------------------------------------------
+  const slotS = rig.slots[slotIndex];
+  const newSlots: RigSlot[] = names.slice(1).map((name) => {
+    const copy: RigSlot = { ...structuredClone(slotS), name };
+    if (slotS.attachment !== undefined) copy.attachment = slotS.attachment === placeholder ? placeholder : null;
+    return copy;
+  });
+  rig.slots.splice(slotIndex + 1, 0, ...newSlots);
+  // The skin, short or long form: `splitRigSkin` hands back the live table inside this copy.
+  const liveSkin = rig.skins?.[skinName];
+  if (liveSkin === undefined) throw new Error('internal: the skin vanished from the copy');
+  const table = splitRigSkin(liveSkin, `skin "${skinName}"`).attachments;
+  table[slotName] = { ...table[slotName], [placeholder]: pieceAttachments[0] };
+  const rebuilt = insertAfter<Record<string, RigAttachment>>(table, slotName, names.slice(1).map((name, i): [string, Record<string, RigAttachment>] => [name, { [placeholder]: pieceAttachments[i + 1] }]));
+  for (const key of Object.keys(table)) delete table[key];
+  Object.assign(table, rebuilt);
+  const folds = rig.invariants?.deformMayFold;
+  if (folds !== undefined && rig.invariants !== undefined) {
+    rig.invariants.deformMayFold = folds.flatMap((entry) => (entry.slot === slotName ? [entry, ...names.slice(1).map((name) => ({ ...structuredClone(entry), slot: name }))] : [entry]));
+  }
+  if (request.images !== undefined) rig.images = request.images;
+
+  // --- the motion spec's setup ------------------------------------------------------------------------------
+  const setup = motion.setup;
+  const setupS = setup?.[slotName];
+  if (setup !== undefined && setupS !== undefined) {
+    const entries = names.slice(1).map((name): [string, MotionSetupSlot] => {
+      const copy: MotionSetupSlot = structuredClone(setupS);
+      if (setupS.attachment !== undefined) copy.attachment = setupS.attachment === placeholder ? placeholder : null;
+      return [name, copy];
+    });
+    motion.setup = insertAfter(setup, slotName, entries);
+  }
+
+  // --- the record and the lines --------------------------------------------------------------------------------
+  const record: SplitRecord = {
+    spec: SPLIT_SPEC,
+    skin: skinName,
+    slot: slotName,
+    attachment: placeholder,
+    vertices: vertexCount,
+    triangles: triangles.length / 3,
+    pieces: pieces.map((piece, p) => ({
+      slot: names[p],
+      attachment: placeholder,
+      vertices: orders[p],
+      triangles: piece.triangles,
+      hull: hulls[p],
+      renumbered: renumbered[p],
+    })),
+    dropped: orphans,
+  };
+  const lines: string[] = [
+    `mesh     ${at}: ${vertexCount} vertices, ${triangles.length / 3} triangles, ${pieces.length} pieces (triangles that share a vertex are one piece)`,
+    ...pieces.map((piece, p) =>
+      `piece ${p + 1}  slot "${names[p]}"${p === 0 ? ' (the original slot)' : ` (new, drawn after "${names[p - 1]}")`}: ${orders[p].length} vertices, ${piece.triangles.length} triangles, hull ${hulls[p]} — ` +
+        (renumbered[p]
+          ? `renumbered outline first, as the hull rule needs: piece vertex 0.. is original ${formatWalk(orders[p].slice(0, hulls[p]))}, then the interior ${shortList(orders[p].slice(hulls[p]))}`
+          : `original order kept: ${shortList(orders[p])}`),
+    ),
+  ];
+  // Interleaving: a later piece's triangle listed before an earlier piece's last one.
+  for (let p = 1; p < pieces.length; p++) {
+    const earlierLast = Math.max(...pieces.slice(0, p).map((q) => q.triangles[q.triangles.length - 1]));
+    const first = pieces[p].triangles[0];
+    if (first < earlierLast) {
+      lines.push(
+        `order    piece ${p + 1}'s triangle ${first} is listed before triangle ${earlierLast} of an earlier piece: the original drew their triangles interleaved, and the split draws each piece whole, after the one before it — where they overlap on screen, the stacking can differ`,
+      );
+      break;
+    }
+  }
+  if (orphans.length > 0) lines.push(`dropped  ${orphans.length} vertex(es) no triangle names, ${shortList(orphans)}: no piece holds them and neither rig draws them`);
+  if (droppedEdges.length > 0) {
+    const shown = droppedEdges.length <= 12 ? droppedEdges.join(', ') : `${droppedEdges.slice(0, 12).join(', ')}, … ${droppedEdges.length - 12} more`;
+    lines.push(`dropped  ${droppedEdges.length} stated edge(s) between vertices no triangle names, ${shown}: no piece holds them, so no piece's "edges" states them`);
+  }
+  lines.push(...deformLines, ...trackLines);
+  if (folds?.some((entry) => entry.slot === slotName)) lines.push(`invariant invariants.deformMayFold names slot "${slotName}"; its entry is copied to ${quoteList(names.slice(1))}`);
+  const budget = rig.invariants?.meshSlots;
+  if (budget !== undefined) {
+    // Counted over the proposal itself, the new slots' meshes included: the arithmetic the build's own refusal does.
+    const total = budgetedMeshCount(rig);
+    const head = `invariant invariants.meshSlots states ${budget}, and the split adds ${names.length - 1} mesh slot(s): the proposal's skins hold ${total} mesh attachment(s)`;
+    lines.push(
+      total > budget
+        ? `${head}, ${total - budget} over the budget, so its build is refused at compile ("${total} mesh slot(s) emitted") unless the rig spec raises invariants.meshSlots by ${total - budget}, to ${total}; the split leaves the budget as the spec states it`
+        : `${head}, within the budget; the split leaves it as the spec states it`,
+    );
+  }
+  return { kind: 'split', rig, motion, record, lines };
+}