@rig-c/parts 1.15.0 → 1.17.0

package/README.md

@@ -291,9 +291,13 @@ agent skill.
 | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
 | `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
 | `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
+| `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](docs/AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
 
 `rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
 reason is a FAIL line), 2 a usage error or a command this version does not implement.
+Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
+guide's row for that rule, and each row is anchored on the web as
+`docs/AUTHORING.md#<RULE>`.
 
 What 1.0.0 holds stable — these commands and their flags, the config
 fields, the files a build writes and their spec ids, the environment, and what this

package/cli.ts

@@ -20,7 +20,8 @@ import { assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns,
 import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, rigcRunnerAt, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
 import { type CharacterConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
-import { PartsError, problemLine } from './src/errors.ts';
+import { failLine, guidePointer, PartsError } from './src/errors.ts';
+import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guide.ts';
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
@@ -136,7 +137,11 @@ usage:
       hip (the midpoint of r_hip and l_hip), the chest half way along neck ->
       hip, and each sleeve chain shoulder -> elbow with its tip at the wrist
       when every handwear part holds a wrist; a missing joint leaves its bone to
-      the rule. One note per joint says which. LINT then reads the torso along
+      the rule. One note per joint says which. Each arm and leg so placed is a
+      limb (issue #349): proposal.json's "limbs" cuts its layer at the elbow or
+      the knee into parts rigid on its links (and, when every ankle lies on a
+      footwear part, a foot on a bone of its own at the ankle that keeps its
+      setup angle); assemble with the block makes the cut. LINT then reads the torso along
       the neck -> hips line and each sleeve chain along shoulder -> wrist
       instead of by screen y, and prints the rule set it used first. Without
       --keypoints nothing changes. A wrist holds a part when it lies within
@@ -350,9 +355,13 @@ usage:
       holds an animation, ANIMATIONS_DO_NOT_FOLD reads each, the idle included,
       with rigc render --folds, physics constraints left out: a mesh triangle turned
       over against the setup pose fails, unless the --requirements file's
-      may_fold declares that slot and animation with a why. The last line says
-      how many of the bars measured — nine, ten with the fold bar — and names
-      the skipped ones.
+      may_fold declares that slot and animation with a why. Where a footwear
+      part rides a bone that hangs from another, FEET_STAY_LEVEL reads the
+      same render's geometry: while a bone above that bone is turned, the
+      part's drawing must stay within ±10 degrees of its setup pose (HQ's
+      line); config.bones' "inherit" on the foot is what keeps it there. The
+      last line says how many of the bars measured — nine, ten with the fold
+      bar, eleven with the feet-level bar — and names the skipped ones.
       --source adds SETUP_POSE_VS_SOURCE: REPORTED, never a FAIL — the setup
       pose against the painting by assemble's own recomposite figures (mean |d|,
       % within 8, error px over 40, uncovered error px where the pose has alpha
@@ -430,11 +439,16 @@ usage:
       drawn "back", "front" or {"before": <plan part>}, recorded in parts.json
       as from "painting:<name>" and counted 100 % source — and .cuts — a plan
       part's pixels inside a rig-pixel polygon taken into a new part, drawn the
-      same way, recorded with the plan part's from — and no rig section:
+      same way, recorded with the plan part's from — and .limbs (issue #349),
+      with the bones they name: each limb's layer cut at its joints into one
+      part per segment, each lower part carrying a cap past its joint, the
+      upper drawn over the lower — and no other rig section:
       bones, meshes, regions and motion need not exist yet, because propose
       drafts them from these parts (AUTHORING §4, the table).
       Prints one line per part, one \`cut:\` line per part a cut split (its
-      opaque pixels = what it kept + what each cut took), the seam override
+      opaque pixels = what it kept + what each cut took), one \`limb cut:\`
+      line per part a limb took and one \`limb cap:\` line per joint (the cap's
+      pixels from the layer and missing, and the box to paint them into), the seam override
       counts, the \`pixels:\` totals
       (opaque = visible + occluded; taken from the painting; visible but not
       projected), and \`recomposite vs source\` (mean |d| and % within 8 over the
@@ -590,6 +604,23 @@ usage:
       line and ${SCENE_REPORT_FILE} name what was accepted, and the run exits 1.
       Exit 0 when the check is PASS and nothing was accepted, 1 otherwise.
 
+  rig-parts guide <RULE | §<n> | §<n>.<m> | §<n>.<m>.<k>>
+      Print a slice of ${GUIDE_DOC}, the guide this package ships, read
+      from the installed file at the moment of the call; nothing is kept
+      apart from it. Every FAIL line ends with the command that prints its
+      rule's row: "(see rig-parts guide <RULE>)". guide <RULE> prints
+      "docs/AUTHORING.md §<addr>, line <N> — under "<heading>"" and the one
+      row naming the rule; a refusal and the bar it enforces (CHECK_<LINE>
+      and <LINE>) print one after the other, joined by "paired with
+      <OTHER>:". A name no row holds is refused on stderr
+      (GUIDE_RULE_KNOWN), with the three nearest names the guide holds,
+      and nothing printed in their place. guide §<n> prints section n,
+      after its subsections' numbers and sizes in KB; §<n>.<m>
+      is the m-th ### heading under it and §<n>.<m>.<k> the k-th #### under
+      that, counted as the file stands (the headings carry no number), and
+      §<n>.<m> lists its ####s as §<n> lists its ###s. Exit 0 printed, 1
+      refused, 2 usage.
+
   rig-parts --version
   rig-parts --help
 
@@ -598,7 +629,7 @@ ${LATER.length === 0 ? '' : `not implemented in this version (each exits 2):\n${
 
 function printRefusal(err: unknown): number {
   if (err instanceof PartsError) {
-    for (const p of err.problems) console.log(`  FAIL  ${problemLine(p)}`);
+    for (const p of err.problems) console.log(failLine(p));
     console.log(`refused: ${err.problems.length} problem(s)`);
     return EXIT_REFUSED;
   }
@@ -606,11 +637,28 @@ function printRefusal(err: unknown): number {
 }
 
 function usage(message: string): number {
-  console.log(`  FAIL  USAGE: ${message}`);
+  console.log(`  FAIL  USAGE: ${message}${guidePointer('USAGE')}`);
   console.log('rig-parts --help lists the commands');
   return EXIT_USAGE;
 }
 
+/** `guide`: one argument, a rule name or a section; the slice printed, or the refusal. */
+function cmdGuide(args: string[]): number {
+  if (args.length !== 1) return usage(`guide takes one rule name or one §<n> / §<n>.<m> / §<n>.<m>.<k>; got ${args.length} argument(s)`);
+  if (args[0].startsWith('-')) return usage(`guide takes no flag; "${args[0]}" is neither a rule name nor §<n> / §<n>.<m>`);
+  const path = join(import.meta.dir, GUIDE_DOC);
+  if (!existsSync(path)) return printRefusal(new PartsError([{ code: 'GUIDE_FILE_PRESENT', object: path, detail: 'no such file; the guide ships in the package beside cli.ts' }]));
+  const text = readFileSync(path, 'utf8');
+  const answer: GuideAnswer = args[0].startsWith('§') ? guideSection(text, args[0]) : guideRule(text, args[0]);
+  // The shared form: an unknown name or section is one coded FAIL line on stderr, exit 1.
+  if ('problem' in answer) {
+    console.error(failLine(answer.problem));
+    return EXIT_REFUSED;
+  }
+  for (const l of answer.lines) console.log(l);
+  return EXIT_OK;
+}
+
 function fixed(v: number | null): string {
   return v === null ? '-' : v.toFixed(4);
 }
@@ -655,7 +703,8 @@ function printLayerTable(set: LayerSet): void {
 /**
  * Every flag each command takes: `valued` flags carry a value, `switches` are bare. Each parser reads its row to
  * decide what it accepts, and {@link notTaken} prints the same row in the unknown-flag refusal, so the refusal
- * lists exactly the flags the parser accepts (CL26). `layers` takes one positional path and no flag, so it has no row.
+ * lists exactly the flags the parser accepts (CL26). `layers` takes one positional path and `guide` one positional
+ * argument, and neither takes a flag, so neither has a row.
  */
 const TAKES = {
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
@@ -1047,7 +1096,7 @@ function cmdCompare(args: string[]): number {
     console.log(`rig-parts compare: left ${left}, right ${right}${map === null ? ', no map' : `, map ${map}`}`);
     for (const l of structureLines(c)) console.log(l);
     const missing = requiredProblems(c, map ?? 'the map');
-    for (const p of missing) console.log(`  FAIL  ${problemLine(p)}`);
+    for (const p of missing) console.log(failLine(p));
     return missing.length > 0 ? EXIT_REFUSED : EXIT_OK;
   } catch (err) {
     return printRefusal(err);
@@ -1398,9 +1447,10 @@ function main(argv: string[]): number | Promise<number> {
   if (command === 'build') return cmdBuild(rest);
   if (command === 'compose') return cmdCompose(rest);
   if (command === 'mesh-draft') return cmdMeshDraft(rest);
+  if (command === 'guide') return cmdGuide(rest);
   const later = LATER.find(([name]) => name === command);
   if (later !== undefined) {
-    console.log(`  FAIL  NOT_IMPLEMENTED: \`rig-parts ${command}\` (${later[1]}) is not implemented in this version, ${version()}`);
+    console.log(`  FAIL  NOT_IMPLEMENTED: \`rig-parts ${command}\` (${later[1]}) is not implemented in this version, ${version()}${guidePointer('NOT_IMPLEMENTED')}`);
     return EXIT_USAGE;
   }
   return usage(`unknown command "${command}"`);