@hatiolab/figure-model 0.1.36 → 0.1.38

package/dist/v3-authoring-actions.js

@@ -0,0 +1,812 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+/*
+ * What a person is trying to say when they build a figure, as commands.
+ *
+ * The four things the hand-written sliding gate needed and the authoring API had no word for (V3 designer's
+ * ruling 2026-09-23): a dimension that follows something, a part fastened to a face, a part that moves, and the
+ * room the figure takes up. This file carries the first two; the other two follow.
+ *
+ * Every command here is pure. It clones the asset, edits the clone, compiles it, and returns it — so a command
+ * that fails throws with the original untouched, and one command is one step to undo. Part ids never change, so
+ * a reference an author or a connector holds keeps pointing at the same part after any of these.
+ *
+ * Frames. A part's placement is built from three nodes that are never merged, so adding one does not erase
+ * another (V3 designer's ruling: attachment and motion must not overwrite the same pose):
+ *
+ *     <id>.local  --<id>.pose-->  <id>.seat  --<id>.motion-->  <parent>.local  --<parent>.world-->  asset
+ *
+ * `<id>.pose` is where the part sits on what it is fastened to. `<id>.motion` is how it moves from there, and is
+ * absent until something makes it move. `<parent>.world` is the parent's own chain, so moving or resizing the
+ * 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) => {
+    throw new V3ContractError(code, path, message);
+};
+/** The six faces of a box-shaped part, and the axis each one faces along. */
+export const V3_FACES = { left: 'x', right: 'x', bottom: 'y', top: 'y', back: 'z', front: 'z' };
+const SIGN = { left: -1, right: 1, bottom: -1, top: 1, back: -1, front: 1 };
+const OPPOSITE = { left: 'right', right: 'left', bottom: 'top', top: 'bottom', back: 'front', front: 'back' };
+const clone = (asset) => structuredClone(asset);
+const nodeById = (m, id) => m.nodes.find((n) => n.id === id);
+const writerOf = (m, ref) => m.nodes.find((n) => Object.values(n.outputs).includes(ref));
+/** A part an authoring command can work with, and the pieces of it those commands need. */
+function partOf(m, id, path) {
+    const place = nodeById(m, id);
+    if (!place || place.op !== 'place@1')
+        fail('TARGET_ABSENT', path, `${id} is not a placed part`);
+    const shape = writerOf(m, place.args[0]);
+    if (!shape)
+        fail('TARGET_ABSENT', path, `${id} has no shape`);
+    const pose = nodeById(m, `${id}.pose`);
+    if (!pose || pose.op !== 'rigid@1')
+        fail('EDIT_TARGET', path, `${id} is not posed by a rigid@1 this command can read`);
+    return { place, shape, pose };
+}
+/** The three size references of a box-shaped part, or a refusal naming what it is instead. */
+function sizeRefsOf(m, id, path) {
+    const { shape } = partOf(m, id, path);
+    if (shape.op !== 'box-shape@1' && shape.op !== 'rounded-box@1' && shape.op !== 'rounded-box@2')
+        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))
+        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) {
+    const taken = new Set([...m.nodes.map((n) => n.id), ...m.nodes.flatMap((n) => Object.values(n.outputs)), ...m.constants.map((c) => c.id), ...m.inputs.map((i) => i.id)]);
+    return (hint) => {
+        let id = `${prefix}.${hint}`;
+        for (let k = 2; taken.has(id) || taken.has(`${id}.value`); k++)
+            id = `${prefix}.${hint}.${k}`;
+        taken.add(id);
+        taken.add(`${id}.value`);
+        return id;
+    };
+}
+/** A constant, reusing one that already holds the same number in the same unit. */
+function constantOf(m, unit, value, hint) {
+    const found = m.constants.find((c) => c.unit === unit && c.value === value);
+    if (found)
+        return found.id;
+    const id = `${hint}.${unit}.${String(value).replace(/[^0-9a-zA-Z]/g, '_')}`;
+    m.constants.push({ id, unit, value });
+    return id;
+}
+/** value = ref × times + plus, written as nodes, and folded away when there is nothing to do. */
+function scaled(m, name, ref, times, plus, hint) {
+    let out = ref;
+    if (times !== 1) {
+        const id = name(`${hint}.times`);
+        m.nodes.push({ id, op: 'mul@1', args: [out, constantOf(m, 'ratio', times, 'k')], outputs: { value: `${id}.value` } });
+        out = `${id}.value`;
+    }
+    if (plus !== 0) {
+        const id = name(`${hint}.plus`);
+        m.nodes.push({ id, op: 'add@1', args: [out, constantOf(m, 'mm', plus, 'd')], outputs: { value: `${id}.value` } });
+        out = `${id}.value`;
+    }
+    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');
+    if (source.of === 'instance') {
+        const id = `size.${source.axis}`;
+        if (!m.inputs.some((i) => i.id === id))
+            fail('TARGET_ABSENT', path, `the instance has no ${id}; declare it before following it`);
+        return id;
+    }
+    if (source.of === 'input') {
+        const input = m.inputs.find((i) => i.id === source.input);
+        if (!input)
+            fail('TARGET_ABSENT', path, `${source.input} is not an input of this asset`);
+        if (input.role === 'state')
+            fail('EDIT_TARGET', path, `${source.input} is a state input; a dimension that follows state is a different declaration`);
+        return source.input;
+    }
+    if (source.of === 'part')
+        return stableDimension(m, source.part, source.axis, path);
+    return fail('SCHEMA', path, `${String(source.of)} is not a dimension source`);
+}
+/**
+ * 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.
+ */
+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 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 === 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');
+    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');
+    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 node = nodeById(m, `${a.part}.dimension.${a.axis}`);
+    const was = node.args[0];
+    node.args = [id, node.args[1]];
+    dropIfUnused(asset, was);
+    return asset;
+}
+/**
+ * Remove a value nothing reads any more, and whatever fed only it. An input is removed only when it is the one
+ * this command owns — the part's own dimension control. A shared input, such as the instance's size, stays even
+ * when the command that stopped reading it was the last reader: it is the author's, not this command's.
+ */
+function dropIfUnused(asset, ref, ownedInput) {
+    const m = asset.document.model;
+    const referenced = (r) => m.nodes.some((n) => n.args.includes(r) || Object.values(n.params ?? {}).includes(r)) || Object.values(asset.occupancy?.bounds ?? {}).some((b) => b.min === r || b.max === r);
+    if (referenced(ref))
+        return;
+    const input = m.inputs.findIndex((i) => i.id === ref);
+    if (input >= 0) {
+        if (ref !== ownedInput)
+            return;
+        m.inputs.splice(input, 1);
+        delete asset.designInputs[ref];
+        delete asset.stateDefaults[ref];
+        return;
+    }
+    const writer = writerOf(m, ref);
+    if (!writer || writer.op === 'place@1' || Object.values(writer.outputs).some((r) => r !== ref && referenced(r)))
+        return;
+    m.nodes = m.nodes.filter((n) => n !== writer);
+    for (const arg of writer.args)
+        dropIfUnused(asset, arg);
+}
+/** Which part each part is fastened to, read from the frames rather than from a second record of it. */
+function parentOf(m, id) {
+    if (!nodeById(m, `${id}.chain`))
+        return null;
+    // The seat's own frame leads either to a motion node or, when the part does not move, to an identity rigid.
+    const above = nodeById(m, `${id}.motion`) ?? nodeById(m, `${id}.seat.rigid`);
+    const match = /^(.*)\.local$/.exec(String(above?.params?.to));
+    return match && match[1] !== id ? match[1] : null;
+}
+function attach(asset, a) {
+    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');
+    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 axis = V3_FACES[to.face];
+    if (V3_FACES[a.face] !== axis)
+        fail('ATTACH_FACE', path, `${a.face} faces along ${V3_FACES[a.face]} and ${to.face} along ${axis}; fastening them would need a turn, which this command does not do`);
+    if (facing === 'meet' && a.face !== OPPOSITE[to.face])
+        fail('ATTACH_FACE', path, `to meet ${to.face}, ${a.part} offers its ${OPPOSITE[to.face]}; pass flush to lay ${a.face} in the same plane instead`);
+    if (facing === 'flush' && a.face !== to.face)
+        fail('ATTACH_FACE', path, `to lie flush with ${to.face}, ${a.part} offers its ${to.face}`);
+    if (parentOf(m, a.part) && !a.replace)
+        fail('ATTACH_REPLACED', path, `${a.part} is already fastened to ${parentOf(m, a.part)}; pass replace to move it, or detach it first`);
+    // A part cannot end up its own ancestor.
+    for (let up = to.part; up; up = parentOf(m, up))
+        if (up === a.part)
+            fail('ATTACH_CYCLE', path, `${to.part} already hangs from ${a.part}`);
+    const mine = sizeRefsOf(m, a.part, path);
+    const theirs = sizeRefsOf(m, to.part, path);
+    requireUnturned(m, asset, a.part, path);
+    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 outward = facing === 'meet' ? sign : -sign;
+    const gap = measureRef(m, asset, name, a.gap, `gap.${axis}`, path);
+    const translation = { x: '', y: '', z: '' };
+    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 && 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;
+            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, `${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) {
+    const m = asset.document.model;
+    const path = a.part;
+    const parent = parentOf(m, a.part);
+    if (!parent)
+        fail('EDIT_TARGET', path, `${a.part} is not fastened to anything`);
+    /*
+      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 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;
+/**
+ * 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.
+ */
+function reseat(asset, id, to, translation) {
+    const m = asset.document.model;
+    const { place, pose } = partOf(m, id, id);
+    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)
+        motion.params = { ...motion.params, from: `${id}.seat`, to };
+    // seat → the frame it is fastened to. Without a motion node the seat is that frame, through an identity rigid.
+    let chain = nodeById(m, `${id}.chain`);
+    if (!chain) {
+        chain = { id: `${id}.chain`, op: 'compose@1', args: ['', pose.outputs.pose], outputs: { pose: `${id}.chain.value` } };
+        m.nodes.push(chain);
+    }
+    let seat = nodeById(m, `${id}.seat.rigid`);
+    if (!motion) {
+        const zero = constantOf(m, 'mm', 0, 'd');
+        const noTurn = constantOf(m, 'deg', 0, 'a');
+        if (!seat) {
+            seat = { id: `${id}.seat.rigid`, op: 'rigid@1', args: [zero, zero, zero, noTurn, noTurn, noTurn], outputs: { pose: `${id}.seat.value` }, params: { from: `${id}.seat`, to } };
+            m.nodes.push(seat);
+        }
+        else
+            seat.params = { ...seat.params, to };
+        chain.args = [seat.outputs.pose, pose.outputs.pose];
+    }
+    else
+        chain.args = [motion.outputs.pose, pose.outputs.pose];
+    const parent = /^(.*)\.local$/.exec(to);
+    let world = nodeById(m, `${id}.world`);
+    if (parent && parent[1] !== id) {
+        const above = nodeById(m, `${parent[1]}.world`)?.outputs?.pose ?? nodeById(m, `${parent[1]}.chain`)?.outputs?.pose ?? nodeById(m, `${parent[1]}.pose`).outputs.pose;
+        if (!world) {
+            world = { id: `${id}.world`, op: 'compose@1', args: [above, chain.outputs.pose], outputs: { pose: `${id}.world.value` } };
+            m.nodes.push(world);
+        }
+        else
+            world.args = [above, chain.outputs.pose];
+        place.args = [place.args[0], world.outputs.pose];
+    }
+    else {
+        if (world)
+            m.nodes = m.nodes.filter((n) => n !== world);
+        place.args = [place.args[0], chain.outputs.pose];
+    }
+    for (const ref of old)
+        dropIfUnused(asset, ref);
+}
+/** Apply one authoring command. Throws on any refusal, leaving the asset it was given untouched. */
+export function applyV3Authoring(source, action) {
+    compileV3Asset(source);
+    if (!action || typeof action !== 'object')
+        fail('SCHEMA', 'action', 'an authoring action is required');
+    const asset = clone(source);
+    switch (action.kind) {
+        case 'link-dimension':
+            linkDimension(asset, action);
+            break;
+        case 'unlink-dimension':
+            unlinkDimension(asset, action);
+            break;
+        case 'attach':
+            attach(asset, action);
+            break;
+        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`);
+    }
+    compileV3Asset(asset);
+    return asset;
+}
+/** What each part is fastened to, for a reader that wants the structure rather than the graph. */
+export function v3AttachmentsOf(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 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