@rig-c/parts 2.49.1 → 2.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -333,6 +333,7 @@ Command details and config saving are in the [command reference](docs/AUTHORING.
333
333
  | `edited-part` | [Record an edited part receipt](docs/AUTHORING.md#edited-rig-space-parts-assembleedited_parts-issue-1278) |
334
334
  | `external-receipt` | [Record or verify an external mask](docs/AUTHORING.md#external-mask-receipt) |
335
335
  | `propose` | [Draft or inspect a character config](docs/AUTHORING.md#command-reference) |
336
+ | `bust-landmarks` | [Write the chest landmarks file from a review act](docs/AUTHORING.md#drafting-the-chest-carrier) |
336
337
  | `compare` | [Compare two skeletons by name](docs/AUTHORING.md#command-reference) |
337
338
  | `rig` | [Author gated rig and motion specs](docs/AUTHORING.md#command-reference) |
338
339
  | `check` | [Build, render and measure a rig](docs/AUTHORING.md#command-reference) |
package/cli.ts CHANGED
@@ -5,6 +5,7 @@ import { DIFF_DRAFTS_SPEC, diffDraftsCommand } from './src/diffdrafts.ts';
5
5
  import { applyTakenLayers } from './src/takelayers.ts';
6
6
  import { applyDepth, bindDepthMap, prepareDepth } from './src/depthworkflow.ts';
7
7
  import { externalReceipt } from './src/externalreceipt.ts';
8
+ import { BUST_LANDMARKS_ACT_SCHEMA, BUST_LANDMARKS_PROVENANCE_SPEC, BUST_LANDMARKS_PROVENANCE_SUFFIX, BUST_POINT_SHAPE_FIELDS, bustShapeClause, type BustSidecar, effectiveBustShape, planBustLandmarks, readBustSidecar, stageBustLandmarks, stageReplacements, type StagedBustLandmarks } from './src/bustlandmarks.ts';
8
9
  import { writeEditedPart } from './tools/edited-part-cli.ts';
9
10
  /**
10
11
  * rig-parts — one painting and its See-through layers in, Spine-ready parts
@@ -31,8 +32,9 @@ import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK
31
32
  import { ComfyClient, resolveHost, runBackground, runMatte, runPainting, runSeeThrough } from './src/comfy/index.ts';
32
33
  import { coreCfg, DEFAULT_GROW_PX, runForeground } from './src/plate.ts';
33
34
  import { type CharacterConfig, loadClothConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
34
- import { configWriteLines, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
35
- import { failLine, guidePointer, PartsError } from './src/errors.ts';
35
+ import { type ConfigWritePatch, onlyMissingAttachments } from './src/configwrite.ts';
36
+ import { configWriteLines, type ConfigWriteTarget, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
37
+ import { failLine, guidePointer, PartsError, type Problem } from './src/errors.ts';
36
38
  import { GUIDE_DOC, type GuideAnswer, guideRule, guideSection } from './src/guide.ts';
37
39
  import { proposeHeadBox, type Box } from './src/headbox.ts';
38
40
  import { headCropPreflight, headCropPreflightLines } from './src/headcroppreflight.ts';
@@ -41,7 +43,7 @@ import { idleKeysOf, isIdleKeys } from './src/rig.ts';
41
43
  import { bodyCoreBox, bodyOpaqueBox, CORE_ALPHA, depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerCoreBox, layerFigures, layerOpaqueBox, type LayerSet, layerSetDiff, type OpaqueBox, OPAQUE_ALPHA_ABOVE, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
42
44
  import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJoints, toRigJoints } from './src/keypoints.ts';
43
45
  import { checkPartsStage } from './src/partscheck.ts';
44
- import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, type BustDraft, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, PROPOSAL_CONFIG_SECTIONS, proposalAsConfig, proposeWithBasis, readBustLandmarks, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
46
+ import { basisLines, branchSqueezeLine, bustCleavage, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, type BustDraft, type Proposal, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, PROPOSAL_CONFIG_SECTIONS, proposalAsConfig, proposeWithBasis, readBustLandmarks, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
45
47
  import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, legChainChoice, serializeBasis } from './src/diagnostics.ts';
46
48
  import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, relativeConfigPaths, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
47
49
  import { meshStatsStage } from './src/meshstats.ts';
@@ -211,6 +213,10 @@ usage:
211
213
  Draft the chest-holding topwear as contour. Landmark JSON declares apex_r,
212
214
  apex_l and optional cleavage in rig pixels. Without cleavage, intersect
213
215
  their segment with the neck-to-hip midline. --no-bust needs a stated reason.
216
+ A record <landmarks.json>${BUST_LANDMARKS_PROVENANCE_SUFFIX} beside the file (bust-landmarks
217
+ writes one) must name the drafted chest carrier and the file's own
218
+ sha256; a pending shape in it needs --write-config, which writes it with
219
+ the points and marks the record applied.
214
220
  rig-parts propose … [--keypoints <keypoints.json> [--person <id>] [--wrist-snap <px>]]
215
221
  Read the figure's pose from one explicit file (spec "${KEYPOINTS_SPEC}"):
216
222
  its space (painting-px, origin top-left, y down — another is refused),
@@ -261,6 +267,10 @@ usage:
261
267
  rigid sibling unit under the body carrier. Reassembled art is written to
262
268
  <out>/rig; depth comes from the existing scalar input, named in note:.
263
269
  Missing depth, landmarks or clean source is refused, never invented.
270
+ With --bust-landmarks or --no-bust instead of --full and --head, write
271
+ only the chest carrier's contour.bust and bones boob_r/boob_l, every
272
+ other entry as read; a cleavage the file omits is derived from the
273
+ config's own neck and hip bones, and the output says which source.
264
274
 
265
275
  rig-parts propose … [--grid-rule figure|part]
266
276
  How each drafted lattice's spacing (meshes.<part>.grid) is chosen.
@@ -374,6 +384,24 @@ usage:
374
384
  --no-back-hair leaves "back hair" out of the box. --write-config updates
375
385
  only seethrough.head_box in an existing config through the layers loader.
376
386
 
387
+ rig-parts bust-landmarks --from-act <act.json> --parts <dir> --config <config.json> --out <landmarks.json> [--write-config]
388
+ Write the file propose --bust-landmarks reads (apex_r, apex_l and
389
+ optional cleavage, rig px) from the one chest row of a Review
390
+ ${BUST_LANDMARKS_ACT_SCHEMA} act, and <out>${BUST_LANDMARKS_PROVENANCE_SUFFIX} beside it (spec
391
+ "${BUST_LANDMARKS_PROVENANCE_SPEC}": the act's schema, id and
392
+ file sha256, the row's sha256, verified against the row's edit, the
393
+ slot, the source hash and frame). The row's slot must be a part of
394
+ parts.json whose config mesh is a contour, its frame parts.json's
395
+ rig_size, and its alpha, clearance, spacing, bone_r and bone_l those of
396
+ the config's contour.bust. --write-config instead takes those five into
397
+ the config's existing contour.bust, a field the act omits removed,
398
+ through the config loader; the config is untouched when none differs.
399
+ With no contour.bust yet, fields that differ from the defaults are
400
+ recorded as a pending shape in the record, and propose --write-config
401
+ --bust-landmarks writes them with the points and marks them applied.
402
+ Writes nothing on a refusal; the outputs are renamed into place only
403
+ once both are staged.
404
+
377
405
  rig-parts head-crop-preflight --full <run> --canvas <W>x<H> --head-box '[left,top,right,bottom]'
378
406
  Report full-run drawn pixels beyond the crop: JSON stdout, advice stderr; no head run needed.
379
407
 
@@ -1214,6 +1242,7 @@ const TAKES = {
1214
1242
  'edited-part': { valued: ['--config', '--part', '--file', '--from', '--editor', '--producer', '--parts', '--rig-config'], switches: ['--help'] },
1215
1243
  'external-receipt': { valued: ['--kind', '--file', '--painting', '--producer', '--out', '--verify'], switches: ['--help'] },
1216
1244
  'check-parts': { valued: ['--parts', '--out'], switches: ['--json', '--help'] },
1245
+ 'bust-landmarks': { valued: ['--from-act', '--parts', '--config', '--out'], switches: ['--write-config', '--help'] },
1217
1246
  'diff-components': { valued: ['--stack', '--painting', '--parts', '--figure', '--floor', '--threshold', '--out', '--verify'], switches: ['--owners', '--help'] },
1218
1247
  'diff-drafts': { valued: ['--left', '--right', '--out'], switches: ['--help'] },
1219
1248
  'depth-bind': { valued: ['--map', '--input', '--part'], switches: ['--help'] },
@@ -1712,6 +1741,8 @@ function cmdPropose(args: string[]): number {
1712
1741
  if (!flags.has('--write-config')) return usage(`--only-missing belongs to ${mode}; give --write-config <config.json>, the existing config the entries are added to`);
1713
1742
  }
1714
1743
  let staged: StagedConfigWrite | null = null;
1744
+ // Issue #1382: the landmarks file's record, marked applied beside the config write that applies its pending shape.
1745
+ let sidecarStaged: StagedBustLandmarks | null = null;
1715
1746
  try {
1716
1747
  if (headBox) {
1717
1748
  const stray = [...flags.keys()].filter((f) => f !== '--full' && f !== '--canvas' && f !== '--write-config');
@@ -1800,14 +1831,30 @@ function cmdPropose(args: string[]): number {
1800
1831
  if (!existsSync(source)) {
1801
1832
  throw new PartsError([{ code: 'PROPOSE_SOURCE_PRESENT', object: source, detail: 'no such file; the painting is drawn under the overlay' }]);
1802
1833
  }
1834
+ // Issue #1436: on a sampled body-turn neck config the chest flags without the runs write the chest alone.
1835
+ let chestOnly = false;
1803
1836
  if (target !== null && typeof target.raw === 'object' && target.raw !== null && 'turn' in target.raw) {
1804
1837
  const turn = target.raw.turn;
1805
1838
  if (typeof turn === 'object' && turn !== null && 'body' in turn && (loadEarlyConfig(target.path, 'assemble').assemble.plan.some(([, , tag]) => tag === 'neck'))) {
1806
- const unsupported = [...flags.keys()].filter(f => !['--parts', '--source', '--out', '--full', '--head', '--write-config'].includes(f));
1807
- if (unsupported.length > 0) throw new PartsError([{ code: 'PROPOSE_NECK_MODE', object: unsupported.join(', '), detail: 'cannot be combined with the authored sampled-turn neck draft; use --parts, --source, --out, --full, --head and --write-config only; run comparison or landmark drafting separately' }]);
1839
+ const chestFlags = ['--bust-landmarks', '--no-bust'].filter((f) => flags.has(f));
1840
+ const runs = ['--full', '--head'].filter((f) => flags.has(f));
1841
+ const chestCommand = `rig-parts propose --parts <dir> --source <painting.png> --out <dir> --write-config ${writeArg} ${chestFlags.includes('--no-bust') ? '--no-bust "<reason>"' : '--bust-landmarks <landmarks.json>'}`;
1842
+ if (chestFlags.length > 0 && runs.length > 0) {
1843
+ throw new PartsError([{ code: 'PROPOSE_NECK_MODE', object: [...chestFlags, ...runs].join(', '), detail: `the neck draft (--full, --head) and the chest-only write (${chestFlags.join(', ')}) are separate runs on a sampled body-turn neck config; write the chest with ${chestCommand}, without --full and --head, and draft the neck in its own run` }]);
1844
+ }
1845
+ chestOnly = chestFlags.length > 0;
1846
+ const allowed = chestOnly ? ['--parts', '--source', '--out', '--write-config', '--bust-landmarks', '--no-bust'] : ['--parts', '--source', '--out', '--full', '--head', '--write-config'];
1847
+ const unsupported = [...flags.keys()].filter(f => !allowed.includes(f));
1848
+ if (unsupported.length > 0) {
1849
+ throw new PartsError([{ code: 'PROPOSE_NECK_MODE', object: unsupported.join(', '), detail: chestOnly
1850
+ ? `cannot be combined with the chest-only write on a sampled body-turn neck config; use --parts, --source, --out, --write-config and ${chestFlags.join(', ')} only (${chestCommand}); run comparison or other drafting separately`
1851
+ : 'cannot be combined with the authored sampled-turn neck draft; use --parts, --source, --out, --full, --head and --write-config only; run comparison or landmark drafting separately' }]);
1852
+ }
1808
1853
  if (onlyMissing) throw new PartsError([{ code: 'PROPOSE_NECK_MODE', object: '--only-missing', detail: 'cannot replace an attached neck; omit --only-missing for the explicit sampled body-turn neck draft' }]);
1809
- proposeNeck(target, { source, parts: partsDir, out, full: flags.get('--full'), head: flags.get('--head') });
1810
- return EXIT_OK;
1854
+ if (!chestOnly) {
1855
+ proposeNeck(target, { source, parts: partsDir, out, full: flags.get('--full'), head: flags.get('--head') });
1856
+ return EXIT_OK;
1857
+ }
1811
1858
  }
1812
1859
  }
1813
1860
  if (flags.has('--from-config') && (flags.has('--bust-landmarks') || flags.has('--no-bust'))) return usage('--bust-landmarks and --no-bust draft a torso. --from-config reads authored meshes');
@@ -1839,9 +1886,12 @@ function cmdPropose(args: string[]): number {
1839
1886
  if (noBust !== undefined && (noBust.trim().length === 0 || bustPath !== undefined)) return usage('--no-bust requires a non-blank reason and cannot accompany --bust-landmarks');
1840
1887
  const bust: BustDraft = {};
1841
1888
  if (noBust !== undefined) bust.noBust = noBust;
1889
+ let sidecar: BustSidecar | null = null;
1842
1890
  if (bustPath !== undefined) {
1891
+ let bytes: Buffer;
1843
1892
  try {
1844
- bust.landmarks = readBustLandmarks(JSON.parse(readFileSync(bustPath, 'utf8')) as unknown);
1893
+ bytes = readFileSync(bustPath);
1894
+ bust.landmarks = readBustLandmarks(JSON.parse(bytes.toString('utf8')) as unknown);
1845
1895
  } catch (error) {
1846
1896
  if (error instanceof PartsError) throw error;
1847
1897
  throw new PartsError([{
@@ -1849,6 +1899,30 @@ function cmdPropose(args: string[]): number {
1849
1899
  detail: `cannot read the declared JSON file (${error instanceof Error ? error.message : String(error)}). Give an object with apex_r, apex_l and optional cleavage in rig pixels`,
1850
1900
  }]);
1851
1901
  }
1902
+ // Issue #1382: no record beside the file is the hand-written fallback, read as before.
1903
+ sidecar = readBustSidecar(bustPath, bytes);
1904
+ if (sidecar?.pending != null) {
1905
+ const what = `${sidecar.path} holds a pending shape (${pendingFields(sidecar.pending.fields)}) from act ${JSON.stringify(sidecar.provenance.act.act_id)}`;
1906
+ if (writeArg === undefined) throw new PartsError([{ code: 'PROPOSE_BUST_PENDING', object: '--bust-landmarks', detail: `${what}, which only a config write keeps; give --write-config <config.json> so propose writes it into contour.bust with the three points, or it is lost — nothing was written` }]);
1907
+ if (target === null || onlyMissing) throw new PartsError([{ code: 'PROPOSE_BUST_PENDING', object: onlyMissing ? '--only-missing' : '--cloth', detail: `${what}; propose writes it only through an ordinary --write-config update of an existing config, not with ${onlyMissing ? '--only-missing' : '--cloth'} — nothing was written` }]);
1908
+ separateConfigWriteTarget(target, [sidecar.path]);
1909
+ }
1910
+ }
1911
+ // Issue #1436: the config is the record, so a cleavage the file leaves out is derived from the config's own midline.
1912
+ let cleavageSource: string | null = null;
1913
+ if (chestOnly && bust.landmarks !== undefined) {
1914
+ if (bust.landmarks.cleavage === undefined) {
1915
+ const declared = loadConfig(target!.path).bones;
1916
+ const at = (name: string): [number, number] => {
1917
+ const bone = declared.find((b) => 'name' in b && b.name === name);
1918
+ if (bone === undefined || !('at' in bone)) throw new PartsError([{ code: 'PROPOSE_BUST_INPUT', object: 'landmarks.cleavage', detail: `is absent and config.bones declares no "${name}" bone with an origin; the config's neck-to-hip midline is required to derive it, or declare cleavage in the landmarks file` }]);
1919
+ return [bone.at[0], bone.at[1]];
1920
+ };
1921
+ const neckAt = at('neck'), hipAt = at('hip');
1922
+ bust.landmarks = { ...bust.landmarks, cleavage: bustCleavage(bust.landmarks.apex_r, bust.landmarks.apex_l, neckAt, hipAt) };
1923
+ cleavageSource = `derived at the apex segment crossing of the config's neck [${neckAt.join(', ')}] -> hip [${hipAt.join(', ')}] midline`;
1924
+ bust.cleavageFrom = cleavageSource;
1925
+ } else cleavageSource = 'from the landmarks file';
1852
1926
  }
1853
1927
  const { proposal: drafted, basis, draftLint } = proposeWithBasis(P, joints, wristSnap, gridRule, cloth, true, bust);
1854
1928
  const fullRun = flags.get('--full');
@@ -1858,7 +1932,15 @@ function cmdPropose(args: string[]): number {
1858
1932
  ? drafted
1859
1933
  : withTurn(drafted, draftTurn(P, { ...(fullRun === undefined ? {} : { full: readLayers(fullRun) }), ...(headRun === undefined ? {} : { head: readLayers(headRun) }) }, drafted));
1860
1934
  // Emit only after green: a proposal the config loader would refuse is not written, nor a basis record that does not hold to it.
1861
- checkProposal(P, prop);
1935
+ // Issue #1441: the chest carrier's points are checked with the shape the config write will hold.
1936
+ checkProposalWithBustShape(P, prop, target, sidecar, onlyMissing);
1937
+ if (sidecar !== null) {
1938
+ // The record's part must be the chest carrier this draft makes: points placed on another part are not these.
1939
+ const carriers = Object.entries(prop.meshes).filter(([, mesh]) => 'contour' in mesh && mesh.contour.bust !== undefined).map(([part]) => part);
1940
+ if (!carriers.includes(sidecar.provenance.slot)) {
1941
+ throw new PartsError([{ code: 'PROPOSE_BUST_SIDECAR_PART', object: `${sidecar.path} slot`, detail: `is "${sidecar.provenance.slot}"; the chest carrier this draft makes (${carriers.length === 0 ? 'none' : carriers.map((c) => `"${c}"`).join(', ')}) is required: the record's points were placed on another part` }]);
1942
+ }
1943
+ }
1862
1944
  // The same parts drafted without the recipe: what --write-config measures its edits against, and what issue #572's chain reading compares with.
1863
1945
  const plain = cloth === null ? null : proposeWithBasis(P, joints, wristSnap, gridRule, null, true, bust).proposal;
1864
1946
  // Issue #537: the sections the recipe moves, measured against the same parts drafted without it, spliced before anything is written.
@@ -1894,16 +1976,38 @@ function cmdPropose(args: string[]): number {
1894
1976
  })();
1895
1977
  const bfile = basisFile(P, prop, basis, cfg === null || cmpPath === undefined ? null : { where: cmpPath, config: cfg });
1896
1978
  const img = drawLandmarks(P, painting, prop.bones, 'PROPOSAL - CORRECT ME');
1897
- if (target !== null) staged = stageConfigWrite(target, onlyMissing ? { kind: 'proposal-missing', proposal: prop, parts: P.recs } : { kind: 'proposal', proposal: prop, sections: PROPOSAL_CONFIG_SECTIONS });
1979
+ const pending = sidecar?.pending ?? null;
1980
+ let chest: { patch: Extract<ConfigWritePatch, { kind: 'bust' }>; line: string } | null = null;
1981
+ if (target !== null && chestOnly) {
1982
+ chest = chestOnlyPatch(target, prop, bust, cleavageSource);
1983
+ staged = stageConfigWrite(target, { ...chest.patch, ...(pending === null ? {} : { bustShape: pending }) });
1984
+ } else if (target !== null) staged = stageConfigWrite(target, onlyMissing ? { kind: 'proposal-missing', proposal: prop, parts: P.recs } : { kind: 'proposal', proposal: prop, sections: PROPOSAL_CONFIG_SECTIONS, ...(pending === null ? {} : { bustShape: pending }) });
1898
1985
  else if (written !== null) staged = stageConfigWrite({ kind: 'fresh', path: written.at, text: written.text });
1986
+ // The record marked applied is staged after the config and renamed in before the config's commit; a failed
1987
+ // config commit puts the record back, so the two change together or not at all.
1988
+ if (sidecar !== null && sidecar.appliedText !== null && staged !== null) sidecarStaged = stageReplacements([[sidecar.path, sidecar.appliedText]]);
1899
1989
  mkdirSync(render, { recursive: true });
1900
1990
  writeFileSync(join(out, 'proposal.json'), serializeProposal(prop));
1901
1991
  writeFileSync(join(out, BASIS_FILE), serializeBasis(bfile));
1902
1992
  writePng(join(render, 'landmarks.png'), img.full);
1903
1993
  if (img.head !== null) writePng(join(render, 'landmarks_head.png'), img.head);
1904
1994
  if (staged !== null) {
1905
- staged.commit();
1995
+ const marked = sidecarStaged;
1996
+ if (marked !== null) { marked.commit(); sidecarStaged = null; }
1997
+ try { staged.commit(); }
1998
+ catch (error) {
1999
+ if (marked === null) throw error;
2000
+ const problems = error instanceof PartsError ? [...error.problems] : [];
2001
+ try { marked.undo(); } catch (cleanup) { if (cleanup instanceof PartsError) problems.push(...cleanup.problems); }
2002
+ staged = null;
2003
+ if (problems.length === 0) throw error;
2004
+ throw new PartsError(problems);
2005
+ }
1906
2006
  if (target !== null) for (const line of configWriteLines(target, staged.changes)) console.error(line);
2007
+ if (chest !== null) console.log(chest.line);
2008
+ if (marked !== null && pending !== null && sidecar !== null) {
2009
+ console.log(`propose: wrote the pending shape of act ${JSON.stringify(sidecar.provenance.act.act_id)} into meshes.${pending.part}.contour.bust (${pendingFields(pending.fields)}) with the three points; marked it applied in ${sidecar.path}`);
2010
+ }
1907
2011
  const writtenPath = target?.path ?? written?.at;
1908
2012
  if (writtenPath !== undefined && P.manifest.assembly_config !== undefined) {
1909
2013
  try {
@@ -1935,6 +2039,9 @@ function cmdPropose(args: string[]): number {
1935
2039
  if (cfg !== null) for (const l of compareLines(compare(prop.bones, cfg.bones))) console.log(l);
1936
2040
  return EXIT_OK;
1937
2041
  } catch (err) {
2042
+ if (sidecarStaged !== null) {
2043
+ try { sidecarStaged.cancel(); } catch (cleanup) { if (!(cleanup instanceof PartsError)) throw cleanup; }
2044
+ }
1938
2045
  if (staged !== null) {
1939
2046
  try { staged.abort(err); } catch (combined) { return printRefusal(combined); }
1940
2047
  }
@@ -2662,6 +2769,132 @@ function cmdExternalReceipt(args: string[]): number {
2662
2769
  } catch (error) { return printRefusal(error); }
2663
2770
  }
2664
2771
 
2772
+ /** A pending shape's fields, as `alpha 0.3, bone_r "chest"`. */
2773
+ function pendingFields(fields: Readonly<Record<string, number | string | undefined>>): string {
2774
+ return Object.entries(fields).filter(([, v]) => v !== undefined).map(([k, v]) => `${k} ${JSON.stringify(v)}`).join(', ');
2775
+ }
2776
+
2777
+ /**
2778
+ * The chest-only write on a sampled body-turn neck config (issue #1436): the chest carrier this draft makes, its
2779
+ * `contour.bust` points (none with --no-bust) and the `boob_r` / `boob_l` bones, as one `bust` patch, and the line
2780
+ * that says what it writes and where the cleavage came from. The config's carrier must already be a contour mesh.
2781
+ */
2782
+ /**
2783
+ * Issue #1441: `checkProposal`, with the chest carrier's `contour.bust` checked against the effective shape
2784
+ * (`effectiveBustShape`): the config's declared shape fields on that part, a pending record's over them, the
2785
+ * defaults for the rest, which is what the config write keeps. The proposal written is the draft as it was. With
2786
+ * no declared or pending alpha or clearance the check is the draft's own, so its refusals read as before; otherwise a
2787
+ * clearance refusal names the shape it used and where each value came from.
2788
+ */
2789
+ function checkProposalWithBustShape(P: PartSet, prop: Proposal, target: ConfigWriteTarget | null, sidecar: BustSidecar | null, onlyMissing: boolean): void {
2790
+ const carrier = Object.entries(prop.meshes).find(([, mesh]) => 'contour' in mesh && mesh.contour.bust !== undefined);
2791
+ if (carrier === undefined || !('contour' in carrier[1]) || carrier[1].contour.bust === undefined) { checkProposal(P, prop); return; }
2792
+ const [part, mesh] = carrier;
2793
+ // --only-missing skips a part the config attaches (the write's own decision), so the draft's points are not
2794
+ // written and the declared shape is not theirs: the draft is checked as drafted, as before #1441.
2795
+ if (onlyMissing && target !== null && onlyMissingAttachments(target.raw).has(part)) { checkProposal(P, prop); return; }
2796
+ const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
2797
+ const raw = target === null ? undefined : target.raw;
2798
+ const meshes = isObject(raw) && isObject(raw.meshes) ? raw.meshes : undefined;
2799
+ const declaredMesh = meshes !== undefined && Object.hasOwn(meshes, part) ? meshes[part] : undefined;
2800
+ const declared = isObject(declaredMesh) && isObject(declaredMesh.contour) && isObject(declaredMesh.contour.bust) ? declaredMesh.contour.bust : undefined;
2801
+ const pending = sidecar?.pending?.part === part ? sidecar.pending.fields : undefined;
2802
+ const shape = effectiveBustShape(declared, pending);
2803
+ const used = BUST_POINT_SHAPE_FIELDS.filter((key) => shape[key].source !== 'the default');
2804
+ if (used.length === 0) { checkProposal(P, prop); return; }
2805
+ const bust = { ...mesh.contour.bust, ...Object.fromEntries(used.map((key) => [key, shape[key].value])) };
2806
+ // checkProposal's own reader (proposalAsConfig), given the shape values as read: the loader types them.
2807
+ const meshesChecked: Record<string, unknown> = { ...prop.meshes, [part]: { ...mesh, contour: { ...mesh.contour, bust } } };
2808
+ try { proposalAsConfig(P, { ...prop, meshes: meshesChecked }); }
2809
+ catch (error) {
2810
+ if (!(error instanceof PartsError)) throw error;
2811
+ const at = `config.meshes.${part}.contour.bust.clearance`;
2812
+ throw new PartsError(error.problems.map((p) => p.code === 'CONFIG_BUST_CLEARANCE' && p.object === at ? { ...p, detail: `${p.detail}; ${bustShapeClause(shape)}` } : p));
2813
+ }
2814
+ }
2815
+
2816
+ function chestOnlyPatch(target: ConfigWriteTarget, prop: Proposal, bust: BustDraft, cleavageSource: string | null): { patch: Extract<ConfigWritePatch, { kind: 'bust' }>; line: string } {
2817
+ const omitted = (part: string): boolean => prop.notes.some((n) => n.startsWith(`${part}: contour bust omitted for the declared reason: `));
2818
+ const carrier = Object.entries(prop.meshes).find(([part, mesh]) => 'contour' in mesh && (mesh.contour.bust !== undefined || omitted(part)));
2819
+ if (carrier === undefined) {
2820
+ const chestBone = prop.bones.find((b) => 'name' in b && b.name === 'chest');
2821
+ const where = chestBone !== undefined && 'at' in chestBone ? ` at [${chestBone.at.join(', ')}]` : '';
2822
+ throw new PartsError([{ code: 'PROPOSE_BUST_INPUT', object: 'chest carrier', detail: `no topwear art covers chest${where}. A chest-holding topwear part is required for the declared bust input` }]);
2823
+ }
2824
+ const [part, mesh] = carrier;
2825
+ const raw = target.raw as { meshes?: Record<string, unknown> };
2826
+ const declared = typeof raw.meshes === 'object' && raw.meshes !== null ? raw.meshes[part] : undefined;
2827
+ if (typeof declared !== 'object' || declared === null || !('contour' in declared)) {
2828
+ const found = typeof declared !== 'object' || declared === null ? 'no mesh' : `a ${['grid', 'auto', 'influence', 'explicit'].find((m) => m in declared) ?? 'non-contour'} mesh`;
2829
+ throw new PartsError([{ code: 'PROPOSE_BUST_CARRIER_MESH', object: `config.meshes.${part}`, detail: `is ${found}; the chest-only write on a sampled body-turn neck config sets contour.bust on the chest carrier's contour mesh, which it does not draft. Produce one in this order: rig-parts propose … --write-config <config> --no-bust "<reason>" before turn.body is written, then write turn.body and draft the neck` }]);
2830
+ }
2831
+ const points = 'contour' in mesh ? mesh.contour.bust : undefined;
2832
+ const bones = prop.bones.filter((b): b is { name: string; parent: string; at: [number, number] } => 'name' in b && (b.name === 'boob_r' || b.name === 'boob_l') && 'at' in b).map((b) => ({ name: b.name, parent: b.parent, at: [b.at[0], b.at[1]] }));
2833
+ const patch: Extract<ConfigWritePatch, { kind: 'bust' }> = { kind: 'bust', part, bust: points === undefined || points.cleavage === undefined ? null : { apex_r: [...points.apex_r], apex_l: [...points.apex_l], cleavage: [...points.cleavage] }, bones };
2834
+ const line = patch.bust === null
2835
+ ? `propose: chest-only write on the sampled body-turn neck config: meshes.${part}.contour.bust and bones boob_r, boob_l removed where present (--no-bust: ${bust.noBust ?? ''}); every other entry as read`
2836
+ : `propose: chest-only write on the sampled body-turn neck config: meshes.${part}.contour.bust apex_r ${JSON.stringify(patch.bust.apex_r)} apex_l ${JSON.stringify(patch.bust.apex_l)} cleavage ${JSON.stringify(patch.bust.cleavage)} (${cleavageSource ?? 'from the landmarks file'}); bones boob_r, boob_l under chest at the apices; every other entry as read`;
2837
+ return { patch, line };
2838
+ }
2839
+
2840
+ function cmdBustLandmarks(args: string[]): number {
2841
+ // The one switch (issue #1382, round 2): taken out before the valued flags are read.
2842
+ const writes = args.filter((a) => a === '--write-config').length;
2843
+ if (writes > 1) return usage('--write-config is given twice');
2844
+ const f = flags(args.filter((a) => a !== '--write-config'), 'bust-landmarks', ['--from-act', '--parts', '--config', '--out']);
2845
+ if (typeof f === 'string') return usage(f);
2846
+ try {
2847
+ const input = { act: f.get('--from-act')!, parts: f.get('--parts')!, config: f.get('--config')!, out: f.get('--out')!, writeConfig: writes === 1 };
2848
+ // The config to write is read before it is checked, so its commit refuses a change made in between; a refusal
2849
+ // reading it joins the act's and the inputs' in one report.
2850
+ const prior: Problem[] = [];
2851
+ let target: ConfigWriteTarget | null = null;
2852
+ if (input.writeConfig) {
2853
+ try { target = readConfigWriteTarget(input.config); }
2854
+ catch (error) { if (error instanceof PartsError) prior.push(...error.problems); else throw error; }
2855
+ }
2856
+ const plan = planBustLandmarks(input, prior);
2857
+ if (target !== null) separateConfigWriteTarget(target, [plan.out, plan.provenancePath], 'BUST_LANDMARKS_OUT');
2858
+ // propose's order: the config staged (and checked through the loader) first, then the outputs written, then the
2859
+ // config committed; a failure before the config's commit leaves it as it was, and a failed config commit puts
2860
+ // the earlier outputs back.
2861
+ const staged: StagedConfigWrite | null = target !== null && plan.configPatch !== null ? stageConfigWrite(target, plan.configPatch) : null;
2862
+ let outputs: StagedBustLandmarks;
2863
+ try {
2864
+ outputs = stageBustLandmarks(plan);
2865
+ outputs.commit();
2866
+ } catch (error) {
2867
+ if (staged !== null) staged.abort(error);
2868
+ throw error;
2869
+ }
2870
+ if (staged !== null) {
2871
+ try { staged.commit(); }
2872
+ catch (error) {
2873
+ const problems = error instanceof PartsError ? [...error.problems] : [];
2874
+ try { outputs.undo(); } catch (cleanup) { if (cleanup instanceof PartsError) problems.push(...cleanup.problems); }
2875
+ if (problems.length === 0) throw error;
2876
+ throw new PartsError(problems);
2877
+ }
2878
+ }
2879
+ const { landmarks, provenance } = plan;
2880
+ if (target !== null) for (const line of configWriteLines(target, staged?.changes ?? [])) console.error(line);
2881
+ console.log(`bust-landmarks: slot "${provenance.slot}" apex_r ${JSON.stringify(landmarks.apex_r)} apex_l ${JSON.stringify(landmarks.apex_l)} cleavage ${landmarks.cleavage === undefined ? 'absent (propose derives it)' : JSON.stringify(landmarks.cleavage)}; act ${JSON.stringify(provenance.act.act_id)} sha256=${provenance.act.file_sha256} row sha256=${provenance.row_sha256} (verified against the row's edit)`);
2882
+ const shape = provenance.shape;
2883
+ // Issue #1436: both lines name the command that writes the points into the config; without --write-config,
2884
+ // propose writes only proposal.json.
2885
+ const next = `wrote ${plan.out} and ${plan.provenancePath}; next, to apply it: rig-parts propose … --write-config ${resolve(input.config)} --bust-landmarks ${plan.out}`;
2886
+ if (shape === undefined) console.log(next);
2887
+ else {
2888
+ // Issue #1382: the config declares no contour.bust, so the reviewed shape waits in the record for propose.
2889
+ // Issue #1443: or the act moved the declared points, and the shape is not written against the old ones.
2890
+ const why = plan.moved ? `the act moves the points of meshes.${provenance.slot}.contour.bust, so the config is not written and` : 'the config declares no contour.bust yet, so';
2891
+ console.log(`bust-landmarks: pending shape for "${provenance.slot}": ${pendingFields(shape.fields)}; ${why} ${plan.provenancePath} carries it until propose writes it with the three points`);
2892
+ console.log(next);
2893
+ }
2894
+ return EXIT_OK;
2895
+ } catch (error) { return printRefusal(error); }
2896
+ }
2897
+
2665
2898
  function cmdDepthBind(args: string[]): number {
2666
2899
  const f = flags(args, 'depth-bind', ['--map', '--input', '--part']);
2667
2900
  if (typeof f === 'string') return usage(f);
@@ -2702,6 +2935,7 @@ function main(argv: string[]): number | Promise<number> {
2702
2935
  if (command === 'depth-prepare') return cmdDepthPrepare(rest);
2703
2936
  if (command === 'edited-part') return cmdEditedPart(rest);
2704
2937
  if (command === 'external-receipt') return cmdExternalReceipt(rest);
2938
+ if (command === 'bust-landmarks') return cmdBustLandmarks(rest);
2705
2939
  if (command === 'depth-bind') return cmdDepthBind(rest);
2706
2940
  if (command === 'depth-apply') return cmdDepthApply(rest);
2707
2941
  if (command === 'sheet') return cmdSheet(rest);