@hatiolab/figure-model 0.1.37 → 0.1.38

package/dist/v3-authoring-actions.js

@@ -22,6 +22,7 @@
  * 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 { V3ContractError } from "./v3-contract.js";
 import { AXES } from "./types.js";
 const fail = (code, path, message) => {
@@ -54,15 +55,22 @@ function sizeRefsOf(m, id, path) {
         fail('EDIT_TARGET', path, `${id} is a ${shape.op}; a face of it is not an axis-aligned plane this command can measure`);
     return { x: shape.args[0], y: shape.args[1], z: shape.args[2] };
 }
+/** The angle a pose argument holds, whether it is a constant or a design input, or null when it is neither. */
+function angleOf(m, asset, ref) {
+    const constant = m.constants.find((c) => c.id === ref);
+    if (constant)
+        return constant.value;
+    const input = m.inputs.find((i) => i.id === ref);
+    if (input && input.role !== 'state')
+        return asset.designInputs[ref] ?? null;
+    return null;
+}
 /** A part with no turn in its pose: a face of a turned body is not the plane this command assumes. */
 function requireUnturned(m, asset, id, path) {
     const { pose } = partOf(m, id, path);
-    for (const ref of pose.args.slice(3, 6)) {
-        const constant = m.constants.find((c) => c.id === ref);
-        const value = constant ? constant.value : asset.designInputs[ref];
-        if (value === undefined || value !== 0)
+    for (const ref of pose.args.slice(3, 6))
+        if (angleOf(m, asset, ref) !== 0)
             fail('EDIT_TARGET', path, `${id} is turned; fastening a turned part by its faces is not covered by this command`);
-    }
 }
 /** Fresh node ids under a part, so two commands never claim one id. */
 function namer(m, prefix) {
@@ -100,6 +108,37 @@ function scaled(m, name, ref, times, plus, hint) {
     }
     return out;
 }
+/** A measure as one graph reference: a constant, or the source it follows times a multiple plus a margin. */
+function measureRef(m, asset, name, measure, hint, path) {
+    if (measure === undefined)
+        return constantOf(m, 'mm', 0, 'd');
+    if (typeof measure === 'number') {
+        if (!Number.isFinite(measure))
+            fail('SCHEMA', path, 'a finite length is required');
+        return constantOf(m, 'mm', measure, 'd');
+    }
+    if (!measure || typeof measure !== 'object' || !measure.from)
+        fail('SCHEMA', path, 'a length is a number of millimetres, or something to follow');
+    return scaled(m, name, sourceRef(m, asset, measure.from, path), measure.times ?? 1, measure.plus ?? 0, hint);
+}
+/** Σ k·ref, written as nodes, with nothing emitted for a weight of zero and no node for a single term. */
+function sumOf(m, name, terms, hint) {
+    const live = terms.filter(t => t.k !== 0);
+    if (!live.length)
+        return constantOf(m, 'mm', 0, 'd');
+    let out = '';
+    for (const [i, t] of live.entries()) {
+        const piece = scaled(m, name, t.ref, t.k, 0, `${hint}.${i}`);
+        if (!out)
+            out = piece;
+        else {
+            const id = name(`${hint}.${i}.sum`);
+            m.nodes.push({ id, op: 'add@1', args: [out, piece], outputs: { value: `${id}.value` } });
+            out = `${id}.value`;
+        }
+    }
+    return out;
+}
 function sourceRef(m, asset, source, path) {
     if (!source || typeof source !== 'object')
         fail('SCHEMA', path, 'a dimension source is required');
@@ -118,56 +157,91 @@ function sourceRef(m, asset, source, path) {
         return source.input;
     }
     if (source.of === 'part')
-        return sizeRefsOf(m, source.part, path)[source.axis];
+        return stableDimension(m, source.part, source.axis, path);
     return fail('SCHEMA', path, `${String(source.of)} is not a dimension source`);
 }
 /**
- * Whether this side of the part already follows something. A part created by the authoring API reads its own
- * `<id>.size.<axis>` input and nothing else; anything else in that argument is a link, whether it is a chain of
- * nodes or the followed value used directly.
+ * The name of a part's dimension, which stays the same name however that dimension is later worked out.
+ *
+ * "B is as wide as A" has to keep meaning that when A is told to follow something else. Reading A's shape
+ * argument at the moment of linking gave B whatever A happened to read then — A's own control — so relinking A
+ * left B on the old value (V3 designer's counterexample 2026-09-23: A went to 300 and B stayed at 100). Every
+ * dimension a command touches gets a node of its own, `<part>.dimension.<axis>`, and that is what the shape
+ * reads and what anything following it reads. Relinking rewrites what that node computes, and everyone pointing
+ * at it comes along — fastenings included, since they measure the same references.
  */
-const followsAlready = (part, axis, ref) => ref !== `${part}.size.${axis}`;
+function stableDimension(m, part, axis, path) {
+    const shape = partOf(m, part, path).shape;
+    const i = AXES.indexOf(axis);
+    const id = `${part}.dimension.${axis}`;
+    const ref = `${id}.value`;
+    if (nodeById(m, id))
+        return ref;
+    const one = constantOf(m, 'ratio', 1, 'k');
+    m.nodes.push({ id, op: 'mul@1', args: [shape.args[i], one], outputs: { value: ref } });
+    shape.args = shape.args.map((r, k) => (k === i ? ref : r));
+    return ref;
+}
+/** What a part's dimension is worked out from right now: the first argument of its own dimension node. */
+const dimensionSource = (m, part, axis) => nodeById(m, `${part}.dimension.${axis}`)?.args?.[0];
+/** Whether this side of the part already follows something, rather than reading its own control. */
+const followsAlready = (m, part, axis) => {
+    const from = dimensionSource(m, part, axis);
+    return from !== undefined && from !== `${part}.size.${axis}`;
+};
 function linkDimension(asset, a) {
     const m = asset.document.model;
     const path = `${a.part}.${a.axis}`;
-    const sizes = sizeRefsOf(m, a.part, path);
-    const current = sizes[a.axis];
-    if (followsAlready(a.part, a.axis, current) && !a.replace)
+    const mine = stableDimension(m, a.part, a.axis, path);
+    if (followsAlready(m, a.part, a.axis) && !a.replace)
         fail('DIMENSION_LINKED', path, `${a.part}'s ${a.axis} already follows something; pass replace to change what it follows, or unlink it first`);
     const times = a.times ?? 1;
     const plus = a.plus ?? 0;
     if (!Number.isFinite(times) || !Number.isFinite(plus))
         fail('SCHEMA', path, 'finite times and plus required');
+    if (a.source.of === 'part' && a.source.part === a.part && a.source.axis === a.axis)
+        fail('DIMENSION_CYCLE', path, `${a.part}'s ${a.axis} cannot follow itself`);
     const from = sourceRef(m, asset, a.source, path);
-    if (from === current)
+    if (from === mine)
         fail('DIMENSION_CYCLE', path, `${a.part}'s ${a.axis} cannot follow itself`);
+    if (reaches(m, from, mine))
+        fail('DIMENSION_CYCLE', path, `${String(a.source.of === 'part' ? a.source.part : a.source.of)} already follows ${a.part}'s ${a.axis}`);
     const name = namer(m, `${a.part}.${a.axis}`);
     const value = scaled(m, name, from, times, plus, 'follows');
-    if (value === from && a.source.of === 'part' && a.source.part === a.part)
-        fail('DIMENSION_CYCLE', path, `${a.part}'s ${a.axis} cannot follow itself`);
-    const shape = partOf(m, a.part, path).shape;
-    shape.args = shape.args.map((ref) => (ref === current ? value : ref));
-    // The part's own input is no longer read by anything; leaving it would show a control that changes nothing.
-    dropIfUnused(asset, current, `${a.part}.size.${a.axis}`);
+    const node = nodeById(m, `${a.part}.dimension.${a.axis}`);
+    const was = node.args[0];
+    node.args = [value, node.args[1]];
+    // The part's own control is no longer read by anything; leaving it would show a dial that changes nothing.
+    dropIfUnused(asset, was, `${a.part}.size.${a.axis}`);
     return asset;
 }
+/** Whether one value is worked out from another, so a link cannot be made to close a loop. */
+function reaches(m, from, target, seen = new Set()) {
+    if (from === target)
+        return true;
+    if (seen.has(from))
+        return false;
+    seen.add(from);
+    const writer = writerOf(m, from);
+    return !!writer && writer.args.some((ref) => reaches(m, ref, target, seen));
+}
 function unlinkDimension(asset, a) {
     const m = asset.document.model;
     const path = `${a.part}.${a.axis}`;
     if (!(Number.isFinite(a.mm) && a.mm > 0))
         fail('GEOMETRY_DOMAIN', path, 'a positive length is required');
-    const sizes = sizeRefsOf(m, a.part, path);
-    const current = sizes[a.axis];
-    if (!followsAlready(a.part, a.axis, current))
+    stableDimension(m, a.part, a.axis, path);
+    if (!followsAlready(m, a.part, a.axis))
         fail('EDIT_TARGET', path, `${a.part}'s ${a.axis} does not follow anything`);
     const id = `${a.part}.size.${a.axis}`;
     if (m.inputs.some((i) => i.id === id))
         fail('DUPLICATE_WRITER', path, `${id} already exists`);
     m.inputs.push({ id, unit: 'mm', min: Number.MIN_VALUE, max: Number.MAX_VALUE, role: 'design' });
     asset.designInputs[id] = a.mm;
-    const shape = partOf(m, a.part, path).shape;
-    shape.args = shape.args.map((ref) => (ref === current ? id : ref));
-    dropIfUnused(asset, current);
+    const node = nodeById(m, `${a.part}.dimension.${a.axis}`);
+    const was = node.args[0];
+    node.args = [id, node.args[1]];
+    dropIfUnused(asset, was);
     return asset;
 }
 /**
@@ -207,75 +281,100 @@ function parentOf(m, id) {
 }
 function attach(asset, a) {
     const m = asset.document.model;
-    const path = `${a.part} to ${a.to?.part}`;
-    if (!a.to || typeof a.to !== 'object')
-        fail('SCHEMA', path, 'a target part and face are required');
-    if (a.part === a.to.part)
+    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');
-    for (const face of [a.face, a.to.face])
+    for (const face of [a.face, to.face])
         if (!Object.hasOwn(V3_FACES, String(face)))
             fail('SCHEMA', path, `${String(face)} is not a face`);
     const facing = a.facing ?? 'meet';
     if (facing !== 'meet' && facing !== 'flush')
         fail('SCHEMA', path, `${String(facing)} is neither meet nor flush`);
-    const gap = a.gap ?? 0;
-    if (!Number.isFinite(gap))
-        fail('SCHEMA', path, 'a finite gap is required');
-    const axis = V3_FACES[a.to.face];
+    const axis = V3_FACES[to.face];
     if (V3_FACES[a.face] !== axis)
-        fail('ATTACH_FACE', path, `${a.face} faces along ${V3_FACES[a.face]} and ${a.to.face} along ${axis}; fastening them would need a turn, which this command does not do`);
-    if (facing === 'meet' && a.face !== OPPOSITE[a.to.face])
-        fail('ATTACH_FACE', path, `to meet ${a.to.face}, ${a.part} offers its ${OPPOSITE[a.to.face]}; pass flush to lay ${a.face} in the same plane instead`);
-    if (facing === 'flush' && a.face !== a.to.face)
-        fail('ATTACH_FACE', path, `to lie flush with ${a.to.face}, ${a.part} offers its ${a.to.face}`);
+        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}`);
     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 = a.to.part; up; up = parentOf(m, up))
+    for (let up = to.part; up; up = parentOf(m, up))
         if (up === a.part)
-            fail('ATTACH_CYCLE', path, `${a.to.part} already hangs from ${a.part}`);
+            fail('ATTACH_CYCLE', path, `${to.part} already hangs from ${a.part}`);
     const mine = sizeRefsOf(m, a.part, path);
-    const theirs = sizeRefsOf(m, a.to.part, path);
+    const theirs = sizeRefsOf(m, to.part, path);
     requireUnturned(m, asset, a.part, path);
-    requireUnturned(m, asset, a.to.part, path);
-    const name = namer(m, `${a.part}.on.${a.to.part}`);
-    const half = (ref, hint) => scaled(m, name, ref, 0.5, 0, hint);
-    const sign = SIGN[a.to.face];
+    requireUnturned(m, asset, to.part, path);
+    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.
     */
-    const reach = facing === 'meet' ? sign * (gap + 0) : -sign * 0;
-    void reach;
-    const ownHalf = half(mine[axis], `half.${axis}`);
-    const theirHalf = half(theirs[axis], `their.half.${axis}`);
     const outward = facing === 'meet' ? sign : -sign;
-    const alongId = name(`along.${axis}`);
-    m.nodes.push({ id: alongId, op: 'add@1', args: [scaled(m, name, theirHalf, sign, 0, `face.${axis}`), scaled(m, name, ownHalf, outward, gap * outward, `stand.${axis}`)], outputs: { value: `${alongId}.value` } });
+    const gap = measureRef(m, asset, name, a.gap, `gap.${axis}`, path);
     const translation = { x: '', y: '', z: '' };
-    translation[axis] = `${alongId}.value`;
+    translation[axis] = sumOf(m, name, [
+        { ref: theirs[axis], k: sign * 0.5 },
+        { ref: mine[axis], k: outward * 0.5 },
+        { 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.
     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 && Number.isFinite(how.mm))
-            translation[other] = constantOf(m, 'mm', how.mm, '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') {
             const s = how === 'min' ? -1 : 1;
-            const id = name(`align.${other}`);
-            m.nodes.push({
-                id,
-                op: 'add@1',
-                args: [scaled(m, name, half(theirs[other], `their.half.${other}`), s, 0, `edge.${other}`), scaled(m, name, half(mine[other], `half.${other}`), -s, 0, `inset.${other}`)],
-                outputs: { value: `${id}.value` }
-            });
-            translation[other] = `${id}.value`;
+            translation[other] = sumOf(m, name, [{ ref: theirs[other], k: s * 0.5 }, { ref: mine[other], k: -s * 0.5 }], `align.${other}`);
         }
         else
             fail('SCHEMA', path, `${String(how)} is not an alignment`);
     }
-    reseat(asset, a.part, `${a.to.part}.local`, [translation.x, translation.y, translation.z]);
+    reseat(asset, a.part, `${to.part}.local`, [translation.x, translation.y, translation.z]);
+    return asset;
+}
+/**
+ * Standing a part on the plane the figure is mounted on. The plane has no width and no depth, so there is
+ * nothing to line the part's edges up with: across the plane, only the centre or a measured offset.
+ */
+function standOnPlane(asset, a, path) {
+    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');
+    if (a.face !== 'bottom' && a.face !== 'top')
+        fail('ATTACH_FACE', path, `${String(a.face)} faces along ${V3_FACES[a.face] ?? '?'}; the plane faces along y, so a part stands on it by its bottom or hangs from it by its top`);
+    if (parentOf(m, a.part) && !a.replace)
+        fail('ATTACH_REPLACED', path, `${a.part} is already fastened to ${parentOf(m, a.part)}; pass replace to stand it on the plane instead`);
+    const mine = sizeRefsOf(m, a.part, path);
+    requireUnturned(m, asset, a.part, path);
+    const 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, k: outward * 0.5 }, { ref: gap, k: outward }], 'stand.y');
+    for (const other of ['x', 'z']) {
+        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);
+        else
+            fail('SCHEMA', path, `the plane has no edges to line ${a.part} up with on ${other}; give the centre or a measured offset`);
+    }
+    reseat(asset, a.part, asset.document.capabilities.assetFrame, [translation.x, translation.y, translation.z]);
     return asset;
 }
 function detach(asset, a) {
@@ -284,13 +383,36 @@ function detach(asset, a) {
     const parent = parentOf(m, a.part);
     if (!parent)
         fail('EDIT_TARGET', path, `${a.part} is not fastened to anything`);
-    // Where it stands now, kept as plain numbers in the asset frame, so detaching does not move it.
+    /*
+      Detaching keeps the part where it stands, and keeps it moving the way it moved. Taking the world pose and
+      writing it in as the part's own pose did neither: the part's motion was already in that pose and was then
+      applied a second time, so a part with 20 mm of travel jumped to 40 (V3 designer's counterexample
+      2026-09-23).
+  
+      What the part's pose has to gain is exactly what the parent's chain was contributing — and that is a plain
+      translation only while nothing above the part is turned. Where something is, the two cannot be separated
+      into a translation the pose can absorb, and this refuses rather than moving the part.
+    */
+    for (let up = parent; up; up = parentOf(m, up))
+        requireUnturned(m, asset, up, path);
     const evaluated = compileV3Asset(asset).evaluate();
-    const here = evaluated.geometry.find((g) => g.id === a.part);
-    if (!here)
-        fail('TARGET_ABSENT', path, `${a.part} is not drawn`);
-    const at = AXES.map((_axis, i) => constantOf(m, 'mm', round6(here.pose.t[i]), 'd'));
-    reseat(asset, a.part, asset.document.capabilities.assetFrame, at);
+    const above = evaluated.values?.[nodeById(m, `${parent}.world`)?.outputs?.pose ?? nodeById(m, `${parent}.chain`)?.outputs?.pose ?? nodeById(m, `${parent}.pose`).outputs.pose];
+    if (!above || !above.t)
+        fail('TARGET_ABSENT', path, `${parent} has no pose to read`);
+    const turned = above.r.some((row, i) => row.some((v, j) => Math.abs(v - (i === j ? 1 : 0)) > 1e-9));
+    if (turned)
+        fail('EDIT_TARGET', path, `${parent} is turned; taking ${a.part} off it would move it, and this command does not move a part`);
+    const { pose } = partOf(m, a.part, path);
+    const own = evaluated.values?.[pose.outputs.pose];
+    if (!own || !own.t)
+        fail('TARGET_ABSENT', path, `${a.part} has no pose to read`);
+    /*
+      Where it stands, as plain numbers: what the parent was contributing plus what the part's own pose was. Its
+      motion is left out, because the motion node stays and would otherwise be counted twice. Numbers rather than
+      references, because a part that is no longer fastened to the plate should not still grow with it.
+    */
+    const translation = AXES.map((_axis, i) => constantOf(m, 'mm', round6(above.t[i] + own.t[i]), 'd'));
+    reseat(asset, a.part, asset.document.capabilities.assetFrame, translation);
     return asset;
 }
 const round6 = (v) => Math.round(v * 1e6) / 1e6;
@@ -301,8 +423,9 @@ const round6 = (v) => Math.round(v * 1e6) / 1e6;
 function reseat(asset, id, to, translation) {
     const m = asset.document.model;
     const { place, pose } = partOf(m, id, id);
-    const old = pose.args.slice(0, 3);
-    pose.args = [...translation, ...pose.args.slice(3)];
+    const old = translation ? pose.args.slice(0, 3) : [];
+    if (translation)
+        pose.args = [...translation, ...pose.args.slice(3)];
     pose.params = { ...pose.params, to: `${id}.seat` };
     const motion = nodeById(m, `${id}.motion`);
     if (motion)
@@ -366,6 +489,21 @@ export function applyV3Authoring(source, action) {
         case 'detach':
             detach(asset, action);
             break;
+        case 'add-motion':
+            addMotion(asset, action);
+            break;
+        case 'remove-motion':
+            removeMotion(asset, action);
+            break;
+        case 'declare-occupancy':
+            declareOccupancy(asset, action);
+            break;
+        case 'set-mounting-face':
+            setMountingFace(asset, action);
+            break;
+        case 'clear-mounting-face':
+            clearMountingFace(asset);
+            break;
         default:
             fail('SCHEMA', 'action', `${String(action.kind)} is not an authoring action`);
     }
@@ -381,4 +519,294 @@ export function v3AttachmentsOf(asset) {
             out[n.id] = parentOf(m, n.id);
     return out;
 }
+/** The frame a part is fastened into: its parent's, or the asset's. */
+const attachmentFrameOf = (asset, id) => {
+    const parent = parentOf(asset.document.model, id);
+    return parent ? `${parent}.local` : asset.document.capabilities.assetFrame;
+};
+function addMotion(asset, a) {
+    const m = asset.document.model;
+    const path = a.part;
+    partOf(m, a.part, path);
+    if (!a.motion || (a.motion.kind !== 'slide' && a.motion.kind !== 'turn'))
+        fail('SCHEMA', path, 'a slide or a turn is required');
+    if (!AXES.includes(a.motion.axis))
+        fail('SCHEMA', path, `${String(a.motion.axis)} is not an axis`);
+    if (nodeById(m, `${a.part}.motion`) && !a.replace)
+        fail('MOTION_REPLACED', path, `${a.part} already moves; pass replace to change how, or remove the motion first`);
+    if (nodeById(m, `${a.part}.motion`))
+        removeMotion(asset, { kind: 'remove-motion', part: a.part });
+    const frame = a.motion.frame ?? 'attachment';
+    const seatedIn = attachmentFrameOf(asset, a.part);
+    if (frame === 'asset' && seatedIn !== asset.document.capabilities.assetFrame)
+        fail('MOTION_FRAME', path, `${a.part} is fastened into ${seatedIn}; an axis in the asset frame would have to be re-expressed there, which this command does not do`);
+    else if (frame !== 'attachment' && frame !== 'asset')
+        fail('SCHEMA', path, `${String(frame)} is not a frame for the axis`);
+    const st = a.state;
+    if (!st || typeof st.id !== 'string' || !st.id.trim())
+        fail('SCHEMA', path, 'a state input id is required');
+    if (m.inputs.some((i) => i.id === st.id))
+        fail('DUPLICATE_WRITER', path, `${st.id} already exists`);
+    const wanted = a.motion.kind === 'turn' ? ['deg'] : ['mm', 'ratio'];
+    if (!wanted.includes(st.unit))
+        fail('SCHEMA', path, `a ${a.motion.kind} takes a ${wanted.join(' or ')} control, not ${String(st.unit)}`);
+    if (!(Number.isFinite(st.min) && Number.isFinite(st.max) && st.max > st.min))
+        fail('SCHEMA', path, 'a range with max above min is required');
+    const start = st.start ?? st.min;
+    if (!(start >= st.min && start <= st.max))
+        fail('SCHEMA', path, 'the starting value is outside the range');
+    m.inputs.push({ id: st.id, unit: st.unit, min: st.min, max: st.max, role: 'state' });
+    asset.stateDefaults[st.id] = start;
+    if (st.label !== undefined || st.sweep !== undefined) {
+        asset.stateInputs = { ...(asset.stateInputs ?? {}) };
+        asset.stateInputs[st.id] = { ...(st.label !== undefined ? { label: st.label } : {}), ...(st.sweep !== undefined ? { sweep: st.sweep } : {}) };
+    }
+    const name = namer(m, `${a.part}.motion`);
+    let quantity = st.id;
+    if (a.motion.kind === 'slide' && st.unit === 'ratio') {
+        if (!a.travel)
+            fail('SCHEMA', path, 'a ratio control needs travel: how far the part goes at 1');
+        const travel = a.travel;
+        const base = travel.source ? sourceRef(m, asset, travel.source, path) : constantOf(m, 'mm', travel.plus ?? 0, 'd');
+        const length = travel.source ? scaled(m, name, base, travel.times ?? 1, travel.plus ?? 0, 'travel') : base;
+        const id = name('distance');
+        m.nodes.push({ id, op: 'mul@1', args: [st.id, length], outputs: { value: `${id}.value` } });
+        quantity = `${id}.value`;
+    }
+    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'));
+    m.nodes.push({
+        id: `${a.part}.motion`,
+        op: a.motion.kind === 'slide' ? 'axis-slide@1' : 'axis-turn@1',
+        args: [...unit, quantity],
+        outputs: { pose: `${a.part}.motion.value` },
+        params: { from: `${a.part}.seat`, to: seatedIn }
+    });
+    reseat(asset, a.part, seatedIn);
+    if (a.clip) {
+        const c = a.clip;
+        if (typeof c.name !== 'string' || !c.name.trim())
+            fail('SCHEMA', path, 'a clip is named');
+        if (!(Number.isFinite(c.duration) && c.duration > 0))
+            fail('SCHEMA', path, 'a clip runs for a positive number of seconds');
+        asset.drivers = [...(asset.drivers ?? []), { id: `${a.part}/${c.name}`, clip: c.name, state: st.id, time: { unit: 's', duration: c.duration }, keys: structuredClone(c.keys), interpolation: 'linear', loop: c.loop ?? 'wrap', accumulates: c.accumulates ?? false }];
+    }
+    return asset;
+}
+/** "This part does not move any more." The control it created goes with it, and so does its clip. */
+function removeMotion(asset, a) {
+    const m = asset.document.model;
+    const motion = nodeById(m, `${a.part}.motion`);
+    if (!motion)
+        fail('EDIT_TARGET', a.part, `${a.part} does not move`);
+    const quantity = motion.args[3];
+    const to = motion.params.to;
+    // Which control this motion introduced, read before the nodes that name it are taken away.
+    const state = m.inputs.find((i) => i.id === quantity && i.role === 'state')
+        ?? m.inputs.find((i) => i.role === 'state' && (writerOf(m, quantity)?.args ?? []).includes(i.id));
+    m.nodes = m.nodes.filter((n) => n !== motion);
+    reseat(asset, a.part, to);
+    dropIfUnused(asset, quantity, quantity);
+    if (state && !m.nodes.some((n) => n.args.includes(state.id))) {
+        m.inputs = m.inputs.filter((i) => i !== state);
+        delete asset.stateDefaults[state.id];
+        if (asset.stateInputs)
+            delete asset.stateInputs[state.id];
+        if (asset.drivers)
+            asset.drivers = asset.drivers.filter((d) => d.state !== state.id);
+        if (asset.drivers && !asset.drivers.length)
+            delete asset.drivers;
+        if (asset.stateInputs && !Object.keys(asset.stateInputs).length)
+            delete asset.stateInputs;
+    }
+    return asset;
+}
+/** A figure as one value, for saying "this is the figure I read". The declaration itself is left out of it. */
+function fingerprintOf(asset) {
+    const text = JSON.stringify({ ...asset, occupancy: asset.occupancy ? { ...asset.occupancy, bounds: null } : undefined });
+    let h1 = 0x811c9dc5;
+    let h2 = 0x01000193;
+    for (let i = 0; i < text.length; i++) {
+        h1 = Math.imul(h1 ^ text.charCodeAt(i), 0x01000193) >>> 0;
+        h2 = Math.imul(h2 + text.charCodeAt(i), 0x85ebca6b) >>> 0;
+    }
+    return `${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}:${text.length}`;
+}
+const linAdd = (a, b, k = 1) => ({ terms: [...a.terms, ...b.terms.map(t => ({ ref: t.ref, k: t.k * k }))], c: a.c + b.c * k });
+const linOf = (m, ref) => {
+    const constant = m.constants.find((c) => c.id === ref);
+    return constant ? { terms: [], c: constant.value } : { terms: [{ ref, k: 1 }], c: 0 };
+};
+/** How far a slide has gone when its control is at one end of its range. */
+function travelAt(m, asset, motion, bound) {
+    const quantity = motion.args[3];
+    const direct = m.inputs.find((i) => i.id === quantity && i.role === 'state');
+    const pick = (i) => (bound === 'start' ? (asset.stateDefaults[i.id] ?? i.min) : bound === 'min' ? i.min : i.max);
+    if (direct)
+        return { terms: [], c: pick(direct) };
+    const writer = writerOf(m, quantity);
+    if (writer?.op === 'mul@1' && writer.args.length === 2) {
+        const state = m.inputs.find((i) => i.id === writer.args[0] && i.role === 'state');
+        if (state)
+            return { terms: [{ ref: writer.args[1], k: pick(state) }], c: 0 };
+    }
+    return null;
+}
+/** Where a part's centre is on one axis, as a sum, following whatever it is fastened to. */
+function centreLin(m, asset, id, axis, bound) {
+    const i = AXES.indexOf(axis);
+    let out = { terms: [], c: 0 };
+    for (let part = id; part; part = parentOf(m, part)) {
+        const pose = nodeById(m, `${part}.pose`);
+        if (!pose)
+            return `${part} has no pose this command can read`;
+        for (const ref of pose.args.slice(3, 6))
+            if (angleOf(m, asset, ref) !== 0)
+                return `${part} is turned, so its reach is not a box this command can add up`;
+        out = linAdd(out, linOf(m, pose.args[i]));
+        const motion = nodeById(m, `${part}.motion`);
+        if (motion) {
+            if (motion.op !== 'axis-slide@1')
+                return `${part} turns, so its reach is not a box this command can add up`;
+            const unit = motion.args.slice(0, 3).map((ref) => m.constants.find((k) => k.id === ref)?.value ?? null);
+            if (unit.some((v) => v === null))
+                return `${part}'s slide axis is not a constant`;
+            const along = unit[i];
+            if (along !== 0) {
+                const travel = travelAt(m, asset, motion, bound);
+                if (!travel)
+                    return `${part}'s travel is not a distance this command can read`;
+                out = linAdd(out, travel, along);
+            }
+        }
+    }
+    return out;
+}
+/** The bounds the parts come to, as sums, with what could not be read named. */
+function occupancyLins(asset, over) {
+    const m = asset.document.model;
+    const parts = [];
+    const skipped = [];
+    const low = { x: [], y: [], z: [] };
+    const high = { x: [], y: [], z: [] };
+    for (const place of m.nodes.filter((n) => n.op === 'place@1')) {
+        let sizes;
+        try {
+            sizes = sizeRefsOf(m, place.id, place.id);
+        }
+        catch {
+            skipped.push({ part: place.id, reason: 'not a box-shaped part; this command measures boxes' });
+            continue;
+        }
+        /*
+          Both ends of every control are candidates, and which one is the low end is not decided here: a travel of
+          −40 mm puts the low end at the control's maximum (V3 designer's counterexample 2026-09-23, where the
+          proposal read −50..10 for a part that needs −90..50). Both candidates go into the same min and the same
+          max, so the answer holds whichever way the travel runs, and holds at every design size, because the
+          choice is made when the graph is evaluated rather than when the proposal is written.
+        */
+        const ends = over === 'rest' ? ['start'] : ['min', 'max'];
+        const readings = AXES.map(axis => ({ axis, at: ends.map(end => centreLin(m, asset, place.id, axis, end)) }));
+        const bad = readings.flatMap(r => r.at).find(v => typeof v === 'string');
+        if (bad) {
+            skipped.push({ part: place.id, reason: String(bad) });
+            continue;
+        }
+        parts.push(place.id);
+        for (const r of readings) {
+            const half = { terms: [{ ref: sizes[r.axis], k: 0.5 }], c: 0 };
+            const seen = new Set();
+            for (const centre of r.at) {
+                const key = JSON.stringify([centre.terms.map(t => [t.ref, t.k]).sort(), centre.c]);
+                if (seen.has(key))
+                    continue; // a part that does not move gives the same candidate twice
+                seen.add(key);
+                low[r.axis].push(linAdd(centre, half, -1));
+                high[r.axis].push(linAdd(centre, half, 1));
+            }
+        }
+    }
+    return { parts, skipped, low, high };
+}
+const valueOfLin = (values, l) => l.terms.reduce((s, t) => s + t.k * (values[t.ref] ?? NaN), l.c);
+/** What the parts come to, and what a person is being asked to confirm. Reads the asset; changes nothing. */
+export function proposeV3Occupancy(asset, options = {}) {
+    const over = options.over ?? 'range';
+    if (over !== 'rest' && over !== 'range')
+        fail('SCHEMA', 'over', `${String(over)} is neither rest nor range`);
+    const source = structuredClone(asset);
+    const { parts, skipped, low, high } = occupancyLins(source, over);
+    if (!parts.length)
+        fail('OCCUPANCY_NO_PARTS', 'occupancy', `no part could be measured${skipped.length ? `: ${skipped.map(s => `${s.part} — ${s.reason}`).join('; ')}` : ''}`);
+    const values = compileV3Graph(source.document.model).evaluate({ ...source.designInputs, ...source.stateDefaults }).values;
+    const at = Object.fromEntries(AXES.map(axis => [axis, { min: round6(Math.min(...low[axis].map(l => valueOfLin(values, l)))), max: round6(Math.max(...high[axis].map(l => valueOfLin(values, l)))) }]));
+    return { over, at, parts, skipped, basis: fingerprintOf(source) };
+}
+function declareOccupancy(asset, a) {
+    const m = asset.document.model;
+    if (!a.proposal || (a.proposal.over !== 'rest' && a.proposal.over !== 'range'))
+        fail('SCHEMA', 'occupancy', 'a proposal is required; propose first, then confirm');
+    if (!['floor', 'ceiling', 'center'].includes(a.placement))
+        fail('SCHEMA', 'occupancy', `${String(a.placement)} is not a placement`);
+    const now = fingerprintOf(asset);
+    if (a.proposal.basis !== now)
+        fail('OCCUPANCY_STALE', 'occupancy', 'the figure changed since this was proposed, so the volume it would declare is not the one that was looked at; propose again and confirm that');
+    const { parts, low, high } = occupancyLins(asset, a.proposal.over);
+    if (parts.join('|') !== a.proposal.parts.join('|'))
+        fail('OCCUPANCY_STALE', 'occupancy', `the figure changed since the proposal was made (${a.proposal.parts.join(', ')} then, ${parts.join(', ')} now); propose again and confirm that`);
+    const name = namer(m, 'occupancy');
+    const emit = (l, hint) => {
+        if (!l.terms.length)
+            return constantOf(m, 'mm', round6(l.c), 'd');
+        let out = '';
+        for (const t of l.terms) {
+            const piece = scaled(m, name, t.ref, t.k, 0, hint);
+            if (!out)
+                out = piece;
+            else {
+                const id = name(`${hint}.sum`);
+                m.nodes.push({ id, op: 'add@1', args: [out, piece], outputs: { value: `${id}.value` } });
+                out = `${id}.value`;
+            }
+        }
+        if (l.c !== 0) {
+            const id = name(`${hint}.offset`);
+            m.nodes.push({ id, op: 'add@1', args: [out, constantOf(m, 'mm', round6(l.c), 'd')], outputs: { value: `${id}.value` } });
+            out = `${id}.value`;
+        }
+        return out;
+    };
+    const pick = (ls, op, hint) => {
+        const refs = ls.map((l, k) => emit(l, `${hint}.${k}`));
+        if (refs.length === 1)
+            return refs[0];
+        const id = name(hint);
+        m.nodes.push({ id, op, args: refs, outputs: { value: `${id}.value` } });
+        return `${id}.value`;
+    };
+    const bounds = Object.fromEntries(AXES.map(axis => [axis, { min: pick(low[axis], 'min@1', `${axis}.min`), max: pick(high[axis], 'max@1', `${axis}.max`) }]));
+    asset.occupancy = { ...(asset.occupancy?.contact ? { contact: asset.occupancy.contact } : {}), bounds, placement: a.placement };
+    return asset;
+}
+/** "This face is what the figure is mounted on." Kept apart from how much room the figure takes up. */
+function setMountingFace(asset, a) {
+    const m = asset.document.model;
+    if (!asset.occupancy)
+        fail('OCCUPANCY_UNDECLARED', 'occupancy', 'declare the room the figure takes up before naming the face it stands on');
+    if (!Object.hasOwn(V3_FACES, String(a.face)))
+        fail('SCHEMA', a.part, `${String(a.face)} is not a face`);
+    const { place } = partOf(m, a.part, a.part);
+    const id = `${a.part}.mount.${a.face}`;
+    if (!nodeById(m, id))
+        m.nodes.push({ id, op: 'feature@1', args: [place.args[0]], outputs: { pose: `${id}.value` }, params: { frame: `${id}.frame`, name: a.face } });
+    asset.occupancy.contact = { plane: 'mounting-plane', surface: { placement: place.outputs.placed, feature: `${id}.value` } };
+    return asset;
+}
+function clearMountingFace(asset) {
+    if (!asset.occupancy?.contact)
+        fail('EDIT_TARGET', 'occupancy', 'this figure names no mounting face');
+    delete asset.occupancy.contact;
+    return asset;
+}
 //# sourceMappingURL=v3-authoring-actions.js.map