@hatiolab/figure-model 0.1.92 → 0.1.94

package/dist/{v3-authoring-actions.js → authoring-actions.js}

@@ -4,7 +4,7 @@
 /*
  * 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
+ * The four things the hand-written sliding gate needed and the authoring API had no word for (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.
  *
@@ -13,7 +13,7 @@
  * 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):
+ * another (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
  *
@@ -21,25 +21,27 @@
  * 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 { checkPublicInput, keepPublicInputs } from "./v3-public-inputs.js";
-import { v3PartsExtentOf } from "./v3-gate.js";
-import { compileV3Graph, v3ShapeFaces } from "./v3-graph.js";
-import { V3ContractError } from "./v3-contract.js";
-import { AXES, REPEAT_LIMIT } from "./v3-words.js";
-import { defaultInstanceSizeRange, foldInstanceSizeRange, v3InstanceSizeLimitsOf, V3_INSTANCE_SIZE_DEFAULT, V3_INSTANCE_SIZE_INPUTS } from "./v3-instance-size.js";
-import { V3_PLACEMENTS } from "./v3-asset-types.js";
+import { settleFigureClips } from "./clip-keeping.js";
+import { compileFigureAsset, figurePlacementOf, upgradeFigurePlacement } from "./asset.js";
+import { checkPublicInput, keepPublicInputs } from "./public-inputs.js";
+import { figurePartsExtentOf } from "./gate.js";
+import { compileFigureGraph, figureShapeFaces } from "./graph.js";
+import { figureFollowableAxesOf } from "./shape-provider.js";
+import { FigureContractError } from "./contract.js";
+import { AXES, REPEAT_LIMIT } from "./words.js";
+import { defaultInstanceSizeRange, foldInstanceSizeRange, figureInstanceSizeLimitsOf, FIGURE_INSTANCE_SIZE_DEFAULT, FIGURE_INSTANCE_SIZE_INPUTS } from "./instance-size.js";
+import { FIGURE_PLACEMENTS } from "./asset-types.js";
 const fail = (code, path, message) => {
-    throw new V3ContractError(code, path, message);
+    throw new FigureContractError(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' };
+export const FIGURE_FACES = { left: 'x', right: 'x', bottom: 'y', top: 'y', back: 'z', front: 'z' };
 /**
  * UsdPhysics's joint types (ADR-0093, amended 2026-09-25: the joint follows USD). A `fixed` joint is a fastening; a
  * `revolute` joint turns -- with no limits it turns without end, its value a phase (-180..180), as USD's revolute
  * joint without limits does; a `prismatic` joint slides.
  */
-export const V3_JOINT_TYPES = ['fixed', 'revolute', 'prismatic'];
+export const FIGURE_JOINT_TYPES = ['fixed', 'revolute', 'prismatic'];
 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);
@@ -172,7 +174,7 @@ const OUTER = { x: ['left', 'right'], y: ['bottom', 'top'], z: ['back', 'front']
 /** A part's declared faces, from its shape's own definition, or a refusal saying the shape has none. */
 function facesOfPart(m, id, path) {
     const { shape } = partOf(m, id, path);
-    const faces = v3ShapeFaces(shape.op);
+    const faces = figureShapeFaces(shape.op);
     if (!faces)
         fail('EDIT_TARGET', path, `${id} is a ${shape.op}; it has no flat face to fasten by`);
     return { shape, faces: faces };
@@ -189,12 +191,12 @@ function childFaceOf(m, j) {
         fail('JOINT_SCHEMA', path, 'a part stands on the mounting plane by a face of its own, not by its centre');
     /* One of the six, in the record's words: the face across from it. An opening's face, read from the parent's shape. */
     const named = j.body0.face;
-    if (Object.hasOwn(V3_FACES, named))
-        return Object.keys(V3_FACES).find(f => V3_FACES[f] === V3_FACES[named] && SIGN[f] === -SIGN[named]);
+    if (Object.hasOwn(FIGURE_FACES, named))
+        return Object.keys(FIGURE_FACES).find(f => FIGURE_FACES[f] === FIGURE_FACES[named] && SIGN[f] === -SIGN[named]);
     const theirs = facesOfPart(m, j.body0.part, path).faces[j.body0.face];
     if (!theirs)
         fail('JOINT_SCHEMA', path, `${j.body0.part} has no face ${j.body0.face}`);
-    return Object.keys(V3_FACES).find(f => V3_FACES[f] === theirs.axis && SIGN[f] === -theirs.normal);
+    return Object.keys(FIGURE_FACES).find(f => FIGURE_FACES[f] === theirs.axis && SIGN[f] === -theirs.normal);
 }
 const planeOf = (shape, face) => face.plane.map(p => ({ ref: shape.args[p.arg], k: p.k }));
 /** The part's outer faces on each axis in its own frame; an axis without a pair of flat faces has none. */
@@ -328,7 +330,7 @@ function sourceRef(m, asset, source, path) {
  *
  * "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
+ * left B on the old value (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.
@@ -356,7 +358,7 @@ function stableDimension(m, part, axis, path) {
 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. */
 /**
- * A part's own number for a dimension: a design input named under the part. `addV3Box` names it `<part>.size.<axis>`,
+ * A part's own number for a dimension: a design input named under the part. `addFigureBox` names it `<part>.size.<axis>`,
  * the editor's shape palette `<part>.dimension.width` (and height, depth); both are the part's own, and a dimension
  * read from one follows nothing. Reading only the first name made a palette box look linked as soon as any command
  * had routed its dimension, and a link was refused as a replacement (2026-09-24, :3300).
@@ -415,9 +417,17 @@ function unlinkDimension(asset, a) {
     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))
+    /*
+      The part's own field may still be there: the declared room was measured from it and still reads it, so it stayed
+      when the measure began to follow (ADR-0097). Setting the measure back to fixed takes that field back -- it is the
+      part's own number -- rather than refusing (found 2026-09-27: 「고정으로 되돌리기」 failed on any figure with a room).
+      Only a field of the part's own kind: anything else by that name is refused as before.
+    */
+    const kept = m.inputs.find((i) => i.id === id);
+    if (kept && !(kept.role === 'design' && kept.unit === 'mm'))
         fail('DUPLICATE_WRITER', path, `${id} already exists`);
-    m.inputs.push({ id, unit: 'mm', min: Number.MIN_VALUE, max: Number.MAX_VALUE, role: 'design' });
+    if (!kept)
+        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];
@@ -476,7 +486,7 @@ function attach(asset, a, twist) {
     if (a.part === to.part)
         fail('ATTACH_CYCLE', path, 'a part cannot be fastened to itself');
     const byCentre = a.face === 'centre';
-    if (!byCentre && !Object.hasOwn(V3_FACES, String(a.face)))
+    if (!byCentre && !Object.hasOwn(FIGURE_FACES, String(a.face)))
         fail('SCHEMA', path, `${String(a.face)} is not a face`);
     /* The target's faces are the ones its shape declares: a portal's opening as well as its outer faces. */
     const target = facesOfPart(m, to.part, path);
@@ -492,10 +502,10 @@ function attach(asset, a, twist) {
         fail('ATTACH_FACE', path, `${a.part} fastened by its centre sits on ${to.face}; flush has no meaning for a centre`);
     /* By its centre, the part is measured as the face that would meet the target's; only its offset differs. */
     if (byCentre)
-        a = { ...a, face: Object.keys(V3_FACES).find(f => V3_FACES[f] === axis && SIGN[f] === -sign) };
-    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`);
-    const wanted = Object.keys(V3_FACES).find(f => V3_FACES[f] === axis && SIGN[f] === (facing === 'meet' ? -sign : sign));
+        a = { ...a, face: Object.keys(FIGURE_FACES).find(f => FIGURE_FACES[f] === axis && SIGN[f] === -sign) };
+    if (FIGURE_FACES[a.face] !== axis)
+        fail('ATTACH_FACE', path, `${a.face} faces along ${FIGURE_FACES[a.face]} and ${to.face} along ${axis}; fastening them would need a turn, which this command does not do`);
+    const wanted = Object.keys(FIGURE_FACES).find(f => FIGURE_FACES[f] === axis && SIGN[f] === (facing === 'meet' ? -sign : sign));
     if (facing === 'meet' && a.face !== wanted)
         fail('ATTACH_FACE', path, `to meet ${to.face}, ${a.part} offers its ${wanted}; pass flush to lay ${a.face} in the same plane instead`);
     if (facing === 'flush' && a.face !== wanted)
@@ -640,13 +650,13 @@ function standOnPlane(asset, a, path) {
     if (a.facing !== undefined && a.facing !== 'meet')
         fail('SCHEMA', path, 'a part standing on the plane meets it; flush says nothing here');
     /* Which plane it is, the figure's placement says: the floor or the ceiling is Y = 0, a wall is Z = 0 (ADR-0093). */
-    const placement = (asset.occupancy?.placement ?? 'floor');
+    const placement = figurePlacementOf(asset);
     const takes = planeFacesOf(placement);
     const normal = placement === 'wall' ? 'z' : 'y';
     if (!takes.includes(a.face))
         fail('ATTACH_FACE', path, placement === 'wall'
-            ? `${String(a.face)} faces along ${V3_FACES[a.face] ?? 'no axis'}; the figure hangs on a wall, the plane Z = 0, so a part is fastened to it by its back`
-            : `${String(a.face)} faces along ${V3_FACES[a.face] ?? 'no axis'}; the plane faces along y, so a part stands on it by its bottom or hangs from it by its top`);
+            ? `${String(a.face)} faces along ${FIGURE_FACES[a.face] ?? 'no axis'}; the figure hangs on a wall, the plane Z = 0, so a part is fastened to it by its back`
+            : `${String(a.face)} faces along ${FIGURE_FACES[a.face] ?? 'no axis'}; the plane faces along y, so a part stands on it by its bottom or hangs from it by its top`);
     if (parentOf(m, a.part) && !a.replace)
         fail('ATTACH_REPLACED', path, `${a.part} is already fastened to ${parentOf(m, a.part)}; pass replace to stand it on the plane instead`);
     const mine = standingSpansOf(m, asset, a.part, path);
@@ -701,7 +711,7 @@ function detach(asset, a) {
     /*
       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
+      applied a second time, so a part with 20 mm of travel jumped to 40 (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
@@ -710,7 +720,7 @@ function detach(asset, a) {
     */
     for (let up = parent; up; up = parentOf(m, up))
         requireUnturned(m, asset, up, path);
-    const evaluated = compileV3Asset(asset).evaluate();
+    const evaluated = compileFigureAsset(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`);
@@ -833,8 +843,17 @@ function reseat(asset, id, to, place) {
         dropIfUnused(asset, ref, ownInput(m, id, ref) ? ref : undefined);
 }
 /** Apply one authoring command. Throws on any refusal, leaving the asset it was given untouched. */
-export function applyV3Authoring(source, action) {
-    compileV3Asset(source);
+export function applyFigureAuthoring(source, action, consent) {
+    /*
+      Writing the joints again strips each moving joint's clip with it; which clips stay, go (only when agreed) or refuse
+      the command is settled here, against the figure as it was (clip-keeping.ts).
+    */
+    const before = upgradeFigurePlacement(source);
+    return settleFigureClips(before, authoring(before, action), consent);
+}
+function authoring(source, action) {
+    source = upgradeFigurePlacement(source);
+    compileFigureAsset(source);
     if (!action || typeof action !== 'object')
         fail('SCHEMA', 'action', 'an authoring action is required');
     /* Made of the commands it stands for, each checked as it would be alone. */
@@ -851,6 +870,9 @@ export function applyV3Authoring(source, action) {
         case 'attach':
             fastenAsJoint(asset, action);
             break;
+        case 'set-placement':
+            setPlacement(asset, action);
+            break;
         case 'detach': {
             const joint = jointAbove(asset, action.part);
             if (!joint)
@@ -989,28 +1011,19 @@ export function applyV3Authoring(source, action) {
         rewriteJoints(asset);
     /* An input a command took away takes its place on the board with it (ADR-0096). */
     keepPublicInputs(asset);
-    compileV3Asset(asset);
+    compileFigureAsset(asset);
     if ((action.kind === 'link-dimension' || action.kind === 'make-repeat' || action.kind === 'set-joint') && action.narrowRange)
         narrowDeclaredSize(asset);
     holdsOverDeclaredSize(asset, source);
     return asset;
 }
 /* ----------------------------------------------------------- instance size */
-/** The shapes whose first measures lie along X, Y and Z, and which axes they have. */
-const MEASURED_ALONG = {
-    'box-shape@1': ['x', 'y', 'z'],
-    'rounded-box@1': ['x', 'y', 'z'],
-    'portal-profile@2': ['x', 'y', 'z'],
-    'hollow-box@2': ['x', 'y', 'z'],
-    /* A cylinder's radius is read across (X), its length along (Y). */
-    'cylinder-shape@1': ['x', 'y']
-};
 function followSize(source, a) {
     const path = `${a.part}.follow-size`;
     const shape = source.document.model.nodes.find((n) => n.id === `${a.part}.shape`);
     if (!shape)
         fail('TARGET_ABSENT', path, `${a.part} is not a part`);
-    const along = MEASURED_ALONG[shape.op] ?? [];
+    const along = figureFollowableAxesOf(shape.op);
     if (!along.length)
         fail('EDIT_TARGET', path, `${a.part} is a ${shape.op}; its measures do not lie along X, Y and Z`);
     const axes = a.axes ?? along;
@@ -1020,28 +1033,28 @@ function followSize(source, a) {
     let asset = source;
     const m = asset.document.model;
     if (!AXES.every(axis => sizeInputOf(m, axis))) {
-        const at = v3PartsExtentOf(asset);
+        const at = figurePartsExtentOf(asset);
         const start = defaultInstanceSizeRange(at);
-        const range = foldInstanceSizeRange(start, v3InstanceSizeLimitsOf(asset, start)).range;
-        asset = applyV3Authoring(asset, { kind: 'declare-instance-size', range, at, replace: AXES.some(axis => sizeInputOf(m, axis)) });
+        const range = foldInstanceSizeRange(start, figureInstanceSizeLimitsOf(asset, start)).range;
+        asset = applyFigureAuthoring(asset, { kind: 'declare-instance-size', range, at, replace: AXES.some(axis => sizeInputOf(m, axis)) });
     }
-    const values = compileV3Graph(asset.document.model).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const values = compileFigureGraph(asset.document.model).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
     const argsNow = (asset.document.model.nodes.find((n) => n.id === `${a.part}.shape`)).args;
     for (const axis of axes) {
         const measure = values[argsNow[AXES.indexOf(axis)]];
-        const size = asset.designInputs[V3_INSTANCE_SIZE_INPUTS[axis]];
+        const size = asset.designInputs[FIGURE_INSTANCE_SIZE_INPUTS[axis]];
         if (!(typeof measure === 'number' && measure > 0 && typeof size === 'number' && size > 0))
             fail('EDIT_TARGET', `${path}.${axis}`, `${a.part}'s ${axis} or the figure's size is not a length to follow`);
-        asset = applyV3Authoring(asset, { kind: 'link-dimension', part: a.part, axis, source: { of: 'instance', axis }, times: measure / size, replace: true, narrowRange: true });
+        asset = applyFigureAuthoring(asset, { kind: 'link-dimension', part: a.part, axis, source: { of: 'instance', axis }, times: measure / size, replace: true, narrowRange: true });
     }
     return asset;
 }
-const sizeInputOf = (m, axis) => m.inputs.find((i) => i.id === V3_INSTANCE_SIZE_INPUTS[axis]);
+const sizeInputOf = (m, axis) => m.inputs.find((i) => i.id === FIGURE_INSTANCE_SIZE_INPUTS[axis]);
 function declareInstanceSize(asset, a) {
     const m = asset.document.model;
     const declared = AXES.filter(axis => sizeInputOf(m, axis));
     if (declared.length && !a.replace)
-        fail('INSTANCE_SIZE_DECLARED', 'size', `the instance size is already declared (${declared.map(x => V3_INSTANCE_SIZE_INPUTS[x]).join(', ')}); pass replace to change its range`);
+        fail('INSTANCE_SIZE_DECLARED', 'size', `the instance size is already declared (${declared.map(x => FIGURE_INSTANCE_SIZE_INPUTS[x]).join(', ')}); pass replace to change its range`);
     if (!a.range || typeof a.range !== 'object')
         fail('SCHEMA', 'size', 'a range per axis is required');
     let measured;
@@ -1049,18 +1062,18 @@ function declareInstanceSize(asset, a) {
         const given = a.at?.[axis];
         if (given !== undefined)
             return given;
-        const existing = asset.designInputs[V3_INSTANCE_SIZE_INPUTS[axis]];
+        const existing = asset.designInputs[FIGURE_INSTANCE_SIZE_INPUTS[axis]];
         if (typeof existing === 'number')
             return existing;
         /* The parts as they rest, not the room their joints carry them through (a door's swing). */
         if (!measured)
-            measured = v3PartsExtentOf(asset);
+            measured = figurePartsExtentOf(asset);
         return measured[axis];
     };
     for (const axis of AXES) {
         const r = a.range[axis];
         const at = authoredOf(axis);
-        const path = V3_INSTANCE_SIZE_INPUTS[axis];
+        const path = FIGURE_INSTANCE_SIZE_INPUTS[axis];
         if (!r || ![r.min, r.max, at].every(Number.isFinite))
             fail('SCHEMA', path, 'finite min, max and size required');
         if (!(r.min > 0))
@@ -1088,7 +1101,7 @@ function sizeRangeGaps(asset) {
     if (!AXES.every(axis => sizeInputOf(m, axis)))
         return [];
     const range = Object.fromEntries(AXES.map(axis => [axis, { min: sizeInputOf(m, axis).min, max: sizeInputOf(m, axis).max }]));
-    const limits = v3InstanceSizeLimitsOf(asset, range);
+    const limits = figureInstanceSizeLimitsOf(asset, range);
     const { range: holds } = foldInstanceSizeRange(range, limits);
     const gaps = [];
     for (const axis of AXES) {
@@ -1108,9 +1121,9 @@ function narrowDeclaredSize(asset) {
         return;
     for (const gap of sizeRangeGaps(asset)) {
         const input = sizeInputOf(m, gap.axis);
-        const at = asset.designInputs[V3_INSTANCE_SIZE_INPUTS[gap.axis]];
+        const at = asset.designInputs[FIGURE_INSTANCE_SIZE_INPUTS[gap.axis]];
         if (gap.bound === 'min' ? at < gap.need : at > gap.need)
-            fail('INSTANCE_SIZE_RANGE', V3_INSTANCE_SIZE_INPUTS[gap.axis], `the figure is authored at ${at} mm, where a length is already gone; change the link or the size`);
+            fail('INSTANCE_SIZE_RANGE', FIGURE_INSTANCE_SIZE_INPUTS[gap.axis], `the figure is authored at ${at} mm, where a length is already gone; change the link or the size`);
         if (gap.bound === 'min')
             input.min = gap.need;
         else
@@ -1133,7 +1146,7 @@ function holdsOverDeclaredSize(asset, before) {
         const worse = !prior || (gap.bound === 'min' ? gap.need > prior.need + 1e-9 || gap.declared < prior.declared : gap.need < prior.need - 1e-9 || gap.declared > prior.declared);
         if (!worse)
             continue;
-        const path = V3_INSTANCE_SIZE_INPUTS[gap.axis];
+        const path = FIGURE_INSTANCE_SIZE_INPUTS[gap.axis];
         const by = gap.who ? ` (${gap.who})` : '';
         if (gap.bound === 'min')
             fail('INSTANCE_SIZE_RANGE', path, `below ${round6(gap.need)} mm a length goes to zero${by}; declare the smallest size at ${round6(gap.need)} mm or more`);
@@ -1141,7 +1154,7 @@ function holdsOverDeclaredSize(asset, before) {
     }
 }
 /** What each part is fastened to, for a reader that wants the structure rather than the graph. */
-export function v3AttachmentsOf(asset) {
+export function figureAttachmentsOf(asset) {
     const m = asset.document.model;
     const out = {};
     for (const n of m.nodes)
@@ -1161,8 +1174,8 @@ function checkJoint(asset, j) {
     const path = `joints.${String(j?.id)}`;
     if (!j || typeof j.id !== 'string' || !j.id.trim())
         fail('JOINT_SCHEMA', 'joints', 'a joint has an id');
-    if (!V3_JOINT_TYPES.includes(j.type))
-        fail('JOINT_SCHEMA', path, `${String(j.type)} is not a joint type; ${V3_JOINT_TYPES.join(', ')}`);
+    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);
@@ -1247,7 +1260,7 @@ function checkJoint(asset, j) {
             fail('JOINT_SCHEMA', row, 'a row fills the part it is fastened to; the mounting plane has no length to fill');
         if (!['X', 'Y', 'Z'].includes(r.axis))
             fail('JOINT_SCHEMA', row, `a row runs along X, Y or Z, not ${String(r.axis)}`);
-        if (r.axis.toLowerCase() === V3_FACES[childFaceOf(asset.document.model, j)])
+        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) : !(r.pitch && typeof r.pitch === 'object' && r.pitch.from))
             fail('GEOMETRY_DOMAIN', row, 'a row has a positive pitch, or one that follows a length');
@@ -1282,7 +1295,7 @@ function writeJoint(asset, j) {
     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 = V3_FACES[childFace];
+    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);
@@ -1373,7 +1386,7 @@ function standingTurnOf(asset, part, path) {
         fail('EDIT_TARGET', path, `${part} is turned (${saidTurn(turn)}); fastening to a turned part by its faces is covered only for quarter turns`);
     const quarter = turn.every(t => t === 0) ? IDENTITY : turnMatrix(turn);
     /* A twisted part stands twisted about the normal of the face it is fastened by. */
-    return record?.origin?.twist ? mul3(axisTurn(V3_FACES[childFaceOf(asset.document.model, record)], record.origin.twist), quarter) : quarter;
+    return record?.origin?.twist ? mul3(axisTurn(FIGURE_FACES[childFaceOf(asset.document.model, record)], record.origin.twist), quarter) : quarter;
 }
 /** How a part stands before its twist: its quarter turn only. */
 function standingQuarterOf(asset, part, path) {
@@ -1689,7 +1702,7 @@ function rewriteJoints(asset) {
  * was no longer there, and the author could not save (TARGET_ABSENT on joints.*, 2026-09-25).
  */
 /** The records follow a part's new name -- as a joint's parent, as its child, and as the joint a follower follows -- and the nodes are made again from them. */
-export function renameV3PartInJoints(asset, from, to) {
+export function renameFigurePartInJoints(asset, from, to) {
     const joints = asset.joints;
     if (!joints?.length)
         return;
@@ -1746,7 +1759,7 @@ function refuseIfRead(asset, part, spaceFittedAgain = false) {
  * A copied part is fastened as the original is: its own record, the same faces and place, so it is not held by nodes
  * no record makes. A moving joint gets its own control -- a copy is a second thing, not the original's shadow.
  */
-export function copyV3PartJoint(asset, from, to) {
+export function copyFigurePartJoint(asset, from, to) {
     const joints = (asset.joints ?? []);
     const j = joints.find(o => o.body1.part === from);
     if (!j)
@@ -1799,7 +1812,7 @@ function baseUnitOf(type) {
  * size or place becomes the number it is now. One thing is refused, by name: a row laid along it, or hanging in it --
  * a row is made from its record, and a record needs the part (ADR-0093).
  */
-export function releaseV3PartJoints(asset, part, options = {}) {
+export function releaseFigurePartJoints(asset, part, options = {}) {
     const a = asset;
     const m = a.document.model;
     const notice = { released: [], fixed: [], controls: [] };
@@ -1815,7 +1828,7 @@ export function releaseV3PartJoints(asset, part, options = {}) {
     const inputs = (over = {}) => ({ ...a.designInputs, ...a.stateDefaults, ...over });
     const controls = m.inputs.filter((i) => i.role === 'state');
     const rest = Object.fromEntries(controls.map((i) => [i.id, Math.min(i.max, Math.max(i.min, 0))]));
-    const graph = compileV3Graph(m);
+    const graph = compileFigureGraph(m);
     const atRest = graph.evaluate(inputs(rest)).values;
     const now = graph.evaluate(inputs()).values;
     /* A part moving with a joint that goes: its own control, over what the leader's distance or angle came to. */
@@ -1848,7 +1861,7 @@ export function releaseV3PartJoints(asset, part, options = {}) {
             return measure;
         const probe = structuredClone(m);
         const ref = stableDimension(probe, part, measure.from.axis, where);
-        const value = round6(Number(compileV3Graph(probe).evaluate(inputs()).values[ref]) * (measure.times ?? 1) + (measure.plus ?? 0));
+        const value = round6(Number(compileFigureGraph(probe).evaluate(inputs()).values[ref]) * (measure.times ?? 1) + (measure.plus ?? 0));
         notice.fixed.push({ part: where, value, unit: 'mm' });
         return value;
     };
@@ -2066,7 +2079,7 @@ function setJoint(asset, joint) {
     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(V3_FACES[childFaceOf(asset.document.model, j)]);
+        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)
@@ -2092,7 +2105,7 @@ function removeJoint(asset, id) {
         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 = compileV3Asset(asset).evaluate();
+    const evaluated = compileFigureAsset(asset).evaluate();
     const placed = nodeById(m, child);
     const at = evaluated.values?.[placed.args[1]];
     if (!at?.t)
@@ -2147,7 +2160,7 @@ function fastenAsJoint(asset, a) {
  * 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 checkV3Joints(asset) {
+export function checkFigureJoints(asset) {
     const joints = asset.joints;
     if (!joints?.length)
         return;
@@ -2306,7 +2319,8 @@ function removeMotion(asset, a) {
 }
 /** 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 });
+    /* The room and the placement are left out: neither changes what the room would measure (ADR-0097). */
+    const text = JSON.stringify({ ...asset, placement: undefined, occupancy: asset.occupancy ? { ...asset.occupancy, bounds: null } : undefined });
     let h1 = 0x811c9dc5;
     let h2 = 0x01000193;
     for (let i = 0; i < text.length; i++) {
@@ -2699,7 +2713,7 @@ function occupancyLins(asset, over) {
         const own = occupiedExtentsOf(m, id, id, turns);
         const c = turns ? IDENTITY : worldTurnOf(m, asset, id);
         if (!c)
-            throw new V3ContractError('EDIT_TARGET', id, `${id} is turned by other than quarter turns`);
+            throw new FigureContractError('EDIT_TARGET', id, `${id} is turned by other than quarter turns`);
         return Object.fromEntries(AXES.map((axis, i) => [axis, own[AXES[c[i].findIndex(v => v !== 0)]]]));
     };
     /*
@@ -2749,7 +2763,7 @@ function occupancyLins(asset, over) {
             sizes = sizesOf(place.id, turns);
         }
         catch (e) {
-            skipped.push({ part: place.id, reason: e instanceof V3ContractError ? e.message : 'not a part whose size this command can read' });
+            skipped.push({ part: place.id, reason: e instanceof FigureContractError ? e.message : 'not a part whose size this command can read' });
             continue;
         }
         /*
@@ -2818,7 +2832,7 @@ function occupancyLins(asset, over) {
         }
         /*
           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
+          −40 mm puts the low end at the control's maximum (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.
@@ -2890,7 +2904,8 @@ function occupancyLins(asset, over) {
 }
 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 = {}) {
+export function proposeFigureOccupancy(asset, options = {}) {
+    asset = upgradeFigurePlacement(asset);
     const over = options.over ?? 'range';
     if (over !== 'rest' && over !== 'range')
         fail('SCHEMA', 'over', `${String(over)} is neither rest nor range`);
@@ -2903,28 +2918,35 @@ export function proposeV3Occupancy(asset, options = {}) {
         }
     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 values = compileFigureGraph(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) };
 }
+/**
+ * The placement says which plane the mounting plane is. A part already fastened to it by a face the new plane does not
+ * take -- a bottom on the floor, when the figure is to hang on a wall -- is named, not seated again without a word
+ * (chief architect's condition, 2026-09-25): fasten it again by the face the new plane takes.
+ */
+function setPlacement(asset, a) {
+    if (!FIGURE_PLACEMENTS.includes(a.placement))
+        fail('SCHEMA', 'placement', `${String(a.placement)} is not a placement`);
+    const takes = planeFacesOf(a.placement);
+    const misfit = (asset.joints ?? []).filter(j => 'plane' in j.body0 && !takes.includes(j.body1.face));
+    if (misfit.length)
+        fail('PLACEMENT_PLANE', 'placement', `${misfit.map(j => `${j.body1.part} (${j.body1.face})`).join(', ')} ${misfit.length > 1 ? 'are' : 'is'} fastened to the mounting plane by a face a ${a.placement} does not take (${takes.join(' or ')}); detach ${misfit.length > 1 ? 'them' : 'it'} or fasten ${misfit.length > 1 ? 'them' : 'it'} by ${takes.join(' or ')} first`);
+    asset.placement = a.placement;
+    return asset;
+}
 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 (!V3_PLACEMENTS.includes(a.placement))
-        fail('SCHEMA', 'occupancy', `${String(a.placement)} is not a placement`);
-    /*
-      The placement says which plane the mounting plane is. A part already fastened to it by a face the new plane does
-      not take -- a bottom on the floor, when the figure is to hang on a wall -- is named, not seated again without a
-      word (chief architect's condition, 2026-09-25): fasten it again by the face the new plane takes.
-    */
-    const takes = planeFacesOf(a.placement);
-    const misfit = (asset.joints ?? []).filter(j => 'plane' in j.body0 && !takes.includes(j.body1.face));
-    if (misfit.length)
-        fail('PLACEMENT_PLANE', 'occupancy.placement', `${misfit.map(j => `${j.body1.part} (${j.body1.face})`).join(', ')} ${misfit.length > 1 ? 'are' : 'is'} fastened to the mounting plane by a face a ${a.placement} does not take (${takes.join(' or ')}); detach ${misfit.length > 1 ? 'them' : 'it'} or fasten ${misfit.length > 1 ? 'them' : 'it'} by ${takes.join(' or ')} first`);
     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');
+    /* Declared with a placement, the placement is set by the same command as on its own: one value, one check. */
+    if (a.placement !== undefined)
+        setPlacement(asset, { kind: 'set-placement', placement: a.placement });
     const padding = {};
     for (const axis of AXES) {
         const pad = a.padding?.[axis] ?? 0;
@@ -2963,7 +2985,7 @@ function declareOccupancy(asset, a) {
     m.nodes.push({ id, op: 'affine-bounds@1', args, params: { layout: `L${layout.join('.')}` }, outputs: Object.fromEntries(['xmin', 'xmax', 'ymin', 'ymax', 'zmin', 'zmax'].map(p => [p, port(p)])) });
     const bounds = Object.fromEntries(AXES.map(axis => [axis, { min: port(`${axis}min`), max: port(`${axis}max`) }]));
     const was = stringsIn(asset.occupancy?.bounds);
-    asset.occupancy = { ...(asset.occupancy?.contact ? { contact: asset.occupancy.contact } : {}), bounds, placement: a.placement };
+    asset.occupancy = { ...(asset.occupancy?.contact ? { contact: asset.occupancy.contact } : {}), bounds };
     /*
       The room declared before goes with what fed only it. Left in the graph, it kept reading where parts had been
       fastened, and the next fastening was refused over a room no one read (the gantry, 2026-09-25).
@@ -2972,11 +2994,13 @@ function declareOccupancy(asset, a) {
         dropIfUnused(asset, ref);
     /*
       A part's own measure the old room alone still read -- the part follows something else now -- goes too: kept, it
-      was a dial that changed nothing (the turntable after every part followed the one ratio, 2026-09-25).
+      was a dial that changed nothing (the turntable after every part followed the one ratio, 2026-09-25). So does its
+      own position or turn, once a fastening places it: a floor part's height position stayed as a field that moved
+      nothing (browser check, ADR-0097, 2026-09-27). The room's refit names them before it is confirmed (figureRoomRefitOf).
     */
     const placed = new Set(m.nodes.filter((n) => n.op === 'place@1' || n.op === 'member@1').map((n) => n.id));
     for (const input of [...m.inputs])
-        if (input.role === 'design' && placed.has(String(input.id).split('.')[0]) && /\.(dimension|size)\.[a-z]+$/.test(input.id))
+        if (input.role === 'design' && placed.has(String(input.id).split('.')[0]) && /\.(dimension|size|position|rotation)\.[a-z]+$/.test(input.id))
             dropIfUnused(asset, input.id, input.id);
     return asset;
 }
@@ -2985,7 +3009,7 @@ 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)))
+    if (!Object.hasOwn(FIGURE_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}`;
@@ -3028,7 +3052,7 @@ function addBinding(asset, a) {
         fail('DUPLICATE_BINDING', id, 'a place with this id exists; replace it explicitly');
     if (a.role !== 'seat' && a.role !== 'grip')
         fail('ROLE', id, 'a place is a seat or a grip');
-    if (!Object.hasOwn(V3_FACES, String(a.face)))
+    if (!Object.hasOwn(FIGURE_FACES, String(a.face)))
         fail('SCHEMA', id, `${String(a.face)} is not a face`);
     const place = nodeById(m, a.part);
     if (!place || place.op !== 'place@1')
@@ -3083,7 +3107,7 @@ function dropBindingRefs(asset, binding) {
         if (!declared.has(ref) && !m.nodes.some((n) => n.args.includes(ref)))
             m.constants = m.constants.filter((c) => c.id !== ref);
 }
-export function v3BindingsOf(asset) {
+export function figureBindingsOf(asset) {
     const m = asset.document.model;
     const constant = (ref) => m.constants.find((c) => c.id === ref)?.value;
     return asset.document.capabilities.bindings.map((b) => {
@@ -3213,7 +3237,7 @@ function setRepeat(asset, a) {
       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 = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    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);
@@ -3234,7 +3258,7 @@ function setRepeat(asset, a) {
     /* 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 * V3_INSTANCE_SIZE_DEFAULT.times));
+        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);
@@ -3295,14 +3319,15 @@ function scaleUniformly(asset) {
     return asset;
 }
 /** Reads the asset; changes nothing. Refused for a figure that does not grow by one ratio. */
-export function proposeV3Proportion(asset) {
+export function proposeFigureProportion(asset) {
+    asset = upgradeFigurePlacement(asset);
     return proportionPlan(asset);
 }
 function proportionPlan(asset) {
     const m = asset.document.model;
     if (asset.sizing !== 'uniform')
         fail('SIZING_UNDECLARED', 'sizing', 'the figure does not grow by one ratio; declare that first (scale-uniformly), then every length can follow it');
-    const values = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const values = compileFigureGraph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
     const sizeNow = Object.fromEntries(AXES.map(axis => [axis, values[uniformSizeOf(m, axis, 'sizing')]]));
     const plan = { dimensions: [], lengths: [], skipped: [] };
     /* To nine places: the ratio's own mean is kept to six, and its noise is not the author's (0.1, not 0.0999999999787). */
@@ -3339,7 +3364,7 @@ function proportionPlan(asset) {
             plan.skipped.push({ what: `${part}.place`, reason: 'stands by no fastening; fasten it for its place to follow' });
     }
     for (const j of (asset.joints ?? [])) {
-        const faceAxis = V3_FACES[childFaceOf(m, j)];
+        const faceAxis = FIGURE_FACES[childFaceOf(m, j)];
         const gap = j.origin?.gap;
         if (typeof gap === 'number' && gap !== 0)
             plan.lengths.push({ joint: j.id, at: 'gap', axis: faceAxis, times: share(gap, faceAxis) });
@@ -3401,7 +3426,7 @@ function scalePosition(asset, a) {
         fail('TARGET_ABSENT', path, `the instance has no ${size}; declare it before keeping a place in proportion to it`);
     const i = AXES.indexOf(a.axis);
     const was = pose.args[i];
-    const values = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const values = compileFigureGraph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
     const value = values[was];
     const of = values[size];
     if (!Number.isFinite(value))
@@ -3430,7 +3455,7 @@ function fixPosition(asset, a) {
     const was = pose.args[i];
     if (ownInput(m, a.part, was))
         return asset;
-    const values = compileV3Graph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
+    const values = compileFigureGraph(m).evaluate({ ...asset.designInputs, ...asset.stateDefaults }).values;
     const value = round6(values[was]);
     if (!Number.isFinite(value))
         fail('TARGET_ABSENT', path, `${was} has no value to keep`);
@@ -3451,4 +3476,4 @@ function fixPosition(asset, a) {
     dropIfUnused(asset, was);
     return asset;
 }
-//# sourceMappingURL=v3-authoring-actions.js.map
+//# sourceMappingURL=authoring-actions.js.map