rig-parts 1.76.0 → 1.77.0

package/cli.ts

@@ -16,7 +16,8 @@ import { runBuildProcess, processRigcRunner as rigcRunner } from './tools/build-
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join, resolve } from 'node:path';
-import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, proposeSinglePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
+import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, headGarmentOverlaps, headGarmentWarning, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, proposeSinglePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
+import { proposeNeck } from './tools/neck-propose.ts';
 import { parseAltArg } from './tools/alternate-cli.ts';
 import { type AlternateCliInput, assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage, suppliedCheckFlag } from './src/build.ts';
 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, rigcRanClause, 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';
@@ -88,6 +89,11 @@ usage:
       size is not its box, and anything else outside the input contract —
       never a WARN.
 
+  rig-parts layers <head-run> --full <full-run> --source <painting.png> --config <config.json>
+      Read PLAN_HEAD_GARMENT_OVERLAP on planned head parts against full-run
+      garments registered into the declared crop. Alpha >=250, any overlap;
+      names part, garment, count, half-open head-canvas box and source remedy.
+
   rig-parts layers --export <dir> <dir | layers.json | file.psd>
       Print the table, then write the input as the wrapper form into <dir>
       (absent or empty, LAYERS_EXPORT_DIR_EMPTY): layers.json and one RGBA PNG
@@ -203,6 +209,13 @@ usage:
       or a layer with no depth is refused by name. Without either flag nothing
       changes.
 
+  rig-parts propose … --full <run> --head <run> --write-config <existing.json>
+      When the target declares turn.body and one neck plan row, preserve its
+      sampled turn and authored rig, take a clean full-run neck, and draft one
+      rigid sibling unit under the body carrier. Reassembled art is written to
+      <out>/rig; depth comes from the existing scalar input, named in note:.
+      Missing depth, landmarks or clean source is refused, never invented.
+
   rig-parts propose … [--grid-rule figure|part]
       How each drafted lattice's spacing (meshes.<part>.grid) is chosen.
       figure, the default: round(H / ${FIGURE_GRID_DIVISOR}) rig px for every lattice, H the
@@ -1051,7 +1064,7 @@ function printLayerTable(set: LayerSet): void {
  * no row; `layers` takes one positional path beside its flags (issue #359).
  */
 const TAKES = {
-  layers: { valued: ['--export', '--template', '--canvas'], switches: [] },
+  layers: { valued: ['--export', '--template', '--canvas', '--full', '--source', '--config'], switches: [] },
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
   rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config', '--from'], switches: ['--head-box', '--no-back-hair', '--only-missing'] },
@@ -1109,7 +1122,7 @@ function cmdLayers(args: string[]): number {
   }
   const template = flags.get('--template');
   if (template !== undefined) {
-    if (flags.has('--export') || paths.length > 0) return usage(`--template writes a PSD and reads nothing; it takes --canvas only, and got ${[...[...flags.keys()].filter((f) => f !== '--template' && f !== '--canvas'), ...paths].join(', ')}`);
+    if (flags.has('--export') || paths.length > 0 || ['--full', '--source', '--config'].some(f => flags.has(f))) return usage(`--template writes a PSD and reads nothing; it takes --canvas only, and got ${[...[...flags.keys()].filter((f) => f !== '--template' && f !== '--canvas'), ...paths].join(', ')}`);
     const canvasArg = flags.get('--canvas');
     if (canvasArg === undefined) return usage('--template needs --canvas <W>x<H>, the canvas size in px (with one run, a square of seethrough.resolution)');
     const canvas = parseCanvas(canvasArg);
@@ -1127,6 +1140,14 @@ function cmdLayers(args: string[]): number {
   try {
     const set = readLayers(paths[0]);
     printLayerTable(set);
+    const context = ['--full', '--source', '--config'];
+    if (context.some(f => flags.has(f))) {
+      if (!context.every(f => flags.has(f))) return usage('layers crop overlap inspection requires --full, --source and --config together; the positional path is the head run');
+      const full = readLayers(flags.get('--full')!), source = readSource(flags.get('--source')!);
+      const cfg = loadEarlyConfig(flags.get('--config')!, 'assemble');
+      const g = { sourceW: source.width, sourceH: source.height, ...proposeFields(cfg) };
+      for (const w of headGarmentOverlaps(full, set, g, cfg.assemble.plan)) console.log(`  ${headGarmentWarning(w)}`);
+    }
     const dir = flags.get('--export');
     if (dir !== undefined) {
       const w = exportLayers(set, dir);
@@ -1479,6 +1500,16 @@ function cmdPropose(args: string[]): number {
     if (!existsSync(source)) {
       throw new PartsError([{ code: 'PROPOSE_SOURCE_PRESENT', object: source, detail: 'no such file; the painting is drawn under the overlay' }]);
     }
+    if (target !== null && typeof target.raw === 'object' && target.raw !== null && 'turn' in target.raw) {
+      const turn = target.raw.turn;
+      if (typeof turn === 'object' && turn !== null && 'body' in turn && (loadEarlyConfig(target.path, 'assemble').assemble.plan.some(([, , tag]) => tag === 'neck'))) {
+        const unsupported = [...flags.keys()].filter(f => !['--parts', '--source', '--out', '--full', '--head', '--write-config'].includes(f));
+        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' }]);
+        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' }]);
+        proposeNeck(target, { source, parts: partsDir, out, full: flags.get('--full'), head: flags.get('--head') });
+        return EXIT_OK;
+      }
+    }
     const P = readPartSet(partsDir);
     const painting = readPng(source);
     // Issue #75: the keypoint file, held to this painting's size and taken to rig px by the overlay's map.

package/docs/AUTHORING.md

@@ -2885,6 +2885,67 @@ support. This warning retains the extended scalar sample, all motion arithmetic
 and existing refusal behavior; it is not a gate. Explicit `unitDepths` entries
 bypass that sample and its warning, including an explicit zero.
 
+### A neck that moves on its own
+
+If the head run carries a collar contour in its neck, select a clean `full:neck`
+first. `PLAN_HEAD_GARMENT_OVERLAP` is a source-alpha warning, not a semantic
+collar classifier: any alpha >=250 intersection with a planned full-run
+`topwear`, `neckwear` or `collar` layer is reported on the registered head-crop
+canvas. The half-open box and count locate pixels to inspect. A normal underlap
+may also warn; inspect the source, setup and moving boundaries.
+
+For an existing config with `turn.body`, one neck plan row and named `neck` /
+`head` landmarks, run:
+
+```sh
+rig-parts layers head/ --full full/ --source painting.png --config config.json
+rig-parts propose --parts assembled/rig --source painting.png --full full/ --head head/ --out neck-draft/ --write-config config.json
+rig-parts rig --parts neck-draft/rig --config config.json --out neck-rig/
+```
+
+The existing config is the explicit body-turn context. Choose a fresh output
+whose `rig/` subdirectory does not exist. The draft preserves its
+authored rig and sampled turn, changes the neck's plan row to the full run,
+reassembles source pixels under `neck-draft/rig`, and creates `<part>_part` as a
+sibling of the anatomical neck under the body carrier. One segment binds the
+neck rigidly; its head role is removed and its body role is `unit`.
+Full-run provenance avoids the head-crop warning; alpha overlap does not
+certify semantic cleanliness, because a clean neck may still underlap a garment.
+Inspect the full source and the rendered extremes. If it still carries collar
+art, select another run or rerun See-through; no mask or cut is applied.
+Existing structural operations on other parts are replayed unchanged. A neck
+cut, neck limb split, neck extension or alternate sets require a separate
+assemble/config step; this bounded draft names that refusal. Reassembly uses the
+CLI defaults `seam=near-white` and `project=core`, explicitly stated in its note
+because `parts.json` does not record the source command's selected rules.
+
+The `note:` line derives `turn.body.unitDepths.<part>` as
+`round4(bodyPivot + neckWorldMedian - firstBodySurfaceWorldMedian)`, using the
+existing scalar sheet, declared `near` polarity and `zScale`. If the new source
+has no sheet, only new opaque art overlapping the previous registered neck
+sheet is sampled. An absent sheet, empty overlap, missing body reference or
+missing pivot is refused by name; legacy `depth_median` is never converted to
+world units. Other proposal modes (`--keypoints`, `--compare`, `--grid-rule`,
+`--only-missing`) must run separately and are refused in this mode.
+
+| rule | means | change |
+| --- | --- | --- |
+| <a id="PROPOSE_NECK_BODY_TURN"></a>`PROPOSE_NECK_BODY_TURN` | no authored sampled body turn | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_PLAN"></a>`PROPOSE_NECK_PLAN` | no unique neck plan row | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_FULL_SOURCE"></a>`PROPOSE_NECK_FULL_SOURCE` | no full-run neck source | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_DEPTH_INPUT"></a>`PROPOSE_NECK_DEPTH_INPUT` | missing scalar sheet, body reference, pivot or registered overlap | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_CARRIER"></a>`PROPOSE_NECK_CARRIER` | missing neck/head landmarks or body carrier | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_BONE_UNIQUE"></a>`PROPOSE_NECK_BONE_UNIQUE` | generated sibling name already belongs to another bone | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_REASSEMBLY"></a>`PROPOSE_NECK_REASSEMBLY` | neck structural operations or alternate sets require separate assembly | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_RUNS"></a>`PROPOSE_NECK_RUNS` | full/head runs not both supplied | follow this recipe and supply the named input; the refusal writes no config |
+| <a id="PROPOSE_NECK_OUT_FRESH"></a>`PROPOSE_NECK_OUT_FRESH` | output rig directory already exists or aliases input parts | choose a fresh output directory |
+| <a id="PROPOSE_NECK_MODE"></a>`PROPOSE_NECK_MODE` | incompatible proposal mode requested | follow this recipe and supply the named input; the refusal writes no config |
+
+Build through the normal gate, then use `rigc render --extremes` on `body_turn`,
+`turn` and `tilt`. Read setup, min, max and absolute diff at native scale, then
+inspect neck boundaries at native and 4x nearest-neighbour scale for tears or
+ghosts. A green build alone does not certify the source art.
+
 ## 4. The command order
 
 Two steps are external: the See-through runs (by any route; the optional `comfy seethrough` adapter is only a client for a ComfyUI box). Everything else is this tool.
@@ -3318,7 +3379,8 @@ loads, with `check/contact.png` and the idle frames to look at.
 ### Source before scissors (issue #819)
 
 For a tear, ghost, smudge, outline or seam, first select an appropriate existing
-See-through layer/run or alternate; then measure a tighter See-through resolution,
+See-through layer/run or alternate (for a collar baked into the neck, see
+[A neck that moves on its own](#a-neck-that-moves-on-its-own)); then measure a tighter See-through resolution,
 crop or settings if needed. Next measure the declared depth/turn role and, for a
 `drift:` line with a matching opaque behind holder, opt in with
 `assemble.yield_refused: true`. This config step only clears the original refused
@@ -3664,7 +3726,8 @@ changes draw order. A tear, ghost, smudge, stray outline or seam is a source
 problem. Follow this repair ladder, recording what each step measured:
 
 1. Choose another See-through layer or run (`full` versus `head`, another tag,
-   or `alternates`).
+   or `alternates`). For a collar baked into the neck, follow
+   [A neck that moves on its own](#a-neck-that-moves-on-its-own).
 2. Re-run See-through with a tighter resolution or crop.
 3. Correct the declared depth or role in config.
 
@@ -3981,6 +4044,7 @@ over the whole union: a layer is part of it, so it could never be more than 1x.
 
 | rule | crossed when | [observed] on the two examples' 116 layers (four runs) |
 | --- | --- | --- |
+| <a id="PLAN_HEAD_GARMENT_OVERLAP"></a>`PLAN_HEAD_GARMENT_OVERLAP` | WARN: a planned head-run part has opaque crop pixels (alpha >=250) in common with a planned full-run garment after registration; count and half-open head-canvas box are named. It reports source overlap, not semantic line art | take the part from a clean full run; [A neck that moves on its own](#a-neck-that-moves-on-its-own) |
 | <a id="PLAN_LAYER_TRANSLUCENT"></a>`PLAN_LAYER_TRANSLUCENT` | judged, and `translucent` above 50 % | the most translucent judged layer is 17.8 % (reference-sample, full run, `front hair`) |
 | <a id="PLAN_LAYER_BACKGROUND"></a>`PLAN_LAYER_BACKGROUND` | judged, `background` above 50 %, and `translucent` above 25 % | the most background-coloured judged layer is 21.9 % (reference-demo, head run, `topwear`, a white dress); of judged layers above 10 % background, the most translucent is 5.6 % (reference-demo, full run, `handwear-r`) |
 | <a id="PLAN_LAYER_OVERSIZED"></a>`PLAN_LAYER_OVERSIZED` | `area` above 4x | the largest is 1.681x (reference-demo, head run, `back hair`, which fills the crop) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.76.0",
+  "version": "1.77.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": {
@@ -42,6 +42,7 @@
     "tools/configwrite.ts",
     "tools/build-process.ts",
     "tools/alternate-cli.ts",
+    "tools/neck-propose.ts",
     "src",
     "workflows",
     "docs/AUTHORING.md",

package/src/assemble.ts

@@ -5916,6 +5916,42 @@ function fmt0(v: number): string {
  * before; each gains one such note per tag left out (demo 6, scarf 9,
  * reference-demo 7, reference-sample 9).
  */
+/** Source alpha intersection, not an art classifier. One opaque texel can carry a second contour. */
+export interface HeadGarmentOverlap { part: string; layer: string; px: number; box: [number, number, number, number] }
+
+/** #812: register full garments onto the declared crop; count only planned source pairs. */
+export function headGarmentOverlaps(full: LayerSet, head: LayerSet, g: Geometry, plan: readonly PlanEntry[]): HeadGarmentOverlap[] {
+  if (g.single === true) return [];
+  const frame = checkGeometry(g, { full, head });
+  const garments = plan.filter(([, run, tag]) => run === 'full' && ['topwear', 'neckwear', 'collar'].includes(tag));
+  const out: HeadGarmentOverlap[] = [];
+  for (const [part, run, tag] of plan) {
+    if (run !== 'head') continue;
+    const layer = head.layers.find(l => l.name === tag);
+    if (layer === undefined) continue;
+    const a = placeLayer(layer, g.resolution);
+    for (const [, , name] of garments) {
+      const garment = full.layers.find(l => l.name === name);
+      if (garment === undefined) continue;
+      const b = fullLayerToHead(placeLayer(garment, g.resolution), frame, g.resolution);
+      let px = 0, left = g.resolution, top = g.resolution, right = 0, bottom = 0;
+      for (let y = 0; y < g.resolution; y++) for (let x = 0; x < g.resolution; x++) {
+        const k = (y * g.resolution + x) * 4 + 3;
+        if (a.data[k] < CORE_ALPHA || b.data[k] < CORE_ALPHA) continue;
+        px++; left = Math.min(left, x); top = Math.min(top, y); right = Math.max(right, x + 1); bottom = Math.max(bottom, y + 1);
+      }
+      if (px > 0) out.push({ part, layer: name, px, box: [left, top, right, bottom] });
+    }
+  }
+  return out;
+}
+
+export const HEAD_GARMENT_WARNING = 'PLAN_HEAD_GARMENT_OVERLAP';
+
+export function headGarmentWarning(w: HeadGarmentOverlap): string {
+  return `WARN  ${HEAD_GARMENT_WARNING}: part "${w.part}" (head run) overlaps full-run layer "${w.layer}" — ${w.px} opaque crop px (alpha >= ${CORE_ALPHA}), box [${w.box.join(', ')}] (right/bottom exclusive, head-canvas px); take this part from the full run, then inspect the source and rebuild (AUTHORING: A neck that moves on its own)`;
+}
+
 export function proposePlan(full0: LayerSet, head0: LayerSet, g: Geometry, minPx = PROPOSE_MIN_PX): PlanProposal {
   const frame = checkGeometry(g, { full: full0, head: head0 });
   // Issue #366: one run's file, padded to the resolution square as the stage pads it.
@@ -6055,7 +6091,7 @@ export function proposePlan(full0: LayerSet, head0: LayerSet, g: Geometry, minPx
   const bodyNotes = left.map((u) => uncoveredNote(u, plan, minBody));
   const unplanned = unplannedNotes(runs, plan, extend, noted, figures, minPx, (run, tag) => (find(run, tag)?.opaqueRunPx ?? 0) * (run === 'head' ? headArea : fullArea), new Set(left.map((u) => u.tag)));
   // The reference's notes, then the uncovered bodies, then the layers in no row (issue #308), then the plausibility drops — a drop note is last, as it was.
-  return { plan, extend_below_crop: extend, notes: [...notes, ...bodyNotes, ...unplanned, ...dropNotes] };
+  return { plan, extend_below_crop: extend, notes: [...notes, ...bodyNotes, ...unplanned, ...dropNotes, ...headGarmentOverlaps(full, head, g, plan).map(headGarmentWarning)] };
 }
 
 /**

package/src/config.ts

@@ -1794,6 +1794,14 @@ export function controlSkeletonOf(cfg: object): ControlSkeleton | undefined {
   return resolveControlSkeleton(gen, null);
 }
 
+/** Clone a config and its already resolved control pose, without reading a relative file again. */
+export function cloneConfig<T extends object>(cfg: T): T {
+  const clone = structuredClone(cfg);
+  const skeleton = controlSkeletonOf(cfg);
+  if (skeleton !== undefined) controlSkeletons.set(clone, structuredClone(skeleton));
+  return clone;
+}
+
 /** The pose file a checked `generation` block's control names, read relative to `base`; null for a built-in, an absent control, or a block already refused. */
 function poseBeside(c: Check, gen: Json, base: string): ControlPose | null {
   if (!isPlainObject(gen) || !isPlainObject(gen.control)) return null;

package/src/configwrite.ts

@@ -10,6 +10,7 @@
  */
 import type { PlanProposal } from './assemble.ts';
 import type { HeadBoxProposal } from './headbox.ts';
+import type { CharacterConfig } from './config.ts';
 import type { Proposal, PROPOSAL_CONFIG_SECTIONS } from './propose.ts';
 import { PartsError } from './errors.ts';
 import { parseProposalSections } from './config.ts';
@@ -18,6 +19,7 @@ import type { ConfigEdit } from './meshdraft.ts';
 export type ConfigJson = null | boolean | number | string | ConfigJson[] | ConfigObject;
 export interface ConfigObject { [key: string]: ConfigJson }
 export type ConfigWritePatch =
+  | { kind: 'neck-unit'; config: CharacterConfig }
   | { kind: 'head-box'; head_box: HeadBoxProposal['head_box'] }
   | { kind: 'assemble-plan'; plan: PlanProposal['plan']; extend_below_crop: PlanProposal['extend_below_crop'] }
   | { kind: 'proposal'; proposal: Proposal; sections: typeof PROPOSAL_CONFIG_SECTIONS }
@@ -91,6 +93,18 @@ export function mergeConfigProposal(raw: unknown, patch: ConfigWritePatch): Conf
   const config = clone(before, 'config') as ConfigObject;
   const edits: ConfigEdit[] = [];
   switch (patch.kind) {
+    case 'neck-unit': {
+      const values = { bones: patch.config.bones, meshes: patch.config.meshes, regions: patch.config.regions, turn: patch.config.turn };
+      for (const [key, value] of Object.entries(values)) {
+        config[key] = clone(value, `neck.${key}`);
+        if (!equal(before[key], config[key])) edits.push({ path: [key], value: config[key] });
+      }
+      if (!object(config.assemble)) return refuse('config.assemble', 'must be an object before drafting the neck source');
+      config.assemble.plan = clone(patch.config.assemble.plan, 'neck.plan');
+      if (!equal((before.assemble as ConfigObject).plan, config.assemble.plan)) edits.push({ path: ['assemble', 'plan'], value: config.assemble.plan });
+      break;
+    }
+
     case 'head-box': {
       if (!object(config.seethrough)) return refuse('config.seethrough', 'is absent or not an object; the existing See-through settings are required before writing head_box');
       const previous = config.seethrough.head_box;

package/src/neckdraft.ts

@@ -0,0 +1,82 @@
+/** #812: source-first drafting into an explicitly authored sampled body turn. */
+import { assemble, checkGeometry, fullLayerToHead, headGarmentOverlaps, headGarmentWarning, placeLayer, stageFields, type AssembleResult, type AssembleInput } from './assemble.ts';
+import { cloneConfig, type CharacterConfig } from './config.ts';
+import { type LayerSet } from './layers.ts';
+import { PartsError } from './errors.ts';
+import { extendDepthSilhouette } from './depthsheets.ts';
+import { type PartsFile } from './parts.ts';
+import type { Raster } from './raster/types.ts';
+import { sampleUnitPartDepth } from './turn.ts';
+import { pyRound } from './round.ts';
+import { partGrid } from './propose.ts';
+
+function refuse(code: string, object: string, detail: string): never { throw new PartsError([{ code, object, detail }]); }
+export interface NeckDraft { config: CharacterConfig; assembled: AssembleResult; notes: string[] }
+
+/** No inference of a body turn, depth units, source art or anatomical endpoints. */
+export function draftIndependentNeck(input: { config: CharacterConfig; source: Raster; full: LayerSet; head: LayerSet; base: string; under?: AssembleInput['under']; caps?: AssembleInput['caps']; previous?: { parts: PartsFile; images: ReadonlyMap<string, Raster> } }): NeckDraft {
+  const cfg = cloneConfig(input.config), body = cfg.turn?.body;
+  if (body === undefined) return refuse('PROPOSE_NECK_BODY_TURN', 'config.turn.body', 'is absent; declare the sampled body turn before drafting an independent neck');
+  // Body overrides the entire fallback map; snapshot before removing the legacy neck entry.
+  const unitDepths = { ...(body.unitDepths ?? cfg.turn?.unitDepths) };
+  const rows = cfg.assemble.plan.filter(([, , tag]) => tag === 'neck');
+  if (rows.length !== 1) return refuse('PROPOSE_NECK_PLAN', 'config.assemble.plan', `has ${rows.length} neck rows; one unambiguous neck source is required`);
+  const [part] = rows[0];
+  const fullNeck = input.full.layers.find(l => l.name === 'neck');
+  if (fullNeck === undefined) return refuse('PROPOSE_NECK_FULL_SOURCE', `part "${part}"`, 'full-run neck layer is missing; supply --full with a clean neck layer, then rerun propose');
+  const fields = stageFields(cfg), g = { ...fields, sourceW: input.source.width, sourceH: input.source.height };
+  const frame = checkGeometry(g, input);
+  const notes = headGarmentOverlaps(input.full, input.head, g, cfg.assemble.plan).map(headGarmentWarning);
+  const projected = fullLayerToHead(placeLayer(fullNeck, fields.resolution), frame, fields.resolution);
+  notes.push('neck source: full-run provenance avoids the head-crop warning; opaque overlap alone does not identify collar line art or distinguish normal seam underlap. Inspect the full source and rendered setup/extremes before accepting the draft');
+  const pivot = body.pivot ?? cfg.turn?.pivot;
+  if (pivot === undefined) return refuse('PROPOSE_NECK_DEPTH_INPUT', 'config.turn.body.pivot', 'and config.turn.pivot are absent; declare the body pivot in the existing depth world units');
+  const neck = cfg.bones.find(b => 'name' in b && b.name === 'neck');
+  const head = cfg.bones.find(b => 'name' in b && b.name === 'head');
+  const carrier = body.bone ?? (cfg.bones.some(b => 'name' in b && b.name === 'chest') ? 'chest' : 'hip');
+  if (neck === undefined || !('at' in neck) || head === undefined || !('at' in head) || !cfg.bones.some(b => 'name' in b && b.name === carrier)) return refuse('PROPOSE_NECK_CARRIER', `part "${part}"`, `neck/head landmarks or body carrier "${carrier}" are missing; declare their named bones and coordinates`);
+  // This path changes a source, not structural cuts/alternate sets that require their own readers.
+  if (cfg.assemble.cuts?.some(c => c.from === part || c.into === part) || cfg.assemble.alternates?.length || Object.values(cfg.limbs ?? {}).some(l => l.segments.some(s => s.from === part)) || cfg.assemble.extend_below_crop?.some(e => e.part === part)) return refuse('PROPOSE_NECK_REASSEMBLY', `part "${part}"`, 'this neck has a cut, limb split or extension, or the config has alternate sets; first assemble the clean full-run neck with the existing assemble command and draft its base config without those neck operations or alternate sets');
+  cfg.assemble.plan = cfg.assemble.plan.map(row => row[0] === part ? [part, 'full', 'neck'] : row);
+  const unit = `${part}_part`;
+  const found = cfg.bones.find(b => 'name' in b && b.name === unit);
+  if (found !== undefined && (!('at' in found) || found.parent !== carrier || JSON.stringify(found.at) !== JSON.stringify(neck.at))) return refuse('PROPOSE_NECK_BONE_UNIQUE', unit, 'already names a different bone; rename that bone before drafting the neck unit');
+  if (found === undefined) cfg.bones.splice(cfg.bones.indexOf(neck) + 1, 0, { name: unit, parent: carrier, at: [...neck.at] });
+  const current = cfg.meshes[part];
+  const [grid, r] = partGrid(input.previous?.parts.parts.find(p => p.name === part) ?? { w: projected.width, h: projected.height });
+  cfg.meshes[part] = { grid: current !== undefined && 'grid' in current ? current.grid : grid, r: current !== undefined && 'r' in current ? current.r : r, segments: [[unit, [...neck.at], [...head.at]]] };
+  delete cfg.regions[part];
+  if (cfg.turn!.roles !== undefined) delete cfg.turn!.roles[part];
+  if (cfg.turn!.unitDepths !== undefined) delete cfg.turn!.unitDepths[part];
+  body.roles[part] = 'unit';
+  // Stage fields now see the new role before any color/fringe ownership operation.
+  const assembled = assemble({ source: input.source, full: input.full, head: input.head, ...stageFields(cfg), under: input.under, caps: input.caps, seamRule: 'near-white', projectRule: 'core', depth: cfg.depth, depthBase: input.base });
+  const rec = assembled.parts.parts.find(p => p.name === part)!;
+  const image = assembled.images.find(p => p.record.name === part)!.image;
+  const own = assembled.images.find(p => p.record.name === part)!;
+  let ref = rec.depth, scalar = own.depthImage, art = image, population = 'new full-run opaque neck texels';
+  if (ref === undefined || scalar === undefined) {
+    const old = input.previous?.parts.parts.find(p => p.name === part);
+    const oldSheet = old?.depth === undefined ? undefined : input.previous?.images.get(old.depth.image);
+    if (old?.depth === undefined || oldSheet === undefined) return refuse('PROPOSE_NECK_DEPTH_INPUT', `part "${part}"`, 'full-run scalar depth sheet and previous parts.json neck depth sheet are missing; supply config.depth with near/zScale and the source sheet, or reassemble parts with its existing scalar depth input');
+    ref = old.depth; scalar = oldSheet; art = { ...oldSheet, data: new Uint8ClampedArray(oldSheet.width * oldSheet.height * 4) };
+    let n = 0;
+    for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
+      const ox = rec.x + x - old.x, oy = rec.y + y - old.y;
+      if (image.data[(y * image.width + x) * 4 + 3] < 128 || ox < 0 || oy < 0 || ox >= old.w || oy >= old.h) continue;
+      art.data[(oy * old.w + ox) * 4 + 3] = 255; n++;
+    }
+    if (n === 0) return refuse('PROPOSE_NECK_DEPTH_INPUT', `part "${part}"`, 'new art has no opaque overlap with the previous scalar sheet; supply a registered full-run neck scalar sheet');
+    population = `${n} new-art opaque texels overlapping previous registered neck sheet`;
+  }
+  const surface = Object.entries(body.roles).find(([, role]) => role === 'surface')?.[0];
+  const surf = assembled.images.find(p => p.record.name === surface);
+  if (surf?.record.depth === undefined || surf.depthImage === undefined) return refuse('PROPOSE_NECK_DEPTH_INPUT', `turn.body surface "${surface ?? '(none)'}"`, 'the first declared body surface or its scalar depth sheet is missing; declare a body surface and assemble its config.depth input');
+  const zNeck = sampleUnitPartDepth(scalar, art, ref);
+  const zRef = sampleUnitPartDepth(extendDepthSilhouette(surf.depthImage, surf.image), surf.image, surf.record.depth);
+  const value = pyRound(pivot + zNeck - zRef, 4);
+  body.unitDepths = { ...unitDepths, [part]: value };
+  notes.push(`neck: "${part}" takes full:neck; sibling bone "${unit}" under "${carrier}", one rigid segment from neck to head; reassembled with the CLI defaults seam=near-white/project=core (source rules are not recorded in parts.json); turn.body.roles.${part} = unit (no head role)`);
+  notes.push(`neck depth: turn.body.unitDepths.${part} = ${value} = round4(body pivot ${pivot} + neck world median ${zNeck} - first body surface "${surface}" world median ${zRef}); median over ${population}, sheet "${ref.image}", near=${ref.near}, zScale=${ref.zScale}; levelToDepthZ applies the declared polarity, not depth_median`);
+  return { config: cfg, assembled, notes };
+}

package/tools/neck-propose.ts

@@ -0,0 +1,39 @@
+/** Filesystem adapter for the explicit --write-config sampled-turn context. */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { loadConfig, parseConfig } from '../src/config.ts';
+import { draftIndependentNeck } from '../src/neckdraft.ts';
+import { readRigInputs, readUnders, readCaps } from '../src/build.ts';
+import { readLayers } from '../src/layers.ts';
+import { readPng, writePng } from '../src/raster/png.ts';
+import { writeParts } from '../src/parts.ts';
+import { configWriteLines, separateConfigWriteTarget, stageConfigWrite, type ConfigWriteTarget } from './configwrite.ts';
+import { PartsError } from '../src/errors.ts';
+
+export function proposeNeck(target: ConfigWriteTarget, args: { source: string; full?: string; head?: string; parts: string; out: string }): void {
+  if (args.full === undefined || args.head === undefined) throw new PartsError([{ code: 'PROPOSE_NECK_RUNS', object: 'propose --write-config', detail: 'a sampled body turn with a neck requires --full and --head to inspect and reassemble its source; give both runs' }]);
+  const output = join(args.out, 'rig');
+  if (existsSync(output) || resolve(output) === resolve(args.parts)) throw new PartsError([{ code: 'PROPOSE_NECK_OUT_FRESH', object: output, detail: 'already exists or is the input parts directory; choose a fresh --out so source parts and previous draft evidence remain intact' }]);
+  const config = loadConfig(target.path);
+  const previous = readRigInputs(target.path, args.parts);
+  const draft = draftIndependentNeck({ config, source: readPng(args.source), full: readLayers(args.full), head: readLayers(args.head), base: dirname(target.path), under: readUnders(target.path, config.assemble.cuts ?? []), caps: config.limbs === undefined ? undefined : readCaps(target.path, config.limbs), previous });
+  parseConfig(draft.config);
+  separateConfigWriteTarget(target, [join(args.out, 'proposal.json'), join(output, 'parts.json'), ...draft.assembled.images.flatMap(p => [join(output, 'parts', `${p.record.name}.png`), ...(p.record.depth === undefined ? [] : [join(output, 'parts', p.record.depth.image)])])]);
+  const staged = stageConfigWrite(target, { kind: 'neck-unit', config: draft.config });
+  try {
+    const out = join(args.out, 'rig');
+    mkdirSync(join(out, 'parts'), { recursive: true });
+    writeParts(join(out, 'parts.json'), draft.assembled.parts);
+    for (const p of draft.assembled.images) {
+      writePng(join(out, 'parts', `${p.record.name}.png`), p.image);
+      if (p.depthImage !== undefined && p.record.depth !== undefined) writePng(join(out, 'parts', p.record.depth.image), p.depthImage);
+    }
+    const { bones, meshes, regions, motion, constraints, turn, proposed_rig_scale } = draft.config;
+    writeFileSync(join(args.out, 'proposal.json'), JSON.stringify({ bones, meshes, regions, motion, ...(constraints === undefined ? {} : { constraints }), turn, ...(proposed_rig_scale === undefined ? {} : { proposed_rig_scale }), notes: draft.notes }, null, 2) + '\n');
+    staged.commit();
+    for (const line of configWriteLines(target, staged.changes)) console.error(line);
+    for (const note of draft.notes) console.log(`note: ${note}`);
+    console.log(`wrote proposal.json and reassembled full-run neck pixels under ${out}; config body turn and other authored sections retained; run rig/build through the gate`);
+  } catch (error) { staged.abort(error); }
+  finally { staged.cancel(); }
+}