@hatiolab/figure-model 0.7.3 → 0.9.0

package/dist/authoring-fastening.d.ts

@@ -1,12 +1,57 @@
 import { type Axis } from './words.ts';
-import { type FigureAuthoringAction, type FigureMotionRequest } from './authoring-types.ts';
+import { type FigureJoint, type FigureJointPivot, type FigureMeasure, type FigureMotionRequest } from './authoring-types.ts';
 type Dynamic = any;
-export declare function attach(asset: Dynamic, a: Extract<FigureAuthoringAction, {
-    kind: 'attach';
-}>, twist?: {
-    axis: Axis;
-    deg: number;
-}): Dynamic;
+/**
+ * A joint frame's own words, as `writeJoint` hands them on (ADR-0107, contract 2026-10-03): the pivot, the offset and
+ * the parent end's rotation.
+ */
+export interface JointFrame {
+    pivot?: FigureJointPivot;
+    offset?: Partial<Record<Axis, FigureMeasure>>;
+    parentRotate?: Partial<Record<Axis, number>>;
+    path: string;
+}
+/**
+ * A part fastened, in the pose `childRotate` gives it, to a face of its parent or to the mounting plane (ADR-0140 3):
+ * its real shape meets the face -- by its outermost point toward it (`meet`), away from it (`flush`), or their middle
+ * (`centre`) -- and its real extent lines up across it. Everything is said in the parent's own frame (3.11), and
+ * written as graph nodes of the shapes' own values (3.3), so it holds as either is resized.
+ *
+ * Along the face's outward normal n (a coordinate c, the face at c_f, σ its sign on its axis):
+ *     meet    c = c_f + σ·(gap + e(−n))        flush   c = c_f − σ·(gap + e(+n))
+ *     centre  c = c_f + σ·(gap + (e(−n) − e(+n)) / 2)
+ * and across it on each axis u, by the reaches e(±u):
+ *     centre  c = mid + mm − (e(+u) − e(−u)) / 2      min  c = lo + e(−u)      max  c = hi − e(+u)
+ * where e(d) is how far the part reaches along d in its pose (figureShapeExtremeAlong). The seat -- the point it turns
+ * about -- is the point it is lined up by, on the face (3.10): the edge it is level with -- a hinge (ADR-0107 decision 1)
+ * -- or the middle of its real extent; or its pivot. The pose is the part's origin from there.
+ */
+export declare function placeOnFace(asset: Dynamic, j: FigureJoint, frame: JointFrame): void;
+/**
+ * The seat turned by a joint frame's parent-end rotation (`rigid@1` turns X, then Y, then Z). Its angles are named by
+ * the rotation the record gives, and by the parent's standing turn when that is not none -- not by their value, which
+ * carries float noise -- and rounded to twelve places, as a twist's factors are (JOINT_DRIFT, 2026-09-25).
+ */
+export declare function turnSeat(asset: Dynamic, part: string, r: number[][], rotate: Partial<Record<Axis, number>>, back: number[][]): void;
+/**
+ * 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.
+ */
+/**
+ * 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).
+ */
+export declare function reseat(asset: Dynamic, id: string, to: string, place?: {
+    seat: string[];
+    pose: string[];
+}): void;
 export declare function addMotion(asset: Dynamic, a: FigureMotionRequest, follow?: {
     terms: Array<{
         of: string;
@@ -14,7 +59,7 @@ export declare function addMotion(asset: Dynamic, a: FigureMotionRequest, follow
     }>;
     c: number;
     sum: boolean;
-}, sign?: 1 | -1): Dynamic;
+}, sign?: 1 | -1 | number[]): Dynamic;
 /** "This part does not move any more." The control it created goes with it, and so does its clip. */
 export declare function removeMotion(asset: Dynamic, a: {
     kind: 'remove-motion';

package/dist/authoring-fastening.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring-fastening.d.ts","sourceRoot":"","sources":["../src/authoring-fastening.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,IAAI,EAAQ,MAAM,YAAY,CAAA;AAC5C,OAAO,EAKL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAgC7B,KAAK,OAAO,GAAG,GAAG,CAAA;AAElB,wBAAgB,MAAM,CACpB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,OAAO,CAAC,qBAAqB,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EACrD,KAAK,CAAC,EAAE;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC,OAAO,CA+NT;AAkLD,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,mBAAmB,EACtB,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,EAC7E,IAAI,GAAE,CAAC,GAAG,CAAC,CAAK,GACf,OAAO,CA8KT;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAsBhG"}
+{"version":3,"file":"authoring-fastening.d.ts","sourceRoot":"","sources":["../src/authoring-fastening.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,IAAI,EAAQ,MAAM,YAAY,CAAA;AAC5C,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAkC7B,KAAK,OAAO,GAAG,GAAG,CAAA;AAElB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAA;IAC7C,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5C,IAAI,EAAE,MAAM,CAAA;CACb;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CA2GnF;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,EAAE,EAAE,EACb,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,EAAE,EAAE,QAkBjB;AAED;;;GAGG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAuE/G;AAQD,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,CAAC,EAAE,mBAAmB,EACtB,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,EAC7E,IAAI,GAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,EAAM,GAC1B,OAAO,CAiLT;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAsBhG"}

package/dist/authoring-fastening.js

@@ -7,257 +7,170 @@
  */
 import { figurePlacementOf } from "./asset.js";
 import { AXES } from "./words.js";
-import { FIGURE_FACES, SIGN } from "./authoring-types.js";
+import { FIGURE_FACINGS } from "./authoring-types.js";
+import { figureShapeExtremeAlong, lin, plus, times, writeFigureReach } from "./shape-extreme.js";
 import { fail, nodeById, writerOf, partOf, namer, constantOf, scaled, measureRef, termRefs, sumOf, sourceRef, ownInput, dropIfUnused, parentOf, round6, sizeInputOf } from "./authoring-nodes.js";
-import { neg, half, facesOfPart, planeOf, ownSpansOf, standingSpansOf, planeFacesOf, ACROSS } from "./authoring-geometry.js";
-export function attach(asset, a, twist) {
+import { half, facesOfPart, planeOf, ownSpansOf, transpose3, isIdentity, eulerOfAny, rpyMatrix, mv3, IDENTITY } from "./authoring-geometry.js";
+const unitAlong = (axis, sign) => AXES.map(x => (x === axis ? sign : 0));
+/**
+ * A part fastened, in the pose `childRotate` gives it, to a face of its parent or to the mounting plane (ADR-0140 3):
+ * its real shape meets the face -- by its outermost point toward it (`meet`), away from it (`flush`), or their middle
+ * (`centre`) -- and its real extent lines up across it. Everything is said in the parent's own frame (3.11), and
+ * written as graph nodes of the shapes' own values (3.3), so it holds as either is resized.
+ *
+ * Along the face's outward normal n (a coordinate c, the face at c_f, σ its sign on its axis):
+ *     meet    c = c_f + σ·(gap + e(−n))        flush   c = c_f − σ·(gap + e(+n))
+ *     centre  c = c_f + σ·(gap + (e(−n) − e(+n)) / 2)
+ * and across it on each axis u, by the reaches e(±u):
+ *     centre  c = mid + mm − (e(+u) − e(−u)) / 2      min  c = lo + e(−u)      max  c = hi − e(+u)
+ * where e(d) is how far the part reaches along d in its pose (figureShapeExtremeAlong). The seat -- the point it turns
+ * about -- is the point it is lined up by, on the face (3.10): the edge it is level with -- a hinge (ADR-0107 decision 1)
+ * -- or the middle of its real extent; or its pivot. The pose is the part's origin from there.
+ */
+export function placeOnFace(asset, j, frame) {
     const m = asset.document.model;
-    const to = a.to;
-    const path = `${a.part} to ${to?.plane ?? to?.part}`;
-    if (!to || typeof to !== 'object')
-        fail('SCHEMA', path, 'a target face, or the plane the figure is mounted on, is required');
-    if (to.plane !== undefined)
-        return standOnPlane(asset, a, path);
-    if (a.part === to.part)
-        fail('ATTACH_CYCLE', path, 'a part cannot be fastened to itself');
-    const byCentre = a.face === 'centre';
-    if (!byCentre && !Object.hasOwn(FIGURE_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 = theirFace.axis;
-    const sign = theirFace.normal;
-    if (byCentre && facing !== 'meet')
-        fail('ATTACH_FACE', path, `${a.part} fastened by its centre sits on ${to.face}; flush has no meaning for a centre`);
-    /* By its centre, the part is measured as the face that would meet the target's; only its offset differs. */
-    if (byCentre)
-        a = {
-            ...a,
-            face: Object.keys(FIGURE_FACES).find(f => FIGURE_FACES[f] === axis && SIGN[f] === -sign)
-        };
-    if (FIGURE_FACES[a.face] !== axis)
-        fail('ATTACH_FACE', path, `${a.face} faces along ${FIGURE_FACES[a.face]} and ${to.face} along ${axis}; fastening them would need a turn, which this command does not do`);
-    const wanted = Object.keys(FIGURE_FACES).find(f => FIGURE_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}`);
-    /*
-      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 || !Object.hasOwn(facesOfPart(m, a.part, path).faces, a.face)) && !byCentre)
-        fail('EDIT_TARGET', path, `${a.part} has no flat ${a.face} face`);
-    const name = namer(m, `${a.part}.on.${to.part}`);
-    /*
-      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.
-    */
-    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: '' };
-    const offset = { x: zero, y: zero, z: zero };
-    /* By its centre, the gap goes into the seat: the point fastened at -- and turned about -- is the part's middle. */
-    translation[axis] = sumOf(m, name, [...planeOf(target.shape, theirFace), ...(byCentre ? [{ ref: gap, k: outward }] : [])], `seat.${axis}`);
-    const ownFace = byCentre
-        ? mineAlong && !mineAlong.centred
-            ? [...half(mineAlong.lo), ...half(mineAlong.hi)]
-            : []
-        : SIGN[a.face] > 0
-            ? mineAlong.hi
-            : mineAlong.lo;
-    offset[axis] = byCentre
-        ? ownFace.length
-            ? sumOf(m, name, neg(ownFace), `along.${axis}`)
-            : zero
-        : 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. 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';
-        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();
+    const child = j.body1.part;
+    const path = frame.path;
+    const to = j.body0;
+    const o = j.origin ?? {};
+    const facing = o.facing ?? 'meet';
+    if (!FIGURE_FACINGS.includes(facing))
+        fail('JOINT_SCHEMA', `${path}.origin.facing`, `${String(facing)} is not a facing; ${FIGURE_FACINGS.join(', ')}`);
+    const onPlane = 'plane' in to;
+    const name = namer(m, `${child}.on.${onPlane ? 'plane' : to.part}`);
+    /* The face: its axis, its outward sign and where it lies, in the parent's own frame; across it, the parent's edges. */
+    let axis, sign, plane;
+    const edges = {};
+    if (onPlane) {
+        const placement = figurePlacementOf(asset);
+        axis = placement === 'wall' ? 'z' : 'y';
+        sign = 1;
+        plane = [];
+        if (placement === 'wall' && facing !== 'meet')
+            fail('ATTACH_FACE', path, `the figure hangs on a wall; ${child} stands out of it (meet), not ${facing}`);
+        if (facing === 'centre')
+            fail('JOINT_SCHEMA', `${path}.origin.facing`, 'a part stands on the mounting plane or hangs from it; its middle is not on it');
+        for (const x of AXES.filter(x => x !== axis))
+            if (sizeInputOf(m, x)) {
+                const size = sourceRef(m, asset, { of: 'instance', axis: x }, path);
+                edges[x] = { lo: [{ ref: size, k: -0.5 }], hi: [{ ref: size, k: 0.5 }] };
+            }
+    }
+    else {
+        if (to.part === child)
+            fail('ATTACH_CYCLE', path, 'a part cannot be fastened to itself');
+        const target = facesOfPart(m, to.part, path);
+        const face = Object.hasOwn(target.faces, String(to.face)) ? target.faces[to.face] : undefined;
+        if (!face)
+            fail('SCHEMA', path, `${to.part} has no face ${String(to.face)}; it has ${Object.keys(target.faces).join(', ')}`);
+        axis = face.axis;
+        sign = face.normal;
+        plane = planeOf(target.shape, face);
+        const spans = ownSpansOf(m, to.part, path);
+        for (const x of AXES.filter(x => x !== axis))
+            if (spans[x])
+                edges[x] = { lo: spans[x].lo, hi: spans[x].hi };
+    }
+    /* The child's pose in the parent's frame, and how far its real shape reaches along a direction there. */
+    const rotate = o.childRotate ?? {};
+    const C = rpyMatrix(rotate);
+    const reach = (d) => figureShapeExtremeAlong(m, child, mv3(transpose3(C), d), path);
+    const gap = o.gap === undefined ? lin([]) : lin([{ ref: measureRef(m, asset, name, o.gap, `gap.${axis}`, path), k: 1 }]);
+    const [toward, away] = [reach(unitAlong(axis, -sign)), reach(unitAlong(axis, sign))];
+    const at = {};
+    const seat = {};
+    const face = lin(plane);
+    at[axis] =
+        facing === 'meet'
+            ? plus(face, times(plus(gap, toward), sign))
+            : facing === 'flush'
+                ? plus(face, times(plus(gap, away), -sign))
+                : plus(face, times(plus(gap, times(plus(toward, times(away, -1)), 0.5)), sign));
+    /* On the face; by its middle (centre), at that middle, gap and all -- it turns in place, a roller spinning. */
+    seat[axis] = facing === 'centre' ? plus(at[axis], times(plus(reach(unitAlong(axis, 1)), times(reach(unitAlong(axis, -1)), -1)), 0.5)) : face;
+    for (const u of AXES.filter(x => x !== axis)) {
+        const [hi, lo] = [reach(unitAlong(u, 1)), reach(unitAlong(u, -1))];
+        /* The middle of its real extent, from its origin: (e(+u) − e(−u)) / 2. */
+        const middle = times(plus(hi, times(lo, -1)), 0.5);
+        const how = o.align?.[u] ?? 'centre';
+        const edge = edges[u];
+        if (how === 'min' || how === 'max') {
+            if (!edge)
+                fail(onPlane ? 'SCHEMA' : 'ATTACH_FACE', path, onPlane ? `the plane has no edges to line ${child} up with on ${u}; declare the figure's size, or give the centre or a measured offset` : `${to.part} has no edges along ${u} to line ${child} up with; give the centre or a measured offset`);
+            at[u] = how === 'min' ? plus(lin(edge.lo), lo) : plus(lin(edge.hi), times(hi, -1));
+            /* Level with an edge, it turns about that edge, as a hinge does (ADR-0107 decision 1). */
+            seat[u] = lin(how === 'min' ? edge.lo : edge.hi);
+            continue;
         }
-        else if (how === 'min' || how === 'max') {
-            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 if (how === 'centre' || (typeof how === 'object' && how && Object.hasOwn(how, 'mm'))) {
+            const mid = edge ? lin([...half(edge.lo), ...half(edge.hi)]) : lin([]);
+            const off = typeof how === 'object' ? lin([{ ref: measureRef(m, asset, name, how.mm, `align.${u}`, path), k: 1 }]) : lin([]);
+            at[u] = plus(mid, off, times(middle, -1));
         }
         else
             fail('SCHEMA', path, `${String(how)} is not an alignment`);
+        seat[u] = plus(at[u], middle);
     }
-    /*
-      Twisted about the face's normal: the seat is the face's centre, and the part's own offset across the face -- its
-      distance and its own centre -- turns with it, so a blade set out along X and twisted 120° stands out along the
-      blade, about the hub. With no twist this is the same place written as before.
-    */
-    if (twist && twist.deg) {
-        const [p, q] = ACROSS[axis];
-        for (const other of [p, q]) {
-            const how = a.align?.[other] ?? 'centre';
-            if (how === 'min' || how === 'max')
-                fail('ATTACH_FACE', path, `${a.part} is twisted ${round6(twist.deg)}° about ${axis}; its sides are not level with ${to.part}'s edges -- place it by the centre or a distance`);
-        }
-        const across = (other) => {
-            const how = a.align?.[other] ?? 'centre';
-            const o = mine[other];
-            const own = o && !o.centred ? neg([...half(o.lo), ...half(o.hi)]) : [];
-            return typeof how === 'object' && how && Object.hasOwn(how, 'mm')
-                ? [{ ref: measureRef(m, asset, name, how.mm, `twist.${other}`, path), k: 1 }, ...own]
-                : own;
-        };
-        const [vp, vq] = [across(p), across(q)];
-        /*
-          The turn's factors are named by the angle, as the record gives it -- not by their value, which may carry float
-          noise that depends on how it was computed, so a rewrite named them apart (JOINT_DRIFT, the architect's fan,
-          2026-09-25). Their values are rounded to twelve places, which is the second defence.
-        */
-        const exact = (v) => {
-            const r = Math.round(v * 1e12) / 1e12;
-            return r === 0 ? 0 : r;
-        };
-        const tag = String(round6(twist.deg)).replace('-', 'm').replace('.', '_');
-        const factor = (fn) => {
-            const id = `twist.${fn}.${tag}`;
-            const rad = (twist.deg * Math.PI) / 180;
-            if (!m.constants.some((c) => c.id === id))
-                m.constants.push({
-                    id,
-                    unit: 'ratio',
-                    value: exact(fn === 'cos' ? Math.cos(rad) : fn === 'sin' ? Math.sin(rad) : -Math.sin(rad))
-                });
-            return id;
-        };
-        const times = (ref, k, hint) => {
-            const id = name(hint);
-            m.nodes.push({ id, op: 'mul@1', args: [ref, k], outputs: { value: `${id}.value` } });
-            return `${id}.value`;
-        };
-        const plus = (a, b, hint) => {
-            const id = name(hint);
-            m.nodes.push({ id, op: 'add@1', args: [a, b], outputs: { value: `${id}.value` } });
-            return `${id}.value`;
-        };
-        for (const other of [p, q]) {
-            const t = theirs[other];
-            translation[other] =
-                t && !t.centred
-                    ? sumOf(m, name, [...half(t.lo), ...half(t.hi)], `twist-centre.${other}`)
-                    : constantOf(m, 'mm', 0, 'd');
-        }
-        const sp = sumOf(m, name, vp, `twist-own.${p}`), sq = sumOf(m, name, vq, `twist-own.${q}`);
-        offset[p] = plus(times(sp, factor('cos'), `twisted.${p}.cos`), times(sq, factor('nsin'), `twisted.${p}.sin`), `twisted.${p}`);
-        offset[q] = plus(times(sp, factor('sin'), `twisted.${q}.sin`), times(sq, factor('cos'), `twisted.${q}.cos`), `twisted.${q}`);
+    /* Where it turns (3.10): its lined-up middle on the face, the middle of its real extent, or the centre of its flat face on the face. */
+    const pivot = frame.pivot ?? 'seat';
+    if (pivot === 'child-centre')
+        for (const x of AXES)
+            seat[x] = plus(at[x], times(plus(reach(unitAlong(x, 1)), times(reach(unitAlong(x, -1)), -1)), 0.5));
+    if (pivot === 'child-face') {
+        const own = mv3(transpose3(C), unitAlong(axis, -sign));
+        const k = own.findIndex(v => Math.abs(Math.abs(v) - 1) < 1e-9);
+        const spans = facing === 'meet' && k >= 0 ? ownSpansOf(m, child, path) : {};
+        const along = k >= 0 ? spans[AXES[k]] : undefined;
+        if (!along)
+            fail('JOINT_SCHEMA', `${path}.origin.pivot`, `${child} meets ${onPlane ? 'the plane' : `${to.part}'s ${to.face}`} at a point or a line${facing === 'meet' ? '' : ` (${facing})`}, not by a face of its own; child-face has no face to turn about -- child-centre or seat`);
+        /* The face's centre in the child's own frame, turned into the parent's and placed with the child. */
+        const centre = AXES.map((x, i) => (i === k ? (own[k] > 0 ? along.hi : along.lo) : spans[x] ? [...half(spans[x].lo), ...half(spans[x].hi)] : []));
+        AXES.forEach((x, i) => {
+            seat[x] = plus(at[x], ...AXES.map((_, c) => lin(centre[c].map(t => ({ ref: t.ref, k: t.k * C[i][c] })))));
+        });
     }
-    reseat(asset, a.part, `${to.part}.local`, {
-        seat: [translation.x, translation.y, translation.z],
-        pose: [offset.x, offset.y, offset.z]
+    /* The pose is the child's origin from the seat; the seat moves by the frame's offset (3.10, ADR-0107). */
+    const pose = AXES.map(x => plus(at[x], times(seat[x], -1)));
+    const shift = frame.offset ?? {};
+    const seatAt = AXES.map(x => (shift[x] === undefined || shift[x] === 0 ? seat[x] : plus(seat[x], lin([{ ref: measureRef(m, asset, name, shift[x], `offset.${x}`, `${path}.origin.offset.${x}`), k: 1 }]))));
+    const write = (r, h) => writeFigureReach(m, name, r, h);
+    reseat(asset, child, onPlane ? asset.document.capabilities.assetFrame : `${to.part}.local`, {
+        seat: seatAt.map((r, i) => write(r, `seat.${AXES[i]}`)),
+        pose: pose.map((r, i) => write(r, `pose.${AXES[i]}`))
     });
-    return asset;
+    /* The child's own pose: childRotate is Rz·Ry·Rx (3.6); rigid@1 takes its angles X then Y then Z, so they are worked out. */
+    const { pose: node } = partOf(m, child, path);
+    const old = node.args.slice(3, 6);
+    node.args = [...node.args.slice(0, 3), ...eulerOfAny(C, true).map(t => constantOf(m, 'deg', t, 'a'))];
+    for (const ref of old)
+        dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
+    if (AXES.some(x => (frame.parentRotate?.[x] ?? 0) !== 0))
+        turnSeat(asset, child, rpyMatrix(frame.parentRotate), frame.parentRotate, IDENTITY);
 }
-function standOnPlane(asset, a, path) {
+/**
+ * The seat turned by a joint frame's parent-end rotation (`rigid@1` turns X, then Y, then Z). Its angles are named by
+ * the rotation the record gives, and by the parent's standing turn when that is not none -- not by their value, which
+ * carries float noise -- and rounded to twelve places, as a twist's factors are (JOINT_DRIFT, 2026-09-25).
+ */
+export function turnSeat(asset, part, r, rotate, back) {
     const m = asset.document.model;
-    const to = a.to;
-    if (to.plane !== 'mounting-plane')
-        fail('SCHEMA', path, `${String(to.plane)} is not a plane a part can stand on`);
-    if (a.facing !== undefined && a.facing !== 'meet')
-        fail('SCHEMA', path, 'a part standing on the plane meets it; flush says nothing here');
-    /* Which plane it is, the figure's placement says: the floor or the ceiling is Y = 0, a wall is Z = 0 (ADR-0093). */
-    const placement = figurePlacementOf(asset);
-    const takes = planeFacesOf(placement);
-    const normal = placement === 'wall' ? 'z' : 'y';
-    if (!takes.includes(a.face))
-        fail('ATTACH_FACE', path, placement === 'wall'
-            ? `${String(a.face)} faces along ${FIGURE_FACES[a.face] ?? 'no axis'}; the figure hangs on a wall, the plane Z = 0, so a part is fastened to it by its back`
-            : `${String(a.face)} faces along ${FIGURE_FACES[a.face] ?? 'no axis'}; 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 = standingSpansOf(m, asset, a.part, path);
-    if (!mine[normal] || !Object.hasOwn(facesOfPart(m, a.part, path).faces, a.face))
-        fail('EDIT_TARGET', path, `${a.part} has no flat ${a.face} face`);
-    const name = namer(m, `${a.part}.on.plane`);
-    /* Out of the plane: a bottom stands up from the floor, a back comes out of the wall, a top hangs down. */
-    const outward = a.face === 'top' ? -1 : 1;
-    const gap = measureRef(m, asset, name, a.gap, `gap.${normal}`, path);
-    const translation = { x: '', y: '', z: '' };
-    translation[normal] = sumOf(m, name, [...neg(outward > 0 ? mine[normal].lo : mine[normal].hi), { ref: gap, k: outward }], `stand.${normal}`);
-    const zero = constantOf(m, 'mm', 0, 'd');
-    const pose = { x: zero, y: zero, z: zero };
-    pose[normal] = translation[normal];
-    for (const other of AXES.filter(x => x !== normal)) {
-        const how = a.align?.[other] ?? 'centre';
-        const span = mine[other];
-        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);
-        else if ((how === 'min' || how === 'max') && sizeInputOf(m, other)) {
-            /*
-              The plane has no edges, but a figure that declares its size has a box on it: its sides are half the size
-              either way of the origin. A part level with one keeps to it when the figure is resized -- a door's post at
-              the figure's left, a gantry's legs at its corners (2026-09-25).
-            */
-            if (!span)
-                fail('ATTACH_FACE', path, `${a.part} has no edges along ${other} to line up with the figure's side`);
-            const s = how === 'min' ? -1 : 1;
-            translation[other] = sumOf(m, name, [{ ref: sourceRef(m, asset, { of: 'instance', axis: other }, path), k: s * 0.5 }], `figure-edge.${other}`);
-            pose[other] = sumOf(m, name, neg(how === 'min' ? span.lo : span.hi), `own-edge.${other}`);
-            continue;
-        }
-        else
-            fail('SCHEMA', path, `the plane has no edges to line ${a.part} up with on ${other}; declare the figure's size, or give the centre or a measured offset`);
-        /* A shape not centred on its origin stands centred by its faces. */
-        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 the plane's normal turns it where it stands.
-    const seat = AXES.map(x => (x === normal ? zero : translation[x]));
-    reseat(asset, a.part, asset.document.capabilities.assetFrame, {
-        seat: [seat[0], seat[1], seat[2]],
-        pose: [pose.x, pose.y, pose.z]
-    });
-    return asset;
+    const seat = nodeById(m, `${part}.seat.rigid`);
+    const tag = (deg) => String(round6(deg)).replace('-', 'm').replace('.', '_');
+    const within = isIdentity(back) ? '' : `.in.${eulerOfAny(transpose3(back)).map(tag).join('_')}`;
+    const name = `rotate.${AXES.map(x => tag(rotate[x] ?? 0)).join('_')}${within}`;
+    const angles = eulerOfAny(r, true);
+    const old = seat.args.slice(3, 6);
+    seat.args = [
+        ...seat.args.slice(0, 3),
+        ...AXES.map((x, i) => {
+            const id = `${name}.${x}`;
+            if (!m.constants.some((c) => c.id === id))
+                m.constants.push({ id, unit: 'deg', value: angles[i] });
+            return id;
+        })
+    ];
+    for (const ref of old)
+        dropIfUnused(asset, ref);
 }
 /**
  * Put a part's pose on a new frame with a new translation, and rebuild the chain that carries it to the asset.
@@ -274,7 +187,7 @@ function standOnPlane(asset, a, path) {
  *
  * 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) {
+export function reseat(asset, id, to, place) {
     const m = asset.document.model;
     const { place: placed, pose } = partOf(m, id, id);
     const old = place ? pose.args.slice(0, 3) : [];
@@ -500,7 +413,10 @@ export function addMotion(asset, a, follow, sign = 1) {
     }
     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 ? sign : 0, 'axis'));
+    /* A direction given as a vector (a joint's axis vector) is the motion's unit vector as it is. */
+    const unit = Array.isArray(sign)
+        ? sign.map(v => constantOf(m, 'ratio', v, 'axis'))
+        : 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',