@hatiolab/figure-model 0.5.0 → 0.5.2

package/dist/joint-writing.js

@@ -0,0 +1,847 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+/*
+ * 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 { 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 { 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";
+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'),
+    axes: everyKey()('x', 'y', 'z'),
+    alignment: everyKey()('mm'),
+    measure: everyKey()('from', 'times', 'plus', 'sum'),
+    term: everyKey()('from', 'times'),
+    source: everyKey()('of', 'axis', 'input', 'part'),
+    travel: everyKey()('source', 'times', 'plus', 'sum'),
+    state: everyKey()('id', 'label', 'start', 'sweep'),
+    mimic: everyKey()('joint', 'multiplier', 'offset', 'sum'),
+    leader: everyKey()('joint', 'multiplier'),
+    repeat: everyKey()('axis', 'pitch', 'count', 'rise'),
+    rise: everyKey()('axis', 'mm')
+};
+/** Refuses, by name, a key of a joint record or of an object in it that this kernel does not know. A key left undefined is no field. */
+function knownJointFields(j, path) {
+    const only = (o, allowed, at) => {
+        if (!o || typeof o !== 'object' || Array.isArray(o))
+            return;
+        for (const [k, v] of Object.entries(o))
+            if (v !== undefined && !allowed.includes(k))
+                fail('JOINT_SCHEMA', at, `${k} is a field this kernel does not know`);
+    };
+    const source = (s, at) => only(s, JOINT_FIELDS.source, at);
+    const measure = (m, at) => {
+        if (!m || typeof m !== 'object')
+            return;
+        only(m, JOINT_FIELDS.measure, at);
+        source(m.from, `${at}.from`);
+        if (Array.isArray(m.sum))
+            for (const [i, t] of m.sum.entries()) {
+                only(t, JOINT_FIELDS.term, `${at}.sum.${i}`);
+                source(t?.from, `${at}.sum.${i}.from`);
+            }
+    };
+    only(j, JOINT_FIELDS.joint, path);
+    only(j.body0, JOINT_FIELDS.body0, `${path}.body0`);
+    only(j.body1, JOINT_FIELDS.body1, `${path}.body1`);
+    const o = j.origin;
+    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.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`);
+        }
+    }
+    if (j.travel && typeof j.travel === 'object') {
+        only(j.travel, JOINT_FIELDS.travel, `${path}.travel`);
+        source(j.travel.source, `${path}.travel.source`);
+        if (Array.isArray(j.travel.sum))
+            measure({ sum: j.travel.sum }, `${path}.travel`);
+    }
+    only(j.state, JOINT_FIELDS.state, `${path}.state`);
+    only(j.mimic, JOINT_FIELDS.mimic, `${path}.mimic`);
+    if (Array.isArray(j.mimic?.sum))
+        for (const [i, t] of j.mimic.sum.entries())
+            only(t, JOINT_FIELDS.leader, `${path}.mimic.sum.${i}`);
+    only(j.repeat, JOINT_FIELDS.repeat, `${path}.repeat`);
+    if (j.repeat && typeof j.repeat === 'object') {
+        measure(j.repeat.pitch, `${path}.repeat.pitch`);
+        only(j.repeat.rise, JOINT_FIELDS.rise, `${path}.repeat.rise`);
+    }
+}
+/** What each part is fastened to, for a reader that wants the structure rather than the graph. */
+export function figureAttachmentsOf(asset) {
+    const m = asset.document.model;
+    const out = {};
+    for (const n of m.nodes)
+        if (n.op === 'place@1')
+            out[n.id] = parentOf(m, n.id);
+    return out;
+}
+/** The joint whose child is this part, if any. */
+export function jointAbove(asset, part) {
+    return asset.joints?.find(j => j.body1.part === part);
+}
+export const stateIdOf = (j) => j.state?.id ?? j.id;
+/** A record that is well formed on its own, and fits the tree the others make. */
+function checkJoint(asset, j) {
+    const m = asset.document.model;
+    const path = `joints.${String(j?.id)}`;
+    if (!j || typeof j.id !== 'string' || !j.id.trim())
+        fail('JOINT_SCHEMA', 'joints', 'a joint has an id');
+    knownJointFields(j, path);
+    if (!FIGURE_JOINT_TYPES.includes(j.type))
+        fail('JOINT_SCHEMA', path, `${String(j.type)} is not a joint type; ${FIGURE_JOINT_TYPES.join(', ')}`);
+    if (!j.body1 || typeof j.body1.part !== 'string')
+        fail('JOINT_SCHEMA', path, 'a joint carries a part (body1)');
+    partOf(m, j.body1.part, path);
+    if (!j.body0 || (!('plane' in j.body0) && typeof j.body0.part !== 'string'))
+        fail('JOINT_SCHEMA', path, 'a joint hangs from a part or the mounting plane (body0)');
+    if ('part' in j.body0)
+        partOf(m, j.body0.part, path);
+    const others = (asset.joints ?? []).filter(o => o.id !== j.id);
+    const above = others.find(o => o.body1.part === j.body1.part);
+    if (above)
+        fail('JOINT_TREE', path, `${j.body1.part} already hangs from ${'part' in above.body0 ? above.body0.part : 'the mounting plane'} by ${above.id}; a part has one joint above it`);
+    if ('part' in j.body0) {
+        const parentOfPart = (part) => others.find(o => o.body1.part === part)?.body0;
+        for (let up = j.body0.part; up;) {
+            if (up === j.body1.part)
+                fail('ATTACH_CYCLE', path, `${j.body0.part} already hangs from ${j.body1.part}; ${j.body1.part} would hang from itself`);
+            const next = parentOfPart(up);
+            up = next && 'part' in next ? next.part : undefined;
+        }
+    }
+    const moving = j.type !== 'fixed';
+    const limited = j.lowerLimit !== undefined || j.upperLimit !== undefined;
+    if (moving && !['X', 'Y', 'Z'].includes(j.axis))
+        fail('JOINT_SCHEMA', path, `a ${j.type} joint has an axis, X, Y or Z`);
+    if (!moving && (j.axis !== undefined || limited || j.mimic !== undefined || j.travel !== undefined))
+        fail('JOINT_SCHEMA', path, 'a fixed joint has no axis, limits, mimic or travel');
+    if (j.travel !== undefined && j.type !== 'prismatic')
+        fail('JOINT_SCHEMA', path, 'only a prismatic joint travels a length');
+    if (j.type === 'prismatic' && j.travel && !limited) {
+        j.lowerLimit = 0;
+        j.upperLimit = 1;
+    }
+    /* A revolute joint without limits turns without end (USD); with them, both are given. A slide always has them. */
+    if (moving && !j.mimic && (limited || j.type === 'prismatic')) {
+        const [lo, hi] = [j.lowerLimit, j.upperLimit];
+        if (!(Number.isFinite(lo) && Number.isFinite(hi) && lo < hi))
+            fail('JOINT_SCHEMA', path, `a ${j.type} joint has both limits, lower below upper`);
+        /*
+          The rest pose is every joint at 0 -- the kinematic reference its axis is read at (joint-list.ts) -- and 0 need not
+          be a value the joint may take: a joint limited to 10..80 still has its reference at 0 (ADR-0107 J4). Its starting
+          value, the stored state default, is held to its limits as every control's is (addMotion).
+        */
+    }
+    if (j.mimic) {
+        /*
+          One leader or a sum of them (ADR-0107 decision 2), each held to the same rules: a moving joint that leads itself
+          -- so a follower is never a leader and no loop can close -- that moves the way this one does (degrees are not
+          added to millimetres), named once, with a finite multiplier.
+        */
+        const sum = Object.hasOwn(j.mimic, 'sum');
+        if (sum && !(Array.isArray(j.mimic.sum) && j.mimic.sum.length))
+            fail('JOINT_SCHEMA', path, 'a mimic sum follows one joint or more');
+        const seen = new Set();
+        for (const t of figureMimicLeadersOf(j)) {
+            const leader = others.find(o => o.id === t?.joint);
+            if (!leader || leader.type === 'fixed')
+                fail('JOINT_SCHEMA', path, `${String(t?.joint)} is not a moving joint to follow`);
+            if (seen.has(leader.id))
+                fail('JOINT_SCHEMA', path, `${leader.id} is followed twice; a sum names each joint once`);
+            seen.add(leader.id);
+            if (leader.mimic)
+                fail('JOINT_SCHEMA', path, `${leader.id} follows another joint; follow the one it follows`);
+            if ((leader.type === 'prismatic') !== (j.type === 'prismatic'))
+                fail('JOINT_SCHEMA', path, `${leader.id} ${leader.type === 'prismatic' ? 'slides' : 'turns'}; a joint follows ones that move the same way: a slide a slide, a turn a turn`);
+            if (!Number.isFinite(t.multiplier))
+                fail('JOINT_SCHEMA', path, 'a mimic has a multiplier');
+        }
+        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");
+    /*
+      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.
+    */
+    const all = [...others, j];
+    const upOf = (part) => all.find(o => o.body1.part === part && 'part' in o.body0);
+    const rowAbove = (part) => {
+        for (let up = upOf(part); up; up = upOf(up.body0.part))
+            if (up.repeat)
+                return up;
+        return undefined;
+    };
+    if (j.repeat) {
+        const below = (part) => all.filter(o => 'part' in o.body0 && o.body0.part === part).flatMap(o => [o.body1.part, ...below(o.body1.part)]);
+        const around = [];
+        for (let up = ('part' in j.body0) ? rowAbove(j.body0.part) : undefined; up; up = 'part' in up.body0 ? rowAbove(up.body0.part) : undefined)
+            around.push(up);
+        const inside = below(j.body1.part)
+            .map(p => all.find(o => o.body1.part === p))
+            .filter(o => o.repeat);
+        const same = [...around, ...inside].find(o => o.repeat.axis === j.repeat.axis);
+        if (same)
+            fail('JOINT_SCHEMA', `${path}.repeat`, `${same.body1.part}'s row runs along ${same.repeat.axis} too; a row inside a row runs along another axis`);
+    }
+    if (j.repeat) {
+        const r = j.repeat;
+        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');
+        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)])
+            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');
+        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`, { reason: 'row-copies-out-of-range', count: r.count, min: 1, max: REPEAT_LIMIT });
+        if (r.rise !== undefined) {
+            if (!r.rise || !['X', 'Y', 'Z'].includes(r.rise.axis) || r.rise.axis === r.axis)
+                fail('JOINT_SCHEMA', `${row}.rise`, `a row rises along X, Y or Z other than the one it runs along (${r.axis})`);
+            if (!(Number.isFinite(r.rise.mm) && r.rise.mm !== 0))
+                fail('GEOMETRY_DOMAIN', `${row}.rise`, 'a rise is a length in mm, not zero');
+        }
+    }
+}
+/**
+ * Write a joint's nodes from its record: the child's quarter turn, the fastening (the seat on the parent's face and
+ * the child's offset from it), and for a moving joint the turn or slide at the seat. The node ids are the child's and
+ * are chosen the same way each time, so writing a record again gives the same nodes.
+ */
+function writeJoint(asset, j) {
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const { pose } = partOf(m, child, child);
+    /*
+      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 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 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'))
+    ];
+    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`);
+    /* 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)
+            repeatPart(asset, j);
+        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 leaders = figureMimicLeadersOf(j).map(t => ({
+        leader: (asset.joints ?? []).find(o => o.id === t.joint),
+        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);
+    if (axisIndex < 0)
+        fail('JOINT_SCHEMA', path, `${parent} stands twisted; the axis ${j.axis} is not level with an axis in it`);
+    addMotion(asset, {
+        kind: 'add-motion',
+        part: child,
+        motion: { kind, axis: AXES[axisIndex] },
+        state: {
+            id: stateIdOf(j),
+            unit,
+            min: range.min,
+            max: range.max,
+            start: j.state?.start ?? Math.min(range.max, Math.max(range.min, 0)),
+            ...(j.state?.label !== undefined ? { label: j.state.label } : {}),
+            ...(j.state?.sweep !== undefined ? { sweep: j.state.sweep } : {})
+        },
+        ...(j.travel ? { travel: j.travel } : {}),
+        replace: true
+    }, 
+    /*
+      A follower follows how far its leader has gone -- its distance or angle -- not the leader's control: a leader whose
+      stroke is a share of a length has a control of 0..1, and multiplying that gave a follower a number with no length
+      (the telescopic conveyor, 2026-09-25). For a leader whose control is its distance the two are one value.
+    */
+    j.mimic
+        ? {
+            terms: leaders.map(({ leader, k }) => ({
+                of: nodeById(m, `${leader.body1.part}.motion`)?.args[3] ?? stateIdOf(leader),
+                k
+            })),
+            c: j.mimic.offset ?? 0,
+            sum: Object.hasOwn(j.mimic, 'sum')
+        }
+        : undefined, along[axisIndex] > 0 ? 1 : -1);
+    if (j.repeat)
+        repeatPart(asset, j);
+}
+/**
+ * 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];
+    /* 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`);
+    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');
+    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 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,
+                measureRef(m, asset, name, j.repeat.pitch, 'pitch', path),
+                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 -- turned by its motion, if it moves. */
+    place.op = 'member@1';
+    place.args = [place.args[0], nodeById(m, `${part}.turned`)?.outputs?.pose ?? pose.outputs.pose];
+    m.nodes.push({
+        id: `${part}.assembly`,
+        op: 'assembly@1',
+        args: [place.outputs.placed],
+        outputs: { assembly: `${part}.assembly.value` }
+    });
+    /* Where the parent stands, as `attach` finds it: fastened (its world or chain), or placed by its own numbers. */
+    const above = nodeById(m, `${parent}.world`)?.outputs?.pose ??
+        nodeById(m, `${parent}.chain`)?.outputs?.pose ??
+        nodeById(m, `${parent}.turned`)?.outputs?.pose ??
+        nodeById(m, `${parent}.pose`)?.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`);
+    const rise = j.repeat.rise;
+    m.nodes.push({
+        id: `${part}.repeat`,
+        op: 'repeat@1',
+        args: [
+            `${part}.layout.value`,
+            `${part}.assembly.value`,
+            root,
+            ...(rise ? [constantOf(m, 'mm', rise.mm, 'rise')] : [])
+        ],
+        outputs: { collection: `${part}.repeat.value` },
+        params: { axis, ...(rise ? { riseAxis: rise.axis.toLowerCase() } : {}) }
+    });
+}
+/**
+ * Everything fastened to a row's part, however far down, goes into the row's assembly: each copy carries it (ADR-0093,
+ * 2026-09-26). Its placement already reads its copy's frame -- it hangs from the part's pose, not from a chain.
+ */
+function gatherRows(asset, joints) {
+    const m = asset.document.model;
+    for (const row of joints.filter(j => j.repeat)) {
+        const assembly = nodeById(m, `${row.body1.part}.assembly`);
+        /* Down to the next row: a row inside this one joins as its copies, and what hangs from its part is its own. */
+        const gather = (part) => {
+            for (const o of joints.filter(o => 'part' in o.body0 && o.body0.part === part)) {
+                if (o.repeat) {
+                    const inner = nodeById(m, `${o.body1.part}.repeat`);
+                    inner.params = { ...inner.params, within: `${row.body1.part}.repeat` };
+                    assembly.args.push(inner.outputs.collection);
+                    continue;
+                }
+                const place = nodeById(m, o.body1.part);
+                place.op = 'member@1';
+                assembly.args.push(place.outputs.placed);
+                gather(o.body1.part);
+            }
+        };
+        gather(row.body1.part);
+    }
+}
+/** 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 rise = nodeById(m, `${part}.repeat`)?.args[3];
+    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 ?? []), ...(rise ? [rise] : [])])
+        dropIfUnused(asset, ref);
+}
+/** Take a joint's nodes away, leaving its child standing in the asset frame at the origin. */
+export 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);
+    const owned = new Set([`${child}.seat.rigid`, `${child}.chain`, `${child}.world`, `${child}.turned`]);
+    m.nodes = m.nodes.filter((n) => !owned.has(n.id) && !n.id.startsWith(`${child}.on.`));
+    const zero = constantOf(m, 'mm', 0, 'd');
+    const old = pose.args.slice(0, 3);
+    pose.args = [zero, zero, zero, ...pose.args.slice(3)];
+    pose.params = { ...pose.params, to: asset.document.capabilities.assetFrame };
+    // Its own position numbers, if it still had them, place nothing now: the joint places it.
+    for (const ref of old)
+        dropIfUnused(asset, ref, ownInput(m, child, ref) ? ref : undefined);
+    place.args = [place.args[0], pose.outputs.pose];
+}
+/**
+ * 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.
+ */
+export function jointMeasures(j) {
+    const out = [];
+    if (j.origin?.gap !== undefined)
+        out.push({ at: 'gap', get: () => j.origin.gap, set: v => (j.origin.gap = v) });
+    if (j.repeat)
+        out.push({ at: 'pitch', get: () => j.repeat.pitch, set: v => (j.repeat.pitch = v) });
+    if (j.travel) {
+        const t = j.travel;
+        out.push({
+            at: 'travel',
+            get: () => Object.hasOwn(t, 'sum')
+                ? { sum: t.sum, ...(t.plus !== undefined ? { plus: t.plus } : {}) }
+                : t.source
+                    ? {
+                        from: t.source,
+                        ...(t.times !== undefined ? { times: t.times } : {}),
+                        ...(t.plus !== undefined ? { plus: t.plus } : {})
+                    }
+                    : (t.plus ?? 0),
+            set: v => {
+                const f = followedTermsOf(v);
+                j.travel = !f
+                    ? { plus: v }
+                    : f.sum
+                        ? { sum: f.terms, ...(f.plus ? { plus: f.plus } : {}) }
+                        : {
+                            source: f.terms[0].from,
+                            ...(f.terms[0].times !== undefined ? { times: f.terms[0].times } : {}),
+                            ...(v.plus !== undefined ? { plus: v.plus } : {})
+                        };
+            }
+        });
+    }
+    for (const axis of Object.keys(j.origin?.align ?? {})) {
+        const how = j.origin.align[axis];
+        if (how && typeof how === 'object' && Object.hasOwn(how, 'mm'))
+            out.push({
+                at: `align.${axis}`,
+                get: () => how.mm,
+                set: v => (how.mm = v)
+            });
+    }
+    return out;
+}
+/** The same measure with each term's source put through `to`, in the form it was written. */
+export function mapMeasureSources(measure, to) {
+    const f = followedTermsOf(measure);
+    if (!f)
+        return measure;
+    if (f.sum)
+        return { ...measure, sum: f.terms.map(t => ({ ...t, from: to(t.from) })) };
+    return { ...measure, from: to(f.terms[0].from) };
+}
+/** Joints in an order each can be written in: its parent's joint and the joints it mimics first. */
+function writingOrder(joints) {
+    const done = new Set();
+    const out = [];
+    const byChild = new Map(joints.map(j => [j.body1.part, j]));
+    while (out.length < joints.length) {
+        const ready = joints.filter(j => {
+            if (done.has(j.id))
+                return false;
+            const up = 'part' in j.body0 ? byChild.get(j.body0.part) : undefined;
+            return (!up || done.has(up.id)) && figureMimicLeadersOf(j).every(t => done.has(t.joint));
+        });
+        if (!ready.length)
+            fail('JOINT_TREE', 'joints', 'the joints do not make a tree');
+        for (const j of ready) {
+            done.add(j.id);
+            out.push(j);
+        }
+    }
+    return out;
+}
+/** Every joint's nodes again, from the records: the ones below first away, then all written parents first. */
+export function rewriteJoints(asset) {
+    const joints = (asset.joints ?? []);
+    /*
+      A stroke that follows a part's length reads that length by its stable name (`<part>.dimension.<axis>`), and naming
+      it rewires the shape to read it. Done in the middle of the writing, the joints already written measured the part by
+      its old reference and the parse's rewrite measured it by the new one (JOINT_DRIFT, the telescopic conveyor,
+      2026-09-25). The names are made first, so every joint measures the same references.
+    */
+    for (const j of joints)
+        for (const { at, get } of jointMeasures(j))
+            for (const t of followedTermsOf(get())?.terms ?? [])
+                if (t?.from?.of === 'part')
+                    stableDimension(asset.document.model, t.from.part, t.from.axis, `joints.${j.id}.${at}`);
+    const order = writingOrder(joints);
+    const keep = { ...asset.stateDefaults };
+    holdingDeclared(asset, () => {
+        /* What hangs from a row's part is drawn through the row; it is a part of its own again while the joints are written. */
+        for (const n of asset.document.model.nodes)
+            if (n.op === 'member@1' && !nodeById(asset.document.model, `${n.id}.repeat`))
+                n.op = 'place@1';
+        for (const j of [...order].reverse())
+            stripJoint(asset, j);
+        for (const j of order)
+            writeJoint(asset, j);
+        gatherRows(asset, joints);
+        // A joint's value as the author left it (「지금 자세를 기본으로」) is theirs, not the record's.
+        for (const j of order)
+            if (j.type !== 'fixed' && !j.mimic && keep[stateIdOf(j)] !== undefined)
+                asset.stateDefaults[stateIdOf(j)] = keep[stateIdOf(j)];
+    });
+}
+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]]))
+            };
+    }
+    const joints = (asset.joints ?? []).filter(o => o.id !== j.id);
+    const followers = joints.filter(o => figureMimicLeadersOf(o).some(t => t.joint === j.id));
+    if (followers.length && j.type === 'fixed')
+        fail('JOINT_SCHEMA', `joints.${j.id}`, `${followers.map(f => f.id).join(', ')} follow ${j.id}; it cannot stop moving`);
+    asset.joints = [...joints, j];
+    rewriteJoints(asset);
+}
+/** The joint goes; its child keeps where it stands now, as plain position numbers. */
+/**
+ * Where what refers to a face an edit takes away goes instead (ADR-0100 A8): a joint re-pointed to another face of
+ * the part, or let go where it stands (`detach`, a joint only); a named face moved to another face -- a capability
+ * hangs on it, so it is never let go. Applied before the edit, in the same command: one step of the history. The new
+ * faces must be the part's after the edit; `keepReferencedFaces` refuses one that is not.
+ */
+export function applyFaceRemap(asset, part, remap) {
+    if (!remap?.length)
+        return;
+    const faces = new Set();
+    const shapeOutput = asset.document.model.nodes.find((o) => o.id === `${part}.shape`)?.outputs?.shape;
+    const faceOf = (to, path) => {
+        const face = typeof to?.face === 'string' ? to.face.trim() : '';
+        if (!face)
+            fail('SCHEMA', `${path}.to`, `a face of ${part}, or 'detach'`);
+        return face;
+    };
+    for (const [i, r] of remap.entries()) {
+        const path = `remap.${i}`;
+        if (r?.ref?.kind === 'joint') {
+            const j = (asset.joints ?? []).find(o => o.id === r.ref.id);
+            if (!j || !(j.body0?.part === part || j.body1?.part === part))
+                fail('EDIT_TARGET', path, `${r.ref.id} is not a joint on ${part}`);
+            if (r.to === 'detach') {
+                removeJoint(asset, j.id);
+                continue;
+            }
+            const face = faceOf(r.to, path);
+            if (j.body0?.part === part)
+                j.body0.face = face;
+            else
+                j.body1.face = face;
+            faces.add(face);
+        }
+        else if (r?.ref?.kind === 'feature') {
+            const n = asset.document.model.nodes.find((o) => o.id === r.ref.id && o.op === 'feature@1');
+            if (!n || n.args[0] !== shapeOutput)
+                fail('EDIT_TARGET', path, `${r.ref.id} is not a named face of ${part}`);
+            if (r.to === 'detach')
+                fail('SCHEMA', `${path}.to`, `a named face moves to another face; a capability hangs on it, so it is not let go`);
+            const face = faceOf(r.to, path);
+            n.params = { ...n.params, name: face };
+            faces.add(face);
+        }
+        else
+            fail('SCHEMA', `${path}.ref`, `{ kind: 'joint' | 'feature', id }`);
+    }
+    remappedFaces.set(asset, faces);
+}
+export function removeJoint(asset, id) {
+    const joints = (asset.joints ?? []);
+    const j = joints.find(o => o.id === id);
+    if (!j)
+        fail('EDIT_TARGET', `joints.${id}`, `there is no joint ${id}`);
+    const followers = joints.filter(o => figureMimicLeadersOf(o).some(t => t.joint === id));
+    if (followers.length)
+        fail('JOINT_SCHEMA', `joints.${id}`, `${followers.map(f => f.id).join(', ')} follow ${id}; remove them first`);
+    const m = asset.document.model;
+    const child = j.body1.part;
+    const evaluated = compileFigureAssetUnjointed(asset).evaluate();
+    const placed = nodeById(m, child);
+    const at = evaluated.values?.[placed.args[1]];
+    if (!at?.t)
+        fail('TARGET_ABSENT', child, `${child} has no pose to read`);
+    const own = m.nodes.find((n) => n.id === `${child}.pose`);
+    const turned = (r, want) => r.some((row, i) => row.some((v, k) => Math.abs(v - want[i][k]) > 1e-9));
+    const ownTurn = evaluated.values?.[own.outputs.pose]?.r;
+    if (ownTurn && turned(at.r, ownTurn))
+        fail('EDIT_TARGET', child, `${child} stands turned by what it hangs from; taking the joint away would turn it`);
+    asset.joints = joints.filter(o => o.id !== id);
+    stripJoint(asset, j);
+    const translation = AXES.map((axis, i) => {
+        const input = `${child}.position.${axis}`;
+        const value = round6(at.t[i]);
+        if (!m.inputs.some((n) => n.id === input))
+            m.inputs.push({ id: input, unit: 'mm', min: -Number.MAX_VALUE, max: Number.MAX_VALUE, role: 'design' });
+        asset.designInputs[input] = value;
+        return input;
+    });
+    own.args = [...translation, ...own.args.slice(3)];
+    // Parts hanging from it are written again: they hang from where it stands now.
+    rewriteJoints(asset);
+}
+/** `attach` is the modeller's word for a fixed joint: the record says it, whatever joint was there keeps its id and motion. */
+export function fastenAsJoint(asset, a) {
+    const was = jointAbove(asset, a.part);
+    if (was && !a.replace)
+        fail('ATTACH_REPLACED', a.part, `${a.part} is already fastened by ${was.id}; pass replace to move it, or detach it first`);
+    const to = a.to;
+    /*
+      A new record is named after its part -- unless another joint already has that name: a robot arm's finger joint
+      was named `gripper`, and fastening the gripper wrote over it (2026-09-25). The first free name after it is taken.
+    */
+    const taken = new Set((asset.joints ?? []).map(j => j.id));
+    let id = a.part;
+    for (let k = 2; !was && taken.has(id); k++)
+        id = `${a.part}-${k}`;
+    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 },
+        origin: {
+            ...(was?.origin?.turn ? { turn: was.origin.turn } : {}),
+            ...(a.twist !== undefined
+                ? a.twist
+                    ? { twist: a.twist }
+                    : {}
+                : was?.origin?.twist
+                    ? { twist: was.origin.twist }
+                    : {}),
+            ...(a.facing ? { facing: a.facing } : {}),
+            ...(a.gap !== undefined ? { gap: a.gap } : {}),
+            ...(a.align ? { align: a.align } : {})
+        }
+    });
+}
+/**
+ * The records are the canon: made again from them, the joints' nodes must be the nodes the asset holds. An asset
+ * whose nodes or records were edited apart is refused, not quietly rebuilt (ADR-0093, chief architect's condition).
+ */
+export function checkFigureJoints(asset) {
+    const joints = asset.joints;
+    if (!joints?.length)
+        return;
+    const again = structuredClone(asset);
+    for (const j of joints)
+        checkJoint({ ...again, joints: joints.filter(o => o.id !== j.id).concat(j) }, j);
+    rewriteJoints(again);
+    const canon = (model) => JSON.stringify({
+        nodes: [...model.nodes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+        inputs: [...model.inputs].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    });
+    if (canon(again.document.model) !== canon(asset.document.model))
+        fail('JOINT_DRIFT', 'joints', "the joints' nodes are not what their records make; the asset was edited apart from its joints");
+}
+export 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`);
+    if (layout.op === 'fixed-count@1')
+        fail('EDIT_TARGET', path, `${a.part} repeats a fixed count; its pitch is built into its length and cannot be set yet`);
+    if (layout.op !== 'fit-pitch@1')
+        fail('EDIT_TARGET', path, `${a.part} lays its copies out by ${layout.op}, which has no pitch`);
+    /* A pitch read from an input is a record's: a row without one takes a number (ADR-0096). */
+    if (typeof a.pitch !== 'number')
+        fail('EDIT_TARGET', path, `${a.part}'s row has no record to read its pitch from an input; make it again with make-repeat`);
+    const pitch = a.pitch;
+    if (!(Number.isFinite(pitch) && pitch > 0))
+        fail('GEOMETRY_DOMAIN', path, 'a positive pitch is required');
+    /*
+      One number, the pitch: copies = floor(row length / pitch), at most `limit` of them (the kernel's copy cap).
+      So the longest row the figure may be placed at is limit x pitch. A new pitch moves that bound with it; the pitch is refused only when the length the figure
+      is authored at would already hold more copies than the cap.
+    */
+    const values = compileFigureGraph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const lengthRef = layout.args[0];
+    const authored = values[lengthRef];
+    const limit = (values[layout.args[6]] ?? m.constants.find((c) => c.id === layout.args[6])?.value);
+    const smallest = Math.ceil((authored / limit) * 1000) / 1000;
+    if (pitch < smallest)
+        fail('INPUT_RANGE', path, `at the length it is authored (${round6(authored)} mm) a pitch under ${smallest} mm makes more than ${limit} copies`, {
+            reason: 'pitch-too-many-copies',
+            part: a.part,
+            length: round6(authored),
+            least: smallest,
+            limit
+        });
+    const id = `${a.part}.repeat.pitch`;
+    if (!m.inputs.some((i) => i.id === id)) {
+        if (m.nodes.some((n) => n.id === id || Object.values(n.outputs).includes(id)))
+            fail('DUPLICATE_WRITER', path, `${id} already exists`);
+        m.inputs.push({ id, unit: 'mm', min: Number.MIN_VALUE, max: Number.MAX_VALUE, role: 'design' });
+        const was = [layout.args[3], layout.args[4]];
+        layout.args = layout.args.map((r, k) => (k === 3 || k === 4 ? id : r));
+        for (const ref of new Set(was))
+            dropIfUnused(asset, ref);
+    }
+    asset.designInputs[id] = pitch;
+    /* The longest length follows the pitch, within the default range (ten times the authored length). */
+    const length = m.inputs.find((i) => i.id === lengthRef && i.role === 'design');
+    if (length) {
+        const longest = Math.min(round6(limit * pitch), round6(authored * FIGURE_INSTANCE_SIZE_DEFAULT.times));
+        length.max = Math.max(longest, authored);
+        if (length.min > length.max)
+            length.min = Math.min(length.min, authored);
+    }
+    return asset;
+}
+//# sourceMappingURL=joint-writing.js.map