@hatiolab/figure-model 0.1.57 → 0.1.59

package/dist/v3-authoring-actions.js

@@ -22,9 +22,9 @@
  * parent carries the child with it. A part that is fastened to nothing poses straight into the asset frame.
  */
 import { compileV3Asset } from "./v3-asset.js";
-import { compileV3Graph } from "./v3-graph.js";
+import { compileV3Graph, v3ShapeFaces } from "./v3-graph.js";
 import { V3ContractError } from "./v3-contract.js";
-import { AXES } from "./types.js";
+import { AXES, REPEAT_LIMIT } from "./types.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);
@@ -45,7 +45,9 @@ const writerOf = (m, ref) => m.nodes.find((n) => Object.values(n.outputs).includ
 /** A part an authoring command can work with, and the pieces of it those commands need. */
 function partOf(m, id, path) {
     const place = nodeById(m, id);
-    if (!place || place.op !== 'place@1')
+    /* A row's template is the part too: it is placed through its row (`repeatPart`). */
+    const rowTemplate = place?.op === 'member@1' && !!nodeById(m, `${id}.repeat`);
+    if (!place || (place.op !== 'place@1' && !rowTemplate))
         fail('TARGET_ABSENT', path, `${id} is not a placed part`);
     const shape = writerOf(m, place.args[0]);
     if (!shape)
@@ -97,20 +99,18 @@ function requireUnturned(m, asset, id, path) {
  * 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);
+/**
+ * The part's own turn as a signed axis permutation, when it is a whole number of quarter turns; any other turn is
+ * refused and says the angle. With `freeze` the turn is 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 quarterTurnOf(m, asset, id, path, freeze) {
     const turn = turnOf(m, asset, id, path);
     if (turn.every(t => t === 0))
-        return own;
+        return [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
     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
+    const r = turnMatrix(turn);
     if (freeze) {
         const pose = partOf(m, id, path).pose;
         const old = pose.args.slice(3, 6);
@@ -119,10 +119,67 @@ function standingRefsOf(m, asset, id, path, freeze = true) {
         for (const ref of old)
             dropIfUnused(asset, ref, ownInput(m, id, ref) ? ref : undefined);
     }
+    return r;
+}
+/** A quarter turn in degrees about X, Y and Z as `rigid@1` turns (X, then Y, then Z), as a signed axis permutation. */
+function turnMatrix(turn) {
+    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]];
+    return mul3(mul3(X, Y), Z);
+}
+const mul3 = (a, b) => a.map(row => b[0].map((_, j) => row.reduce((sum, v, k) => sum + v * b[k][j], 0)));
+function standingRefsOf(m, asset, id, path, freeze = true) {
+    const own = sizeRefsOf(m, id, path);
+    const r = quarterTurnOf(m, asset, id, path, freeze);
     const standing = {};
     AXES.forEach((axis, i) => (standing[axis] = own[AXES[r[i].findIndex(v => v !== 0)]]));
     return standing;
 }
+const neg = (lin) => lin.map(t => ({ ref: t.ref, k: -t.k }));
+const half = (lin) => lin.map(t => ({ ref: t.ref, k: t.k / 2 }));
+const OUTER = { x: ['left', 'right'], y: ['bottom', 'top'], z: ['back', 'front'] };
+/** A part's declared faces, from its shape's own definition, or a refusal saying the shape has none. */
+function facesOfPart(m, id, path) {
+    const { shape } = partOf(m, id, path);
+    const faces = v3ShapeFaces(shape.op);
+    if (!faces)
+        fail('EDIT_TARGET', path, `${id} is a ${shape.op}; it has no flat face to fasten by`);
+    return { shape, faces: faces };
+}
+const planeOf = (shape, face) => face.plane.map(p => ({ ref: shape.args[p.arg], k: p.k }));
+/** The part's outer faces on each axis in its own frame; an axis without a pair of flat faces has none. */
+function ownSpansOf(m, id, path) {
+    const { shape, faces } = facesOfPart(m, id, path);
+    const spans = {};
+    for (const axis of AXES) {
+        const [lo, hi] = OUTER[axis].map(n => faces[n]);
+        if (!lo || !hi)
+            continue;
+        const l = planeOf(shape, lo), h = planeOf(shape, hi);
+        spans[axis] = { lo: l, hi: h, centred: JSON.stringify(l) === JSON.stringify(neg(h)) };
+    }
+    return spans;
+}
+/**
+ * The part's spans as it stands in its seat, after its own quarter turn (the turn is fixed as `standingRefsOf` fixes
+ * it). A turn that flips an axis swaps its two faces: the part's own right face becomes the standing left.
+ */
+function standingSpansOf(m, asset, id, path) {
+    const own = ownSpansOf(m, id, path);
+    const r = quarterTurnOf(m, asset, id, path, true);
+    const standing = {};
+    AXES.forEach((axis, i) => {
+        const j = r[i].findIndex(v => v !== 0);
+        const span = own[AXES[j]];
+        if (!span)
+            return;
+        standing[axis] = r[i][j] > 0 ? span : { lo: neg(span.hi), hi: neg(span.lo), centred: span.centred };
+    });
+    return standing;
+}
 /** Fresh node ids under a part, so two commands never claim one id. */
 function namer(m, prefix) {
     const taken = new Set([...m.nodes.map((n) => n.id), ...m.nodes.flatMap((n) => Object.values(n.outputs)), ...m.constants.map((c) => c.id), ...m.inputs.map((i) => i.id)]);
@@ -355,30 +412,42 @@ function attach(asset, a) {
         return standOnPlane(asset, a, path);
     if (a.part === to.part)
         fail('ATTACH_CYCLE', path, 'a part cannot be fastened to itself');
-    for (const face of [a.face, to.face])
-        if (!Object.hasOwn(V3_FACES, String(face)))
-            fail('SCHEMA', path, `${String(face)} is not a face`);
+    if (!Object.hasOwn(V3_FACES, String(a.face)))
+        fail('SCHEMA', path, `${String(a.face)} is not a face`);
+    /* The target's faces are the ones its shape declares: a portal's opening as well as its outer faces. */
+    const target = facesOfPart(m, to.part, path);
+    const theirFace = Object.hasOwn(target.faces, String(to.face)) ? target.faces[to.face] : undefined;
+    if (!theirFace)
+        fail('SCHEMA', path, `${to.part} has no face ${String(to.face)}; it has ${Object.keys(target.faces).join(', ')}`);
     const facing = a.facing ?? 'meet';
     if (facing !== 'meet' && facing !== 'flush')
         fail('SCHEMA', path, `${String(facing)} is neither meet nor flush`);
-    const axis = V3_FACES[to.face];
+    const axis = theirFace.axis;
+    const sign = theirFace.normal;
     if (V3_FACES[a.face] !== axis)
         fail('ATTACH_FACE', path, `${a.face} faces along ${V3_FACES[a.face]} and ${to.face} along ${axis}; fastening them would need a turn, which this command does not do`);
-    if (facing === 'meet' && a.face !== OPPOSITE[to.face])
-        fail('ATTACH_FACE', path, `to meet ${to.face}, ${a.part} offers its ${OPPOSITE[to.face]}; pass flush to lay ${a.face} in the same plane instead`);
-    if (facing === 'flush' && a.face !== to.face)
-        fail('ATTACH_FACE', path, `to lie flush with ${to.face}, ${a.part} offers its ${to.face}`);
+    const wanted = Object.keys(V3_FACES).find(f => V3_FACES[f] === axis && SIGN[f] === (facing === 'meet' ? -sign : sign));
+    if (facing === 'meet' && a.face !== wanted)
+        fail('ATTACH_FACE', path, `to meet ${to.face}, ${a.part} offers its ${wanted}; pass flush to lay ${a.face} in the same plane instead`);
+    if (facing === 'flush' && a.face !== wanted)
+        fail('ATTACH_FACE', path, `to lie flush with ${to.face}, ${a.part} offers its ${wanted}`);
     if (parentOf(m, a.part) && !a.replace)
         fail('ATTACH_REPLACED', path, `${a.part} is already fastened to ${parentOf(m, a.part)}; pass replace to move it, or detach it first`);
     // A part cannot end up its own ancestor.
     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 theirs = sizeRefsOf(m, to.part, path);
-    requireUnturned(m, asset, to.part, path);
-    const mine = standingRefsOf(m, asset, a.part, path);
+    /*
+      Measured in the target's own frame, where its faces are the planes its shape declares: the seat is written into
+      that frame. A target standing turned is met there too -- the joint record's words are turned into that frame
+      before this runs (`writeJoint`).
+    */
+    const theirs = ownSpansOf(m, to.part, path);
+    const mine = standingSpansOf(m, asset, a.part, path);
+    const mineAlong = mine[axis];
+    if (!mineAlong)
+        fail('EDIT_TARGET', path, `${a.part} has no flat ${a.face} face`);
     const name = namer(m, `${a.part}.on.${to.part}`);
-    const sign = SIGN[to.face];
     /*
       Along the face's own axis. `meet`: the part's centre is half its own depth past the target's face, plus the
       gap. `flush`: the part's centre is half its own depth back from that face, so its named face lies in it.
@@ -392,24 +461,38 @@ function attach(asset, a) {
     const zero = constantOf(m, 'mm', 0, 'd');
     const translation = { x: '', y: '', z: '' };
     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}`);
+    translation[axis] = sumOf(m, name, planeOf(target.shape, theirFace), `seat.${axis}`);
+    const ownFace = SIGN[a.face] > 0 ? mineAlong.hi : mineAlong.lo;
+    offset[axis] = sumOf(m, name, [...neg(ownFace), { 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.
+      is the middle of the face. A shape not centred on its origin (a portal stands on its bottom) is centred by its
+      faces, not by its origin.
     */
     for (const other of AXES.filter(x => x !== axis)) {
         const how = a.align?.[other] ?? 'centre';
-        if (how === 'centre')
-            translation[other] = constantOf(m, 'mm', 0, 'd');
-        else if (typeof how === 'object' && how && Object.hasOwn(how, 'mm'))
-            translation[other] = measureRef(m, asset, name, how.mm, `align.${other}`, path);
+        const t = theirs[other], o = mine[other];
+        const middle = (span) => (span && !span.centred ? [...half(span.lo), ...half(span.hi)] : []);
+        const centreOf = (span, hint) => (middle(span).length ? sumOf(m, name, middle(span), hint) : constantOf(m, 'mm', 0, 'd'));
+        const ownCentre = () => (middle(o).length ? sumOf(m, name, neg(middle(o)), `own-centre.${other}`) : zero);
+        if (how === 'centre') {
+            translation[other] = centreOf(t, `centre.${other}`);
+            offset[other] = ownCentre();
+        }
+        else if (typeof how === 'object' && how && Object.hasOwn(how, 'mm')) {
+            const mm = measureRef(m, asset, name, how.mm, `align.${other}`, path);
+            translation[other] = middle(t).length ? sumOf(m, name, [...middle(t), { ref: mm, k: 1 }], `align.${other}.from-centre`) : mm;
+            offset[other] = ownCentre();
+        }
         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 }], `edge.${other}`);
-            offset[other] = sumOf(m, name, [{ ref: mine[other].ref, k: -s * 0.5 * mine[other].k }], `own-edge.${other}`);
+            if (!t)
+                fail('ATTACH_FACE', path, `${to.part} has no edges along ${other} to line ${a.part} up with; give the centre or a measured offset`);
+            if (!o)
+                fail('ATTACH_FACE', path, `${a.part} has no edges along ${other} to line up; give the centre or a measured offset`);
+            translation[other] = sumOf(m, name, how === 'min' ? t.lo : t.hi, `edge.${other}`);
+            offset[other] = sumOf(m, name, neg(how === 'min' ? o.lo : o.hi), `own-edge.${other}`);
         }
         else
             fail('SCHEMA', path, `${String(how)} is not an alignment`);
@@ -432,12 +515,16 @@ 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 = standingRefsOf(m, asset, a.part, path);
+    const mine = standingSpansOf(m, asset, a.part, path);
+    if (!mine.y)
+        fail('EDIT_TARGET', path, `${a.part} has no flat ${a.face} face`);
     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);
     const translation = { x: '', y: '', z: '' };
-    translation.y = sumOf(m, name, [{ ref: mine.y.ref, k: outward * 0.5 * mine.y.k }, { ref: gap, k: outward }], 'stand.y');
+    translation.y = sumOf(m, name, [...neg(a.face === 'bottom' ? mine.y.lo : mine.y.hi), { ref: gap, k: outward }], 'stand.y');
+    const zero = constantOf(m, 'mm', 0, 'd');
+    const pose = { x: zero, y: translation.y, z: zero };
     for (const other of ['x', 'z']) {
         const how = a.align?.[other] ?? 'centre';
         if (how === 'centre')
@@ -446,10 +533,13 @@ function standOnPlane(asset, a, path) {
             translation[other] = measureRef(m, asset, name, how.mm, `align.${other}`, 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`);
+        /* A shape not centred on its origin stands centred by its faces. */
+        const span = mine[other];
+        if (span && !span.centred)
+            pose[other] = sumOf(m, name, neg([...half(span.lo), ...half(span.hi)]), `own-centre.${other}`);
     }
     // 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] });
+    reseat(asset, a.part, asset.document.capabilities.assetFrame, { seat: [translation.x, zero, translation.z], pose: [pose.x, pose.y, pose.z] });
     return asset;
 }
 function detach(asset, a) {
@@ -646,6 +736,22 @@ export function applyV3Authoring(source, action) {
         case 'set-repeat':
             setRepeat(asset, action);
             break;
+        case 'make-repeat': {
+            const j = (asset.joints ?? []).find(o => o.body1.part === action.part);
+            if (!j)
+                fail('EDIT_TARGET', `${action.part}.repeat`, `${action.part} is not fastened to anything; fasten it to the part it repeats across first`);
+            const count = action.count === undefined || action.count === 'fills' ? undefined : action.count;
+            setJoint(asset, { ...j, repeat: { axis: String(action.axis).toUpperCase(), pitch: action.pitch, ...(count !== undefined ? { count } : {}) } });
+            break;
+        }
+        case 'remove-repeat': {
+            const j = (asset.joints ?? []).find(o => o.body1.part === action.part);
+            if (!j?.repeat)
+                fail('EDIT_TARGET', `${action.part}.repeat`, `${action.part} is not repeated`);
+            const { repeat: _gone, ...once } = j;
+            setJoint(asset, once);
+            break;
+        }
         case 'nudge-part':
             nudgePart(asset, action);
             break;
@@ -838,6 +944,31 @@ function checkJoint(asset, j) {
         if (!Number.isFinite(j.mimic.multiplier))
             fail('JOINT_SCHEMA', path, 'a mimic has a multiplier');
     }
+    /* A part in a row is its copies: nothing can hang from one place of it. */
+    const repeatedParent = 'part' in j.body0 ? others.find(o => o.repeat && o.body1.part === j.body0.part) : undefined;
+    if (repeatedParent)
+        fail('JOINT_SCHEMA', path, `${repeatedParent.body1.part} is repeated; its copies have no one place for ${j.body1.part} to hang from`);
+    if (j.repeat) {
+        const r = j.repeat;
+        const row = `${path}.repeat`;
+        if (j.type !== 'fixed')
+            fail('JOINT_SCHEMA', row, 'a part in a row does not move on a joint of its own (ADR-0093); fasten it fixed to repeat it');
+        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');
+        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() === V3_FACES[j.body1.face])
+            fail('JOINT_SCHEMA', row, `a row runs across the face it is fastened to; ${r.axis} is out of that face`);
+        if (!(Number.isFinite(r.pitch) && r.pitch > 0))
+            fail('GEOMETRY_DOMAIN', row, 'a row has a positive pitch');
+        if (r.count !== undefined && !(Number.isSafeInteger(r.count) && r.count >= 1 && r.count <= REPEAT_LIMIT))
+            fail('GEOMETRY_DOMAIN', row, `a row has 1 to ${REPEAT_LIMIT} copies`);
+        const held = others.filter(o => 'part' in o.body0 && o.body0.part === j.body1.part).map(o => o.body1.part);
+        if (held.length)
+            fail('JOINT_SCHEMA', row, `${j.body1.part} holds ${held.join(', ')}; a part in a row holds nothing`);
+        if (others.some(o => o.mimic?.joint === j.id))
+            fail('JOINT_SCHEMA', row, `a joint follows ${j.id}; a part in a row does not move`);
+    }
 }
 /**
  * Write a joint's nodes from its record: the child's quarter turn, the fastening (the seat on the parent's face and
@@ -848,39 +979,172 @@ function writeJoint(asset, j) {
     const m = asset.document.model;
     const child = j.body1.part;
     const { pose } = partOf(m, child, child);
+    /*
+      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).
+    */
+    const parent = 'part' in j.body0 ? j.body0.part : undefined;
+    const back = parent ? transpose3(standingTurnOf(asset, parent, `joints.${j.id}`)) : IDENTITY;
+    const turned = !isIdentity(back);
+    const own = AXES.map(a => j.origin?.turn?.[a] ?? 0);
+    const turn = turned ? eulerOf(mul3(back, turnMatrix(own))) : own;
     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'))];
+    pose.args = [...pose.args.slice(0, 3), ...turn.map(t => constantOf(m, 'deg', t, 'a'))];
     for (const ref of old)
         dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
+    const face = (name) => (turned && Object.hasOwn(FACE_VECTOR, name) ? faceAlong(mv3(back, FACE_VECTOR[name])) : name);
     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 },
+        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 } : {}),
-        ...(j.origin?.align ? { align: j.origin.align } : {}),
+        ...(j.origin?.align ? { align: turned ? alignInto(back, j.origin.align, `joints.${j.id}`) : j.origin.align } : {}),
         replace: true
     });
+    if (j.repeat) {
+        if (turned)
+            fail('JOINT_SCHEMA', `joints.${j.id}.repeat`, `${parent} stands turned; a row across a turned part is not covered yet`);
+        return repeatPart(asset, j);
+    }
     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);
+    /* 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 => v !== 0);
     addMotion(asset, {
         kind: 'add-motion',
         part: child,
-        motion: { kind, axis: j.axis.toLowerCase() },
+        motion: { kind, axis: AXES[axisIndex] },
         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);
+    }, leader ? { of: stateIdOf(leader), k: j.mimic.multiplier, c: j.mimic.offset ?? 0 } : undefined, along[axisIndex] > 0 ? 1 : -1);
+}
+const IDENTITY = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const isIdentity = (r) => r.every((row, i) => row.every((v, k) => v === (i === k ? 1 : 0)));
+const transpose3 = (r) => r[0].map((_, i) => r.map(row => row[i]));
+const mv3 = (r, v) => r.map(row => row.reduce((sum, x, k) => sum + x * v[k], 0));
+const FACE_VECTOR = { left: [-1, 0, 0], right: [1, 0, 0], bottom: [0, -1, 0], top: [0, 1, 0], back: [0, 0, -1], front: [0, 0, 1] };
+const faceAlong = (v) => Object.keys(FACE_VECTOR).find(f => FACE_VECTOR[f].every((x, i) => x === v[i]));
+/**
+ * How a part stands, as a signed axis permutation: its own quarter turn, which its joint record keeps (the pose may
+ * carry the turn back given under a turned parent). A part with no joint stands as its pose turns it. Any turn but
+ * quarter turns is refused and says the angle: nothing can be fastened level with its faces.
+ */
+function standingTurnOf(asset, part, path) {
+    const record = (asset.joints ?? []).find(o => o.body1.part === part);
+    const turn = record ? AXES.map(a => record.origin?.turn?.[a] ?? 0) : turnOf(asset.document.model, asset, part, path);
+    if (turn.every(t => t === 0))
+        return IDENTITY;
+    if (turn.some(t => t === null || !Number.isFinite(t) || Math.abs(t / 90 - Math.round(t / 90)) > 1e-9))
+        fail('EDIT_TARGET', path, `${part} is turned (${saidTurn(turn)}); fastening to a turned part by its faces is covered only for quarter turns`);
+    return turnMatrix(turn);
+}
+/** A quarter-turn matrix back as degrees about X, Y and Z in the order `rigid@1` turns. */
+function eulerOf(r) {
+    const deg = (a) => {
+        const d = Math.round((a * 180) / Math.PI / 90) * 90;
+        return d === 0 ? 0 : d;
+    };
+    const out = Math.abs(r[0][2]) < 1
+        ? [deg(Math.atan2(-r[1][2], r[2][2])), deg(Math.asin(r[0][2])), deg(Math.atan2(-r[0][1], r[0][0]))]
+        : [deg(Math.atan2(r[1][0], r[1][1])), deg(Math.asin(r[0][2])), 0];
+    if (!turnMatrix(out).every((row, i) => row.every((v, k) => v === r[i][k])))
+        throw new Error(`no turn gives ${JSON.stringify(r)}`);
+    return out;
+}
+/** Where a part sits across a face, said on the standing axes, turned onto the parent's own: an edge flips where an axis does. */
+function alignInto(back, align, path) {
+    const out = {};
+    for (const [a, how] of Object.entries(align)) {
+        const v = mv3(back, AXES.map(x => (x === a ? 1 : 0)));
+        const k = v.findIndex(x => x !== 0);
+        const s = v[k];
+        const to = AXES[k];
+        if (how === 'centre' || s > 0)
+            out[to] = how;
+        else if (how === 'min' || how === 'max')
+            out[to] = how === 'min' ? 'max' : 'min';
+        else if (typeof how.mm === 'number')
+            out[to] = { mm: -how.mm };
+        else
+            fail('SCHEMA', path, `an offset that follows another value cannot be turned over onto ${to}; give it as a number`);
+    }
+    return out;
+}
+/**
+ * A fastened part made a row (r3 §8): its placement becomes the template of a `repeat@1`. The row starts at the
+ * parent's lower edge along the axis and runs to its upper edge, so its length is the parent's and follows it; each
+ * copy stands as the fastening put the part, moved along the axis. The part keeps its id, as the row's template.
+ */
+function repeatPart(asset, j) {
+    const m = asset.document.model;
+    const part = j.body1.part;
+    const parent = j.body0.part;
+    const path = `joints.${j.id}.repeat`;
+    const axis = j.repeat.axis.toLowerCase();
+    const k = AXES.indexOf(axis);
+    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];
+    if (!mine)
+        fail('EDIT_TARGET', path, `${part} has no two faces along ${axis}; its copies cannot be spaced`);
+    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 = mine.centred ? zero : sumOf(m, name, neg([...half(mine.lo), ...half(mine.hi)]), '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 = sumOf(m, name, [...mine.hi, ...neg(mine.lo)], 'extent');
+    const centred = constantOf(m, 'ratio', 0.5, 'k');
+    const limit = constantOf(m, 'count', REPEAT_LIMIT, 'limit');
+    const count = j.repeat.count;
+    m.nodes.push(count === undefined
+        ? { id: `${part}.layout`, op: 'fit-pitch@1', args: [length, zero, zero, extent, constantOf(m, 'mm', j.repeat.pitch, 'pitch'), centred, limit], outputs: { layout: `${part}.layout.value` } }
+        : { id: `${part}.layout`, op: 'fixed-count@1', args: [constantOf(m, 'count', count, 'count'), length, zero, zero, extent, centred, limit], outputs: { layout: `${part}.layout.value` } });
+    /* The part is the row's template now: a member, drawn only through the row. */
+    place.op = 'member@1';
+    place.args = [place.args[0], pose.outputs.pose];
+    m.nodes.push({ id: `${part}.assembly`, op: 'assembly@1', args: [place.outputs.placed], outputs: { assembly: `${part}.assembly.value` } });
+    const above = nodeById(m, `${parent}.world`)?.outputs?.pose ?? nodeById(m, `${parent}.chain`)?.outputs?.pose;
+    let root = seat.outputs.pose;
+    if (above) {
+        m.nodes.push({ id: `${part}.row`, op: 'compose@1', args: [above, seat.outputs.pose], outputs: { pose: `${part}.row.value` } });
+        root = `${part}.row.value`;
+    }
+    m.nodes = m.nodes.filter((n) => n.id !== `${part}.chain` && n.id !== `${part}.world`);
+    m.nodes.push({ id: `${part}.repeat`, op: 'repeat@1', args: [`${part}.layout.value`, `${part}.assembly.value`, root], outputs: { collection: `${part}.repeat.value` }, params: { axis } });
+}
+/** A row made back into its one part, so its fastening can be taken away or written again. */
+function unrepeatPart(asset, part) {
+    const m = asset.document.model;
+    const template = nodeById(m, part);
+    if (template?.op !== 'member@1' || !nodeById(m, `${part}.repeat`))
+        return;
+    const layout = nodeById(m, `${part}.layout`);
+    const row = new Set([`${part}.layout`, `${part}.assembly`, `${part}.repeat`, `${part}.row`]);
+    const gone = m.nodes.filter((n) => row.has(n.id) || n.id.startsWith(`${part}.row.`));
+    m.nodes = m.nodes.filter((n) => !gone.includes(n));
+    template.op = 'place@1';
+    for (const ref of layout?.args ?? [])
+        dropIfUnused(asset, ref);
 }
 /** 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;
+    unrepeatPart(asset, child);
     if (nodeById(m, `${child}.motion`))
         removeMotion(asset, { kind: 'remove-motion', part: child });
     const { pose, place } = partOf(m, child, child);
@@ -930,6 +1194,72 @@ function rewriteJoints(asset) {
         if (j.type !== 'fixed' && !j.mimic && keep[stateIdOf(j)] !== undefined)
             asset.stateDefaults[stateIdOf(j)] = keep[stateIdOf(j)];
 }
+/*
+ * A part edit that renames or removes a part reads the joint records first: the records are the canon and the joint
+ * nodes are made from them (ADR-0093). Renaming or deleting a part in the graph alone left records naming a part that
+ * was no longer there, and the author could not save (TARGET_ABSENT on joints.*, 2026-09-25).
+ */
+/** The records follow a part's new name -- as a joint's parent, as its child, and as the joint a follower follows -- and the nodes are made again from them. */
+export function renameV3PartInJoints(asset, from, to) {
+    const joints = asset.joints;
+    if (!joints?.length)
+        return;
+    const name = (id) => (id === from ? to : id);
+    asset.joints = joints.map(j => ({
+        ...j,
+        id: name(j.id),
+        body0: 'part' in j.body0 ? { ...j.body0, part: name(j.body0.part) } : j.body0,
+        body1: { ...j.body1, part: name(j.body1.part) },
+        ...(j.mimic ? { mimic: { ...j.mimic, joint: name(j.mimic.joint) } } : {}),
+        ...(j.state?.id !== undefined ? { state: { ...j.state, id: name(j.state.id) } } : {})
+    }));
+    rewriteJoints(asset);
+}
+/**
+ * A copied part is fastened as the original is: its own record, the same faces and place, so it is not held by nodes
+ * no record makes. A moving joint gets its own control -- a copy is a second thing, not the original's shadow.
+ */
+export function copyV3PartJoint(asset, from, to) {
+    const joints = (asset.joints ?? []);
+    const j = joints.find(o => o.body1.part === from);
+    if (!j)
+        return;
+    const m = asset.document.model;
+    const ids = new Set(joints.map(o => o.id));
+    const inputs = new Set(m.inputs.map((i) => i.id));
+    const fresh = (base, taken) => {
+        let id = base;
+        for (let n = 2; taken.has(id); n++)
+            id = `${base}-${n}`;
+        return id;
+    };
+    const id = fresh(j.id === from ? to : `${j.id}-copy`, ids);
+    const copy = { ...structuredClone(j), id, body1: { ...j.body1, part: to } };
+    if (j.type !== 'fixed' && !j.mimic)
+        copy.state = { ...(j.state ?? {}), id: fresh(j.state?.id ? `${j.state.id}-copy` : id, inputs) };
+    asset.joints = [...joints, copy];
+    rewriteJoints(asset);
+}
+/**
+ * Before a part is taken away. What hangs from it, or follows its joint, is named and the removal refused -- a
+ * silent cascade would take parts the author did not pick. A part nothing hangs from goes with its own joint.
+ */
+export function releaseV3PartJoints(asset, part) {
+    const joints = (asset.joints ?? []);
+    const hanging = joints.filter(j => 'part' in j.body0 && j.body0.part === part).map(j => j.body1.part);
+    if (hanging.length)
+        fail('PART_REFERENCED', part, `${part} holds ${hanging.join(', ')}; take ${hanging.length > 1 ? 'them' : 'it'} off first`);
+    const own = joints.find(j => j.body1.part === part);
+    if (!own)
+        return;
+    const followers = joints.filter(o => o.mimic?.joint === own.id).map(o => o.body1.part);
+    if (followers.length)
+        fail('PART_REFERENCED', part, `${followers.join(', ')} ${followers.length > 1 ? 'move' : 'moves'} with ${part}; make ${followers.length > 1 ? 'them' : 'it'} move on ${followers.length > 1 ? 'their' : 'its'} own first`);
+    asset.joints = joints.filter(j => j.id !== own.id);
+    if (!asset.joints.length)
+        delete asset.joints;
+    stripJoint(asset, own);
+}
 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));
@@ -1024,7 +1354,7 @@ const attachmentFrameOf = (asset, id) => {
     const parent = parentOf(asset.document.model, id);
     return parent ? `${parent}.local` : asset.document.capabilities.assetFrame;
 };
-function addMotion(asset, a, follow) {
+function addMotion(asset, a, follow, sign = 1) {
     const m = asset.document.model;
     const path = a.part;
     partOf(m, a.part, path);
@@ -1089,7 +1419,7 @@ function addMotion(asset, a, follow) {
     }
     else if (a.motion.kind === 'slide' && a.travel)
         fail('SCHEMA', path, 'a mm control is the distance; travel would say it twice');
-    const unit = AXES.map(x => constantOf(m, 'ratio', x === a.motion.axis ? 1 : 0, 'axis'));
+    const unit = AXES.map(x => constantOf(m, 'ratio', x === a.motion.axis ? sign : 0, 'axis'));
     m.nodes.push({
         id: `${a.part}.motion`,
         op: a.motion.kind === 'slide' ? 'axis-slide@1' : 'axis-turn@1',
@@ -1730,6 +2060,12 @@ const mostChanged = (a, b) => {
 function setRepeat(asset, a) {
     const m = asset.document.model;
     const path = `${a.part}.repeat`;
+    /* A row made in the modeller lives in its fastening's record: the pitch changes there, and the row is made again. */
+    const record = (asset.joints ?? []).find(o => o.body1.part === a.part && o.repeat);
+    if (record) {
+        setJoint(asset, { ...record, repeat: { ...record.repeat, pitch: a.pitch } });
+        return asset;
+    }
     const layout = nodeById(m, `${a.part}.layout`);
     if (!layout || !nodeById(m, `${a.part}.repeat`))
         fail('EDIT_TARGET', path, `${a.part} is not a repeated part`);