@rig-c/parts 1.23.0 → 1.24.0

package/docs/AUTHORING.md

@@ -1619,6 +1619,28 @@ to 0.258 of its weight on the trees; and `check`'s `BREATH_VISIBLE`, which reads
 `topwear` part as the torso, read the dress's idle heat at 1.592 against the floor
 3.809, where the same dress with the robe chains read 3.9 — the half on the trees has
 no idle key. Neither is barred here; both are the dress's to weigh before declaring it.
+Since issue #411 the bar reads the breath alone, and on that fixture the breath moves
+the dress 0.106 and the robe-chained dress 2.62: both fail, and the 3.9 was the robe
+chains' keyed swing below the hip, not the breath (the CK502 and CK503 controls).
+
+**What rides a tail** (issue #391). An accessory wrapped round a tail the `back hair`
+recipe drafts — a ribbon, in See-through's `headwear` or `earwear` layer — rides that
+tail's links, not `head`: under the recipe the tail moves by the world, and a part left on
+`head` stays where the tail was. Which links is read off the overlap, never off the
+part's name: each of the part's pixels over the tail's art is given to the span of the
+back hair's mesh nearest it (its fixed segment on `head`, or one tree link, the distance
+the weights read), and the part rides when one of those spans is a link. Its mesh's
+segments are then the spans it lies on — each link by name, the head's span written
+out — so every vertex weights by the rule the tail's own art does, the pixels off the
+tail (a ribbon's loops) included; no accessory bone, pendant or strand chain is drafted
+for it, and a note names each span with its pixel count. A part over no link keeps the
+accessory rule. It is part of the recipe's drafting, not a field: the rule reads only
+the art, and without the recipe no tail moves by the world and nothing here runs. On
+`wind` (rig-c 2.54.0, `rigc render --environment`, idle frame 200 of 200 at 60 fps,
+0.916 px per rig px), the ribbon pixels painted over the tail that are drawn where the
+tail has no hair went from 2,429 at calm and 8,363 at wind (10, 0) to 30 and 230; the
+230 all lie within 3.6 px of the hair's edge, where the ribbon's mesh and the hair's are
+two different lattices.
 
 **Every spring is stable at its step (A23's inequality).** Per step spine-core does
 `v += −strength·x·step·massInverse`, `x += v·step`, `v *= d` with d = damping^(60·step);
@@ -2753,7 +2775,7 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="CHECK_LOOP_LAST_FRAME_AT_DURATION"></a>`CHECK_LOOP_LAST_FRAME_AT_DURATION` | the idle's last frame does not sit at `duration` | `motion.duration` — a whole number of 1/12 s |
 | <a id="CHECK_LOOP_CLOSES"></a>`CHECK_LOOP_CLOSES` | frame 0 and the frame at `duration` differ (max and first pixel quoted); with a physics constraint, the frames of the rig with every physics constraint left out, and the object says so (§7, *loop*) | a track whose last key is not its first |
 | <a id="CHECK_SEAM_WITHIN_BAR"></a>`CHECK_SEAM_WITHIN_BAR` | the setup pose does not reproduce the flat stack of parts | read the `seam pair` lines and `check/seam/` pictures (§7; magenta = a counted pixel, cyan = the box round them): the pair, its boxes and the pixels counted. Usually a region or mesh placed off its part; compare with `recomposite_rig.png`. A pair of one layer cut in two with `differing_copies_px` is the cut line: move the polygon's edge, not `overlap` |
-| <a id="CHECK_BREATH_VISIBLE"></a>`CHECK_BREATH_VISIBLE` | the torso (`topwear`), rendered alone, barely moves over the idle — or the feet (`footwear`), rendered alone, move at all | the chest's breath tracks (`motion.tracks` on `chest`), or the torso mesh's `segments`; for the feet, the bone their region rides (`regions.<part>`, `root` in both examples) |
+| <a id="CHECK_BREATH_VISIBLE"></a>`CHECK_BREATH_VISIBLE` | the breath alone barely moves the torso (`topwear`, rendered alone, the idle with and without its breath tracks — issue #411; the whole idle's figure is printed beside it, and motion that is not the breath's is not counted), or the idle has no breath track at all — or the feet (`footwear`), rendered alone, move at all | the chest's breath tracks (`motion.tracks` on `chest`), or the torso mesh's `segments`; for the feet, the bone their region rides (`regions.<part>`, `root` in both examples) |
 | <a id="CHECK_BLINK_NO_HOLE"></a>`CHECK_BLINK_NO_HOLE` | with the blink held shut, the eyewhite box shows the page where the open eye had art | the layer under the eye: the `face` part has no art there. Take the face from the other run, or add a part under the eye; `motion.blink.squash` only hides the hole less |
 | <a id="CHECK_CHAIN_LAG"></a>`CHECK_CHAIN_LAG` | a rotate track leads (or does not lag) the keyed bone above it, or a chain link swings less than the link above — or, in a chain that carries a part the scene file declares `rests`, more than the link above (issue #245; the object names the part and the file) | that chain track's `phase`/`lag` (a positive `lag`, a child `phase` above its parent's) or its `amps` (non-decreasing toward the tip; non-increasing on a chain declared resting) |
 | <a id="CHECK_TIP_OVER_ROOT"></a>`CHECK_TIP_OVER_ROOT` | a `handwear`/`bottomwear` part's art in the lower half of its box travels less than 1.4725 times as far as in the upper half, measured from the idle's posed geometry (rig px quoted) | the chain track's `amps` (grow toward the tip), or the mesh's `segments` (the chain must be among them), or its mode: on `scarf`'s short skirt the proposal's lattice read 1.207 and the same part in `contour` mode 1.738 with the same segments and idle (issue #118) — both carried the `chest` segment #262 removed, after which the lattice reads 3.487. When the detail says `the root travels with the breath (x px of y px): it is carried by \`<bone>\`` (issue #262) the chain is not the cause: a bone an idle `translate` track moves (the breath) moves the root more than the tip, and with that translate held still (the part posed again without it, in proportion to each vertex's weight on the bone and those under it) the ratio passes — the row adds `carried_by`, `breath_rig_px`, `root_without_breath_rig_px` and `tip_without_breath_rig_px`; take that bone's segment off the mesh, or bind the root to the bone the part hangs from. A part the scene file declares `rests` (issue #245) is held the other way, its tip half's travel at most its root half's (ratio ≤ 1); the detail then reads `the scene file's rests declares its tip at rest, so a ratio <= 1 is required`, and for it the fix is the chain's `amps` (shrinking toward the tip) or the mesh's tip weighted to a bone the idle does not swing |
@@ -2927,7 +2949,7 @@ the two examples [observed]:
 
 | line | measures | bar | `reference-demo` | `reference-sample` | SKIP when |
 | --- | --- | --- | --- | --- | --- |
-| <a id="BREATH_VISIBLE"></a>`BREATH_VISIBLE` | `topwear` parts rendered alone (`rigc render --slot`): heat mean over their box; `footwear` parts alone: heat max over theirs | torso mean ≥ 3.809; feet max ≤ 0 | 15.251; 0 | 7.617; 0 | no `topwear` and no `footwear` part. One of the two absent (issue #323): the other half is measured and decides the line, which then carries `halves_measured` `"1 of 2"` first, then each half's own status — `torso_status`, `feet_status` — the absent half's `SKIP` with its `torso_reason` or `feet_reason`; a run that measured both halves writes the keys it always wrote |
+| <a id="BREATH_VISIBLE"></a>`BREATH_VISIBLE` | the torso: the breath alone (issue #411). The breath bones are every bone an idle track translates, and the breath tracks every idle track that translates or scales one of them (the drafted breath: `chest` `translatey` and `scalex`). The `topwear` parts are rendered alone (`rigc render --slot`) from one throwaway build that carries, beside every animation, the idle with those tracks held at rest (0 for a translate, 1 for a scale, at each track's first and last key time — the bone as it stands without them, the idle still keyed to its end), so the two idles share a grid; per pixel, the largest \|(with_t − with_0) − (without_t − without_0)\| over the frames and channels, meaned over their box (`torso_heat_mean`). Motion in both renders — a keyed cloth swing, physics answering the world — cancels; physics the breath sets moving counts. Until #411 the figure was the whole idle's heat over the box, which a keyed swing passed for a torso that did not breathe; a refusal still prints that whole-idle figure beside the breath's. An idle with no breath track reads 0 and fails, naming why — a torso that does not breathe is what the bar finds, so it is not a SKIP. The feet: `footwear` parts alone, heat max over theirs | torso mean ≥ 3.809; feet max ≤ 0 | 15.251; 0 | 7.617; 0 | no `topwear` and no `footwear` part. One of the two absent (issue #323): the other half is measured and decides the line, which then carries `halves_measured` `"1 of 2"` first, then each half's own status — `torso_status`, `feet_status` — the absent half's `SKIP` with its `torso_reason` or `feet_reason`; a run that measured both halves writes the keys it always wrote |
 | <a id="BLINK_NO_HOLE"></a>`BLINK_NO_HOLE` | the setup pose with every `scaley` track on the eyewhite slots' bones held at its closed value, against the setup pose, at full size: pixels in the eyewhite box that show the page where the open eye had art | 0 px | 0 | 0 | no `eyewhite` part, or no `scaley` track on its bones goes below its first key |
 | ″ (reported) | the same box: each closed-eye pixel's max-channel distance to the nearest colour the open eye's box holds — max, and pixels over 40 | none | 15; 0 | 11; 0 | as above |
 | <a id="CHAIN_LAG"></a>`CHAIN_LAG` | `motion.json`'s rotate tracks read as sines (DFT of the keys: period, amplitude, phase) and arranged by the bone tree — a keyed bone's parent is its nearest keyed ancestor | every lag ≥ 0.001 cycle; amplitude non-decreasing down each unbranched chain — non-increasing down a chain that carries a part declared `rests` (issue #245) | lags 0.040 (neck to head) to 0.120; 12 chains | lags 0.040 to 0.100; 9 chains | no rotate track under another of the same period |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/check.ts

@@ -101,6 +101,7 @@ import {
   FACE_FEATURE_TAGS,
   FACE_TAGS,
   FEET_TAGS,
+  breathHeat,
   frameBox,
   heatField,
   partsTagged,
@@ -3133,13 +3134,40 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation idle --slot ${ps.map((p) => p.name).join(',')}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
     return readFrameSet(dir);
   };
+  // Issue #411: the breath alone — a throwaway copy of the build carrying, beside every animation, the idle with its
+  // breath tracks held at rest; the torso rendered alone in both idles, from that one build, so the two share a grid.
+  const breathPair = (ps: readonly PartRecord[]): BreathPair | null => {
+    const tracks = breathTracks(inp.motion);
+    if (tracks.length === 0) return null;
+    const dir = join(isoDir, BREATH_SCRATCH);
+    const anims = isRecord(inp.motion.animations) ? inp.motion.animations : {};
+    const idleAnim = isRecord(anims.idle) ? anims.idle : {};
+    let name = BREATH_ANIMATION;
+    while (name in anims) name = `${name}_`;
+    // Each breath track held at rest over its own span: the idle without the breath, still keyed to its end, which rigc
+    // requires of an animation's last key.
+    const kept = (Array.isArray(idleAnim.tracks) ? idleAnim.tracks : []).map((t) => (isRecord(t) && isBreathTrack(t, tracks) ? heldTrack(t) : t));
+    mkdirSync(dir, { recursive: true });
+    const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
+    writeFileSync(join(dir, 'rig.json'), JSON.stringify({ ...inp.rig, images }));
+    writeFileSync(join(dir, 'motion.json'), JSON.stringify({ ...inp.motion, animations: { ...anims, [name]: { ...idleAnim, tracks: kept } } }));
+    const b = rigc(['build', '--rig', join(dir, 'rig.json'), '--motion', join(dir, 'motion.json'), '--out', join(dir, 'build'), ...packedBuildArgs(mode)]);
+    if (b.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (BREATH_VISIBLE's copy, the idle beside it with its breath tracks held at rest)`, b, buildGateLines(b.out)));
+    const slots = ps.map((p) => p.name).join(',');
+    const render = (animation: string, label: string): FrameSet => {
+      const r = rigc(['render', '--candidate', join(dir, 'build'), '--animation', animation, '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--slot', slots, '--out', join(dir, label)]);
+      if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation ${animation} --slot ${slots} (BREATH_VISIBLE's copy)`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+      return readFrameSet(join(dir, label));
+    };
+    return { with: render('idle', 'with'), without: render(name, 'without'), tracks: tracks.map((t) => `${t.bone} ${t.property}`) };
+  };
   // Issue #231: the footwear parts the scene file declares not planted; none without --requirements or the field.
   const notPlanted = reqFile === null ? [] : reqFile.not_planted;
   let breath: JudgementLine = skip(lacking);
   let tip: JudgementLine = skip(lacking);
   if (full !== null) {
     try {
-      breath = breathLine(full, isolated, problems, notPlanted);
+      breath = breathLine(full, isolated, breathPair, problems, notPlanted);
       if (idle !== null) tip = tipLine(full, join(idle.dir, GEOMETRY_FILE), idle.written, problems, reqFile === null ? NO_TIP_EXCEPTIONS : { path: reqFile.path, not_swinging: reqFile.not_swinging, rises: reqFile.rises, rests: reqFile.rests });
     } finally {
       rmSync(isoDir, { recursive: true, force: true });
@@ -3701,33 +3729,32 @@ function noneHeldText(declared: readonly string[]): string {
  * `SKIP` with its reason — so a half nobody read never passes by being silent.
  * With neither, the line is the SKIP it was. A run that measured both halves
  * writes the keys it always wrote.
+ *
+ * Issue #411: the torso half reads the breath alone ({@link torsoBreath}):
+ * `torso_heat_mean` is the heat the breath makes, the idle rendered with and
+ * without its breath tracks, on the same box and against the same floor.
+ * Until #411 it was the whole idle's heat over the box, so a keyed cloth swing
+ * or a physics response to the world inside the torso's box passed the bar
+ * for a torso that did not breathe.
  */
-function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], notPlanted: readonly string[] = []): JudgementLine {
+function breathLine(inp: FullInputs, isolated: Isolate, pair: BreathPairRender, problems: Problem[], notPlanted: readonly string[] = []): JudgementLine {
   const torso = partsTagged(inp.parts, TORSO_TAGS);
   const { all: allFeet, held: feet, declared } = plantedFeet(inp.parts, notPlanted);
   const noTorso = `no part comes from a See-through ${tagWords(TORSO_TAGS)} layer, so there is no torso to see breathe`;
   const noFeet = `no part comes from a See-through ${tagWords(FEET_TAGS)} layer, so there are no feet to hold still`;
   // Issue #323: a figure without one of the two halves still has the other read; with neither, the SKIP it always was.
   if (torso.length === 0 && feet.length === 0) return skip(`${noTorso}${declared.length === 0 ? '' : `; ${declared.map((n) => `"${n}"`).join(', ')} declared not planted`}`);
-  if (torso.length === 0) return oneHalf(inp, isolated, problems, 'feet', feet, noTorso, declared);
-  if (allFeet.length === 0) return oneHalf(inp, isolated, problems, 'torso', torso, noFeet, []);
+  if (torso.length === 0) return oneHalf(inp, isolated, pair, problems, 'feet', feet, noTorso, declared);
+  if (allFeet.length === 0) return oneHalf(inp, isolated, pair, problems, 'torso', torso, noFeet, []);
   const H = inp.parts.rig_size[1];
-  const ts = isolated('torso', torso);
+  const tr = torsoBreath(inp, torso, pair);
   const fs = feet.length === 0 ? null : isolated('feet', feet);
-  const tb = frameBox(torso, H, inp.stage, ts.viewport);
   const fb = fs === null ? null : frameBox(feet, H, inp.stage, fs.viewport);
-  if (tb === null || (fs !== null && fb === null)) return skip(`the ${tb === null ? 'torso' : 'feet'} box falls outside the idle frame`);
-  const th = regionHeat(heatField(ts.frames.map((f) => f.image)), ts.viewport.pixelWidth, tb);
+  if ('skip' in tr || (fs !== null && fb === null)) return skip(`the ${'skip' in tr ? 'torso' : 'feet'} box falls outside the idle frame`);
   const fh = fs === null || fb === null ? null : regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, fb);
-  const mean = round3(th.mean);
+  const mean = tr.mean;
   const ok = mean >= BREATH_TORSO_MEAN_FLOOR && (fh === null || fh.max <= BREATH_FEET_MAX_CEILING);
-  if (mean < BREATH_TORSO_MEAN_FLOOR) {
-    problems.push({
-      code: 'CHECK_BREATH_VISIBLE',
-      object: `torso ${quoteParts(torso)} rendered alone, frame box ${boxLabel(tb)}`,
-      detail: `heat mean ${mean}/255 over the idle; >= ${BREATH_TORSO_MEAN_FLOOR} is required — the chest's breath track moves too little, or the torso is not weighted to the bone it keys`,
-    });
-  }
+  if (mean < BREATH_TORSO_MEAN_FLOOR) problems.push(torsoProblem(torso, tr, ''));
   if (fh !== null && fb !== null && fh.max > BREATH_FEET_MAX_CEILING) {
     problems.push({
       code: 'CHECK_BREATH_VISIBLE',
@@ -3755,22 +3782,15 @@ function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], not
  * `halves_measured`, says `1 of 2` — after `declared_not_planted` when the scene
  * file declares some of the feet read (issue #231), which stays the first.
  */
-function oneHalf(inp: FullInputs, isolated: Isolate, problems: Problem[], half: 'torso' | 'feet', ps: readonly PartRecord[], reason: string, declared: readonly string[]): JudgementLine {
+function oneHalf(inp: FullInputs, isolated: Isolate, pair: BreathPairRender, problems: Problem[], half: 'torso' | 'feet', ps: readonly PartRecord[], reason: string, declared: readonly string[]): JudgementLine {
   const H = inp.parts.rig_size[1];
-  const fs = isolated(half, ps);
-  const box = frameBox(ps, H, inp.stage, fs.viewport);
-  if (box === null) return skip(`the ${half} box falls outside the idle frame, and ${reason}`);
-  const heat = regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, box);
   if (half === 'torso') {
-    const mean = round3(heat.mean);
+    // Issue #411: the torso half is the breath alone.
+    const tr = torsoBreath(inp, ps, pair);
+    if ('skip' in tr) return skip(`the ${half} box falls outside the idle frame, and ${reason}`);
+    const mean = tr.mean;
     const ok = mean >= BREATH_TORSO_MEAN_FLOOR;
-    if (!ok) {
-      problems.push({
-        code: 'CHECK_BREATH_VISIBLE',
-        object: `torso ${quoteParts(ps)} rendered alone, frame box ${boxLabel(box)}; the feet half not measured: ${reason}`,
-        detail: `heat mean ${mean}/255 over the idle; >= ${BREATH_TORSO_MEAN_FLOOR} is required — the chest's breath track moves too little, or the torso is not weighted to the bone it keys`,
-      });
-    }
+    if (!ok) problems.push(torsoProblem(ps, tr, `; the feet half not measured: ${reason}`));
     return {
       status: ok ? 'PASS' : 'FAIL',
       halves_measured: '1 of 2',
@@ -3782,6 +3802,10 @@ function oneHalf(inp: FullInputs, isolated: Isolate, problems: Problem[], half:
       feet_reason: reason,
     };
   }
+  const fs = isolated(half, ps);
+  const box = frameBox(ps, H, inp.stage, fs.viewport);
+  if (box === null) return skip(`the ${half} box falls outside the idle frame, and ${reason}`);
+  const heat = regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, box);
   const ok = heat.max <= BREATH_FEET_MAX_CEILING;
   if (!ok) {
     problems.push({
@@ -3803,6 +3827,130 @@ function oneHalf(inp: FullInputs, isolated: Isolate, problems: Problem[], half:
   };
 }
 
+/** The throwaway animation BREATH_VISIBLE adds beside the idle (issue #411): the idle with its breath tracks held at rest; a trailing `_` is added while the rig already has an animation of the name. */
+export const BREATH_ANIMATION = 'idle_without_breath';
+/** Where BREATH_VISIBLE's copy is built and rendered, under the stage's scratch; removed before the stage returns. */
+const BREATH_SCRATCH = 'breath';
+
+/** The idle track properties that make up the breath on a breath bone (issue #411): it moves and it swells; the drafted breath is `chest` `translatey` and `scalex` (src/propose.ts). */
+const BREATH_TRACK_PROPS: readonly string[] = ['translate', 'translatex', 'translatey', 'scale', 'scalex', 'scaley'];
+
+/**
+ * The breath's tracks (issue #411), in the idle's order: the breath bones are
+ * every bone an idle track translates ({@link BREATH_PROPS}, issue #262), and
+ * their breath tracks every idle track that translates or scales one of them
+ * ({@link BREATH_TRACK_PROPS}). A track that turns a breath bone, a group's
+ * track and every track on another bone are not the breath. Empty when no
+ * idle track translates a bone.
+ */
+export function breathTracks(motion: Record<string, unknown>): Array<{ bone: string; property: string }> {
+  const anims = isRecord(motion.animations) ? motion.animations : {};
+  const idle = isRecord(anims.idle) ? anims.idle : {};
+  const tracks = (Array.isArray(idle.tracks) ? idle.tracks : []).filter(isRecord).filter((t) => typeof t.bone === 'string' && typeof t.property === 'string');
+  const bones = new Set(tracks.filter((t) => BREATH_PROPS.includes(String(t.property))).map((t) => String(t.bone)));
+  return tracks.filter((t) => bones.has(String(t.bone)) && BREATH_TRACK_PROPS.includes(String(t.property))).map((t) => ({ bone: String(t.bone), property: String(t.property) }));
+}
+
+/**
+ * A breath track held at rest (issue #411): the setup pose's value — 0 for a translate, 1 for a scale, one per axis
+ * the track's first key gives — at its first and last key times, no curve. That is the track removed, as the bone
+ * stands without it, while the idle stays keyed to its end: a dropped track could leave the idle's last key before
+ * its duration, which rigc refuses. (Held at its first key instead, the bone would stand offset from frame 0 on and
+ * the physics under it would answer that start, which is not the idle without its breath.)
+ */
+function heldTrack(t: Record<string, unknown>): Record<string, unknown> {
+  const keys = (Array.isArray(t.keys) ? t.keys : []).filter(isRecord);
+  if (keys.length === 0) return t;
+  const first = keys[0];
+  const last = keys[keys.length - 1];
+  const rest = String(t.property).startsWith('scale') ? 1 : 0;
+  const v = (Array.isArray(first.v) ? first.v : [first.v]).map(() => rest);
+  return { ...t, keys: keys.length === 1 ? [{ t: first.t, v }] : [{ t: first.t, v }, { t: last.t, v }] };
+}
+
+function isBreathTrack(t: Record<string, unknown>, tracks: ReadonlyArray<{ bone: string; property: string }>): boolean {
+  return tracks.some((b) => b.bone === t.bone && b.property === t.property);
+}
+
+/** The torso rendered alone twice from one build (issue #411): the idle (`with`) and the idle less its breath tracks (`without`), and those tracks as `bone property`. */
+export interface BreathPair {
+  with: FrameSet;
+  without: FrameSet;
+  tracks: string[];
+}
+
+/** Renders {@link BreathPair} for the torso parts; null when the idle has no breath track. */
+export type BreathPairRender = (ps: readonly PartRecord[]) => BreathPair | null;
+
+/**
+ * Why the two renders of a {@link BreathPair} cannot be compared pixel for
+ * pixel, or null when they can: one grid (the viewport), one background, the
+ * same number of frames, each of one size. Both come from one build, so a
+ * difference is rigc's, refused by name (`CHECK_BREATH_VISIBLE`) rather than
+ * read.
+ */
+export function breathPairProblem(pair: BreathPair): Problem | null {
+  const a = pair.with;
+  const b = pair.without;
+  const size = (s: FrameSet): string => [...new Set(s.frames.map((f) => `${f.image.width}x${f.image.height}`))].join(',');
+  if (sameViewport(a.viewport, b.viewport) && a.background.join(',') === b.background.join(',') && a.frames.length === b.frames.length && size(a) === size(b) && !size(a).includes(',')) return null;
+  return {
+    code: 'CHECK_BREATH_VISIBLE',
+    object: `the torso's two idle renders (with and without the breath tracks ${pair.tracks.join(', ')})`,
+    detail: `are ${a.frames.length} frame(s) of ${size(a)} on ${JSON.stringify(a.viewport)} over ${JSON.stringify(a.background)} and ${b.frames.length} frame(s) of ${size(b)} on ${JSON.stringify(b.viewport)} over ${JSON.stringify(b.background)}; the breath is read pixel for pixel between them, which needs one grid, one background and one frame count`,
+  };
+}
+
+/** The torso half's reading (issue #411): the breath's heat mean over the box, the whole idle's beside it, and the breath tracks; `none` when the idle has no breath track. */
+type TorsoBreath = { box: PixelBox; mean: number; whole: number; tracks: string[] } | { none: string; mean: number } | { skip: true };
+
+/**
+ * `BREATH_VISIBLE`'s torso half (issue #411): the breath alone. The breath
+ * bones are every bone an idle track translates, and the breath tracks every
+ * idle track that translates or scales one of them ({@link breathTracks}).
+ * The torso is rendered alone, idle at its rate and size, from one throwaway
+ * build carrying every animation of the rig and, beside them, the idle with
+ * its breath tracks held at rest ({@link heldTrack}: the bone as it stands
+ * without them, the idle still keyed to its end) — so both renders share a
+ * grid. Per pixel, the largest
+ * |(with_t - with_0) - (without_t - without_0)| over the frames and the RGB
+ * channels ({@link breathHeat}), meaned over the torso's frame box. Motion that
+ * is not the breath's — a keyed cloth swing, physics answering the world, a
+ * head turn — is in both renders and cancels; physics the breath sets moving
+ * is counted. The whole idle's heat over the same box, the reading until #411,
+ * is carried for the refusal's sentence only.
+ *
+ * With no breath track the figure is 0, by the definition (the idle with and
+ * without its breath is one idle), and the bar fails naming why: a torso with
+ * no breath is what the bar exists to find, so it is not a SKIP; nothing is
+ * rendered.
+ */
+function torsoBreath(inp: FullInputs, ps: readonly PartRecord[], pair: BreathPairRender): TorsoBreath {
+  const got = pair(ps);
+  if (got === null) return { none: 'no idle track translates a bone, so the rig has no breath to read (the breath bones are every bone an idle track translates); whatever else the idle moves is not counted', mean: 0 };
+  const grid = breathPairProblem(got);
+  if (grid !== null) refuseIfAny([grid]);
+  const box = frameBox(ps, inp.parts.rig_size[1], inp.stage, got.with.viewport);
+  if (box === null) return { skip: true };
+  const width = got.with.viewport.pixelWidth;
+  const withFrames = got.with.frames.map((f) => f.image);
+  const mean = round3(regionHeat(breathHeat(withFrames, got.without.frames.map((f) => f.image)), width, box).mean);
+  const whole = round3(regionHeat(heatField(withFrames), width, box).mean);
+  return { box, mean, whole, tracks: got.tracks };
+}
+
+/** The torso half's refusal (issue #411): the breath's figure, the tracks it was read from, and the whole idle's beside it. */
+function torsoProblem(ps: readonly PartRecord[], tr: Exclude<TorsoBreath, { skip: true }>, tail: string): Problem {
+  if ('none' in tr) {
+    return { code: 'CHECK_BREATH_VISIBLE', object: `torso ${quoteParts(ps)}${tail}`, detail: `breath heat mean 0/255: ${tr.none}; >= ${BREATH_TORSO_MEAN_FLOOR} is required — key the chest's breath (a translate track on the bone the torso is weighted to)` };
+  }
+  return {
+    code: 'CHECK_BREATH_VISIBLE',
+    object: `torso ${quoteParts(ps)} rendered alone, frame box ${boxLabel(tr.box)}${tail}`,
+    detail: `breath heat mean ${tr.mean}/255 over the idle — the idle with and without its breath tracks (${tr.tracks.join(', ')}), on one grid; the whole idle reads ${tr.whole} over the box, and what is not the breath's is not counted; >= ${BREATH_TORSO_MEAN_FLOOR} is required — the chest's breath track moves too little, or the torso is not weighted to the bone it keys`,
+  };
+}
+
 /** The scene file's exceptions to `TIP_OVER_ROOT` (issues #231, #245), and the file they were read from, which a refusal names. */
 export interface TipExceptions {
   path: string;

package/src/cloth.ts

@@ -62,7 +62,9 @@
  * Pure: no clock, no randomness; every value is a function of its inputs.
  */
 import type { ConfigConstraint, Point } from './config.ts';
+import type { Mask } from './raster/types.ts';
 import { pyRound } from './round.ts';
+import { segmentDistance } from './weights.ts';
 
 /** The tags a `cloth` recipe may name: the parts the proposer drafts chains on that hang. */
 export const CLOTH_TARGETS = ['bottomwear', 'back hair', 'front hair'] as const;
@@ -388,3 +390,67 @@ export function clothNote(part: string, tag: ClothTarget, trees: readonly TreeCh
     (defaults.length === 0 ? '' : `; the recipe's own defaults, measured on its synthetic fixture (AUTHORING §3): ${defaults.join(', ')}`)
   );
 }
+
+/**
+ * Issue #391: a part wrapped round a tail the recipe drafted rides that tail's links. One span of the tail: a segment
+ * of the back hair's mesh as the recipe drafts it — the head's fixed segment, or one tree link from its origin to the
+ * next link (the last to the chain's tip), named by the link's bone.
+ */
+export interface TailSpan {
+  bone: string;
+  a: Point;
+  b: Point;
+  /** Whether the span is a tree link (false: the head's fixed segment). */
+  link: boolean;
+}
+
+/** A tail the recipe drafted: the back hair part, its opaque mask on the rig canvas, and its mesh's spans in segment order. */
+export interface Tail {
+  part: string;
+  mask: Mask;
+  spans: TailSpan[];
+}
+
+/** Where a part's opaque pixels lie against a drafted tail. */
+export interface TailOverlap {
+  /** Per span, in the tail's order: the part's pixels over the tail's art whose nearest span it is. */
+  counts: number[];
+  /** The part's pixels over the tail's art (the sum of `counts`). */
+  over: number;
+  /** The part's opaque pixels in all. */
+  total: number;
+}
+
+/**
+ * Which span of the tail each of the part's pixels over the tail's art belongs to: every pixel where both masks are
+ * set is given to the span nearest it — the distance the weights read (`segmentDistance`, `src/weights.ts`), so a
+ * span here is the art the tail's own weights give mostly to that bone — the first in the tail's order on a tie. No
+ * threshold: a span the part touches by one pixel is one the part overlaps, and the counts are said in the note.
+ * Pure; the part's mask and the tail's are on the same canvas.
+ */
+export function tailOverlap(tail: Tail, part: Mask, box: { x: number; y: number; w: number; h: number }): TailOverlap {
+  const counts = tail.spans.map(() => 0);
+  let over = 0;
+  let total = 0;
+  const W = part.width;
+  for (let y = box.y; y < box.y + box.h; y++) {
+    for (let x = box.x; x < box.x + box.w; x++) {
+      const i = y * W + x;
+      if (part.data[i] === 0) continue;
+      total++;
+      if (tail.mask.data[i] === 0) continue;
+      over++;
+      let best = 0;
+      let bd = Infinity;
+      tail.spans.forEach((s, k) => {
+        const d = segmentDistance([x, y], s.a, s.b);
+        if (d < bd) {
+          bd = d;
+          best = k;
+        }
+      });
+      counts[best]++;
+    }
+  }
+  return { counts, over, total };
+}

package/src/instruments.ts

@@ -137,6 +137,38 @@ export function heatField(frames: readonly Raster[]): Uint8Array {
   return d;
 }
 
+/**
+ * The breath alone (issue #411): each pixel's largest per-channel RGB change
+ * that the breath makes, read off the idle rendered twice on one grid — with
+ * its breath tracks (`withBreath`) and without them (`withoutBreath`). At
+ * frame t the breath's own change at a pixel is (with_t - with_0) -
+ * (without_t - without_0): motion that is the same in both renders (a keyed
+ * cloth swing, a physics response to the world, a head turn) cancels, and so
+ * does a constant offset the breath holds from frame 0 on, while physics that
+ * the breath sets moving stays. The field is that change's largest magnitude
+ * over the frames and the three channels, capped at 255 — {@link heatField}'s
+ * reading when the render without the breath does not move. Both lists hold
+ * the same number of frames of one size; the caller holds the grid.
+ */
+export function breathHeat(withBreath: readonly Raster[], withoutBreath: readonly Raster[]): Uint8Array {
+  const w0 = withBreath[0].data;
+  const o0 = withoutBreath[0].data;
+  const n = withBreath[0].width * withBreath[0].height;
+  const d = new Uint8Array(n);
+  withBreath.forEach((f, i) => {
+    const w = f.data;
+    const o = withoutBreath[i].data;
+    for (let p = 0; p < n; p++) {
+      for (let c = 0; c < 3; c++) {
+        const k = p * 4 + c;
+        const v = Math.min(255, Math.abs(w[k] - w0[k] - (o[k] - o0[k])));
+        if (v > d[p]) d[p] = v;
+      }
+    }
+  });
+  return d;
+}
+
 export interface RegionHeat {
   /** Pixels measured. */
   px: number;

package/src/propose.ts

@@ -43,7 +43,12 @@
  *   layer with hanging strands ({@link Strand}) gets one pendulum chain per
  *   strand instead of the single pendant chain, and one note naming every
  *   strand and what became of it — a strand left without a chain is never
- *   silent (issue #24).
+ *   silent (issue #24). Under the `back hair` cloth recipe (issue #391) a
+ *   layer of either tag lying on a drafted tail rides the links it overlaps
+ *   instead: its pixels over the tail's art are each given to the nearest span
+ *   of the back hair's mesh (`tailOverlap`, `src/cloth.ts`), and when one is a
+ *   link the part's mesh takes those spans as its segments and no rule above
+ *   runs for it; a note names each span with its pixel count.
  * - anything no rule claims rides its nearest trunk bone as a region —
  *   including every part from an author-made layer (`<run>:author:<label>`,
  *   issue #256), which is no See-through tag and so has no role: no rule
@@ -139,7 +144,7 @@ import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
 import { TURN_BONE, TURN_CARRIER_TAG, TURN_PLACES, TURN_RIDER_OFFSET, TURN_RIDER_TAGS, turnFractions, turnNearest, turnPivot, turnRiderDepth, type TurnSpec } from './turn.ts';
 import { edgeLength } from './length.ts';
 import { chainSqueezes, type SqueezeFinding } from './squeeze.ts';
-import { RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, swingName, treeConstraints, type TreeChain, type TreeInput } from './cloth.ts';
+import { RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, swingName, type Tail, tailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput } from './cloth.ts';
 import { TEXTURE_STRETCH_CEILING } from './check.ts';
 
 // ---------------------------------------------------------------------------
@@ -1364,6 +1369,8 @@ export function proposeWithBasis(
   const clothConstraints: ConfigConstraint[] = [];
   const clothUsed = new Set<ClothTarget>();
   const recipeOf = (tag: ClothTarget): ClothRecipe | null => cloth?.[tag] ?? null;
+  // Issue #391: the tails the back hair recipe drafts, each with its mesh's spans, which an accessory wrapped round one rides.
+  const tails: Tail[] = [];
   const T = (p: PartRecord, tag: ClothTarget, r: ClothRecipe, input: TreeInput): TreeChain[] => {
     const trees = draftTrees(input, r);
     const constants = [konst('cloth_chains', r.chains), konst('cloth_links', r.links), konst('length_ratio', roundTo(r.length_ratio ?? RECIPE_LENGTH_RATIO, 6))];
@@ -1548,6 +1555,13 @@ export function proposeWithBasis(
       }
       notes.push(clothNote(p.name, 'back hair', all, rcp, n, ' per side of the eye axis, from head, rooted on the eye line and tipped 4 px above its bottom'));
       meshes[p.name] = { grid: g, r, segments: segs };
+      // Issue #391: the spans are this mesh's segments, the head's fixed one and every tree link, in segment order.
+      const spans: TailSpan[] = [{ bone: 'head', a: rnd(head), b: rnd([axis, top + 13]), link: false }];
+      for (const t of all) {
+        const line = [...t.points, t.tip];
+        t.points.forEach((q, i) => spans.push({ bone: `${t.chain}${i}`, a: q, b: line[i + 1], link: true }));
+      }
+      tails.push({ part: p.name, mask, spans });
     } else {
       const mask = P.alpha(p);
       const segs: Segment[] = [['head', rnd(head), rnd([axis, top + 13])]];
@@ -1726,7 +1740,39 @@ export function proposeWithBasis(
     // gets the bone and chain, the rest ride the head rigidly. A stable sort,
     // as Python's `sorted` is.
     const cands = [...P.byTag(tag)].sort((a, b) => b.opaque_px - a.opaque_px);
+    // Issue #391: a layer of the tag lying on a tail the back hair recipe drafted rides the links it overlaps — the
+    // spans of the tail its pixels over the tail's art fall nearest — and not head: its mesh names those bones and no
+    // others, so every vertex weights by the rule the tail's own art does. The links are read off the overlap, never
+    // off the part's name. A layer over no link keeps its rule below. Only with the recipe: without it no tail moves
+    // by the world, and nothing here runs.
+    const rides = (q: PartRecord): boolean => {
+      const segments: Segment[] = [];
+      const links: string[] = [];
+      const said: string[] = [];
+      for (const tail of tails) {
+        const o = tailOverlap(tail, P.alpha(q), q);
+        if (!tail.spans.some((sp, k) => sp.link && o.counts[k] > 0)) continue;
+        const on: string[] = [];
+        tail.spans.forEach((sp, k) => {
+          if (o.counts[k] === 0) return;
+          on.push(`${sp.link ? sp.bone : `${sp.bone}'s fixed segment`} ${o.counts[k]}`);
+          // A link is named, so its segment is the link as the bones declare it; the head's span is written out, as the tail's mesh writes it.
+          segments.push(sp.link ? sp.bone : [sp.bone, sp.a, sp.b]);
+          if (sp.link) links.push(sp.bone);
+        });
+        said.push(`${o.over} of its ${o.total} px lie over ${tail.part}'s art, nearest ${tail.part}'s spans ${on.join(', ')} px`);
+      }
+      if (links.length === 0) return false;
+      const [g, r] = gridR(q);
+      delete regions[q.name];
+      meshes[q.name] = { grid: g, r, segments };
+      notes.push(
+        `${q.name} (${q.from}): wraps a tail config.cloth."back hair" drafts — ${said.join('; ')} — so its mesh's segments are those spans and it rides the links ${links.join(', ')} with the tail, not head; no ${tag} bone, pendant or strand chain is drafted for it (issue #391)`,
+      );
+      return true;
+    };
     for (const q of cands.slice(1)) {
+      if (rides(q)) continue;
       regions[q.name] = 'head';
       notes.push(`${q.name} (${q.from}): second ${tag} layer, rigid on head`);
       // A region cannot swing, so strands found on it are only said.
@@ -1735,6 +1781,7 @@ export function proposeWithBasis(
       if (strands.length > 0) notes.push(strandNote(q, strands, [], strands, 'it rides the head as a region'));
     }
     for (const p of cands.slice(0, 1)) {
+      if (rides(p)) continue;
       const [g, r] = gridR(p);
       const fullMask = dilate(P.alpha(p), 7);
       const onArt = (pts: ReadonlyArray<readonly [number, number]>): boolean => pts.every((q) => isOn(fullMask, q[0], q[1]));