spine-rigc 2.56.0 → 2.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.56.0",
+  "version": "2.58.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

@@ -18,7 +18,9 @@ whole interface, and this skill only says which of them to open.
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
 it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
 (and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+prints one section of `docs/AUTHORING.md` — a compile error points at its stable `CE_` code row. `rigc guide §5.1.<k>`
+prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
+uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 
@@ -100,7 +102,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/skills/rigc-face/SKILL.md

@@ -16,7 +16,9 @@ it will not do for you.
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
 it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
 (and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+prints one section of `docs/AUTHORING.md` — a compile error points at its stable `CE_` code row. `rigc guide §5.1.<k>`
+prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
+uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-ingest/SKILL.md

@@ -17,7 +17,9 @@ not do for you.
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
 it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
 (and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+prints one section of `docs/AUTHORING.md` — a compile error points at its stable `CE_` code row. `rigc guide §5.1.<k>`
+prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
+uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-motion/SKILL.md

@@ -17,7 +17,9 @@ not do for you.
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
 it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
 (and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+prints one section of `docs/AUTHORING.md` — a compile error points at its stable `CE_` code row. `rigc guide §5.1.<k>`
+prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
+uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/skills/rigc-rigging/SKILL.md

@@ -16,7 +16,9 @@ will not do for you.
 ` (see rigc guide <RULE>)`. Run that command first, before reading anything else:
 it prints that rule's row of the shipped guide and nothing else, and `rigc guide §<n>`
 (and `§<n>.<m>`, `§<n>.<m>.<k>`)
-prints one section of `docs/AUTHORING.md` — a compile error points at `§5.1`.
+prints one section of `docs/AUTHORING.md` — a compile error points at its stable `CE_` code row. `rigc guide §5.1.<k>`
+prints a numbered compile-error group of at most 30,000 UTF-8 bytes; only legacy
+uncoded library errors point at `§5.1`.
 
 ## Non-negotiables
 

package/src/atlas.ts

@@ -1998,7 +1998,7 @@ function packOnePageByFootprint(
       if (shapesMeet(shape, put.x, put.y, other.shape, other.x, other.y)) {
         throw new CompileError(
           `internal: the footprint pass placed a ${shape.width}x${shape.height} cell at ${put.x},${put.y} over ` +
-            `the footprint of the ${other.shape.width}x${other.shape.height} cell at ${other.x},${other.y}`,
+            `the footprint of the ${other.shape.width}x${other.shape.height} cell at ${other.x},${other.y}`, 'CE_ATLAS_INTERNAL_FOOTPRINT_OVERLAP',
         );
       }
     }
@@ -2313,7 +2313,7 @@ function layoutPack(
         // Unreachable: every cell was proven to fit an empty page above. Kept as
         // a named stop rather than an infinite loop if that ever stops holding.
         throw new CompileError(
-          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`,
+          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`, 'CE_ATLAS_PACKING_STALLED',
         );
       }
       // ⭐ Then the page is written at the smallest power-of-two pair that holds
@@ -2337,7 +2337,7 @@ function layoutPack(
       if (shrunk === null) {
         // Unreachable for the same reason as the stall above: these cells were
         // just placed on a maxEdge page.
-        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`);
+        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`, 'CE_ATLAS_SPILL_UNPACKABLE');
       }
       const onThisPage: Placement[] = [];
       shrunk.rects.forEach((rect, i) => {
@@ -2460,19 +2460,19 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
   const stem = opts.pageStem ?? 'skeleton';
   const pageEdges = opts.pageEdges ?? DEFAULT_PAGE_EDGES;
   if (!PAGE_EDGES.includes(pageEdges)) {
-    throw new CompileError(`--page-edges ${JSON.stringify(String(opts.pageEdges))}; known values: ${PAGE_EDGES.join(', ')}`);
+    throw new CompileError(`--page-edges ${JSON.stringify(String(opts.pageEdges))}; known values: ${PAGE_EDGES.join(', ')}`, 'CE_ATLAS_PAGE_EDGES_VALUE');
   }
   const shape = opts.shape ?? DEFAULT_PACK_SHAPE;
   if (!PACK_SHAPES.includes(shape)) {
-    throw new CompileError(`--pack-shape ${JSON.stringify(String(opts.shape))}; known values: ${PACK_SHAPES.join(', ')}`);
+    throw new CompileError(`--pack-shape ${JSON.stringify(String(opts.shape))}; known values: ${PACK_SHAPES.join(', ')}`, 'CE_ATLAS_PACK_SHAPE_VALUE');
   }
   if (!Number.isInteger(pageSize) || pageSize < 1) {
-    throw new CompileError(`--page-size must be a positive integer, got ${String(opts.pageSize)}`);
+    throw new CompileError(`--page-size must be a positive integer, got ${String(opts.pageSize)}`, 'CE_ATLAS_PAGE_SIZE_POSITIVE_INTEGER');
   }
   if (!Number.isInteger(padding) || padding < 0) {
-    throw new CompileError(`--padding must be a non-negative integer, got ${String(opts.padding)}`);
+    throw new CompileError(`--padding must be a non-negative integer, got ${String(opts.padding)}`, 'CE_ATLAS_PADDING_NONNEGATIVE_INTEGER');
   }
-  if (inputs.length === 0) throw new CompileError('nothing to pack: this compile emitted no images');
+  if (inputs.length === 0) throw new CompileError('nothing to pack: this compile emitted no images', 'CE_ATLAS_IMAGES_REQUIRED');
 
   const maxEdge = floorPowerOfTwo(pageSize);
 
@@ -2485,7 +2485,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
       `"${sorted[i].region}" is ${sorted[i].width}x${sorted[i].height} and with --padding ${padding} needs a ` +
         `${cells[i].w}x${cells[i].h} cell, which does not fit a ${maxEdge}x${maxEdge} page ` +
         `(${sorted[i].absPath}). Raise --page-size, lower --padding, or leave this build unpacked — a packer ` +
-        'cannot split one drawing across two pages.',
+        'cannot split one drawing across two pages.', 'CE_ATLAS_REGION_EXCEEDS_PAGE',
     );
   }
 
@@ -2542,7 +2542,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
         // two reads, or one of the two readers is wrong about it.
         throw new CompileError(
           `"${place.region}" measured ${input.width}x${input.height} from its PNG header and decodes to ` +
-            `${source.width}x${source.height} (${input.absPath})`,
+            `${source.width}x${source.height} (${input.absPath})`, 'CE_ATLAS_IMAGE_DIMENSIONS_CHANGED',
         );
       }
       extrudeCell(plate, source, place.x - padding, place.y - padding, padding);

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) {
@@ -2846,8 +2956,8 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     process.exit(2);
   }
   if (err instanceof CompileError) {
-    // Ends with ` (see rigc guide §5.1)` (issue #1397): a compile error names no rule, so it points at the section.
-    console.error(compileErrorLine(err.message));
+    // The site's code points at its one AUTHORING row; uncoded library errors keep the legacy section.
+    console.error(compileErrorLine(err.message, err.code));
     // The drops the compile recorded before it stopped, in the same line the
     // green build prints (issue #671). They were reported from the compile
     // RESULT alone, so the run that failed BECAUSE a file was missing was the
@@ -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