@hatiolab/figure-model 0.7.3 → 0.9.0

package/dist/joint-writing.js

@@ -5,20 +5,21 @@
  * The joint records (ADR-0093): checking one, writing its nodes, and writing every joint again after a command.
  */
 import { compileFigureAssetUnjointed } from "./asset.js";
-import { compileFigureGraph } from "./graph.js";
+import { compileFigureGraph, figureShapeFaces } from "./graph.js";
 import { remappedFaces } from "./shape-edit.js";
 import { REPEAT_LIMIT, AXES } from "./words.js";
 import { FIGURE_INSTANCE_SIZE_DEFAULT } from "./instance-size.js";
-import { FIGURE_FACES, FIGURE_JOINT_TYPES, figureMimicLeadersOf, followsSomething, followedTermsOf } from "./authoring-types.js";
+import { FIGURE_FACES, FIGURE_JOINT_TYPES, FIGURE_JOINT_PIVOTS, figureMimicLeadersOf, followsSomething, followedTermsOf } from "./authoring-types.js";
 import { fail, nodeById, partOf, namer, constantOf, measureRef, sumOf, stableDimension, ownInput, holdingDeclared, dropIfUnused, parentOf, round6 } from "./authoring-nodes.js";
-import { turnOf, turnMatrix, mul3, neg, half, childFaceOf, ownSpansOf, standingSpansOf, IDENTITY, isIdentity, transpose3, mv3, FACE_VECTOR, faceAlong, standingTurnOf, standingQuarterOf, eulerOf, axisTurn, axisOf, splitTwist, eulerOfAny, alignInto, frustumWidthAlong } from "./authoring-geometry.js";
-import { attach, addMotion, removeMotion } from "./authoring-fastening.js";
+import { mul3, neg, half, ownSpansOf, IDENTITY, transpose3, mv3, eulerOfAny, rpyMatrix, isQuarterMatrix, receivingAxisOf, rpyOf } from "./authoring-geometry.js";
+import { placeOnFace, addMotion, removeMotion, reseat, turnSeat } from "./authoring-fastening.js";
+import { figureShapeExtremeAlong, lin, plus, times, writeFigureReach } from "./shape-extreme.js";
 const everyKey = () => (...keys) => keys;
 const JOINT_FIELDS = {
     joint: everyKey()('id', 'type', 'body0', 'body1', 'origin', 'axis', 'lowerLimit', 'upperLimit', 'travel', 'state', 'mimic', 'repeat'),
-    body0: everyKey()('part', 'face', 'plane'),
-    body1: everyKey()('part', 'face'),
-    origin: everyKey()('facing', 'gap', 'align', 'turn', 'twist'),
+    body0: everyKey()('part', 'face', 'plane', 'at'),
+    body1: everyKey()('part', 'at'),
+    origin: everyKey()('facing', 'gap', 'align', 'childRotate', 'pivot', 'offset', 'parentRotate'),
     axes: everyKey()('x', 'y', 'z'),
     alignment: everyKey()('mm'),
     measure: everyKey()('from', 'times', 'plus', 'sum'),
@@ -59,13 +60,18 @@ function knownJointFields(j, path) {
     only(o, JOINT_FIELDS.origin, `${path}.origin`);
     if (o && typeof o === 'object') {
         measure(o.gap, `${path}.origin.gap`);
-        only(o.turn, JOINT_FIELDS.axes, `${path}.origin.turn`);
+        only(o.childRotate, JOINT_FIELDS.axes, `${path}.origin.childRotate`);
+        only(o.parentRotate, JOINT_FIELDS.axes, `${path}.origin.parentRotate`);
+        only(o.offset, JOINT_FIELDS.axes, `${path}.origin.offset`);
+        for (const [axis, d] of Object.entries(o.offset && typeof o.offset === 'object' ? o.offset : {}))
+            measure(d, `${path}.origin.offset.${axis}`);
         only(o.align, JOINT_FIELDS.axes, `${path}.origin.align`);
         for (const [axis, a] of Object.entries(o.align && typeof o.align === 'object' ? o.align : {})) {
             only(a, JOINT_FIELDS.alignment, `${path}.origin.align.${axis}`);
             measure(a?.mm, `${path}.origin.align.${axis}.mm`);
         }
     }
+    only(j.axis, JOINT_FIELDS.axes, `${path}.axis`);
     if (j.travel && typeof j.travel === 'object') {
         only(j.travel, JOINT_FIELDS.travel, `${path}.travel`);
         source(j.travel.source, `${path}.travel.source`);
@@ -97,6 +103,61 @@ export function jointAbove(asset, part) {
     return asset.joints?.find(j => j.body1.part === part);
 }
 export const stateIdOf = (j) => j.state?.id ?? j.id;
+/** Whether a joint is placed at its parent's origin rather than on a face (ADR-0107 decision 4). */
+export const isOriginPlaced = (j) => !!j.body0 && 'at' in j.body0;
+/** A record's axis as a unit vector when it is written as one; undefined for a token. Zero or not finite is refused. */
+export function jointVectorOf(axis, path) {
+    if (!axis || typeof axis !== 'object')
+        return undefined;
+    const v = AXES.map(a => axis[a]);
+    if (!v.every(x => typeof x === 'number' && Number.isFinite(x)))
+        fail('JOINT_SCHEMA', `${path}.axis`, 'an axis vector is three finite numbers { x, y, z }');
+    const n = Math.hypot(...v);
+    if (!(n > 1e-9))
+        fail('JOINT_SCHEMA', `${path}.axis`, 'an axis vector is not zero');
+    return v.map(x => x / n);
+}
+const hasParentRotate = (j) => AXES.some(a => (j.origin?.parentRotate?.[a] ?? 0) !== 0);
+/**
+ * The joint frame's own words (ADR-0107, contract 2026-10-03): the pivot, the offset and the parent end's rotation, and
+ * the ends placed by an origin. A joint at its parent's origin is placed by offset and parentRotate alone: a face's
+ * words are refused by name. A joint frame turned by other than quarter turns turns the child after it is lined up, so
+ * its sides are not level with an edge: min or max is refused with it (ADR-0107 Q-B, kept on the frame's side by
+ * ADR-0140 3.10).
+ */
+function checkJointFrames(j, path) {
+    const o = j.origin ?? {};
+    const body0 = j.body0;
+    const body1 = j.body1;
+    if ('at' in body0 && body0.at !== 'origin')
+        fail('JOINT_SCHEMA', `${path}.body0`, `${String(body0.at)} is not a place on a part; at: 'origin' is`);
+    if ('at' in body1 && body1.at !== 'origin')
+        fail('JOINT_SCHEMA', `${path}.body1`, `${String(body1.at)} is not a place on a part; at: 'origin' is`);
+    if ('at' in body0 && ('face' in body0 || 'plane' in body0))
+        fail('JOINT_SCHEMA', `${path}.body0`, "a joint hangs at a part's origin or on a face, not both");
+    if (isOriginPlaced(j)) {
+        for (const key of ['align', 'gap', 'facing', 'childRotate', 'pivot'])
+            if (o[key] !== undefined)
+                fail('JOINT_SCHEMA', `${path}.origin.${key}`, `${key} places a part on a face; ${body0.part}'s origin is a point and a frame, placed by offset and parentRotate`);
+    }
+    else if ('at' in body1)
+        fail('JOINT_SCHEMA', `${path}.body1`, `a child is placed by its origin only at its parent's origin; ${'plane' in body0 ? 'the mounting plane' : `${body0.part}'s ${String(body0.face)}`} is a face`);
+    if (o.pivot !== undefined && !FIGURE_JOINT_PIVOTS.includes(o.pivot))
+        fail('JOINT_SCHEMA', `${path}.origin.pivot`, `${String(o.pivot)} is not a pivot; ${FIGURE_JOINT_PIVOTS.join(', ')}`);
+    if (o.pivot === 'child-face' && o.facing === 'centre')
+        fail('JOINT_SCHEMA', `${path}.origin.pivot`, `${body1.part} is fastened by its middle, not by a face; child-face has no face to turn about -- it turns about its middle already (child-centre)`);
+    if (o.parentRotate !== undefined) {
+        if (!o.parentRotate ||
+            typeof o.parentRotate !== 'object' ||
+            Object.values(o.parentRotate).some(v => typeof v !== 'number' || !Number.isFinite(v)))
+            fail('JOINT_SCHEMA', `${path}.origin.parentRotate`, 'a rotation is degrees about x, y and z');
+        const edges = AXES.filter(a => o.align?.[a] === 'min' || o.align?.[a] === 'max');
+        if (edges.length && !isQuarterMatrix(rpyMatrix(o.parentRotate)))
+            fail('JOINT_SCHEMA', `${path}.origin.parentRotate`, `the joint frame is turned by other than quarter turns; ${body1.part}'s sides are not level with the edges it is lined up with (${edges.join(', ')}) -- place it by the centre or a distance`);
+    }
+    if (o.offset !== undefined && (!o.offset || typeof o.offset !== 'object'))
+        fail('JOINT_SCHEMA', `${path}.origin.offset`, 'an offset is a length along x, y and z');
+}
 /** 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;
@@ -113,6 +174,7 @@ function checkJoint(asset, j) {
         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);
+    checkJointFrames(j, path);
     const others = (asset.joints ?? []).filter(o => o.id !== j.id);
     const above = others.find(o => o.body1.part === j.body1.part);
     if (above)
@@ -128,8 +190,8 @@ function checkJoint(asset, j) {
     }
     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 && !['X', 'Y', 'Z'].includes(j.axis) && !jointVectorOf(j.axis, path))
+        fail('JOINT_SCHEMA', path, `a ${j.type} joint has an axis, X, Y or Z, or a vector { x, y, 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')
@@ -176,11 +238,9 @@ function checkJoint(asset, j) {
         if (j.mimic.offset !== undefined && !Number.isFinite(j.mimic.offset))
             fail('JOINT_SCHEMA', path, "a mimic's offset is a number in the joint's unit");
     }
-    if (j.origin?.twist !== undefined && !Number.isFinite(j.origin.twist))
-        fail('JOINT_SCHEMA', `${path}.origin.twist`, 'a twist is a number of degrees');
-    if (j.origin?.turn &&
-        Object.values(j.origin.turn).some(t => !Number.isFinite(t) || Math.abs(t / 90 - Math.round(t / 90)) > 1e-9))
-        fail('JOINT_SCHEMA', `${path}.origin.turn`, "a turn is in quarter turns; an angle about the face's normal is its twist");
+    if (j.origin?.childRotate !== undefined &&
+        (!j.origin.childRotate || typeof j.origin.childRotate !== 'object' || Object.values(j.origin.childRotate).some(t => !Number.isFinite(t))))
+        fail('JOINT_SCHEMA', `${path}.origin.childRotate`, 'a pose is degrees about x, y and z');
     /*
       A row repeats its part and everything fastened to it (ADR-0093, 2026-09-26): a part fastened to a part in a row is
       on every copy. A row inside a row is a grid; it runs along another axis than the rows around it.
@@ -210,9 +270,17 @@ function checkJoint(asset, j) {
         const row = `${path}.repeat`;
         if (!('part' in j.body0))
             fail('JOINT_SCHEMA', row, 'a row fills the part it is fastened to; the mounting plane has no length to fill');
+        /* A row runs across a face, from edge to edge: a frame moved, turned or placed at an origin is not covered yet. */
+        if (isOriginPlaced(j))
+            fail('JOINT_SCHEMA', row, 'a row runs across the face it is fastened to; a joint placed at an origin has none');
+        for (const key of ['offset', 'parentRotate'])
+            if (j.origin?.[key] !== undefined)
+                fail('JOINT_SCHEMA', row, `a row with its joint frame moved or turned (origin.${key}) is not covered yet`);
+        if ((j.origin?.pivot ?? 'seat') !== 'seat')
+            fail('JOINT_SCHEMA', row, `a row turning about ${j.origin.pivot} is not covered yet; its copies turn where they are fastened`);
         if (!['X', 'Y', 'Z'].includes(r.axis))
             fail('JOINT_SCHEMA', row, `a row runs along X, Y or Z, not ${String(r.axis)}`);
-        if (r.axis.toLowerCase() === FIGURE_FACES[childFaceOf(asset.document.model, j)])
+        if (r.axis.toLowerCase() === receivingAxisOf(asset.document.model, asset, j))
             fail('JOINT_SCHEMA', row, `a row runs across the face it is fastened to; ${r.axis} is out of that face`);
         if (typeof r.pitch === 'number' ? !(Number.isFinite(r.pitch) && r.pitch > 0) : !followsSomething(r.pitch))
             fail('GEOMETRY_DOMAIN', row, 'a row has a positive pitch, or one that follows a length');
@@ -232,75 +300,59 @@ function checkJoint(asset, j) {
  * 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);
+    if (isOriginPlaced(j)) {
+        placeAtOrigin(asset, j);
+        return moveJoint(asset, j, IDENTITY);
+    }
     /*
-      The record speaks as the parts stand: `top` is up, the axis is the figure's. The seat is written in the parent's
-      own frame, so under a parent standing a quarter turn the record's words are turned into that frame, and the child
-      is given the turn back so it keeps its own (빈틈 A, 2026-09-25: a body on a pipe laid on its side).
+      The record speaks in the parent's own frame (ADR-0140 3.11): its face's name, the axes of the alignment and of the
+      child's pose are the parent's, whatever way the parent stands -- the seat is written in that frame, so it follows
+      the parent as it turns or moves. The child meets the face by its real shape in the pose it is given.
     */
-    const parent = 'part' in j.body0 ? j.body0.part : undefined;
+    placeOnFace(asset, j, { pivot: j.origin?.pivot, offset: j.origin?.offset, parentRotate: j.origin?.parentRotate, path: `joints.${j.id}` });
+    moveJoint(asset, j, IDENTITY);
+}
+/**
+ * A joint at its parent's origin (ADR-0107 decision 4, contract 2026-10-03): F_parent = T(δ)·Rpy in the parent's own
+ * frame, as URDF reads a joint's origin -- no standing turn put in, no face measured. The child stands by its own origin
+ * there (F_child = I), or by its centre (F_child = T(its centre)), unturned.
+ */
+function placeAtOrigin(asset, j) {
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const parent = j.body0.part;
     const path = `joints.${j.id}`;
-    const back = parent ? transpose3(standingTurnOf(asset, parent, path)) : IDENTITY;
-    const turned = !isIdentity(back);
-    const own = AXES.map(a => j.origin?.turn?.[a] ?? 0);
-    /* The child as it stands: its quarter turn, then its twist about the normal of the face it is fastened by. */
-    const childFace = childFaceOf(m, j);
-    const normal = FIGURE_FACES[childFace];
-    const standing = j.origin?.twist ? mul3(axisTurn(normal, j.origin.twist), turnMatrix(own)) : turnMatrix(own);
-    /* In the parent's frame: its twist about the face's normal there, and the quarter turn that is left. */
-    const inParent = mul3(back, standing);
-    const localNormal = axisOf(mv3(back, FACE_VECTOR[childFace]), `${j.body1.part}'s ${childFace}`, parent ?? '', back, path);
-    /* The record's twist, about the normal as it lies in the parent's frame; what is left is a quarter turn. */
-    /*
-      In the parent's frame the child stands twisted about the face's normal -- by its own twist, and back by its
-      parent's -- after a quarter turn. The twist is the one nearest what the record asks for.
-    */
-    const alongNormal = mv3(back, AXES.map(a => (a === normal ? 1 : 0)));
-    const asked = (j.origin?.twist ?? 0) * Math.sign(alongNormal[AXES.indexOf(localNormal.axis)]);
-    const { quarter, deg } = splitTwist(inParent, localNormal.axis, asked, path);
+    const { pose } = partOf(m, child, child);
+    const noTurn = constantOf(m, 'deg', 0, 'a');
     const old = pose.args.slice(3, 6);
-    pose.args = [
-        ...pose.args.slice(0, 3),
-        ...(turned || j.origin?.twist ? eulerOf(quarter) : own).map(t => constantOf(m, 'deg', t, 'a'))
-    ];
+    pose.args = [...pose.args.slice(0, 3), noTurn, noTurn, noTurn];
     for (const ref of old)
         dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
-    const face = (name) => turned && Object.hasOwn(FACE_VECTOR, name)
-        ? faceAlong(axisOf(mv3(back, FACE_VECTOR[name]), name, parent ?? '', back, path).vector)
-        : name;
-    attach(asset, {
-        kind: 'attach',
-        part: child,
-        face: face(j.body1.face),
-        to: 'plane' in j.body0
-            ? { plane: 'mounting-plane' }
-            : { part: j.body0.part, face: face(j.body0.face) },
-        ...(j.origin?.facing ? { facing: j.origin.facing } : {}),
-        ...(j.origin?.gap !== undefined ? { gap: j.origin.gap } : {}),
-        /*
-          A distance across the face is measured in the twisted frame (see `attach`), so under a twisted parent it is
-          carried by the parent's quarter turn only; the twists turn it after.
-        */
-        ...(j.origin?.align
-            ? {
-                align: turned
-                    ? alignInto(parent ? transpose3(standingQuarterOf(asset, parent, path)) : back, j.origin.align, path)
-                    : j.origin.align
-            }
-            : {}),
-        replace: true
-    }, deg ? { axis: localNormal.axis, deg } : undefined);
-    /* The measuring was done on the quarter turn; the part stands with its twist. */
-    if (deg) {
-        const now = pose.args.slice(3, 6);
-        pose.args = [...pose.args.slice(0, 3), ...eulerOfAny(inParent).map(t => constantOf(m, 'deg', t, 'a'))];
-        for (const ref of now)
-            dropIfUnused(asset, ref);
-    }
-    if (j.repeat && turned)
-        fail('JOINT_SCHEMA', `joints.${j.id}.repeat`, `${parent} stands turned; a row across a turned part is not covered yet`);
+    const name = namer(m, `${child}.on.${parent}`);
+    const zero = constantOf(m, 'mm', 0, 'd');
+    /* By its middle: the middle of its real extent (ADR-0140 3.4), from its origin -- or by its origin, nothing. */
+    const centre = (x) => {
+        if ('at' in j.body1)
+            return zero;
+        const along = (sign) => figureShapeExtremeAlong(m, child, AXES.map(a => (a === x ? sign : 0)), path);
+        return writeFigureReach(m, name, times(plus(along(1), times(along(-1), -1)), -0.5), `own-centre.${x}`);
+    };
+    const shift = j.origin?.offset ?? {};
+    const seat = AXES.map(x => shift[x] === undefined ? zero : measureRef(m, asset, name, shift[x], `offset.${x}`, `${path}.origin.offset.${x}`));
+    reseat(asset, child, `${parent}.local`, { seat, pose: AXES.map(centre) });
+    if (hasParentRotate(j))
+        turnSeat(asset, child, rpyMatrix(j.origin.parentRotate), j.origin.parentRotate, IDENTITY);
+}
+/**
+ * A moving joint's motion, at the joint frame, about or along its axis turned into the parent's frame by `back`: a token
+ * is one of the parent's axes, either way along it (a parent standing twisted refuses one that is not); a vector goes
+ * as it is, as its unit vector (URDF's axis). A row is laid out last, once its part's motion is written.
+ */
+function moveJoint(asset, j, back) {
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const parent = 'part' in j.body0 ? j.body0.part : undefined;
+    const path = `joints.${j.id}`;
     /* A row is laid out last, once its part's motion is written: every copy moves on it (a roller row spinning). */
     if (j.type === 'fixed') {
         if (j.repeat)
@@ -319,10 +371,17 @@ function writeJoint(asset, j) {
         k: t.multiplier
     }));
     /* The axis turned into the parent's frame too: one of its axes, either way along it. */
-    const along = mv3(back, AXES.map(a => (a === j.axis.toLowerCase() ? 1 : 0)));
-    const axisIndex = along.findIndex(v => Math.abs(Math.abs(v) - 1) < 1e-9);
+    const vector = jointVectorOf(j.axis, path);
+    const along = mv3(back, vector ?? AXES.map(a => (a === j.axis.toLowerCase() ? 1 : 0)));
+    const axisIndex = vector ? 0 : along.findIndex(v => Math.abs(Math.abs(v) - 1) < 1e-9);
     if (axisIndex < 0)
         fail('JOINT_SCHEMA', path, `${parent} stands twisted; the axis ${j.axis} is not level with an axis in it`);
+    /* Twelve places, as a twist's factors: the same record writes the same constants however the vector was turned. */
+    const direction = vector
+        ? along.map(v => (Math.abs(v) < 1e-12 ? 0 : Math.round(v * 1e12) / 1e12))
+        : along[axisIndex] > 0
+            ? 1
+            : -1;
     addMotion(asset, {
         kind: 'add-motion',
         part: child,
@@ -353,7 +412,7 @@ function writeJoint(asset, j) {
             c: j.mimic.offset ?? 0,
             sum: Object.hasOwn(j.mimic, 'sum')
         }
-        : undefined, along[axisIndex] > 0 ? 1 : -1);
+        : undefined, direction);
     if (j.repeat)
         repeatPart(asset, j);
 }
@@ -372,21 +431,20 @@ function repeatPart(asset, j) {
     const theirs = ownSpansOf(m, parent, path)[axis];
     if (!theirs)
         fail('EDIT_TARGET', path, `${parent} has no two faces along ${axis}; there is no length to fill`);
-    const mine = standingSpansOf(m, asset, part, path)[axis];
-    /* A frustum has no faces across its axis; it is as wide there as its wider end (G6). */
-    const widest = mine ? undefined : frustumWidthAlong(m, asset, part, axis, path);
-    if (!mine && !widest)
-        fail('EDIT_TARGET', path, `${part} has no two faces along ${axis}; its copies cannot be spaced`);
+    /* The part's reach both ways along the row, in its pose (ADR-0140 3.2): its extent, and its middle from its origin. */
+    const C = rpyMatrix(j.origin?.childRotate ?? {});
+    const along = (sign) => figureShapeExtremeAlong(m, part, mv3(transpose3(C), AXES.map(a => (a === axis ? sign : 0))), path);
+    const [ahead, behind] = [along(1), along(-1)];
     const { place, pose } = partOf(m, part, path);
     const seat = nodeById(m, `${part}.seat.rigid`);
     const name = namer(m, `${part}.row`);
     const zero = constantOf(m, 'mm', 0, 'd');
     /* The seat moves to the row's start; each copy's centre is where the layout puts it from there. */
     seat.args = seat.args.map((ref, i) => (i === k ? sumOf(m, name, theirs.lo, 'start') : ref));
-    const own = widest || mine.centred ? zero : sumOf(m, name, neg([...half(mine.lo), ...half(mine.hi)]), 'own-centre');
+    const own = writeFigureReach(m, name, times(plus(ahead, times(behind, -1)), -0.5), 'own-centre');
     pose.args = pose.args.map((ref, i) => (i === k ? own : ref));
     const length = sumOf(m, name, [...theirs.hi, ...neg(theirs.lo)], 'length');
-    const extent = widest ?? sumOf(m, name, [...mine.hi, ...neg(mine.lo)], 'extent');
+    const extent = writeFigureReach(m, name, plus(ahead, behind), 'extent');
     const centred = constantOf(m, 'ratio', 0.5, 'k');
     const limit = constantOf(m, 'count', REPEAT_LIMIT, 'limit');
     const count = j.repeat.count;
@@ -512,8 +570,9 @@ export function stripJoint(asset, j) {
 }
 /**
  * Every length a joint record holds that may follow something, read as a measure, with a way to write it back: the
- * gap, a row's pitch, a slide's travel (its one-term form names the source `source`, and without one is `plus` mm)
- * and each offset across the face. Renaming a part and taking one away read and write them all alike.
+ * gap, a row's pitch, a slide's travel (its one-term form names the source `source`, and without one is `plus` mm),
+ * each offset across the face and each of the joint frame's offset (ADR-0107). Renaming a part and taking one away
+ * read and write them all alike.
  */
 export function jointMeasures(j) {
     const out = [];
@@ -557,6 +616,9 @@ export function jointMeasures(j) {
                 set: v => (how.mm = v)
             });
     }
+    for (const axis of Object.keys(j.origin?.offset ?? {}))
+        if (j.origin.offset[axis] !== undefined)
+            out.push({ at: `offset.${axis}`, get: () => j.origin.offset[axis], set: v => (j.origin.offset[axis] = v) });
     return out;
 }
 /** The same measure with each term's source put through `to`, in the form it was written. */
@@ -610,11 +672,23 @@ export function rewriteJoints(asset) {
         for (const n of asset.document.model.nodes)
             if (n.op === 'member@1' && !nodeById(asset.document.model, `${n.id}.repeat`))
                 n.op = 'place@1';
+        /*
+          What the joints' nodes read before they go: a reach reads a shape's own values -- a pyramid's apex, a drawn
+          section's corners -- and an edit that took one away left it while the old nodes still read it. Once the joints are
+          written again, a part's own input nothing reads any more goes too.
+        */
+        const m = asset.document.model;
+        const read = new Set(m.nodes.filter(n => joints.some(j => n.id.startsWith(`${j.body1.part}.on.`))).flatMap(n => n.args));
         for (const j of [...order].reverse())
             stripJoint(asset, j);
         for (const j of order)
             writeJoint(asset, j);
         gatherRows(asset, joints);
+        for (const ref of read) {
+            const owner = m.nodes.find(n => n.op === 'place@1' && ref.startsWith(`${n.id}.`))?.id;
+            if (owner && ownInput(m, owner, ref))
+                dropIfUnused(asset, ref, ref);
+        }
         // 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)
@@ -625,20 +699,14 @@ export 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);
-        /* A part turned by any angle about the normal of the face it is fastened by keeps that angle as its twist. */
-        const n = AXES.indexOf(FIGURE_FACES[childFaceOf(asset.document.model, j)]);
-        const quarter = (t) => t !== null && Number.isFinite(t) && Math.abs(t / 90 - Math.round(t / 90)) < 1e-9;
-        const twist = !quarter(turn[n]) && turn.every((t, i) => i === n || t === 0) ? turn[n] : undefined;
-        if (twist !== undefined && !j.origin?.twist)
-            j.origin = { ...(j.origin ?? {}), twist };
-        else if (turn.some(t => t !== 0))
-            j.origin = {
-                ...(j.origin ?? {}),
-                turn: Object.fromEntries(AXES.map((a, i) => [a, turn[i]]))
-            };
+    /*
+      The child's pose now, in the parent's frame, becomes the record's childRotate the first time it is fastened -- by a
+      face, at any angle (ADR-0140 3.6): it keeps the pose it has. At an origin it stands unturned.
+    */
+    if (!jointAbove(asset, j.body1.part) && !j.origin?.childRotate && !isOriginPlaced(j)) {
+        const pose = childRotateOf(asset, j.body1.part, j.body0);
+        if (pose)
+            j.origin = { ...(j.origin ?? {}), childRotate: pose };
     }
     const joints = (asset.joints ?? []).filter(o => o.id !== j.id);
     const followers = joints.filter(o => figureMimicLeadersOf(o).some(t => t.joint === j.id));
@@ -676,10 +744,20 @@ export function applyFaceRemap(asset, part, remap) {
                 continue;
             }
             const face = faceOf(r.to, path);
-            if (j.body0?.part === part)
-                j.body0.face = face;
-            else
-                j.body1.face = face;
+            /*
+              An end placed by an origin is on no face, so there is no face to move it to (ADR-0107 decision 4): refused by
+              name, never skipped -- the caller shows it. At a parent's origin the child is placed by its origin or centre, so
+              a face for the child is refused here too, not later by the joint's own check under another path.
+            */
+            /* The child end is on no face of its own (ADR-0140 3.2): only the end it hangs from has one to move to. */
+            if (j.body0?.part !== part)
+                fail('EDIT_TARGET', path, `${r.ref.id} fastens ${part} by no face of ${part}'s own; only the end it hangs from, on ${'part' in j.body0 ? j.body0.part : 'the plane'}, is on a face`);
+            const end = j.body0;
+            if ('at' in end)
+                fail('EDIT_TARGET', path, end === j.body0
+                    ? `${r.ref.id} hangs at ${part}'s origin, not on a face of it`
+                    : `${part} is placed by its own origin on ${r.ref.id}, not by a face of it`);
+            end.face = face;
             faces.add(face);
         }
         else if (r?.ref?.kind === 'feature') {
@@ -731,6 +809,33 @@ export function removeJoint(asset, id) {
     // Parts hanging from it are written again: they hang from where it stands now.
     rewriteJoints(asset);
 }
+/**
+ * A part's pose now, in the frame of what it would hang from -- the parent's own frame, or the plane's, after the joint
+ * frame's own turn (`parentRotate`) -- as degrees about x, y and z (Rz·Ry·Rx), six places: nothing when it stands
+ * square to it. Read from the figure as drawn at rest: every joint at 0, its reference pose.
+ */
+function childRotateOf(asset, part, body0, parentRotate) {
+    const rest = Object.fromEntries((asset.joints ?? []).filter(j => j.type !== 'fixed' && !j.mimic).map(j => [stateIdOf(j), 0]));
+    const compiled = compileFigureAssetUnjointed(asset);
+    /* A control whose range does not hold 0 is read where it stands: its reference is still 0, but it cannot be drawn there. */
+    const geometry = (() => {
+        try {
+            return compiled.evaluate(rest).geometry;
+        }
+        catch {
+            return compiled.evaluate().geometry;
+        }
+    })();
+    const of = (id) => geometry.find(g => g.id === id && g.pose)?.pose?.r;
+    const mine = of(part);
+    if (!mine)
+        return undefined;
+    const theirs = body0 && 'part' in body0 ? of(body0.part) : IDENTITY;
+    if (!theirs)
+        return undefined;
+    const pose = rpyOf(mul3(transpose3(mul3(theirs, rpyMatrix(parentRotate ?? {}))), mine));
+    return Object.keys(pose).length ? pose : undefined;
+}
 /** `attach` is the modeller's word for a fixed joint: the record says it, whatever joint was there keeps its id and motion. */
 export function fastenAsJoint(asset, a) {
     const was = jointAbove(asset, a.part);
@@ -745,19 +850,19 @@ export function fastenAsJoint(asset, a) {
     let id = a.part;
     for (let k = 2; !was && taken.has(id); k++)
         id = `${a.part}-${k}`;
+    const body0 = to?.plane !== undefined ? { plane: to.plane } : { part: to?.part, face: to?.face };
+    /* Its pose now, in the new parent's frame (ADR-0140 3.6): it is fastened as it stands. */
+    const pose = childRotateOf(asset, a.part, body0, was?.origin?.parentRotate);
     setJoint(asset, {
         ...(was ?? { id, type: 'fixed' }),
-        body0: to?.plane !== undefined ? { plane: to.plane } : { part: to?.part, face: to?.face },
-        body1: { part: a.part, face: a.face },
+        body0,
+        body1: { part: a.part },
         origin: {
-            ...(was?.origin?.turn ? { turn: was.origin.turn } : {}),
-            ...(a.twist !== undefined
-                ? a.twist
-                    ? { twist: a.twist }
-                    : {}
-                : was?.origin?.twist
-                    ? { twist: was.origin.twist }
-                    : {}),
+            ...(pose ? { childRotate: pose } : {}),
+            /* The joint frame's own words stay the joint's, as its motion does. */
+            ...(was?.origin?.pivot ? { pivot: was.origin.pivot } : {}),
+            ...(was?.origin?.offset ? { offset: was.origin.offset } : {}),
+            ...(was?.origin?.parentRotate ? { parentRotate: was.origin.parentRotate } : {}),
             ...(a.facing ? { facing: a.facing } : {}),
             ...(a.gap !== undefined ? { gap: a.gap } : {}),
             ...(a.align ? { align: a.align } : {})