@rig-c/parts 1.63.0 → 1.65.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/src/config.ts CHANGED
@@ -997,6 +997,8 @@ export interface LimbSegment {
997
997
  cap_shape?: 'disc' | 'ball';
998
998
  /** Issue #360 (item 14): the half-width, whole rig px, of the band about the joint line the cut is placed in (`placeCut` in `src/limbs.ts`). Absent, the cut is the joint line. */
999
999
  cut_band?: number;
1000
+ /** Issue #399: one generated mesh across this joint; width is full axial rig px. */
1001
+ hybrid?: { part: string; width?: number };
1000
1002
  }
1001
1003
 
1002
1004
  /**
@@ -2357,6 +2359,7 @@ function checkAlternates(
2357
2359
  const path = `${at}.layers.${part}`;
2358
2360
  const covered = ('parts' in e ? seenParts : allSlots).has(part) && !seenHides.has(part);
2359
2361
  if (!covered) c.fail('CONFIG_SET_LAYERS', path, `names "${part}", which the set does not cover; name a covered, nonhidden part`);
2362
+ if (limbs?.parts.get(part)?.band !== undefined) c.fail('CONFIG_SET_LAYERS', path, `names generated band "${part}"; select the shared layer through its rigid segment parts, not a separate band layer`);
2360
2363
  if (made.patches.includes(part)) c.fail('CONFIG_SET_LAYERS', path, `names the painting patch "${part}", which has no run layer source; declare a layer-backed plan part instead`);
2361
2364
  if (typeof layer !== 'string' || readLayerTag(layer) === null) c.fail('CONFIG_TAG_KNOWN', path, `is ${show(layer)}; a See-through v3 tag or "${AUTHOR_PREFIX}<label>" is required; ${AUTHOR_LABEL_RULE}`);
2362
2365
  }
@@ -2386,11 +2389,13 @@ function checkAlternates(
2386
2389
  for (const [limbName, chain] of limbs.chains) {
2387
2390
  const coveredSegs = chain.parts.filter((sp) => seenParts.has(sp) && !seenHides.has(sp));
2388
2391
  const hiddenSegs = chain.parts.filter((sp) => seenHides.has(sp));
2389
- if ((coveredSegs.length > 0 || hiddenSegs.length > 0) && coveredSegs.length !== chain.parts.length) {
2392
+ const bands = [...limbs.parts].filter(([, p]) => p.band?.limb === limbName).map(([name]) => name);
2393
+ const selectedBands = bands.filter((n) => seenParts.has(n)), hiddenBands = bands.filter((n) => seenHides.has(n));
2394
+ if ((coveredSegs.length > 0 || hiddenSegs.length > 0 || selectedBands.length > 0 || hiddenBands.length > 0) && (coveredSegs.length !== chain.parts.length || hiddenBands.length > 0)) {
2390
2395
  c.fail(
2391
2396
  'CONFIG_LIMB_SET_JOINTS',
2392
2397
  `${at}.parts`,
2393
- `covers [${coveredSegs.map((s) => `"${s}"`).join(', ')}]${hiddenSegs.length > 0 ? ` (and hides [${hiddenSegs.map((s) => `"${s}"`).join(', ')}])` : ''} of config.limbs.${limbName}, which cuts at the base's joints into [${chain.parts.map((s) => `"${s}"`).join(', ')}]; a gesture set over a limb chain must cover all ${chain.parts.length} of its segment parts so it is cut at the base's joints`,
2398
+ `covers [${coveredSegs.map((s) => `"${s}"`).join(', ')}]${hiddenSegs.length > 0 ? ` (and hides [${hiddenSegs.map((s) => `"${s}"`).join(', ')}])` : ''} of config.limbs.${limbName}, which cuts at the base's joints into [${chain.parts.map((s) => `"${s}"`).join(', ')}]; a gesture set over a limb chain must cover all ${chain.parts.length} of its segment parts so it is cut at the base's joints${hiddenBands.length === 0 ? '' : `; generated bands [${hiddenBands.join(', ')}] cannot be hidden independently`}`,
2394
2399
  );
2395
2400
  } else if (coveredSegs.length === chain.parts.length && !cutsConsumedLimb && 'cuts' in e && Array.isArray(e.cuts) && e.cuts.length > 0) {
2396
2401
  c.fail(
@@ -2409,6 +2414,7 @@ function checkAlternates(
2409
2414
  const limbSeg = limbs?.parts.get(pn);
2410
2415
  if (limbSeg !== undefined) {
2411
2416
  coveredBones.add(limbSeg.bone);
2417
+ if (limbSeg.band !== undefined) coveredBones.add(limbSeg.band.upper);
2412
2418
  } else if (isPlainObject(regions) && typeof rawRegionBone(regions[pn]) === 'string') {
2413
2419
  coveredBones.add(rawRegionBone(regions[pn]) as string);
2414
2420
  } else if (isPlainObject(meshes) && isPlainObject(meshes[pn])) {
@@ -3256,7 +3262,7 @@ function checkRegions(c: Check, v: Json, bones: Set<string>): void {
3256
3262
 
3257
3263
  /** What the loader read off `config.limbs` (issue #349): each limb part with its bone, and each part a limb takes, with the first limb taking it. */
3258
3264
  interface LimbNames {
3259
- parts: Map<string, { bone: string; at: string }>;
3265
+ parts: Map<string, { bone: string; at: string; band?: { limb: string; upper: string } }>;
3260
3266
  consumed: Map<string, string>;
3261
3267
  chains: Map<string, { parts: string[]; bones: string[]; froms: string[] }>;
3262
3268
  /** Issue #664: each segment part a limb's `front.parts` names -> that limb. */
@@ -3336,14 +3342,14 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
3336
3342
  const bones: Array<string | null> = [];
3337
3343
  segs.forEach((entry, i) => {
3338
3344
  const sat = `${at}.segments[${i}]`;
3339
- const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap', 'edge', 'cap_shape', 'cut_band']);
3345
+ const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap', 'edge', 'cap_shape', 'cut_band', 'hybrid']);
3340
3346
  segParts.push(null);
3341
3347
  froms.push(null);
3342
3348
  bones.push(null);
3343
3349
  if (e === null) return;
3344
3350
  // The upper segment sits below no joint; every other sits below one, which it names.
3345
3351
  if (i === 0) {
3346
- for (const k of ['joint', 'range', 'cap', 'edge', 'cap_shape', 'cut_band'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
3352
+ for (const k of ['joint', 'range', 'cap', 'edge', 'cap_shape', 'cut_band', 'hybrid'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
3347
3353
  } else if (!('joint' in e)) c.fail('CONFIG_FIELD_PRESENT', `${sat}.joint`, 'is absent and required; a segment after the first sits below a joint, at its bone\'s origin, and names it');
3348
3354
  if ('part' in e && c.string(`${sat}.part`, e.part)) {
3349
3355
  const name = e.part;
@@ -3357,6 +3363,22 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
3357
3363
  if ('bone' in e && typeof e.bone === 'string') out.parts.set(name, { bone: e.bone, at: `config.limbs.${limb} segment ${i}` });
3358
3364
  }
3359
3365
  }
3366
+ if ('hybrid' in e && i > 0) {
3367
+ const h = c.object(`${sat}.hybrid`, e.hybrid, ['part'], ['width']);
3368
+ if (h !== null) {
3369
+ if (c.string(`${sat}.hybrid.part`, h.part)) {
3370
+ if (!partNameOk(h.part)) c.fail('CONFIG_PART_NAME', `${sat}.hybrid.part`, `is ${show(h.part)}; a part filename is required`);
3371
+ else if (firstAt.has(h.part) || [...made.parts, ...made.patches, ...made.cuts].includes(h.part)) c.fail('CONFIG_PART_UNIQUE', `${sat}.hybrid.part`, `names "${h.part}", already produced; a unique band name is required`);
3372
+ else {
3373
+ firstAt.set(h.part, `${sat}.hybrid`);
3374
+ if (typeof e.bone === 'string' && typeof bones[i - 1] === 'string') out.parts.set(h.part, { bone: e.bone, at: `${sat}.hybrid`, band: { limb, upper: bones[i - 1] as string } });
3375
+ }
3376
+ }
3377
+ if ('width' in h && !(typeof h.width === 'number' && Number.isFinite(h.width) && h.width > 0)) c.fail('CONFIG_FIELD_TYPE', `${sat}.hybrid.width`, `is ${show(h.width)}; finite full axial width above 0 rig px is required`);
3378
+ }
3379
+ for (const field of ['cap', 'cap_shape', 'edge', 'cut_band']) if (field in e) c.fail('CONFIG_HYBRID_CUT', `${sat}.${field}`, 'is declared with hybrid; the band replaces the cut and cap, so remove the cut option');
3380
+ if (e.from !== froms[i - 1]) c.fail('CONFIG_HYBRID_SOURCE', `${sat}.from`, `is ${show(e.from)}; the upper source ${show(froms[i - 1])} is required for one continuous band`);
3381
+ }
3360
3382
  if ('from' in e) {
3361
3383
  if (typeof e.from !== 'string' || !sources.has(e.from)) {
3362
3384
  c.fail('CONFIG_NAME_RESOLVES', `${sat}.from`, `is ${show(e.from)}; a part named in assemble.plan or made by an assemble.cuts entry is required — the layer the segment's pixels are cut from`);
@@ -3545,6 +3567,7 @@ function checkCoverage(c: Check, made: string[], patches: string[], meshes: Json
3545
3567
  }
3546
3568
  }
3547
3569
  for (const [part, seg] of limbs.parts) {
3570
+ if (seg.band !== undefined) continue;
3548
3571
  const bone = isPlainObject(regions) ? rawRegionBone(regions[part]) : undefined;
3549
3572
  if (typeof bone === 'string' && bone !== seg.bone) {
3550
3573
  c.fail('CONFIG_LIMB_BONE', `config.regions.${part}`, `is "${bone}"; "${part}" is ${seg.at}, which rides "${seg.bone}" with weight 1, so config.regions.${part} "${seg.bone}" is required`);
@@ -3558,6 +3581,10 @@ function checkCoverage(c: Check, made: string[], patches: string[], meshes: Json
3558
3581
  for (const part of parts) {
3559
3582
  const inM = m.includes(part);
3560
3583
  const inR = r.includes(part);
3584
+ if (limbs?.parts.get(part)?.band !== undefined) {
3585
+ if (inM || inR) c.fail('CONFIG_PART_ATTACHED', `part "${part}"`, 'is a generated hybrid band; remove its mesh/region entry — the joint supplies its two-carrier attachment');
3586
+ continue;
3587
+ }
3561
3588
  if (!inM && !inR) c.fail('CONFIG_PART_ATTACHED', `part "${part}"`, 'has neither a meshes entry nor a regions entry; exactly one is required');
3562
3589
  if (inM && inR) c.fail('CONFIG_PART_ATTACHED', `part "${part}"`, 'has both a meshes entry and a regions entry; exactly one is required');
3563
3590
  }
package/src/parts.ts CHANGED
@@ -89,6 +89,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
89
89
  import { type Problem, refuseIfAny } from './errors.ts';
90
90
  import { KEYPOINT_NAMES, type PosePoints } from './skeleton.ts';
91
91
  import { readLayerTag } from './tags.ts';
92
+ import { edgeLength } from './length.ts';
92
93
  import { recordedFocusProblems } from './setfocus.ts';
93
94
 
94
95
  export interface PartRecord {
@@ -137,6 +138,19 @@ export interface LimbRecord {
137
138
  joint?: string;
138
139
  range?: [number, number];
139
140
  cap?: CapRecord;
141
+ /** Issue #399: the rigid lower segment references the band instead of a cap. */
142
+ hybrid?: HybridBandRecord & { part: string };
143
+ /** Only the generated band has this role; ordinary segments remain rigid. */
144
+ band?: HybridBandRecord;
145
+ }
146
+
147
+ /** Source-measured joint geometry, in rig pixels, used for the band's axial weights and the unchanged range disc. */
148
+ export interface HybridBandRecord {
149
+ upper: string;
150
+ width: number;
151
+ radius: number;
152
+ at: [number, number];
153
+ axis: [number, number];
140
154
  }
141
155
 
142
156
  /**
@@ -221,7 +235,7 @@ export interface CapRecord {
221
235
  stroke_luma_max?: number;
222
236
  }
223
237
 
224
- const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'range', 'cap'] as const;
238
+ const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'range', 'cap', 'hybrid', 'band'] as const;
225
239
  const CAP_KEYS = [
226
240
  'at',
227
241
  'width',
@@ -257,7 +271,10 @@ const CUT_KEYS = ['cut_offset', 'cut_at', 'cut_crossed', 'joint_crossed', 'band_
257
271
  /** The limb record with its keys in the fixed order, so two runs write the same bytes. */
258
272
  function orderedLimb(l: LimbRecord): Record<string, unknown> {
259
273
  const cap = l.cap === undefined ? undefined : Object.fromEntries(CAP_KEYS.filter((k) => (l.cap as CapRecord)[k] !== undefined).map((k) => [k, (l.cap as CapRecord)[k]]));
260
- return Object.fromEntries(LIMB_KEYS.filter((k) => (k === 'cap' ? cap : l[k]) !== undefined).map((k) => [k, k === 'cap' ? cap : l[k]]));
274
+ const band = (value: HybridBandRecord & { part?: string }): Record<string, unknown> => Object.fromEntries(
275
+ (['part', 'upper', 'width', 'radius', 'at', 'axis'] as const).filter((k) => value[k] !== undefined).map((k) => [k, value[k]]));
276
+ const values = { ...l, cap, ...(l.hybrid === undefined ? {} : { hybrid: band(l.hybrid) }), ...(l.band === undefined ? {} : { band: band(l.band) }) };
277
+ return Object.fromEntries(LIMB_KEYS.filter((k) => values[k] !== undefined).map((k) => [k, values[k]]));
261
278
  }
262
279
 
263
280
  /** One listed hole: its area, its box in rig pixels, and the parts beside it (`src/assemble.ts` `uncoveredHoles`). */
@@ -645,35 +662,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
645
662
  else if (b.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", whose from is ${show(b.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);
646
663
  }
647
664
  }
648
- if (Array.isArray(o.parts)) {
649
- // A limb segment (issue #349) names its limb, its index, the part it was cut from, its bone, and below a joint the joint and its cap.
650
- for (const p of o.parts) {
651
- if (typeof p !== 'object' || p === null || Array.isArray(p) || !(LIMB_KEY in p)) continue;
652
- const r = p as Record<string, unknown>;
653
- const object = `part "${String(r.name)}" field "${LIMB_KEY}"`;
654
- const l = r[LIMB_KEY];
655
- if (typeof l !== 'object' || l === null || Array.isArray(l)) {
656
- fail('PARTS_FIELD_TYPE', object, `is ${show(l)}; an object {name, segment, of, bone, joint?, cap?} is required`);
657
- continue;
658
- }
659
- const q = l as Record<string, unknown>;
660
- for (const k of Object.keys(q)) if (!(LIMB_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${object} key "${k}"`, `is not a limb field; known: ${LIMB_KEYS.join(', ')}`);
661
- for (const k of ['name', 'of', 'bone'] as const) if (!(typeof q[k] === 'string' && q[k] !== '')) fail('PARTS_FIELD_TYPE', `${object} "${k}"`, `is ${show(q[k])}; a non-empty string is required`);
662
- if (!isCount(q.segment)) fail('PARTS_FIELD_TYPE', `${object} "segment"`, `is ${show(q.segment)}; the segment's index, a non-negative integer, is required`);
663
- const below = isCount(q.segment) && q.segment > 0;
664
- if (below !== ('joint' in q) || below !== ('cap' in q)) fail('PARTS_FIELD_PRESENT', object, `segment ${show(q.segment)} with${'joint' in q ? '' : 'out'} a joint and with${'cap' in q ? '' : 'out'} a cap; a segment below a joint (index above 0) has both, the upper segment neither`);
665
- if ('joint' in q && !(typeof q.joint === 'string' && q.joint !== '')) fail('PARTS_FIELD_TYPE', `${object} "joint"`, `is ${show(q.joint)}; the joint's name is required`);
666
- // Issue #360: a declared range rides below a joint only, and holds the loader's rule — two degrees, rest in it.
667
- if ('range' in q) {
668
- const r = q.range;
669
- if (!below) fail('PARTS_FIELD_PRESENT', `${object} "range"`, `is on segment ${show(q.segment)}; a range is the bend of a joint, so only a segment below one (index above 0) carries it`);
670
- else if (!(Array.isArray(r) && r.length === 2 && r.every((n) => typeof n === 'number' && Number.isFinite(n)) && (r[0] as number) <= 0 && 0 <= (r[1] as number))) {
671
- fail('PARTS_FIELD_TYPE', `${object} "range"`, `is ${show(r)}; [min, max], two finite degrees from rest with min <= 0 <= max, is required — config.limbs' rule (CONFIG_LIMB_RANGE)`);
672
- }
673
- }
674
- if ('cap' in q) checkCap(q.cap, `${object} "cap"`, fail);
675
- }
676
- }
665
+ if (Array.isArray(o.parts)) checkLimbRecords(o.parts, '', fail);
677
666
  if ('scene' in o) {
678
667
  const sc = o.scene;
679
668
  if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);
@@ -734,6 +723,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
734
723
  }
735
724
  }
736
725
  if (!Array.isArray(set.records)) return;
726
+ if (set.records.some((p) => typeof p === 'object' && p !== null && !Array.isArray(p) && typeof p.limb === 'object' && p.limb !== null && ('hybrid' in p.limb || 'band' in p.limb))) checkLimbRecords(set.records, `${at} `, fail, false);
737
727
  set.records.forEach((p, j) => {
738
728
  if (typeof p !== 'object' || p === null || Array.isArray(p)) return;
739
729
  const r = p as Record<string, unknown>;
@@ -748,6 +738,74 @@ function checkParts(raw: unknown, path: string): PartsFile {
748
738
  return raw as PartsFile;
749
739
  }
750
740
 
741
+ /** Same opt-in provenance rules on the base and a set; caps are already checked by the legacy set reader. */
742
+ function checkLimbRecords(recordsRaw: unknown[], prefix: string, fail: (code: string, object: string, detail: string) => void, caps = true): void {
743
+ {
744
+ // A limb segment (issue #349) names its limb, its index, the part it was cut from, its bone, and below a joint the joint and its cap.
745
+ for (const p of recordsRaw) {
746
+ if (typeof p !== 'object' || p === null || Array.isArray(p) || !(LIMB_KEY in p)) continue;
747
+ const r = p as Record<string, unknown>;
748
+ const object = `${prefix}part "${String(r.name)}" field "${LIMB_KEY}"`;
749
+ const l = r[LIMB_KEY];
750
+ if (typeof l !== 'object' || l === null || Array.isArray(l)) {
751
+ fail('PARTS_FIELD_TYPE', object, `is ${show(l)}; an object {name, segment, of, bone, joint?, cap?} is required`);
752
+ continue;
753
+ }
754
+ const q = l as Record<string, unknown>;
755
+ for (const k of Object.keys(q)) if (!(LIMB_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${object} key "${k}"`, `is not a limb field; known: ${LIMB_KEYS.join(', ')}`);
756
+ for (const k of ['name', 'of', 'bone'] as const) if (!(typeof q[k] === 'string' && q[k] !== '')) fail('PARTS_FIELD_TYPE', `${object} "${k}"`, `is ${show(q[k])}; a non-empty string is required`);
757
+ if (!isCount(q.segment)) fail('PARTS_FIELD_TYPE', `${object} "segment"`, `is ${show(q.segment)}; the segment's index, a non-negative integer, is required`);
758
+ const below = isCount(q.segment) && q.segment > 0;
759
+ if (below !== ('joint' in q) || below !== ('cap' in q || 'hybrid' in q || 'band' in q) || ['cap', 'hybrid', 'band'].filter((k) => k in q).length > 1) fail('PARTS_FIELD_PRESENT', object, `segment ${show(q.segment)} with${'joint' in q ? '' : 'out'} a joint and with${'cap' in q ? '' : 'out'} a cap; a segment below a joint requires its joint and exactly one of cap, hybrid, or band; the upper segment has neither`);
760
+ if ('joint' in q && !(typeof q.joint === 'string' && q.joint !== '')) fail('PARTS_FIELD_TYPE', `${object} "joint"`, `is ${show(q.joint)}; the joint's name is required`);
761
+ // Issue #360: a declared range rides below a joint only, and holds the loader's rule — two degrees, rest in it.
762
+ if ('range' in q) {
763
+ const r = q.range;
764
+ if (!below) fail('PARTS_FIELD_PRESENT', `${object} "range"`, `is on segment ${show(q.segment)}; a range is the bend of a joint, so only a segment below one (index above 0) carries it`);
765
+ else if (!(Array.isArray(r) && r.length === 2 && r.every((n) => typeof n === 'number' && Number.isFinite(n)) && (r[0] as number) <= 0 && 0 <= (r[1] as number))) {
766
+ fail('PARTS_FIELD_TYPE', `${object} "range"`, `is ${show(r)}; [min, max], two finite degrees from rest with min <= 0 <= max, is required — config.limbs' rule (CONFIG_LIMB_RANGE)`);
767
+ }
768
+ }
769
+ for (const field of ['hybrid', 'band']) if (field in q) {
770
+ const h = q[field];
771
+ if (!below || typeof h !== 'object' || h === null || Array.isArray(h)) fail('PARTS_FIELD_TYPE', `${object} ${field}`, 'a band below a joint with {upper, width, at, axis} is required');
772
+ else {
773
+ const b = h as Record<string, unknown>;
774
+ const pair = (v: unknown): v is number[] => Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && Number.isFinite(n));
775
+ if (Object.keys(b).sort().join(',') !== (field === 'hybrid' ? 'at,axis,part,radius,upper,width' : 'at,axis,radius,upper,width') || (field === 'hybrid' && (typeof b.part !== 'string' || b.part === '')) || !(typeof b.radius === 'number' && Number.isFinite(b.radius) && b.radius > 0) || typeof b.upper !== 'string' || b.upper === '' || b.upper === q.bone || !(typeof b.width === 'number' && Number.isFinite(b.width) && b.width > 0) || !pair(b.at) || !pair(b.axis) || Math.abs(edgeLength(b.axis[0], b.axis[1]) - 1) > 1e-6 || (field === 'band' && 'range' in q)) fail('PARTS_FIELD_TYPE', `${object} ${field}`, `is ${show(h)}; distinct upper carrier, positive width, finite at, unit axis and no duplicate range are required`);
776
+ }
777
+ }
778
+ if (caps && 'cap' in q) checkCap(q.cap, `${object} "cap"`, fail);
779
+ }
780
+ }
781
+ {
782
+ const records = recordsRaw.filter((p): p is Record<string, unknown> => typeof p === 'object' && p !== null && !Array.isArray(p));
783
+ for (const r of records) {
784
+ const limb = r.limb;
785
+ if (typeof limb !== 'object' || limb === null || Array.isArray(limb)) continue;
786
+ const l = limb as Record<string, unknown>, h = l.hybrid;
787
+ if (typeof l.band === 'object' && l.band !== null && !Array.isArray(l.band)) {
788
+ const referring = records.filter((q) => {
789
+ const ql = q.limb;
790
+ if (typeof ql !== 'object' || ql === null || Array.isArray(ql)) return false;
791
+ const qh = (ql as Record<string, unknown>).hybrid;
792
+ return typeof qh === 'object' && qh !== null && !Array.isArray(qh) && (qh as Record<string, unknown>).part === r.name;
793
+ });
794
+ if (referring.length !== 1) fail('PARTS_HYBRID_PAIR', `${prefix}band "${String(r.name)}"`, `has ${referring.length} referring joints; exactly one matching rigid joint record is required — re-run assemble`);
795
+ }
796
+ if (typeof h !== 'object' || h === null || Array.isArray(h)) continue;
797
+ const joint = h as Record<string, unknown>;
798
+ const target = records.find((q) => q.name === joint.part);
799
+ const record = (v: unknown): Record<string, unknown> | undefined => typeof v === 'object' && v !== null && !Array.isArray(v) ? v as Record<string, unknown> : undefined;
800
+ const bl = record(target?.limb);
801
+ const b = record(bl?.band);
802
+ const same = b !== undefined && ['upper', 'width', 'radius', 'at', 'axis'].every((k) => JSON.stringify(b[k]) === JSON.stringify(joint[k]));
803
+ if (bl === undefined || bl.name !== l.name || bl.segment !== l.segment || bl.bone !== l.bone || bl.of !== l.of || bl.joint !== l.joint || !same) fail('PARTS_HYBRID_PAIR', `${prefix}part "${String(r.name)}" hybrid "${String(joint.part)}"`, 'requires its matching band on the same source, joint, carriers and measured geometry');
804
+ }
805
+ }
806
+
807
+ }
808
+
751
809
  const isCount = (v: unknown): v is number => Number.isInteger(v) && (v as number) >= 0;
752
810
 
753
811
  /**
package/src/rig.ts CHANGED
@@ -175,7 +175,7 @@ import { coalesceLimbSlots } from './limbslots.ts';
175
175
  import { layoutAlias, placeLimbLayouts, type LayoutPlan } from './limblayout.ts';
176
176
  import { artCoverage, ART_ALPHA, latticeCells, latticeMesh, latticeStray, ONE_LOOP_PASSES } from './mesh.ts';
177
177
  import { bindFaceSurfaceDeform, BLINK, blinkHoldMisses, blinkSpan, CONTROL_SUFFIX, controlledBones, IDLE_FPS, idleMotion, type MotionSpec, moveKeysToControls } from './motion.ts';
178
- import { type AlternateSetMap, FRONT_SUFFIX, PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
178
+ import { type PartRecord, type AlternateSetMap, FRONT_SUFFIX, PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
179
179
  import { readTag } from './tags.ts';
180
180
  import { EYE_GROUP_TAGS } from './propose.ts';
181
181
  import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
@@ -1243,6 +1243,15 @@ function pt(p: Point): string {
1243
1243
  * automatic part's reduction, `runReduction` unless a caller hands one that
1244
1244
  * reuses a reduction it already ran on the same input (issue #135).
1245
1245
  */
1246
+ /** Issue #399: source-axis shares, used by base and alternate band attachments alike. */
1247
+ function limbBandShares(p: PartRecord, point: Point): Influence[] | null {
1248
+ const h = p.limb?.band;
1249
+ if (h === undefined) return null;
1250
+ const axial = (point[0] - h.at[0]) * h.axis[0] + (point[1] - h.at[1]) * h.axis[1];
1251
+ const lower = Math.max(0, Math.min(1, axial / h.width + 0.5));
1252
+ return [{ bone: h.upper, weight: 1 - lower }, { bone: (p.limb as NonNullable<typeof p.limb>).bone, weight: lower }].filter((q) => q.weight > 0);
1253
+ }
1254
+
1246
1255
  export function buildRig(
1247
1256
  cfg: CharacterConfig,
1248
1257
  parts: PartsFile,
@@ -1251,10 +1260,28 @@ export function buildRig(
1251
1260
  idleKeys: IdleKeys = DEFAULT_IDLE_KEYS,
1252
1261
  reduce: Reducer = runReduction,
1253
1262
  ): RigOutput {
1263
+ // Generated bands have a fixed one-pixel lattice, with their axial weights
1264
+ // below; config never supplies a second mesh policy for the same source.
1265
+ const bands = parts.parts.filter((p) => p.limb?.band !== undefined);
1266
+ if (bands.length > 0) cfg = { ...cfg, meshes: { ...cfg.meshes, ...Object.fromEntries(bands.map((p) => [p.name, { segments: [(p.limb as NonNullable<typeof p.limb>).band?.upper as string, (p.limb as NonNullable<typeof p.limb>).bone], grid: 1, r: 1 }])) } };
1254
1267
  const problems: Problem[] = [];
1255
1268
  const fail = (code: string, object: string, detail: string): void => {
1256
1269
  problems.push({ code, object, detail });
1257
1270
  };
1271
+ for (const [name, limb] of Object.entries(cfg.limbs ?? {})) limb.segments.forEach((sg, k) => {
1272
+ if (sg.hybrid === undefined) return;
1273
+ const band = parts.parts.find((p) => p.name === sg.hybrid?.part);
1274
+ const joint = parts.parts.find((p) => p.name === sg.part);
1275
+ if (band?.limb?.band === undefined || joint?.limb?.hybrid?.part !== sg.hybrid.part) fail('RIG_HYBRID_SOURCE', `config.limbs.${name}.segments[${k}].hybrid`, `declares band "${sg.hybrid.part}" for "${sg.part}"; assembled band is ${band?.limb?.band === undefined ? 'absent' : 'present'}, joint reference is ${JSON.stringify(joint?.limb?.hybrid?.part ?? null)} — re-run assemble before rig`);
1276
+ });
1277
+ for (const p of bands) {
1278
+ const b = p.limb as NonNullable<typeof p.limb>, h = b.band as NonNullable<typeof b.band>;
1279
+ const segments = cfg.limbs?.[b.name]?.segments;
1280
+ const declared = segments?.[b.segment];
1281
+ if (declared?.hybrid?.part !== p.name || declared.bone !== b.bone || segments?.[b.segment - 1]?.bone !== h.upper || (declared.hybrid.width !== undefined && declared.hybrid.width !== h.width)) fail('RIG_HYBRID_SOURCE', `part "${p.name}"`, 'does not match its declared hybrid joint and two carriers; re-run assemble with the current config');
1282
+ for (const sg of [segments?.[b.segment - 1], declared]) if (sg !== undefined && (!(sg.part in cfg.regions) || sg.part in cfg.meshes)) fail('RIG_HYBRID_RIGID', `part "${sg.part}"`, 'is beside a hybrid band; a rigid region on its own carrier is required');
1283
+ }
1284
+ refuseIfAny(problems);
1258
1285
  const [W, H] = parts.rig_size;
1259
1286
  const CX = W / 2;
1260
1287
  const byPart = new Map(parts.parts.map((p) => [p.name, p]));
@@ -2404,14 +2431,15 @@ export function buildRig(
2404
2431
  const wx = vx0 + ox;
2405
2432
  const wy = vy0 + oy;
2406
2433
  const vSegs = segsAt(wy);
2407
- const shares = heat === null ? influences([wx, wy], vSegs, mesh.r, limits, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], limits);
2434
+ const hybrid = limbBandShares(p, [wx, wy]);
2435
+ const shares = hybrid ?? (heat === null ? influences([wx, wy], vSegs, mesh.r, limits, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], limits));
2408
2436
  if (shares.length === 0) {
2409
2437
  // issue #284: a declared cut that keeps no bone (nothingKeptProblem says when that can be).
2410
2438
  if (emptied === null) emptied = { vertex: vi, at: [wx, wy], capped: heat === null ? influences([wx, wy], vSegs, mesh.r, { maxInfluences: limits.maxInfluences, minWeight: 0 }, mesh.exponent ?? DISTANCE_EXPONENT) : heatInfluences(heat, [vx0, vy0], { maxInfluences: limits.maxInfluences, minWeight: 0 }) };
2411
2439
  else emptiedMore++;
2412
2440
  continue;
2413
2441
  }
2414
- rawShares.push(limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
2442
+ rawShares.push(hybrid !== null || limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
2415
2443
  }
2416
2444
  if (emptied !== null) {
2417
2445
  problems.push(nothingKeptProblem(p.name, limits.floor, emptied, emptiedMore));
@@ -2691,11 +2719,12 @@ export function buildRig(
2691
2719
  const wx = vx0 + ox;
2692
2720
  const wy = vy0 + oy;
2693
2721
  const vSegs = segsAt(wy);
2694
- let shares = influences([wx, wy], vSegs, r, limits, exponent);
2722
+ const hybrid = limbBandShares(p, [wx, wy]);
2723
+ let shares = hybrid ?? influences([wx, wy], vSegs, r, limits, exponent);
2695
2724
  if (shares.length === 0) {
2696
2725
  shares = influences([wx, wy], vSegs, Infinity, { maxInfluences: 1, minWeight: 0 }, exponent);
2697
2726
  }
2698
- rawShares.push(limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
2727
+ rawShares.push(hybrid !== null || limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
2699
2728
  }
2700
2729
  if (touchesArt !== null) {
2701
2730
  let firstArtBone: string | null = null;
@@ -2774,6 +2803,35 @@ export function buildRig(
2774
2803
  // from the drawn link `<link>_d` above it, and slots and weights on a stopped link bind `<link>_d`.
2775
2804
  const rebound = frontSlots.length === 0 ? slots : [...slots, ...frontSlots];
2776
2805
  const stops = cfg.stops === undefined ? null : applyStops(cfg.stops, chains, bones, rebound, skin, (original, emitted) => layoutAlias(explicitLayout.plan, original, emitted));
2806
+ for (const [part, mesh] of Object.entries(cfg.meshes)) if ('explicit' in mesh) {
2807
+ const defaultBone = typeof mesh.segments[0] === 'string' ? mesh.segments[0] : mesh.segments[0][0];
2808
+ if (mesh.explicit.islands !== undefined) {
2809
+ mesh.explicit.islands.forEach((isl, i) => {
2810
+ const att = skin[isl.slot]?.[isl.slot];
2811
+ const slotEntry = slots.find((s) => s.name === isl.slot);
2812
+ const expectedBone = isl.bone ?? defaultBone;
2813
+ const weightsChanged =
2814
+ att !== undefined &&
2815
+ 'type' in att &&
2816
+ JSON.stringify(att.weights) !== JSON.stringify(isl.weights.map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight }))));
2817
+ const boneChanged = slotEntry !== undefined && slotEntry.bone !== expectedBone;
2818
+ if (weightsChanged || boneChanged) {
2819
+ fail('RIG_EXPLICIT_BINDING', `config.meshes.${part}.explicit.islands[${i}].weights`, 'the declared stops would change these accepted bindings; supply the accepted final emitted bone names and bind coordinates, or use a generated mesh; no payload is normalized');
2820
+ }
2821
+ });
2822
+ continue;
2823
+ }
2824
+ const att = skin[part]?.[part];
2825
+ const slotEntry = slots.find((s) => s.name === part);
2826
+ const weightsChanged =
2827
+ att !== undefined &&
2828
+ 'type' in att &&
2829
+ JSON.stringify(att.weights) !== JSON.stringify((mesh.explicit.weights ?? []).map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight }))));
2830
+ const boneChanged = slotEntry !== undefined && slotEntry.bone !== defaultBone;
2831
+ if (weightsChanged || boneChanged) {
2832
+ fail('RIG_EXPLICIT_BINDING', `config.meshes.${part}.explicit.weights`, 'the declared stops would change these accepted bindings; supply the accepted final emitted bone names and bind coordinates, or use a generated mesh; no payload is normalized');
2833
+ }
2834
+ }
2777
2835
  // ---- the turn control (issue #251) -------------------------------------
2778
2836
  // Only when the config has `turn`: every other build adds nothing here, so no byte moves.
2779
2837
  if (cfg.turn !== undefined) refuseIfAny(turnRiderProblems(cfg.turn, cfg, parts.parts));
@@ -2795,30 +2853,6 @@ export function buildRig(
2795
2853
  const att = skin[row.part]?.[row.part];
2796
2854
  if (att !== undefined && 'type' in att) row.bones = meshBoundBones(att);
2797
2855
  }
2798
-
2799
- for (const [part, mesh] of Object.entries(cfg.meshes)) if ('explicit' in mesh) {
2800
- const defaultBone = typeof mesh.segments[0] === 'string' ? mesh.segments[0] : mesh.segments[0][0];
2801
- if (mesh.explicit.islands !== undefined) {
2802
- mesh.explicit.islands.forEach((isl, i) => {
2803
- const att = skin[isl.slot]?.[isl.slot];
2804
- const slotEntry = slots.find((s) => s.name === isl.slot);
2805
- const expectedBone = isl.bone ?? defaultBone;
2806
- const weightsChanged =
2807
- att !== undefined &&
2808
- 'type' in att &&
2809
- JSON.stringify(att.weights) !== JSON.stringify(isl.weights.map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight }))));
2810
- const boneChanged = slotEntry !== undefined && slotEntry.bone !== expectedBone;
2811
- if (weightsChanged || boneChanged) {
2812
- fail('RIG_EXPLICIT_BINDING', `config.meshes.${part}.explicit.islands[${i}].weights`, 'the declared stops or turn would change these accepted bindings; supply the accepted final emitted bone names and bind coordinates, or use a generated mesh; no payload is normalized');
2813
- }
2814
- });
2815
- continue;
2816
- }
2817
- const att = skin[part]?.[part];
2818
- if (att !== undefined && 'type' in att && JSON.stringify(att.weights) !== JSON.stringify((mesh.explicit.weights ?? []).map(row => row.map(w => ({ bone: w.bone, x: w.x, y: w.y, weight: w.weight }))))) {
2819
- fail('RIG_EXPLICIT_BINDING', `config.meshes.${part}.explicit.weights`, 'the declared stops or turn would change these accepted bindings; supply the accepted final emitted bone names and bind coordinates, or use a generated mesh; no payload is normalized');
2820
- }
2821
- }
2822
2856
  refuseIfAny(problems);
2823
2857
  const name = `${cfg.key}_painting`;
2824
2858
  const rig: RigSpec = {