@hatiolab/figure-model 0.1.55 → 0.1.57

package/dist/v3-authoring-actions.js

@@ -25,12 +25,18 @@ import { compileV3Asset } from "./v3-asset.js";
 import { compileV3Graph } from "./v3-graph.js";
 import { V3ContractError } from "./v3-contract.js";
 import { AXES } from "./types.js";
-import { foldInstanceSizeRange, v3InstanceSizeLimitsOf, V3_INSTANCE_SIZE_INPUTS } from "./v3-instance-size.js";
+import { foldInstanceSizeRange, v3InstanceSizeLimitsOf, V3_INSTANCE_SIZE_DEFAULT, V3_INSTANCE_SIZE_INPUTS } from "./v3-instance-size.js";
 const fail = (code, path, message) => {
     throw new V3ContractError(code, path, message);
 };
 /** The six faces of a box-shaped part, and the axis each one faces along. */
 export const V3_FACES = { left: 'x', right: 'x', bottom: 'y', top: 'y', back: 'z', front: 'z' };
+/**
+ * UsdPhysics's joint types (ADR-0093, amended 2026-09-25: the joint follows USD). A `fixed` joint is a fastening; a
+ * `revolute` joint turns -- with no limits it turns without end, its value a phase (-180..180), as USD's revolute
+ * joint without limits does; a `prismatic` joint slides.
+ */
+export const V3_JOINT_TYPES = ['fixed', 'revolute', 'prismatic'];
 const SIGN = { left: -1, right: 1, bottom: -1, top: 1, back: -1, front: 1 };
 const OPPOSITE = { left: 'right', right: 'left', bottom: 'top', top: 'bottom', back: 'front', front: 'back' };
 const clone = (asset) => structuredClone(asset);
@@ -74,12 +80,48 @@ function angleOf(m, asset, ref) {
         return asset.designInputs[ref] ?? null;
     return null;
 }
+/** The turn in a part's pose, in degrees about X, Y and Z, or null for an axis whose turn is neither a number nor a design value. */
+function turnOf(m, asset, id, path) {
+    return partOf(m, id, path).pose.args.slice(3, 6).map((ref) => angleOf(m, asset, ref));
+}
+const saidTurn = (turn) => AXES.map((a, i) => `${a.toUpperCase()} ${turn[i] ?? '?'}°`).join(', ');
 /** A part with no turn in its pose: a face of a turned body is not the plane this command assumes. */
 function requireUnturned(m, asset, id, path) {
-    const { pose } = partOf(m, id, path);
-    for (const ref of pose.args.slice(3, 6))
-        if (angleOf(m, asset, ref) !== 0)
-            fail('EDIT_TARGET', path, `${id} is turned; fastening a turned part by its faces is not covered by this command`);
+    const turn = turnOf(m, asset, id, path);
+    if (turn.some(t => t !== 0))
+        fail('EDIT_TARGET', path, `${id} is turned (${saidTurn(turn)}); fastening to a turned part by its faces is not covered by this command`);
+}
+/**
+ * The part's size along each axis as it stands in its seat -- after its own turn. A turn by a whole number of
+ * quarter turns only swaps the axes (a cylinder laid on its side is 2r tall and its length deep), so its faces are
+ * still axis-aligned planes; any other turn is refused, and says the angle. The turn is then fixed as it is: a part
+ * fastened by its faces keeps the turn its faces were measured in (chief architect's ruling 2026-09-25).
+ */
+function standingRefsOf(m, asset, id, path, freeze = true) {
+    const own = sizeRefsOf(m, id, path);
+    const turn = turnOf(m, asset, id, path);
+    if (turn.every(t => t === 0))
+        return own;
+    if (turn.some(t => t === null || !Number.isFinite(t) || Math.abs(t / 90 - Math.round(t / 90)) > 1e-9))
+        fail('EDIT_TARGET', path, `${id} is turned (${saidTurn(turn)}); only quarter turns keep its faces level with the axes`);
+    const [rx, ry, rz] = turn.map(t => (t * Math.PI) / 180);
+    const cos = (a) => Math.round(Math.cos(a)), sin = (a) => Math.round(Math.sin(a));
+    const X = [[1, 0, 0], [0, cos(rx), -sin(rx)], [0, sin(rx), cos(rx)]];
+    const Y = [[cos(ry), 0, sin(ry)], [0, 1, 0], [-sin(ry), 0, cos(ry)]];
+    const Z = [[cos(rz), -sin(rz), 0], [sin(rz), cos(rz), 0], [0, 0, 1]];
+    const mul = (a, b) => a.map(row => b[0].map((_, j) => row.reduce((sum, v, k) => sum + v * b[k][j], 0)));
+    const r = mul(mul(X, Y), Z); // the order `rigid@1` turns in
+    if (freeze) {
+        const pose = partOf(m, id, path).pose;
+        const old = pose.args.slice(3, 6);
+        pose.args = [...pose.args.slice(0, 3), ...turn.map(t => constantOf(m, 'deg', t, 'a'))];
+        // Its turn fields go with it: typing into them would change nothing.
+        for (const ref of old)
+            dropIfUnused(asset, ref, ownInput(m, id, ref) ? ref : undefined);
+    }
+    const standing = {};
+    AXES.forEach((axis, i) => (standing[axis] = own[AXES[r[i].findIndex(v => v !== 0)]]));
+    return standing;
 }
 /** Fresh node ids under a part, so two commands never claim one id. */
 function namer(m, prefix) {
@@ -228,6 +270,9 @@ function linkDimension(asset, a) {
     const was = node.args[0];
     const owned = ownInput(m, a.part, was) ? was : `${a.part}.size.${a.axis}`;
     node.args = [value, node.args[1]];
+    // Joints read this part's size; made again from their records, they read the size as it now is.
+    if (asset.joints?.length)
+        rewriteJoints(asset);
     // The part's own control is no longer read by anything; leaving it would show a dial that changes nothing.
     dropIfUnused(asset, was, owned);
     return asset;
@@ -258,6 +303,8 @@ function unlinkDimension(asset, a) {
     const node = nodeById(m, `${a.part}.dimension.${a.axis}`);
     const was = node.args[0];
     node.args = [id, node.args[1]];
+    if (asset.joints?.length)
+        rewriteJoints(asset);
     dropIfUnused(asset, was);
     return asset;
 }
@@ -293,8 +340,8 @@ function dropIfUnused(asset, ref, ownedInput) {
 function parentOf(m, id) {
     if (!nodeById(m, `${id}.chain`))
         return null;
-    // The seat's own frame leads either to a motion node or, when the part does not move, to an identity rigid.
-    const above = nodeById(m, `${id}.motion`) ?? nodeById(m, `${id}.seat.rigid`);
+    // The seat rigid carries the part into the frame it is fastened to, moving or not (an old asset may have only a motion).
+    const above = nodeById(m, `${id}.seat.rigid`) ?? nodeById(m, `${id}.motion`);
     const match = /^(.*)\.local$/.exec(String(above?.params?.to));
     return match && match[1] !== id ? match[1] : null;
 }
@@ -327,10 +374,9 @@ function attach(asset, a) {
     for (let up = to.part; up; up = parentOf(m, up))
         if (up === a.part)
             fail('ATTACH_CYCLE', path, `${to.part} already hangs from ${a.part}`);
-    const mine = sizeRefsOf(m, a.part, path);
     const theirs = sizeRefsOf(m, to.part, path);
-    requireUnturned(m, asset, a.part, path);
     requireUnturned(m, asset, to.part, path);
+    const mine = standingRefsOf(m, asset, a.part, path);
     const name = namer(m, `${a.part}.on.${to.part}`);
     const sign = SIGN[to.face];
     /*
@@ -339,13 +385,21 @@ function attach(asset, a) {
     */
     const outward = facing === 'meet' ? sign : -sign;
     const gap = measureRef(m, asset, name, a.gap, `gap.${axis}`, path);
+    /*
+      Split at the point fastened at: the seat is on the target's face (its centre, or level with an edge), the part's
+      centre is half its own depth and the gap past it. A turn added later turns about that point.
+    */
+    const zero = constantOf(m, 'mm', 0, 'd');
     const translation = { x: '', y: '', z: '' };
-    translation[axis] = sumOf(m, name, [
-        { ref: theirs[axis].ref, k: sign * 0.5 * theirs[axis].k },
-        { ref: mine[axis].ref, k: outward * 0.5 * mine[axis].k },
-        { ref: gap, k: outward }
-    ], `along.${axis}`);
-    // Across the face. Centred by default; min and max keep the two parts' edges level as either is resized.
+    const offset = { x: zero, y: zero, z: zero };
+    translation[axis] = sumOf(m, name, [{ ref: theirs[axis].ref, k: sign * 0.5 * theirs[axis].k }], `seat.${axis}`);
+    offset[axis] = sumOf(m, name, [{ ref: mine[axis].ref, k: outward * 0.5 * mine[axis].k }, { ref: gap, k: outward }], `along.${axis}`);
+    /*
+      Across the face. Centred by default; min and max keep the two parts' edges level as either is resized -- and the
+      point fastened at is where those edges meet: the seat on the target's edge, the part's own edge on it. A door
+      fastened level with the frame's min edge turns about that edge, as a hinge does (2026-09-25); centred, the point
+      is the middle of the face.
+    */
     for (const other of AXES.filter(x => x !== axis)) {
         const how = a.align?.[other] ?? 'centre';
         if (how === 'centre')
@@ -354,12 +408,13 @@ function attach(asset, a) {
             translation[other] = measureRef(m, asset, name, how.mm, `align.${other}`, path);
         else if (how === 'min' || how === 'max') {
             const s = how === 'min' ? -1 : 1;
-            translation[other] = sumOf(m, name, [{ ref: theirs[other].ref, k: s * 0.5 * theirs[other].k }, { ref: mine[other].ref, k: -s * 0.5 * mine[other].k }], `align.${other}`);
+            translation[other] = sumOf(m, name, [{ ref: theirs[other].ref, k: s * 0.5 * theirs[other].k }], `edge.${other}`);
+            offset[other] = sumOf(m, name, [{ ref: mine[other].ref, k: -s * 0.5 * mine[other].k }], `own-edge.${other}`);
         }
         else
             fail('SCHEMA', path, `${String(how)} is not an alignment`);
     }
-    reseat(asset, a.part, `${to.part}.local`, [translation.x, translation.y, translation.z]);
+    reseat(asset, a.part, `${to.part}.local`, { seat: [translation.x, translation.y, translation.z], pose: [offset.x, offset.y, offset.z] });
     return asset;
 }
 /**
@@ -377,8 +432,7 @@ function standOnPlane(asset, a, path) {
         fail('ATTACH_FACE', path, `${String(a.face)} faces along ${V3_FACES[a.face] ?? '?'}; the plane faces along y, so a part stands on it by its bottom or hangs from it by its top`);
     if (parentOf(m, a.part) && !a.replace)
         fail('ATTACH_REPLACED', path, `${a.part} is already fastened to ${parentOf(m, a.part)}; pass replace to stand it on the plane instead`);
-    const mine = sizeRefsOf(m, a.part, path);
-    requireUnturned(m, asset, a.part, path);
+    const mine = standingRefsOf(m, asset, a.part, path);
     const name = namer(m, `${a.part}.on.plane`);
     const outward = a.face === 'bottom' ? 1 : -1;
     const gap = measureRef(m, asset, name, a.gap, 'gap.y', path);
@@ -393,7 +447,9 @@ function standOnPlane(asset, a, path) {
         else
             fail('SCHEMA', path, `the plane has no edges to line ${a.part} up with on ${other}; give the centre or a measured offset`);
     }
-    reseat(asset, a.part, asset.document.capabilities.assetFrame, [translation.x, translation.y, translation.z]);
+    // The point it stands on is on the plane, under its centre: a turn about Y turns it where it stands.
+    const zero = constantOf(m, 'mm', 0, 'd');
+    reseat(asset, a.part, asset.document.capabilities.assetFrame, { seat: [translation.x, zero, translation.z], pose: [zero, translation.y, zero] });
     return asset;
 }
 function detach(asset, a) {
@@ -434,8 +490,15 @@ function detach(asset, a) {
       The part gets its own position numbers back, as a part made in the modeller has them, so it can be moved again
       by hand or by the gizmo. Where one of those names is taken, that axis stays a plain number.
     */
+    /*
+      A part that moves keeps turning about the point it was fastened at: that point becomes its seat in the asset, its
+      own numbers the offset from it. A part that does not move gets its place back as plain position numbers.
+    */
+    const seatAt = evaluated.values?.[`${a.part}.seat.value`]?.t ?? [0, 0, 0];
+    const moving = !!nodeById(m, `${a.part}.motion`);
+    const pivot = AXES.map((_, i) => round6(above.t[i] + seatAt[i]));
     const translation = AXES.map((axis, i) => {
-        const value = round6(above.t[i] + own.t[i]);
+        const value = moving ? round6(own.t[i]) : round6(pivot[i] + own.t[i]);
         const id = `${a.part}.position.${axis}`;
         if (m.inputs.some((input) => input.id === id) || m.nodes.some((n) => Object.values(n.outputs).includes(id)))
             return constantOf(m, 'mm', value, 'd');
@@ -443,7 +506,8 @@ function detach(asset, a) {
         asset.designInputs[id] = value;
         return id;
     });
-    reseat(asset, a.part, asset.document.capabilities.assetFrame, translation);
+    const seat = AXES.map((_, i) => constantOf(m, 'mm', moving ? pivot[i] : 0, 'd'));
+    reseat(asset, a.part, asset.document.capabilities.assetFrame, { seat, pose: translation });
     return asset;
 }
 const round6 = (v) => Math.round(v * 1e6) / 1e6;
@@ -451,36 +515,55 @@ const round6 = (v) => Math.round(v * 1e6) / 1e6;
  * Put a part's pose on a new frame with a new translation, and rebuild the chain that carries it to the asset.
  * The part's own id, its shape and its `placed` reference all stay as they were.
  */
-function reseat(asset, id, to, translation) {
+/**
+ * Where a part is fastened, in two translations that are never merged: `seat` is the point it is fastened at, in the
+ * frame it is fastened to -- a point on the target's face; `pose` is the part's centre from that point, in its own
+ * seat frame. A motion sits between the two, so a turn turns about the point the part is fastened at: a hinge, a
+ * joint, a lid (chief architect's ruling 2026-09-25; before this the seat was the target's centre and a fastened
+ * part swung about the middle of what it was fastened to).
+ *
+ *     <id>.local --pose--> <id>.seat [--motion--> <id>.joint] --seat.rigid--> <to>
+ *
+ * Without `place` the part keeps both translations and only its frames are rewired (a motion added or taken away).
+ */
+function reseat(asset, id, to, place) {
     const m = asset.document.model;
-    const { place, pose } = partOf(m, id, id);
-    const old = translation ? pose.args.slice(0, 3) : [];
-    if (translation)
-        pose.args = [...translation, ...pose.args.slice(3)];
+    const { place: placed, pose } = partOf(m, id, id);
+    const old = place ? pose.args.slice(0, 3) : [];
+    if (place)
+        pose.args = [...place.pose, ...pose.args.slice(3)];
     pose.params = { ...pose.params, to: `${id}.seat` };
     const motion = nodeById(m, `${id}.motion`);
-    if (motion)
-        motion.params = { ...motion.params, from: `${id}.seat`, to };
-    // seat → the frame it is fastened to. Without a motion node the seat is that frame, through an identity rigid.
-    let chain = nodeById(m, `${id}.chain`);
-    if (!chain) {
-        chain = { id: `${id}.chain`, op: 'compose@1', args: ['', pose.outputs.pose], outputs: { pose: `${id}.chain.value` } };
-        m.nodes.push(chain);
-    }
+    const zero = constantOf(m, 'mm', 0, 'd');
+    const noTurn = constantOf(m, 'deg', 0, 'a');
     let seat = nodeById(m, `${id}.seat.rigid`);
-    if (!motion) {
-        const zero = constantOf(m, 'mm', 0, 'd');
-        const noTurn = constantOf(m, 'deg', 0, 'a');
-        if (!seat) {
-            seat = { id: `${id}.seat.rigid`, op: 'rigid@1', args: [zero, zero, zero, noTurn, noTurn, noTurn], outputs: { pose: `${id}.seat.value` }, params: { from: `${id}.seat`, to } };
-            m.nodes.push(seat);
+    if (!seat) {
+        seat = { id: `${id}.seat.rigid`, op: 'rigid@1', args: [zero, zero, zero, noTurn, noTurn, noTurn], outputs: { pose: `${id}.seat.value` }, params: {} };
+        m.nodes.push(seat);
+    }
+    const oldSeat = place ? seat.args.slice(0, 3) : [];
+    if (place)
+        seat.args = [...place.seat, ...seat.args.slice(3)];
+    seat.params = { from: motion ? `${id}.joint` : `${id}.seat`, to };
+    // The motion turns the seat frame about its origin -- the point fastened at -- into the joint frame.
+    let turned = nodeById(m, `${id}.turned`);
+    if (motion) {
+        motion.params = { ...motion.params, from: `${id}.seat`, to: `${id}.joint` };
+        if (!turned) {
+            turned = { id: `${id}.turned`, op: 'compose@1', args: [motion.outputs.pose, pose.outputs.pose], outputs: { pose: `${id}.turned.value` } };
+            m.nodes.push(turned);
         }
         else
-            seat.params = { ...seat.params, to };
-        chain.args = [seat.outputs.pose, pose.outputs.pose];
+            turned.args = [motion.outputs.pose, pose.outputs.pose];
     }
-    else
-        chain.args = [motion.outputs.pose, pose.outputs.pose];
+    else if (turned)
+        m.nodes = m.nodes.filter((n) => n !== turned);
+    let chain = nodeById(m, `${id}.chain`);
+    if (!chain) {
+        chain = { id: `${id}.chain`, op: 'compose@1', args: ['', ''], outputs: { pose: `${id}.chain.value` } };
+        m.nodes.push(chain);
+    }
+    chain.args = [seat.outputs.pose, motion ? turned.outputs.pose : pose.outputs.pose];
     const parent = /^(.*)\.local$/.exec(to);
     let world = nodeById(m, `${id}.world`);
     if (parent && parent[1] !== id) {
@@ -491,18 +574,18 @@ function reseat(asset, id, to, translation) {
         }
         else
             world.args = [above, chain.outputs.pose];
-        place.args = [place.args[0], world.outputs.pose];
+        placed.args = [placed.args[0], world.outputs.pose];
     }
     else {
         if (world)
             m.nodes = m.nodes.filter((n) => n !== world);
-        place.args = [place.args[0], chain.outputs.pose];
+        placed.args = [placed.args[0], chain.outputs.pose];
     }
     /*
       The part's own position numbers, once nothing reads them, go with the old pose: a fastened part left its
       position fields in the editor, and typing into them changed nothing (seen on :3300, 2026-09-24).
     */
-    for (const ref of old)
+    for (const ref of [...old, ...oldSeat])
         dropIfUnused(asset, ref, ownInput(m, id, ref) ? ref : undefined);
 }
 /** Apply one authoring command. Throws on any refusal, leaving the asset it was given untouched. */
@@ -519,16 +602,20 @@ export function applyV3Authoring(source, action) {
             unlinkDimension(asset, action);
             break;
         case 'attach':
-            attach(asset, action);
+            fastenAsJoint(asset, action);
             break;
-        case 'detach':
-            detach(asset, action);
+        case 'detach': {
+            const joint = jointAbove(asset, action.part);
+            if (!joint)
+                fail('EDIT_TARGET', action.part, `${action.part} is not fastened to anything`);
+            removeJoint(asset, joint.id);
             break;
-        case 'add-motion':
-            addMotion(asset, action);
+        }
+        case 'set-joint':
+            setJoint(asset, action.joint);
             break;
-        case 'remove-motion':
-            removeMotion(asset, action);
+        case 'remove-joint':
+            removeJoint(asset, action.id);
             break;
         case 'declare-occupancy':
             declareOccupancy(asset, action);
@@ -559,6 +646,9 @@ export function applyV3Authoring(source, action) {
         case 'set-repeat':
             setRepeat(asset, action);
             break;
+        case 'nudge-part':
+            nudgePart(asset, action);
+            break;
         case 'clear-mounting-face':
             clearMountingFace(asset);
             break;
@@ -578,8 +668,11 @@ export function applyV3Authoring(source, action) {
         default:
             fail('SCHEMA', 'action', `${String(action.kind)} is not an authoring action`);
     }
+    /* The joint records are the canon: whatever the command reshaped, their nodes are made again from them. */
+    if (asset.joints?.length && action.kind !== 'set-joint' && action.kind !== 'remove-joint')
+        rewriteJoints(asset);
     compileV3Asset(asset);
-    holdsOverDeclaredSize(asset);
+    holdsOverDeclaredSize(asset, source);
     return asset;
 }
 /* ----------------------------------------------------------- instance size */
@@ -630,21 +723,45 @@ function declareInstanceSize(asset, a) {
  * makes a part 200 mm shorter than the instance is caught when the instance may be 1 mm wide — the kernel alone
  * accepts it, and the board then fails to draw the figure at small sizes.
  */
-function holdsOverDeclaredSize(asset) {
+/** Where the declared size range reaches past what the figure holds: per axis, the bound it would need, and who sets it. */
+function sizeRangeGaps(asset) {
     const m = asset.document.model;
     if (!AXES.every(axis => sizeInputOf(m, axis)))
-        return;
+        return [];
     const range = Object.fromEntries(AXES.map(axis => [axis, { min: sizeInputOf(m, axis).min, max: sizeInputOf(m, axis).max }]));
     const limits = v3InstanceSizeLimitsOf(asset, range);
     const { range: holds } = foldInstanceSizeRange(range, limits);
+    const gaps = [];
     for (const axis of AXES) {
-        const path = V3_INSTANCE_SIZE_INPUTS[axis];
         const who = limits.find(l => l.axis === axis)?.part;
-        const by = who ? ` (${who})` : '';
         if (holds[axis].min > range[axis].min)
-            fail('INSTANCE_SIZE_RANGE', path, `below ${round6(holds[axis].min)} mm a length goes to zero${by}; declare the smallest size at ${round6(holds[axis].min)} mm or more`);
+            gaps.push({ axis, bound: 'min', need: holds[axis].min, declared: range[axis].min, who });
         if (holds[axis].max < range[axis].max)
-            fail('INSTANCE_SIZE_RANGE', path, `above ${round6(holds[axis].max)} mm the figure cannot be drawn${by}; declare the largest size at ${round6(holds[axis].max)} mm or less`);
+            gaps.push({ axis, bound: 'max', need: holds[axis].max, declared: range[axis].max, who });
+    }
+    return gaps;
+}
+/**
+ * After a command, the declared size range must still hold at its ends. A gap the figure already had before the
+ * command -- a range the conversion declared too wide (FORMATION_TRAY: X from 1 mm, its cells gone below 8.8 mm) -- is
+ * not the command's doing: it is refused only if it made a gap or widened one. Refusing every command for it had
+ * blocked even choosing a detail level (user, 2026-09-24).
+ */
+function holdsOverDeclaredSize(asset, before) {
+    const now = sizeRangeGaps(asset);
+    if (!now.length)
+        return;
+    const was = before ? sizeRangeGaps(before) : [];
+    for (const gap of now) {
+        const prior = was.find(g => g.axis === gap.axis && g.bound === gap.bound);
+        const worse = !prior || (gap.bound === 'min' ? gap.need > prior.need + 1e-9 || gap.declared < prior.declared : gap.need < prior.need - 1e-9 || gap.declared > prior.declared);
+        if (!worse)
+            continue;
+        const path = V3_INSTANCE_SIZE_INPUTS[gap.axis];
+        const by = gap.who ? ` (${gap.who})` : '';
+        if (gap.bound === 'min')
+            fail('INSTANCE_SIZE_RANGE', path, `below ${round6(gap.need)} mm a length goes to zero${by}; declare the smallest size at ${round6(gap.need)} mm or more`);
+        fail('INSTANCE_SIZE_RANGE', path, `above ${round6(gap.need)} mm the figure cannot be drawn${by}; declare the largest size at ${round6(gap.need)} mm or less`);
     }
 }
 /** What each part is fastened to, for a reader that wants the structure rather than the graph. */
@@ -656,12 +773,258 @@ export function v3AttachmentsOf(asset) {
             out[n.id] = parentOf(m, n.id);
     return out;
 }
+/* ------------------------------------------------------------------ joints */
+/** The joint whose child is this part, if any. */
+function jointAbove(asset, part) {
+    return asset.joints?.find(j => j.body1.part === part);
+}
+const stateIdOf = (j) => j.state?.id ?? j.id;
+/** A record that is well formed on its own, and fits the tree the others make. */
+function checkJoint(asset, j) {
+    const m = asset.document.model;
+    const path = `joints.${String(j?.id)}`;
+    if (!j || typeof j.id !== 'string' || !j.id.trim())
+        fail('JOINT_SCHEMA', 'joints', 'a joint has an id');
+    if (!V3_JOINT_TYPES.includes(j.type))
+        fail('JOINT_SCHEMA', path, `${String(j.type)} is not a joint type; ${V3_JOINT_TYPES.join(', ')}`);
+    if (!j.body1 || typeof j.body1.part !== 'string')
+        fail('JOINT_SCHEMA', path, 'a joint carries a part (body1)');
+    partOf(m, j.body1.part, path);
+    if (!j.body0 || (!('plane' in j.body0) && typeof j.body0.part !== 'string'))
+        fail('JOINT_SCHEMA', path, 'a joint hangs from a part or the mounting plane (body0)');
+    if ('part' in j.body0)
+        partOf(m, j.body0.part, path);
+    const others = (asset.joints ?? []).filter(o => o.id !== j.id);
+    const above = others.find(o => o.body1.part === j.body1.part);
+    if (above)
+        fail('JOINT_TREE', path, `${j.body1.part} already hangs from ${'part' in above.body0 ? above.body0.part : 'the mounting plane'} by ${above.id}; a part has one joint above it`);
+    if ('part' in j.body0) {
+        const parentOfPart = (part) => others.find(o => o.body1.part === part)?.body0;
+        for (let up = j.body0.part; up;) {
+            if (up === j.body1.part)
+                fail('ATTACH_CYCLE', path, `${j.body0.part} already hangs from ${j.body1.part}; ${j.body1.part} would hang from itself`);
+            const next = parentOfPart(up);
+            up = next && 'part' in next ? next.part : undefined;
+        }
+    }
+    const moving = j.type !== 'fixed';
+    const limited = j.lowerLimit !== undefined || j.upperLimit !== undefined;
+    if (moving && !['X', 'Y', 'Z'].includes(j.axis))
+        fail('JOINT_SCHEMA', path, `a ${j.type} joint has an axis, X, Y or Z`);
+    if (!moving && (j.axis !== undefined || limited || j.mimic !== undefined || j.travel !== undefined))
+        fail('JOINT_SCHEMA', path, 'a fixed joint has no axis, limits, mimic or travel');
+    if (j.travel !== undefined && j.type !== 'prismatic')
+        fail('JOINT_SCHEMA', path, 'only a prismatic joint travels a length');
+    if (j.type === 'prismatic' && j.travel && !limited) {
+        j.lowerLimit = 0;
+        j.upperLimit = 1;
+    }
+    /* A revolute joint without limits turns without end (USD); with them, both are given. A slide always has them. */
+    if (moving && !j.mimic && (limited || j.type === 'prismatic')) {
+        const [lo, hi] = [j.lowerLimit, j.upperLimit];
+        if (!(Number.isFinite(lo) && Number.isFinite(hi) && lo < hi))
+            fail('JOINT_SCHEMA', path, `a ${j.type} joint has both limits, lower below upper`);
+        if (!(lo <= 0 && 0 <= hi))
+            fail('JOINT_SCHEMA', path, 'the rest pose is the joint at 0, so its limits hold 0');
+    }
+    if (j.mimic) {
+        const leader = others.find(o => o.id === j.mimic.joint);
+        if (!leader || leader.type === 'fixed')
+            fail('JOINT_SCHEMA', path, `${String(j.mimic.joint)} is not a moving joint to follow`);
+        if (leader.mimic)
+            fail('JOINT_SCHEMA', path, `${leader.id} follows another joint; follow the one it follows`);
+        if ((leader.type === 'prismatic') !== (j.type === 'prismatic'))
+            fail('JOINT_SCHEMA', path, 'a joint follows one that moves the same way: a slide a slide, a turn a turn');
+        if (!Number.isFinite(j.mimic.multiplier))
+            fail('JOINT_SCHEMA', path, 'a mimic has a multiplier');
+    }
+}
+/**
+ * Write a joint's nodes from its record: the child's quarter turn, the fastening (the seat on the parent's face and
+ * the child's offset from it), and for a moving joint the turn or slide at the seat. The node ids are the child's and
+ * are chosen the same way each time, so writing a record again gives the same nodes.
+ */
+function writeJoint(asset, j) {
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const { pose } = partOf(m, child, child);
+    const old = pose.args.slice(3, 6);
+    pose.args = [...pose.args.slice(0, 3), ...AXES.map(a => constantOf(m, 'deg', j.origin?.turn?.[a] ?? 0, 'a'))];
+    for (const ref of old)
+        dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
+    attach(asset, {
+        kind: 'attach',
+        part: child,
+        face: j.body1.face,
+        to: 'plane' in j.body0 ? { plane: 'mounting-plane' } : { part: j.body0.part, face: j.body0.face },
+        ...(j.origin?.facing ? { facing: j.origin.facing } : {}),
+        ...(j.origin?.gap !== undefined ? { gap: j.origin.gap } : {}),
+        ...(j.origin?.align ? { align: j.origin.align } : {}),
+        replace: true
+    });
+    if (j.type === 'fixed')
+        return;
+    const kind = j.type === 'prismatic' ? 'slide' : 'turn';
+    const unit = j.type === 'prismatic' ? (j.travel ? 'ratio' : 'mm') : 'deg';
+    const range = j.lowerLimit !== undefined && j.upperLimit !== undefined ? { min: j.lowerLimit, max: j.upperLimit } : j.type === 'revolute' ? { min: -180, max: 180 } : { min: 0, max: 1 };
+    const leader = j.mimic && (asset.joints ?? []).find(o => o.id === j.mimic.joint);
+    addMotion(asset, {
+        kind: 'add-motion',
+        part: child,
+        motion: { kind, axis: j.axis.toLowerCase() },
+        state: { id: stateIdOf(j), unit, min: range.min, max: range.max, start: j.state?.start ?? 0, ...(j.state?.label !== undefined ? { label: j.state.label } : {}), ...(j.state?.sweep !== undefined ? { sweep: j.state.sweep } : {}) },
+        ...(j.travel ? { travel: j.travel } : {}),
+        replace: true
+    }, leader ? { of: stateIdOf(leader), k: j.mimic.multiplier, c: j.mimic.offset ?? 0 } : undefined);
+}
+/** Take a joint's nodes away, leaving its child standing in the asset frame at the origin. */
+function stripJoint(asset, j) {
+    const m = asset.document.model;
+    const child = j.body1.part;
+    if (nodeById(m, `${child}.motion`))
+        removeMotion(asset, { kind: 'remove-motion', part: child });
+    const { pose, place } = partOf(m, child, child);
+    const owned = new Set([`${child}.seat.rigid`, `${child}.chain`, `${child}.world`, `${child}.turned`]);
+    m.nodes = m.nodes.filter((n) => !owned.has(n.id) && !n.id.startsWith(`${child}.on.`));
+    const zero = constantOf(m, 'mm', 0, 'd');
+    const old = pose.args.slice(0, 3);
+    pose.args = [zero, zero, zero, ...pose.args.slice(3)];
+    pose.params = { ...pose.params, to: asset.document.capabilities.assetFrame };
+    // Its own position numbers, if it still had them, place nothing now: the joint places it.
+    for (const ref of old)
+        dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
+    place.args = [place.args[0], pose.outputs.pose];
+}
+/** Joints in an order each can be written in: its parent's joint and the joint it mimics first. */
+function writingOrder(joints) {
+    const done = new Set();
+    const out = [];
+    const byChild = new Map(joints.map(j => [j.body1.part, j]));
+    while (out.length < joints.length) {
+        const ready = joints.filter(j => {
+            if (done.has(j.id))
+                return false;
+            const up = 'part' in j.body0 ? byChild.get(j.body0.part) : undefined;
+            return (!up || done.has(up.id)) && (!j.mimic || done.has(j.mimic.joint));
+        });
+        if (!ready.length)
+            fail('JOINT_TREE', 'joints', 'the joints do not make a tree');
+        for (const j of ready) {
+            done.add(j.id);
+            out.push(j);
+        }
+    }
+    return out;
+}
+/** Every joint's nodes again, from the records: the ones below first away, then all written parents first. */
+function rewriteJoints(asset) {
+    const joints = (asset.joints ?? []);
+    const order = writingOrder(joints);
+    const keep = { ...asset.stateDefaults };
+    for (const j of [...order].reverse())
+        stripJoint(asset, j);
+    for (const j of order)
+        writeJoint(asset, j);
+    // A joint's value as the author left it (「지금 자세를 기본으로」) is theirs, not the record's.
+    for (const j of order)
+        if (j.type !== 'fixed' && !j.mimic && keep[stateIdOf(j)] !== undefined)
+            asset.stateDefaults[stateIdOf(j)] = keep[stateIdOf(j)];
+}
+function setJoint(asset, joint) {
+    // As JSON: a field left undefined is a field not there, which is how the asset stores it.
+    const j = JSON.parse(JSON.stringify(joint ?? null));
+    checkJoint(asset, j);
+    /* The child's own quarter turn becomes the record's, the first time it is fastened. */
+    if (!jointAbove(asset, j.body1.part) && !j.origin?.turn) {
+        const turn = turnOf(asset.document.model, asset, j.body1.part, j.body1.part);
+        if (turn.some(t => t !== 0))
+            j.origin = { ...(j.origin ?? {}), turn: Object.fromEntries(AXES.map((a, i) => [a, turn[i]])) };
+    }
+    const joints = (asset.joints ?? []).filter(o => o.id !== j.id);
+    const followers = joints.filter(o => o.mimic?.joint === j.id);
+    if (followers.length && j.type === 'fixed')
+        fail('JOINT_SCHEMA', `joints.${j.id}`, `${followers.map(f => f.id).join(', ')} follow ${j.id}; it cannot stop moving`);
+    asset.joints = [...joints, j];
+    rewriteJoints(asset);
+}
+/** The joint goes; its child keeps where it stands now, as plain position numbers. */
+function removeJoint(asset, id) {
+    const joints = (asset.joints ?? []);
+    const j = joints.find(o => o.id === id);
+    if (!j)
+        fail('EDIT_TARGET', `joints.${id}`, `there is no joint ${id}`);
+    const followers = joints.filter(o => o.mimic?.joint === id);
+    if (followers.length)
+        fail('JOINT_SCHEMA', `joints.${id}`, `${followers.map(f => f.id).join(', ')} follow ${id}; remove them first`);
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const evaluated = compileV3Asset(asset).evaluate();
+    const placed = nodeById(m, child);
+    const at = evaluated.values?.[placed.args[1]];
+    if (!at?.t)
+        fail('TARGET_ABSENT', child, `${child} has no pose to read`);
+    const own = m.nodes.find((n) => n.id === `${child}.pose`);
+    const turned = (r, want) => r.some((row, i) => row.some((v, k) => Math.abs(v - want[i][k]) > 1e-9));
+    const ownTurn = evaluated.values?.[own.outputs.pose]?.r;
+    if (ownTurn && turned(at.r, ownTurn))
+        fail('EDIT_TARGET', child, `${child} stands turned by what it hangs from; taking the joint away would turn it`);
+    asset.joints = joints.filter(o => o.id !== id);
+    stripJoint(asset, j);
+    const translation = AXES.map((axis, i) => {
+        const input = `${child}.position.${axis}`;
+        const value = round6(at.t[i]);
+        if (!m.inputs.some((n) => n.id === input))
+            m.inputs.push({ id: input, unit: 'mm', min: -Number.MAX_VALUE, max: Number.MAX_VALUE, role: 'design' });
+        asset.designInputs[input] = value;
+        return input;
+    });
+    own.args = [...translation, ...own.args.slice(3)];
+    // Parts hanging from it are written again: they hang from where it stands now.
+    rewriteJoints(asset);
+}
+/** `attach` is the modeller's word for a fixed joint: the record says it, whatever joint was there keeps its id and motion. */
+function fastenAsJoint(asset, a) {
+    const was = jointAbove(asset, a.part);
+    if (was && !a.replace)
+        fail('ATTACH_REPLACED', a.part, `${a.part} is already fastened by ${was.id}; pass replace to move it, or detach it first`);
+    const to = a.to;
+    setJoint(asset, {
+        ...(was ?? { id: a.part, type: 'fixed' }),
+        body0: to?.plane !== undefined ? { plane: to.plane } : { part: to?.part, face: to?.face },
+        body1: { part: a.part, face: a.face },
+        origin: {
+            ...(was?.origin?.turn ? { turn: was.origin.turn } : {}),
+            ...(a.facing ? { facing: a.facing } : {}),
+            ...(a.gap !== undefined ? { gap: a.gap } : {}),
+            ...(a.align ? { align: a.align } : {})
+        }
+    });
+}
+/**
+ * The records are the canon: made again from them, the joints' nodes must be the nodes the asset holds. An asset
+ * whose nodes or records were edited apart is refused, not quietly rebuilt (ADR-0093, chief architect's condition).
+ */
+export function checkV3Joints(asset) {
+    const joints = asset.joints;
+    if (!joints?.length)
+        return;
+    const again = structuredClone(asset);
+    for (const j of joints)
+        checkJoint({ ...again, joints: joints.filter(o => o.id !== j.id).concat(j) }, j);
+    rewriteJoints(again);
+    const canon = (model) => JSON.stringify({
+        nodes: [...model.nodes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        inputs: [...model.inputs].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    });
+    if (canon(again.document.model) !== canon(asset.document.model))
+        fail('JOINT_DRIFT', 'joints', 'the joints\' nodes are not what their records make; the asset was edited apart from its joints');
+}
 /** The frame a part is fastened into: its parent's, or the asset's. */
 const attachmentFrameOf = (asset, id) => {
     const parent = parentOf(asset.document.model, id);
     return parent ? `${parent}.local` : asset.document.capabilities.assetFrame;
 };
-function addMotion(asset, a) {
+function addMotion(asset, a, follow) {
     const m = asset.document.model;
     const path = a.part;
     partOf(m, a.part, path);
@@ -680,26 +1043,40 @@ function addMotion(asset, a) {
     else if (frame !== 'attachment' && frame !== 'asset')
         fail('SCHEMA', path, `${String(frame)} is not a frame for the axis`);
     const st = a.state;
-    if (!st || typeof st.id !== 'string' || !st.id.trim())
-        fail('SCHEMA', path, 'a state input id is required');
-    if (m.inputs.some((i) => i.id === st.id))
-        fail('DUPLICATE_WRITER', path, `${st.id} already exists`);
-    const wanted = a.motion.kind === 'turn' ? ['deg'] : ['mm', 'ratio'];
-    if (!wanted.includes(st.unit))
-        fail('SCHEMA', path, `a ${a.motion.kind} takes a ${wanted.join(' or ')} control, not ${String(st.unit)}`);
-    if (!(Number.isFinite(st.min) && Number.isFinite(st.max) && st.max > st.min))
-        fail('SCHEMA', path, 'a range with max above min is required');
-    const start = st.start ?? st.min;
-    if (!(start >= st.min && start <= st.max))
-        fail('SCHEMA', path, 'the starting value is outside the range');
-    m.inputs.push({ id: st.id, unit: st.unit, min: st.min, max: st.max, role: 'state' });
-    asset.stateDefaults[st.id] = start;
-    if (st.label !== undefined || st.sweep !== undefined) {
-        asset.stateInputs = { ...(asset.stateInputs ?? {}) };
-        asset.stateInputs[st.id] = { ...(st.label !== undefined ? { label: st.label } : {}), ...(st.sweep !== undefined ? { sweep: st.sweep } : {}) };
-    }
     const name = namer(m, `${a.part}.motion`);
-    let quantity = st.id;
+    let quantity = st?.id;
+    if (follow) {
+        /* A mimic: the leader's value times k plus c, and no control of its own. */
+        const scaledId = name('mimic');
+        m.nodes.push({ id: scaledId, op: 'mul@1', args: [follow.of, constantOf(m, 'ratio', follow.k, 'k')], outputs: { value: `${scaledId}.value` } });
+        quantity = `${scaledId}.value`;
+        if (follow.c) {
+            const plus = name('mimic.offset');
+            const unitOf = m.inputs.find((i) => i.id === follow.of)?.unit ?? 'deg';
+            m.nodes.push({ id: plus, op: 'add@1', args: [quantity, constantOf(m, unitOf, follow.c, 'd')], outputs: { value: `${plus}.value` } });
+            quantity = `${plus}.value`;
+        }
+    }
+    else {
+        if (!st || typeof st.id !== 'string' || !st.id.trim())
+            fail('SCHEMA', path, 'a state input id is required');
+        if (m.inputs.some((i) => i.id === st.id))
+            fail('DUPLICATE_WRITER', path, `${st.id} already exists`);
+        const wanted = a.motion.kind === 'turn' ? ['deg'] : ['mm', 'ratio'];
+        if (!wanted.includes(st.unit))
+            fail('SCHEMA', path, `a ${a.motion.kind} takes a ${wanted.join(' or ')} control, not ${String(st.unit)}`);
+        if (!(Number.isFinite(st.min) && Number.isFinite(st.max) && st.max > st.min))
+            fail('SCHEMA', path, 'a range with max above min is required');
+        const start = st.start ?? st.min;
+        if (!(start >= st.min && start <= st.max))
+            fail('SCHEMA', path, 'the starting value is outside the range');
+        m.inputs.push({ id: st.id, unit: st.unit, min: st.min, max: st.max, role: 'state' });
+        asset.stateDefaults[st.id] = start;
+        if (st.label !== undefined || st.sweep !== undefined) {
+            asset.stateInputs = { ...(asset.stateInputs ?? {}) };
+            asset.stateInputs[st.id] = { ...(st.label !== undefined ? { label: st.label } : {}), ...(st.sweep !== undefined ? { sweep: st.sweep } : {}) };
+        }
+    }
     if (a.motion.kind === 'slide' && st.unit === 'ratio') {
         if (!a.travel)
             fail('SCHEMA', path, 'a ratio control needs travel: how far the part goes at 1');
@@ -707,7 +1084,7 @@ function addMotion(asset, a) {
         const base = travel.source ? sourceRef(m, asset, travel.source, path) : constantOf(m, 'mm', travel.plus ?? 0, 'd');
         const length = travel.source ? scaled(m, name, base, travel.times ?? 1, travel.plus ?? 0, 'travel') : base;
         const id = name('distance');
-        m.nodes.push({ id, op: 'mul@1', args: [st.id, length], outputs: { value: `${id}.value` } });
+        m.nodes.push({ id, op: 'mul@1', args: [quantity, length], outputs: { value: `${id}.value` } });
         quantity = `${id}.value`;
     }
     else if (a.motion.kind === 'slide' && a.travel)
@@ -738,7 +1115,7 @@ function removeMotion(asset, a) {
     if (!motion)
         fail('EDIT_TARGET', a.part, `${a.part} does not move`);
     const quantity = motion.args[3];
-    const to = motion.params.to;
+    const to = nodeById(m, `${a.part}.seat.rigid`)?.params?.to ?? motion.params.to;
     // Which control this motion introduced, read before the nodes that name it are taken away.
     const state = m.inputs.find((i) => i.id === quantity && i.role === 'state')
         ?? m.inputs.find((i) => i.role === 'state' && (writerOf(m, quantity)?.args ?? []).includes(i.id));
@@ -771,22 +1148,53 @@ function fingerprintOf(asset) {
     return `${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}:${text.length}`;
 }
 const linAdd = (a, b, k = 1) => ({ terms: [...a.terms, ...b.terms.map(t => ({ ref: t.ref, k: t.k * k }))], c: a.c + b.c * k });
+/** The same sum with each reference once. */
+const linNorm = (a) => {
+    const by = new Map();
+    for (const t of a.terms)
+        by.set(t.ref, (by.get(t.ref) ?? 0) + t.k);
+    return { terms: [...by].filter(([, k]) => k !== 0).map(([ref, k]) => ({ ref, k })), c: a.c };
+};
+/** A sum at least as large as either, where every reference is a size (never below zero): term by term, the larger. */
+const linAtLeast = (a, b) => {
+    const by = new Map();
+    for (const t of [...linNorm(a).terms, ...linNorm(b).terms])
+        by.set(t.ref, Math.max(by.get(t.ref) ?? 0, t.k));
+    return { terms: [...by].map(([ref, k]) => ({ ref, k })), c: Math.max(a.c, b.c) };
+};
 const linOf = (m, ref) => {
     const constant = m.constants.find((c) => c.id === ref);
     return constant ? { terms: [], c: constant.value } : { terms: [{ ref, k: 1 }], c: 0 };
 };
 /** How far a slide has gone when its control is at one end of its range. */
 function travelAt(m, asset, motion, bound) {
-    const quantity = motion.args[3];
-    const direct = m.inputs.find((i) => i.id === quantity && i.role === 'state');
     const pick = (i) => (bound === 'start' ? (asset.stateDefaults[i.id] ?? i.min) : bound === 'min' ? i.min : i.max);
-    if (direct)
-        return { terms: [], c: pick(direct) };
+    /* A control's value, or a mimic's: the leader's value times a constant, plus a constant. */
+    const valueOf = (ref) => {
+        const state = m.inputs.find((i) => i.id === ref && i.role === 'state');
+        if (state)
+            return pick(state);
+        const w = writerOf(m, ref);
+        const constant = (r) => m.constants.find((c) => c.id === r)?.value;
+        if (w?.op === 'mul@1' && w.args.length === 2 && constant(w.args[1]) !== undefined) {
+            const v = valueOf(w.args[0]);
+            return v === null ? null : v * constant(w.args[1]);
+        }
+        if (w?.op === 'add@1' && w.args.length === 2 && constant(w.args[1]) !== undefined) {
+            const v = valueOf(w.args[0]);
+            return v === null ? null : v + constant(w.args[1]);
+        }
+        return null;
+    };
+    const quantity = motion.args[3];
+    const direct = valueOf(quantity);
+    if (direct !== null)
+        return { terms: [], c: direct };
     const writer = writerOf(m, quantity);
     if (writer?.op === 'mul@1' && writer.args.length === 2) {
-        const state = m.inputs.find((i) => i.id === writer.args[0] && i.role === 'state');
-        if (state)
-            return { terms: [{ ref: writer.args[1], k: pick(state) }], c: 0 };
+        const v = valueOf(writer.args[0]);
+        if (v !== null)
+            return { terms: [{ ref: writer.args[1], k: v }], c: 0 };
     }
     return null;
 }
@@ -798,10 +1206,15 @@ function centreLin(m, asset, id, axis, bound) {
         const pose = nodeById(m, `${part}.pose`);
         if (!pose)
             return `${part} has no pose this command can read`;
-        for (const ref of pose.args.slice(3, 6))
-            if (angleOf(m, asset, ref) !== 0)
-                return `${part} is turned, so its reach is not a box this command can add up`;
+        /* A part's own turn turns it about its centre; a turn above it would turn everything below. */
+        if (part !== id)
+            for (const ref of pose.args.slice(3, 6))
+                if (angleOf(m, asset, ref) !== 0)
+                    return `${part} is turned, so its reach is not a box this command can add up`;
         out = linAdd(out, linOf(m, pose.args[i]));
+        const seat = nodeById(m, `${part}.seat.rigid`);
+        if (seat)
+            out = linAdd(out, linOf(m, seat.args[i]));
         const motion = nodeById(m, `${part}.motion`);
         if (motion) {
             if (motion.op !== 'axis-slide@1')
@@ -820,6 +1233,161 @@ function centreLin(m, asset, id, axis, bound) {
     }
     return out;
 }
+/** A value written as a sum of design inputs times constants, or null where it is anything else. */
+function affineOf(m, ref, seen = 0) {
+    if (seen > 64)
+        return null;
+    const constant = m.constants.find((c) => c.id === ref);
+    if (constant)
+        return { terms: [], c: constant.value };
+    if (m.inputs.some((i) => i.id === ref))
+        return { terms: [{ ref, k: 1 }], c: 0 };
+    const writer = writerOf(m, ref);
+    if (writer?.op === 'add@1') {
+        let out = { terms: [], c: 0 };
+        for (const arg of writer.args) {
+            const part = affineOf(m, arg, seen + 1);
+            if (!part)
+                return null;
+            out = linAdd(out, part);
+        }
+        return out;
+    }
+    if (writer?.op === 'mul@1' && writer.args.length === 2) {
+        const [a, b] = writer.args.map((arg) => affineOf(m, arg, seen + 1));
+        if (!a || !b)
+            return null;
+        if (!a.terms.length)
+            return linAdd({ terms: [], c: 0 }, b, a.c);
+        if (!b.terms.length)
+            return linAdd({ terms: [], c: 0 }, a, b.c);
+    }
+    return null;
+}
+/**
+ * How long a value can be, at most, as a sum that holds at every design size: each input's coefficient taken
+ * positive. Sound only over inputs that are never below zero (sizes), so any other input makes it unreadable.
+ */
+function magnitudeOf(m, lin) {
+    let out = { terms: [], c: 0 };
+    for (const t of lin.terms) {
+        const a = affineOf(m, t.ref);
+        if (!a)
+            return null;
+        for (const u of a.terms) {
+            const input = m.inputs.find((i) => i.id === u.ref);
+            if (!input || input.role === 'state' || !(input.min >= 0))
+                return null;
+            out = linAdd(out, { terms: [{ ref: u.ref, k: Math.abs(u.k * t.k) }], c: 0 });
+        }
+        out.c += Math.abs(a.c * t.k);
+    }
+    out.c += Math.abs(lin.c);
+    return out;
+}
+/**
+ * Where a part carried by a turn can reach: a ball about the point the first turn above it turns about, as wide as
+ * every step from there to the part laid end to end, plus the part's own half size on each axis (the triangle
+ * inequality -- it holds at every angle and every design size, so it is a bound, not a sample). As a box, that
+ * ball is the pivot plus and minus its radius on each axis. Read by the proposal; the release gate still checks
+ * the parts against it.
+ */
+function reachOf(m, asset, id, freezeless = true) {
+    const chain = [];
+    for (let part = id; part; part = parentOf(m, part))
+        chain.push(part);
+    const top = chain.reduce((found, part, i) => (nodeById(m, `${part}.motion`)?.op === 'axis-turn@1' ? i : found), -1);
+    if (top < 0)
+        return `${id} is carried by no turn`;
+    let radius = { terms: [], c: 0 };
+    const grow = (lin, what) => {
+        const size = lin && magnitudeOf(m, lin);
+        if (!size)
+            return `${what} is not a sum of sizes, so how far it reaches cannot be bounded`;
+        radius = linAdd(radius, size);
+        return null;
+    };
+    const sizes = standingRefsOf(m, asset, id, id, !freezeless);
+    for (const axis of AXES) {
+        const bad = grow({ terms: [{ ref: sizes[axis].ref, k: 0.5 * sizes[axis].k }], c: 0 }, `${id}'s size`);
+        if (bad)
+            return bad;
+    }
+    for (let i = 0; i <= top; i++) {
+        const part = chain[i];
+        const pose = nodeById(m, `${part}.pose`);
+        if (!pose)
+            return `${part} has no pose this command can read`;
+        for (const ref of pose.args.slice(0, 3)) {
+            const bad = grow(linOf(m, ref), `${part}'s place`);
+            if (bad)
+                return bad;
+        }
+        if (i < top) {
+            const seat = nodeById(m, `${part}.seat.rigid`);
+            for (const ref of seat?.args.slice(0, 3) ?? []) {
+                const bad = grow(linOf(m, ref), `where ${part} is fastened`);
+                if (bad)
+                    return bad;
+            }
+            const motion = nodeById(m, `${part}.motion`);
+            if (motion?.op === 'axis-slide@1')
+                for (const end of ['min', 'max']) {
+                    const bad = grow(travelAt(m, asset, motion, end), `${part}'s travel`);
+                    if (bad)
+                        return bad;
+                }
+        }
+    }
+    // The pivot: where the topmost turn is fastened, and everything above it, which neither turns nor slides.
+    const pivotPart = chain[top];
+    const centre = {};
+    for (const axis of AXES) {
+        const k = AXES.indexOf(axis);
+        let at = { terms: [], c: 0 };
+        const seat = nodeById(m, `${pivotPart}.seat.rigid`);
+        if (seat)
+            at = linAdd(at, linOf(m, seat.args[k]));
+        for (let part = parentOf(m, pivotPart); part; part = parentOf(m, part)) {
+            const pose = nodeById(m, `${part}.pose`);
+            if (!pose)
+                return `${part} has no pose this command can read`;
+            for (const ref of pose.args.slice(3, 6))
+                if (angleOf(m, asset, ref) !== 0)
+                    return `${part} is turned, so where ${pivotPart} turns is not a point this command can add up`;
+            if (nodeById(m, `${part}.motion`))
+                return `${part} moves, and so does the point ${pivotPart} turns about`;
+            at = linAdd(at, linOf(m, pose.args[k]));
+            const above = nodeById(m, `${part}.seat.rigid`);
+            if (above)
+                at = linAdd(at, linOf(m, above.args[k]));
+        }
+        centre[axis] = at;
+    }
+    return { centre, radius };
+}
+/** A sum written as graph nodes: each term scaled, then added up, then the constant. */
+function emitLin(m, name, l, hint) {
+    if (!l.terms.length)
+        return constantOf(m, 'mm', round6(l.c), 'd');
+    let out = '';
+    for (const t of l.terms) {
+        const piece = scaled(m, name, t.ref, t.k, 0, hint);
+        if (!out)
+            out = piece;
+        else {
+            const id = name(`${hint}.sum`);
+            m.nodes.push({ id, op: 'add@1', args: [out, piece], outputs: { value: `${id}.value` } });
+            out = `${id}.value`;
+        }
+    }
+    if (l.c !== 0) {
+        const id = name(`${hint}.offset`);
+        m.nodes.push({ id, op: 'add@1', args: [out, constantOf(m, 'mm', round6(l.c), 'd')], outputs: { value: `${id}.value` } });
+        out = `${id}.value`;
+    }
+    return out;
+}
 /** The bounds the parts come to, as sums, with what could not be read named. */
 function occupancyLins(asset, over) {
     const m = asset.document.model;
@@ -827,13 +1395,34 @@ function occupancyLins(asset, over) {
     const skipped = [];
     const low = { x: [], y: [], z: [] };
     const high = { x: [], y: [], z: [] };
+    /* Parts carried by the same turn share one ball: its radius the larger of theirs, term by term. */
+    const balls = new Map();
     for (const place of m.nodes.filter((n) => n.op === 'place@1')) {
         let sizes;
         try {
-            sizes = sizeRefsOf(m, place.id, place.id);
+            sizes = standingRefsOf(m, asset, place.id, place.id, false);
         }
-        catch {
-            skipped.push({ part: place.id, reason: 'not a box-shaped part; this command measures boxes' });
+        catch (e) {
+            skipped.push({ part: place.id, reason: e instanceof V3ContractError ? e.message : 'not a part whose size this command can read' });
+            continue;
+        }
+        const turns = (() => {
+            for (let part = place.id; part; part = parentOf(m, part))
+                if (nodeById(m, `${part}.motion`)?.op === 'axis-turn@1')
+                    return true;
+            return false;
+        })();
+        if (turns) {
+            const reach = reachOf(m, asset, place.id);
+            if (typeof reach === 'string') {
+                skipped.push({ part: place.id, reason: reach });
+                continue;
+            }
+            parts.push(place.id);
+            const centre = Object.fromEntries(AXES.map(a => [a, linNorm(reach.centre[a])]));
+            const key = JSON.stringify(centre);
+            const ball = balls.get(key);
+            balls.set(key, { centre, radius: ball ? linAtLeast(ball.radius, reach.radius) : linNorm(reach.radius) });
             continue;
         }
         /*
@@ -864,7 +1453,7 @@ function occupancyLins(asset, over) {
             }
         }
     }
-    return { parts, skipped, low, high };
+    return { parts, skipped, low, high, balls: [...balls.values()] };
 }
 const valueOfLin = (values, l) => l.terms.reduce((s, t) => s + t.k * (values[t.ref] ?? NaN), l.c);
 /** What the parts come to, and what a person is being asked to confirm. Reads the asset; changes nothing. */
@@ -873,7 +1462,12 @@ export function proposeV3Occupancy(asset, options = {}) {
     if (over !== 'rest' && over !== 'range')
         fail('SCHEMA', 'over', `${String(over)} is neither rest nor range`);
     const source = structuredClone(asset);
-    const { parts, skipped, low, high } = occupancyLins(source, over);
+    const { parts, skipped, low, high, balls } = occupancyLins(source, over);
+    for (const ball of balls)
+        for (const axis of AXES) {
+            low[axis].push(linAdd(ball.centre[axis], ball.radius, -1));
+            high[axis].push(linAdd(ball.centre[axis], ball.radius, 1));
+        }
     if (!parts.length)
         fail('OCCUPANCY_NO_PARTS', 'occupancy', `no part could be measured${skipped.length ? `: ${skipped.map(s => `${s.part} — ${s.reason}`).join('; ')}` : ''}`);
     const values = compileV3Graph(source.document.model).evaluate({ ...source.designInputs, ...source.stateDefaults }).values;
@@ -896,7 +1490,15 @@ function declareOccupancy(asset, a) {
             fail('OCCUPANCY_PADDING', `occupancy.${axis}`, `padding is millimetres, zero or more; got ${String(pad)}`);
         padding[axis] = pad;
     }
-    const { parts, low, high } = occupancyLins(asset, a.proposal.over);
+    const { parts, low, high, balls } = occupancyLins(asset, a.proposal.over);
+    const name0 = namer(m, 'occupancy.reach');
+    balls.forEach((ball, b) => {
+        const radius = emitLin(m, name0, ball.radius, `${b}`);
+        for (const axis of AXES) {
+            low[axis].push(linAdd(ball.centre[axis], { terms: [{ ref: radius, k: 1 }], c: 0 }, -1));
+            high[axis].push(linAdd(ball.centre[axis], { terms: [{ ref: radius, k: 1 }], c: 0 }, 1));
+        }
+    });
     for (const axis of AXES) {
         if (!padding[axis])
             continue;
@@ -906,27 +1508,7 @@ function declareOccupancy(asset, a) {
     if (parts.join('|') !== a.proposal.parts.join('|'))
         fail('OCCUPANCY_STALE', 'occupancy', `the figure changed since the proposal was made (${a.proposal.parts.join(', ')} then, ${parts.join(', ')} now); propose again and confirm that`);
     const name = namer(m, 'occupancy');
-    const emit = (l, hint) => {
-        if (!l.terms.length)
-            return constantOf(m, 'mm', round6(l.c), 'd');
-        let out = '';
-        for (const t of l.terms) {
-            const piece = scaled(m, name, t.ref, t.k, 0, hint);
-            if (!out)
-                out = piece;
-            else {
-                const id = name(`${hint}.sum`);
-                m.nodes.push({ id, op: 'add@1', args: [out, piece], outputs: { value: `${id}.value` } });
-                out = `${id}.value`;
-            }
-        }
-        if (l.c !== 0) {
-            const id = name(`${hint}.offset`);
-            m.nodes.push({ id, op: 'add@1', args: [out, constantOf(m, 'mm', round6(l.c), 'd')], outputs: { value: `${id}.value` } });
-            out = `${id}.value`;
-        }
-        return out;
-    };
+    const emit = (l, hint) => emitLin(m, name, linNorm(l), hint);
     const pick = (ls, op, hint) => {
         const refs = ls.map((l, k) => emit(l, `${hint}.${k}`));
         if (refs.length === 1)
@@ -1068,6 +1650,83 @@ function clearMountingFace(asset) {
     delete asset.occupancy.contact;
     return asset;
 }
+function nudgePart(asset, a) {
+    const m = asset.document.model;
+    const path = a.part;
+    const { pose } = partOf(m, a.part, path);
+    if (pose.op !== 'rigid@1')
+        fail('EDIT_TARGET', path, `${a.part} is not posed by a rigid@1 this command can move`);
+    if (pose.params?.to !== 'asset')
+        fail('EDIT_TARGET', path, `${a.part} is carried by a joint or a seat, which places it`);
+    if (parentOf(m, a.part))
+        fail('EDIT_TARGET', path, `${a.part} is fastened to ${parentOf(m, a.part)}, which places it; detach it first`);
+    const shift = (slot, by, unit, kind, axis) => {
+        if (!by)
+            return;
+        if (!Number.isFinite(by))
+            fail('SCHEMA', `${path}.${kind}.${axis}`, 'a finite amount required');
+        const was = pose.args[slot];
+        const own = `${a.part}.${kind}.${axis}`;
+        /* Already the part's own number: add to it. */
+        if (was === own && m.inputs.some((i) => i.id === own && i.role === 'design')) {
+            asset.designInputs[own] = round6(asset.designInputs[own] + by);
+            return;
+        }
+        const constant = m.constants.find((c) => c.id === was);
+        const free = (id) => !m.inputs.some((i) => i.id === id) && !m.nodes.some((n) => n.id === id || Object.values(n.outputs).includes(id));
+        const input = (id, value) => {
+            m.inputs.push({ id, unit, min: -Number.MAX_VALUE, max: Number.MAX_VALUE, role: 'design' });
+            asset.designInputs[id] = round6(value);
+        };
+        /* A plain number becomes the part's own, moved. */
+        if (constant && free(own)) {
+            input(own, constant.value + by);
+            pose.args = pose.args.map((r, k) => (k === slot ? own : r));
+            return;
+        }
+        /* A worked-out place keeps its rule and takes the drag beside it. */
+        const nudge = `${a.part}.${kind}.nudge.${axis}`;
+        if (m.inputs.some((i) => i.id === nudge)) {
+            asset.designInputs[nudge] = round6(asset.designInputs[nudge] + by);
+            return;
+        }
+        input(nudge, by);
+        const id = namer(m, `${a.part}.${kind}`)(`nudged.${axis}`);
+        m.nodes.push({ id, op: 'add@1', args: [was, nudge], outputs: { value: `${id}.value` } });
+        pose.args = pose.args.map((r, k) => (k === slot ? `${id}.value` : r));
+    };
+    AXES.forEach((axis, i) => shift(i, a.by?.[axis] ?? 0, 'mm', 'position', axis));
+    AXES.forEach((axis, i) => shift(3 + i, a.turn?.[axis] ?? 0, 'deg', 'rotation', axis));
+    /* Sizes: the measure's own node carries a factor beside its rule (`stableDimension` routes every measure through one). */
+    const shape = partOf(m, a.part, path).shape;
+    const measures = shape.op === 'cylinder-shape@1' ? ['x', 'y'] : AXES.filter((_, i) => shape.args[i] !== undefined);
+    for (const axis of measures) {
+        /* A cylinder's radius answers to the cross axis the drag moved more. */
+        const factor = shape.op === 'cylinder-shape@1' && axis === 'x' ? mostChanged(a.grow?.x, a.grow?.z) : a.grow?.[axis];
+        if (factor === undefined || factor === 1)
+            continue;
+        if (!(Number.isFinite(factor) && factor > 0))
+            fail('GEOMETRY_DOMAIN', `${path}.dimension.${axis}`, 'a positive factor required');
+        stableDimension(m, a.part, axis, `${path}.dimension.${axis}`);
+        const node = nodeById(m, `${a.part}.dimension.${axis}`);
+        const id = `${a.part}.dimension.scale.${axis}`;
+        if (node.args[1] === id)
+            asset.designInputs[id] = round6(asset.designInputs[id] * factor);
+        else {
+            if (m.inputs.some((i) => i.id === id))
+                fail('DUPLICATE_WRITER', path, `${id} already exists`);
+            m.inputs.push({ id, unit: 'ratio', min: Number.MIN_VALUE, max: Number.MAX_VALUE, role: 'design' });
+            const was = m.constants.find((c) => c.id === node.args[1])?.value ?? 1;
+            asset.designInputs[id] = round6(was * factor);
+            node.args = [node.args[0], id];
+        }
+    }
+    return asset;
+}
+const mostChanged = (a, b) => {
+    const pick = [a, b].filter((v) => v !== undefined);
+    return pick.length ? pick.reduce((x, y) => (Math.abs(y - 1) > Math.abs(x - 1) ? y : x), 1) : undefined;
+};
 function setRepeat(asset, a) {
     const m = asset.document.model;
     const path = `${a.part}.repeat`;
@@ -1080,27 +1739,38 @@ function setRepeat(asset, a) {
         fail('EDIT_TARGET', path, `${a.part} lays its copies out by ${layout.op}, which has no pitch`);
     if (!(Number.isFinite(a.pitch) && a.pitch > 0))
         fail('GEOMETRY_DOMAIN', path, 'a positive pitch is required');
+    /*
+      One number, the pitch: copies = floor(row length / pitch), at most `limit` of them (the kernel's copy cap, V2's).
+      So the longest row the figure may be placed at is limit x pitch -- the converter set the length's upper bound that
+      way from the V2 pitch. A new pitch moves that bound with it; the pitch is refused only when the length the figure
+      is authored at would already hold more copies than the cap.
+    */
+    const values = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const lengthRef = layout.args[0];
+    const authored = values[lengthRef];
+    const limit = (values[layout.args[6]] ?? m.constants.find((c) => c.id === layout.args[6])?.value);
+    const smallest = Math.ceil((authored / limit) * 1000) / 1000;
+    if (a.pitch < smallest)
+        fail('INPUT_RANGE', path, `at the length it is authored (${round6(authored)} mm) a pitch under ${smallest} mm makes more than ${limit} copies`);
     const id = `${a.part}.repeat.pitch`;
-    let input = m.inputs.find((i) => i.id === id);
-    if (!input) {
+    if (!m.inputs.some((i) => i.id === id)) {
         if (m.nodes.some((n) => n.id === id || Object.values(n.outputs).includes(id)))
             fail('DUPLICATE_WRITER', path, `${id} already exists`);
-        /* The lowest pitch keeps the count within the limit when the row is as long as it gets. */
-        const values = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
-        const lengthRef = layout.args[0];
-        const longest = m.inputs.find((i) => i.id === lengthRef)?.max ?? values[lengthRef];
-        const limit = values[layout.args[6]] ?? m.constants.find((c) => c.id === layout.args[6])?.value;
-        const lowest = Number.isFinite(longest) && limit > 0 ? Math.ceil((longest / limit) * 1000) / 1000 : 1;
-        input = { id, unit: 'mm', min: Math.max(lowest, 0.001), max: Number.isFinite(longest) ? longest : 1e6, role: 'design' };
-        m.inputs.push(input);
+        m.inputs.push({ id, unit: 'mm', min: Number.MIN_VALUE, max: Number.MAX_VALUE, role: 'design' });
         const was = [layout.args[3], layout.args[4]];
         layout.args = layout.args.map((r, k) => (k === 3 || k === 4 ? id : r));
         for (const ref of new Set(was))
             dropIfUnused(asset, ref);
     }
-    if (a.pitch < input.min)
-        fail('INPUT_RANGE', path, `a pitch under ${input.min} mm puts more copies in the row than the kernel allows at its longest`);
     asset.designInputs[id] = a.pitch;
+    /* The longest length follows the pitch, within the default range (ten times the authored length). */
+    const length = m.inputs.find((i) => i.id === lengthRef && i.role === 'design');
+    if (length) {
+        const longest = Math.min(round6(limit * a.pitch), round6(authored * V3_INSTANCE_SIZE_DEFAULT.times));
+        length.max = Math.max(longest, authored);
+        if (length.min > length.max)
+            length.min = Math.min(length.min, authored);
+    }
     return asset;
 }
 function scaleUniformly(asset) {