@hatiolab/figure-model 0.1.33 → 0.1.34

package/dist/v3-from-v2.js

@@ -11,13 +11,14 @@
  * That is what this file does. It reproduces V2 behaviour; it does not improve the asset.
  *
  * What it cannot express, it refuses by name (ADR-0087 decision 2: no silent flattening):
- *   - a hollow polygon (V3 has hollow boxes only), a cylinder with two radii, a polygon whose path
- *     does not fill its declared size about the centre (V2 itself draws that one off-centre)
- *   - a part rotated off the axes whose size still follows the instance (V2 shears it; V3 cannot)
- *   - joints and parameters (motion semantics are not converted here)
+ *   - a hollow polygon (V3 has hollow boxes only), a polygon whose path does not fill its declared size
+ *   - a part rotated off the axes whose size still follows the instance (V2 shears it; V3 placement is rigid,
+ *     ruling 1: those parts are re-authored, not converted)
+ *   - joints and parameters, until `docs/v3-motion-contract.md` is implemented
  *
- * What it converts but does not carry, it lists in `lost` so the caller can show it. Nothing is dropped
- * without being named there.
+ * What it normalises on purpose it lists in `notes` with the value before and after: a corner radius V2 clamped
+ * when drawing, a polygon path recentred with its placement moved by the same amount, the palette it snapshotted.
+ * What it converts but does not carry, it lists in `lost`. Nothing is dropped without being named in one of the two.
  *
  * `compareV2WithV3` is the definition of "the same" from ADR-0087 decision 2: same part list, each
  * part's centre, world extents and rotation within tolerance, same material, at the base size and at
@@ -31,6 +32,16 @@ import { centredPart } from "./origin.js";
 import { rotatedExtentOf } from "./blueprint.js";
 import { anchorOf, clearance, longAxis, repeatOffset, repeatPlan, sizingPosition, sizingScale } from "./sizing.js";
 import { AXES, REPEAT_LIMIT, SEGMENT_PRESETS } from "./types.js";
+import { driverValue } from "./v3-driver.js";
+import { jointOriginPosition } from "./sizing.js";
+/** A short stable fingerprint of the palette, so a report can say which colours it snapshotted. */
+export function paletteHash(palette) {
+    const text = JSON.stringify(Object.entries(palette).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    let h = 5381;
+    for (let i = 0; i < text.length; i++)
+        h = ((h * 33) ^ text.charCodeAt(i)) >>> 0;
+    return h.toString(16).padStart(8, '0');
+}
 /** The V3 design inputs that stand for the instance size, in mm. */
 export const V3_SIZE_INPUTS = Object.freeze({ x: 'size.x', y: 'size.y', z: 'size.z' });
 /** How far a V2 instance may grow in the converted asset, as a multiple of the base box. */
@@ -153,23 +164,20 @@ function materialOf(part, palette) {
 export function convertV2ToV3(source, options) {
     const lost = [];
     const refusals = [];
+    const notes = [];
     const checked = validate(source);
     if (checked.errors.length) {
         return {
             status: 'refused',
             refusals: checked.errors.map(e => ({ code: 'V2_INVALID', part: e.path, detail: `${e.code}: ${e.message}` })),
-            lost
+            lost,
+            notes
         };
     }
     const src = source;
     const base = src.base;
     const palette = options.palette;
-    if (src.joints?.length)
-        refusals.push({ code: 'JOINTS', detail: `${src.joints.length} joints; motion is not converted` });
-    if (src.parameters?.length)
-        refusals.push({ code: 'PARAMETERS', detail: `${src.parameters.length} parameters; motion is not converted` });
-    for (const clip of src.animations ?? [])
-        lost.push({ code: 'ANIMATION', detail: `animation "${clip.name}" (${clip.channels.length} channels) is not carried` });
+    notes.push({ code: 'PALETTE', detail: `colours snapshotted from palette ${options.paletteId ?? `#${paletteHash(palette)}`}` });
     if (src.detailLevel)
         lost.push({ code: 'DETAIL_LEVEL', detail: `detailLevel "${src.detailLevel}" has no V3 field` });
     if (src.styleKit)
@@ -242,6 +250,27 @@ export function convertV2ToV3(source, options) {
     };
     const plans = [];
     const seen = new Set();
+    // Motion (docs/v3-motion-contract.md), planned after the parts and read when the part nodes are written.
+    const info = new Map();
+    const spinOf = new Map();
+    const shiftsOf = new Map();
+    const frameOf = new Map(); // part → the joint whose frame carries it
+    const motionOf = new Map(); // joint → pose asset.rest → asset
+    const partsByName = new Map(parts.map(cp => [cp.name, cp]));
+    const jointByChild = new Map((src.joints ?? []).map(j => [j.child, j]));
+    const carrierJointOf = (name) => {
+        for (let p = partsByName.get(name); p; p = p.parent ? partsByName.get(p.parent) : undefined) {
+            const j = jointByChild.get(p.name);
+            if (j)
+                return j.name;
+        }
+        return undefined;
+    };
+    for (const cp of parts) {
+        const carrier = carrierJointOf(cp.name);
+        if (carrier)
+            frameOf.set(cp.name, carrier);
+    }
     for (const cp of parts) {
         const name = cp.name;
         if (!/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(name)) {
@@ -253,8 +282,8 @@ export function convertV2ToV3(source, options) {
             continue;
         }
         seen.add(name);
-        if (cp.parent)
-            lost.push({ code: 'PARENT', part: name, detail: `attached to "${cp.parent}"; V3 places it in the asset frame` });
+        if (cp.parent && !frameOf.has(name))
+            lost.push({ code: 'PARENT', part: name, detail: `attached to "${cp.parent}" with no joint above it; V3 places it in the asset frame, where it already was at rest` });
         if (cp.label)
             lost.push({ code: 'LABEL', part: name, detail: 'label has no V3 field' });
         if (cp.materialSlot)
@@ -276,28 +305,37 @@ export function convertV2ToV3(source, options) {
             refusals.push({ code: 'NO_PROVIDER', part: name, detail: `V3 has no hollow ${cp.primitive}` });
             continue;
         }
-        const path = cp.primitive === 'polygon' ? cp.shape?.path ?? [] : [];
+        // A polygon's path is drawn as written, so its bounding box may sit off the part centre. V3 keeps the visible
+        // position: the path is recentred and the placement moves by the same amount (ADR-0087 ruling 3).
+        let path = cp.primitive === 'polygon' ? cp.shape?.path ?? [] : [];
+        const recentre = { x: 0, z: 0 };
         if (cp.primitive === 'polygon') {
-            // V2 sizing reads `size`, but draws the path as written. The two agree only when the path fills the
-            // size box symmetrically about the part centre; otherwise V2 itself draws the part off its declared centre.
             const xs = path.map(q => q.x), zs = path.map(q => q.y);
             const spanX = Math.max(...xs) - Math.min(...xs), spanZ = Math.max(...zs) - Math.min(...zs);
-            const midX = (Math.max(...xs) + Math.min(...xs)) / 2, midZ = (Math.max(...zs) + Math.min(...zs)) / 2;
-            if (path.length < 3 || Math.abs(spanX - cp.transform.size.x) > 1e-6 || Math.abs(spanZ - cp.transform.size.z) > 1e-6 || Math.abs(midX) > 1e-6 || Math.abs(midZ) > 1e-6) {
+            if (path.length < 3 || Math.abs(spanX - cp.transform.size.x) > 1e-6 || Math.abs(spanZ - cp.transform.size.z) > 1e-6) {
+                // V2 sizing reads `size` while the drawing reads the path; when they disagree there is no one truth to keep.
                 refusals.push({
-                    code: 'POLYGON_OFF_CENTRE',
+                    code: 'POLYGON_SIZE_MISMATCH',
                     part: name,
-                    detail: `path spans ${spanX}×${spanZ} about (${midX}, ${midZ}); size says ${cp.transform.size.x}×${cp.transform.size.z} about the centre`
+                    detail: `path spans ${spanX}×${spanZ}; size says ${cp.transform.size.x}×${cp.transform.size.z}`
                 });
                 continue;
             }
+            recentre.x = round6((Math.max(...xs) + Math.min(...xs)) / 2);
+            recentre.z = round6((Math.max(...zs) + Math.min(...zs)) / 2);
+            if (recentre.x !== 0 || recentre.z !== 0) {
+                path = path.map(q => ({ x: round6(q.x - recentre.x), y: round6(q.y - recentre.z) }));
+                notes.push({
+                    code: 'POLYGON_RECENTRED',
+                    part: name,
+                    detail: `path was drawn about (${recentre.x}, ${recentre.z}) in its own frame; moved to the origin and the placement moved by the same amount, so it draws where it drew`
+                });
+            }
             if (cp.shape?.round)
                 lost.push({ code: 'POLYGON_ROUND', part: name, detail: 'V2 ignores round on a polygon; so does V3' });
         }
-        if (cp.primitive === 'cylinder' && Math.abs(cp.transform.size.x - cp.transform.size.z) > 1e-9) {
-            refusals.push({ code: 'CONE', part: name, detail: `size.x ${cp.transform.size.x} ≠ size.z ${cp.transform.size.z}; V3 cylinders have one radius` });
-            continue;
-        }
+        // V2 draws a cylinder with size.x as the top diameter and size.z as the bottom one; unequal sizes are a frustum.
+        const frustum = cp.primitive === 'cylinder' && Math.abs(cp.transform.size.x - cp.transform.size.z) > 1e-9;
         const segments = cp.segments ?? SEG_DEFAULT;
         if ((cp.primitive === 'cylinder' || cp.primitive === 'sphere') && !SEGMENT_PRESETS.includes(segments)) {
             refusals.push({ code: 'SEGMENTS', part: name, detail: `${segments} segments; V3 accepts ${SEGMENT_PRESETS.join(', ')}` });
@@ -341,20 +379,13 @@ export function convertV2ToV3(source, options) {
                 pending.push(a); // aspect-*: follows another axis, settled below
             }
         }
-        for (const a of pending) {
-            const named = rules[a].slice('aspect-'.length);
-            factor[a] = factor[named];
-            centre[a] = times(`${name}.${a}.centre`, { kind: 'const', value: cp.transform.position[a] }, factor[named]);
-        }
-        // The V3 asset frame has its origin at the bottom of the box (ADR-0065); V2 sizing works from the centre.
-        centre.y = { kind: 'ref', ref: g.add(`${name}.y.fromBottom`, g.len(centre.y, `${name}.y.centred`), g.mul(`${name}.y.lift`, size.y, ratio(0.5, 'half'))) };
         // A curved part keeps a round section: both cross axes take the geometric mean of their two factors
         // (`sizing.ts` keepRound). When the two are the same expression the mean is that expression; otherwise
-        // it is a `geomean@1` node.
+        // it is a `geomean@1` node. V2 does this before an aspect axis copies its neighbour, so the copy sees the mean.
         if ((cp.primitive === 'cylinder' || cp.primitive === 'sphere') && cp.keepRound !== false) {
             const spin = cp.primitive === 'sphere' ? null : longAxis(subject);
             const across = AXES.filter(a => a !== spin);
-            const fs = across.map(a => factor[a]);
+            const fs = across.map(a => factor[a] ?? ONE); // an aspect axis is still unresolved here and counts as fixed, as V2's keepRound sees it
             const same = fs.every(f => f.kind === 'one') || fs.every(f => f.kind === 'ref' && f.sig === fs[0].sig);
             if (!same) {
                 const asRef = (f) => (f.kind === 'one' ? ratio(1, 'one') : f.ref);
@@ -363,8 +394,42 @@ export function convertV2ToV3(source, options) {
                     factor[a] = even;
             }
         }
+        for (const a of pending) {
+            const named = rules[a].slice('aspect-'.length);
+            factor[a] = factor[named];
+            centre[a] = times(`${name}.${a}.centre`, { kind: 'const', value: cp.transform.position[a] }, factor[named]);
+        }
+        // The V3 asset frame has its origin at the bottom of the box (ADR-0065); V2 sizing works from the centre.
+        centre.y = { kind: 'ref', ref: g.add(`${name}.y.fromBottom`, g.len(centre.y, `${name}.y.centred`), g.mul(`${name}.y.lift`, size.y, ratio(0.5, 'half'))) };
+        // A recentred polygon moves back by R·c, and that offset follows the world factor of each axis as the drawn
+        // mesh did in V2 (rotation baked, then scaled per world axis).
+        if (recentre.x !== 0 || recentre.z !== 0) {
+            const R = eulerXYZ(cp.transform.rotation);
+            for (const [a, axis] of AXES.entries()) {
+                const k = round6(R[a][0] * recentre.x + R[a][2] * recentre.z);
+                if (k === 0)
+                    continue;
+                const shift = times(`${name}.${axis}.recentre`, { kind: 'const', value: k }, factor[axis]);
+                centre[axis] = { kind: 'ref', ref: g.add(`${name}.${axis}.drawnAt`, g.len(centre[axis], `${name}.${axis}.declared`), g.len(shift, `${name}.${axis}.shift`)) };
+            }
+        }
         // Local dimensions scale by the factor of the world axis each local axis lands on.
         const perm = axisPermutation(cp.transform.rotation);
+        // A cylinder that does not keep its section round goes elliptical under a lopsided instance in V2. V3 cylinders
+        // and frustums have one radius per end (ruling 6: per-axis radii are a shape-definition change, not made here).
+        if (cp.primitive === 'cylinder' && cp.keepRound === false && perm) {
+            const spin = longAxis(subject);
+            const across = AXES.filter(a => a !== spin).map(a => factor[a]);
+            const same = across.every(f => f.kind === 'one') || across.every(f => f.kind === 'ref' && f.sig === across[0].sig);
+            if (!same) {
+                refusals.push({
+                    code: 'ELLIPTIC_SECTION',
+                    part: name,
+                    detail: `keepRound is off and the section follows ${AXES.filter(a => a !== spin).map(a => `${a}:${rules[a]}`).join(' and ')}; V2 draws an ellipse, V3 has one radius per end`
+                });
+                continue;
+            }
+        }
         const follows = AXES.some(a => factor[a].kind !== 'one');
         if (!perm && follows) {
             refusals.push({ code: 'ROTATED_FOLLOWS', part: name, detail: 'rotated off the axes and its size follows the instance; V2 shears it, V3 cannot' });
@@ -372,18 +437,28 @@ export function convertV2ToV3(source, options) {
         }
         const dim = (local) => times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE);
         const localFrame = `${name}.local`;
+        // A part that spins gets its shape in a `spun` frame; the turn maps spun → local.
+        const shapeFrame = () => (spinOf.has(name) ? `${name}.spun` : localFrame);
         const rot = cp.transform.rotation;
         const rotationRefs = AXES.map(a => g.constant(rot?.[a] ?? 0, 'deg', `deg.${rot?.[a] ?? 0}`));
         let shape;
-        if (cp.primitive === 'cylinder') {
+        if (cp.primitive === 'cylinder' && frustum) {
+            // Both radii follow the same cross factor (keepRound made the two cross axes agree above).
+            const across = perm ? factor[perm.x] : ONE;
+            const top = times(`${name}.dim.radiusTop`, { kind: 'const', value: cp.transform.size.x / 2 }, across);
+            const bottom = times(`${name}.dim.radiusBottom`, { kind: 'const', value: cp.transform.size.z / 2 }, across);
+            const height = dim('y');
+            shape = () => g.node(`${name}.shape`, 'frustum-shape@1', [g.len(top, `${name}.radiusTop`), g.len(bottom, `${name}.radiusBottom`), g.len(height, `${name}.height`)], 'shape', { frame: shapeFrame() });
+        }
+        else if (cp.primitive === 'cylinder') {
             const radius = times(`${name}.dim.radius`, { kind: 'const', value: cp.transform.size.x / 2 }, perm ? factor[perm.x] : ONE);
             const length = dim('y');
-            shape = () => g.node(`${name}.shape`, 'cylinder-shape@1', [g.len(radius, `${name}.radius`), g.len(length, `${name}.length`)], 'shape', { frame: localFrame });
+            shape = () => g.node(`${name}.shape`, 'cylinder-shape@1', [g.len(radius, `${name}.radius`), g.len(length, `${name}.length`)], 'shape', { frame: shapeFrame() });
         }
         else if (cp.primitive === 'sphere') {
             const r = (local) => times(`${name}.dim.radius${local.toUpperCase()}`, { kind: 'const', value: cp.transform.size[local] / 2 }, perm ? factor[perm[local]] : ONE);
             const [rx, ry, rz] = [r('x'), r('y'), r('z')];
-            shape = () => g.node(`${name}.shape`, 'sphere-shape@1', [g.len(rx, `${name}.rx`), g.len(ry, `${name}.ry`), g.len(rz, `${name}.rz`)], 'shape', { frame: localFrame });
+            shape = () => g.node(`${name}.shape`, 'sphere-shape@1', [g.len(rx, `${name}.rx`), g.len(ry, `${name}.ry`), g.len(rz, `${name}.rz`)], 'shape', { frame: shapeFrame() });
         }
         else if (cp.primitive === 'polygon') {
             const h = dim('y');
@@ -392,10 +467,14 @@ export function convertV2ToV3(source, options) {
                 times(`${name}.p${i}.x`, { kind: 'const', value: q.x }, fx),
                 times(`${name}.p${i}.z`, { kind: 'const', value: q.y }, fz)
             ]);
-            shape = () => g.node(`${name}.shape`, 'polygon-shape@1', [g.len(h, `${name}.h`), ...points.map((v, i) => g.len(v, `${name}.pt${i}`))], 'shape', { frame: localFrame });
+            shape = () => g.node(`${name}.shape`, 'polygon-shape@1', [g.len(h, `${name}.h`), ...points.map((v, i) => g.len(v, `${name}.pt${i}`))], 'shape', { frame: shapeFrame() });
         }
         else if (cp.primitive === 'rect') {
-            const round = cp.shape?.round ?? 0;
+            // V2 draws the corner with min(round, width/2, depth/2) (things-scene roundedRect). Write what was drawn.
+            const declared = cp.shape?.round ?? 0;
+            const round = round6(Math.min(declared, cp.transform.size.x / 2, cp.transform.size.z / 2));
+            if (round < declared)
+                notes.push({ code: 'ROUND_CLAMPED', part: name, detail: `corner radius declared ${declared} mm, drawn ${round} mm (half of the ${cp.transform.size.x}×${cp.transform.size.z} section)` });
             if (round > 0 && (factor.x.kind !== 'one' || factor.z.kind !== 'one'))
                 lost.push({ code: 'ROUND_NOT_SCALED', part: name, detail: `corner radius ${round} mm stays fixed while the section follows the instance; V2 scales it with the section` });
             const [w, h, d] = [dim('x'), dim('y'), dim('z')];
@@ -405,24 +484,42 @@ export function convertV2ToV3(source, options) {
                 const wallX = times(`${name}.wallX`, { kind: 'const', value: hollow.wall }, fx);
                 const wallZ = times(`${name}.wallZ`, { kind: 'const', value: hollow.wall }, fz);
                 const floor = times(`${name}.floor`, { kind: 'const', value: hollow.floor ?? hollow.wall }, fy);
-                shape = () => g.node(`${name}.shape`, 'hollow-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.constant(round, 'mm', `${name}.round`), g.len(wallX, `${name}.wallX`), g.len(wallZ, `${name}.wallZ`), g.len(floor, `${name}.floor`)], 'shape', { frame: localFrame });
+                shape = () => g.node(`${name}.shape`, 'hollow-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.constant(round, 'mm', `${name}.round`), g.len(wallX, `${name}.wallX`), g.len(wallZ, `${name}.wallZ`), g.len(floor, `${name}.floor`)], 'shape', { frame: shapeFrame() });
             }
             else
-                shape = () => g.node(`${name}.shape`, 'rounded-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.constant(round, 'mm', `${name}.round`)], 'shape', { frame: localFrame });
+                shape = () => g.node(`${name}.shape`, 'rounded-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.constant(round, 'mm', `${name}.round`)], 'shape', { frame: shapeFrame() });
         }
         else {
             const [w, h, d] = [dim('x'), dim('y'), dim('z')];
-            shape = () => g.node(`${name}.shape`, 'box-shape@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`)], 'shape', { frame: localFrame });
+            shape = () => g.node(`${name}.shape`, 'box-shape@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`)], 'shape', { frame: shapeFrame() });
         }
         const appearance = { target: name, material: material };
         if (cp.primitive === 'cylinder' || cp.primitive === 'sphere')
             appearance.segments = segments;
+        info.set(name, { centre, factor, repeat: !!repeat });
         if (!repeat) {
             plans.push({
                 appearance,
                 nodes: () => {
                     const s = shape();
-                    const pose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => g.len(centre[a], `${name}.${a}`)), ...rotationRefs], 'pose', { from: localFrame, to: 'asset' });
+                    const shifts = shiftsOf.get(name) ?? [];
+                    const frame = frameOf.get(name);
+                    const finalTo = frame ? 'asset.rest' : 'asset';
+                    // rest: local → F0; each slide F_k → F_k+1 along an asset axis; the last lands in finalTo.
+                    let pose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => g.len(centre[a], `${name}.${a}`)), ...rotationRefs], 'pose', { from: localFrame, to: shifts.length ? `${name}.rest0` : finalTo });
+                    shifts.forEach((shift, k) => {
+                        const axis = AXES.map(a => ratio(a === shift.axis ? 1 : 0, a === shift.axis ? 'one' : 'zeroRatio'));
+                        const slide = g.node(`${name}.slide${k}`, 'axis-slide@1', [...axis, shift.q], 'pose', { from: `${name}.rest${k}`, to: k === shifts.length - 1 ? finalTo : `${name}.rest${k + 1}` });
+                        pose = g.node(`${name}.shifted${k}`, 'compose@1', [slide, pose], 'pose');
+                    });
+                    if (frame)
+                        pose = g.node(`${name}.moved`, 'compose@1', [motionOf.get(frame), pose], 'pose');
+                    const spin = spinOf.get(name);
+                    if (spin) {
+                        const axis = AXES.map(a => ratio(a === spin.axis ? 1 : 0, a === spin.axis ? 'one' : 'zeroRatio'));
+                        const turn = g.node(`${name}.turn`, 'axis-turn@1', [...axis, spin.q], 'pose', { from: `${name}.spun`, to: localFrame });
+                        pose = g.node(`${name}.spinning`, 'compose@1', [pose, turn], 'pose');
+                    }
                     g.node(name, 'place@1', [s, pose], 'placed');
                 }
             });
@@ -437,7 +534,14 @@ export function convertV2ToV3(source, options) {
             appearance,
             nodes: () => {
                 const s = shape();
-                const memberPose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => (a === axis ? g.constant(0, 'mm', 'zero') : g.len(centre[a], `${name}.${a}`))), ...rotationRefs], 'pose', { from: localFrame, to: itemFrame });
+                let memberPose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => (a === axis ? g.constant(0, 'mm', 'zero') : g.len(centre[a], `${name}.${a}`))), ...rotationRefs], 'pose', { from: localFrame, to: itemFrame });
+                // A spinning repeated part (the conveyor's rollers) turns each copy about its own axis: the turn goes on the member.
+                const spin = spinOf.get(name);
+                if (spin) {
+                    const axisRefs = AXES.map(a => ratio(a === spin.axis ? 1 : 0, a === spin.axis ? 'one' : 'zeroRatio'));
+                    const turn = g.node(`${name}.turn`, 'axis-turn@1', [...axisRefs, spin.q], 'pose', { from: `${name}.spun`, to: localFrame });
+                    memberPose = g.node(`${name}.spinning`, 'compose@1', [memberPose, turn], 'pose');
+                }
                 const member = g.node(name, 'member@1', [s, memberPose], 'placed');
                 const assembly = g.node(`${name}.assembly`, 'assembly@1', [member], 'assembly');
                 let layout;
@@ -459,13 +563,25 @@ export function convertV2ToV3(source, options) {
                     const halfRow = times(`${name}.halfRow`, { kind: 'const', value: -((count - 1) * repeat.pitch) / 2 }, factor[axis]);
                     rowStart = g.add(`${name}.rowStart`, g.add(`${name}.rowCentre`, g.len(centre[axis], `${name}.${axis}`), g.len(halfRow, `${name}.halfRow`)), g.constant(-0.5, 'mm', 'minusHalfMm'));
                 }
-                const rootPose = g.node(`${name}.root`, 'rigid@1', [...AXES.map(a => (a === axis ? rowStart : g.constant(0, 'mm', 'zero'))), ...AXES.map(() => g.constant(0, 'deg', 'deg.0'))], 'pose', { from: itemFrame, to: 'asset' });
+                // The row as a whole shifts with a translation channel and moves with the joint frame that carries it.
+                const shifts = shiftsOf.get(name) ?? [];
+                const frame = frameOf.get(name);
+                const finalTo = frame ? 'asset.rest' : 'asset';
+                let rootPose = g.node(`${name}.root`, 'rigid@1', [...AXES.map(a => (a === axis ? rowStart : g.constant(0, 'mm', 'zero'))), ...AXES.map(() => g.constant(0, 'deg', 'deg.0'))], 'pose', { from: itemFrame, to: shifts.length ? `${name}.rest0` : finalTo });
+                shifts.forEach((shift, k) => {
+                    const axisRefs = AXES.map(a => ratio(a === shift.axis ? 1 : 0, a === shift.axis ? 'one' : 'zeroRatio'));
+                    const slide = g.node(`${name}.slide${k}`, 'axis-slide@1', [...axisRefs, shift.q], 'pose', { from: `${name}.rest${k}`, to: k === shifts.length - 1 ? finalTo : `${name}.rest${k + 1}` });
+                    rootPose = g.node(`${name}.shifted${k}`, 'compose@1', [slide, rootPose], 'pose');
+                });
+                if (frame)
+                    rootPose = g.node(`${name}.moved`, 'compose@1', [motionOf.get(frame), rootPose], 'pose');
                 g.node(`${name}.repeat`, 'repeat@1', [layout, assembly, rootPose], 'collection', { axis });
             }
         });
     }
+    planMotion({ src, g, base, size, info, spinOf, shiftsOf, frameOf, motionOf, asset, refusals, notes, ratio, times, factorOfScale });
     if (refusals.length)
-        return { status: 'refused', refusals, lost };
+        return { status: 'refused', refusals, lost, notes };
     for (const plan of plans) {
         plan.nodes();
         asset.appearance.push(plan.appearance);
@@ -475,47 +591,227 @@ export function convertV2ToV3(source, options) {
     }
     catch (e) {
         const err = e;
-        return { status: 'refused', refusals: [{ code: `V3_${err.code ?? 'COMPILE'}`, part: err.path, detail: err.message }], lost };
+        return { status: 'refused', refusals: [{ code: `V3_${err.code ?? 'COMPILE'}`, part: err.path, detail: err.message }], lost, notes };
     }
-    return { status: 'converted', asset, lost };
+    return { status: 'converted', asset, lost, notes };
 }
 /** The subject the sizing rules read: `sizing` filled in like the blueprint does. */
 function withSizing(cp) {
     return { ...cp, sizing: cp.sizing ?? 'scale' };
 }
-/** Where V2 draws every part (and copy) at an instance scale, as world boxes. */
-export function v2WorldBoxes(source, scale) {
+const I3 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+const mm3 = (a, b) => a.map(r => [0, 1, 2].map(j => r[0] * b[0][j] + r[1] * b[1][j] + r[2] * b[2][j]));
+const mv3 = (a, v) => a.map(r => r[0] * v[0] + r[1] * v[1] + r[2] * v[2]);
+const tr3 = (a) => [0, 1, 2].map(i => [0, 1, 2].map(j => a[j][i]));
+/** Rotation about a unit axis by degrees (Rodrigues), the matrix three's setFromAxisAngle builds. */
+export function axisAngle(axis, deg) {
+    const n = Math.hypot(axis.x, axis.y, axis.z);
+    const [x, y, z] = [axis.x / n, axis.y / n, axis.z / n];
+    const q = (deg * Math.PI) / 180, c = Math.cos(q), s = Math.sin(q), k = 1 - c;
+    return [
+        [c + x * x * k, x * y * k - z * s, x * z * k + y * s],
+        [y * x * k + z * s, c + y * y * k, y * z * k - x * s],
+        [z * x * k - y * s, z * y * k + x * s, c + z * z * k]
+    ];
+}
+/** V2's channel sampling (`things-scene` sampleChannel): hold the ends, `step` keeps the earlier key. */
+function sampleV2(channel, at) {
+    const keys = channel.keys;
+    if (at <= keys[0].at)
+        return keys[0].value;
+    const last = keys[keys.length - 1];
+    if (at >= last.at)
+        return last.value;
+    let i = 0;
+    while (i < keys.length - 2 && keys[i + 1].at <= at)
+        i++;
+    const from = keys[i], to = keys[i + 1];
+    if (channel.interpolation === 'step')
+        return from.value;
+    const span = to.at - from.at;
+    const r = span > 0 ? (at - from.at) / span : 0;
+    if (typeof from.value === 'number')
+        return (from.value + r * (to.value - from.value));
+    const f = from.value, t = to.value;
+    return { x: f.x + r * (t.x - f.x), y: f.y + r * (t.y - f.y), z: f.z + r * (t.z - f.z) };
+}
+/** V2's clip length: the last key time across its channels, in seconds. */
+export function v2ClipDuration(clip) {
+    let last = 0;
+    for (const ch of clip.channels) {
+        const end = ch.keys[ch.keys.length - 1]?.at;
+        if (typeof end === 'number' && end > last)
+            last = end;
+    }
+    return last;
+}
+/**
+ * Where V2 draws every part (and copy) at an instance scale and a motion state, as oriented world boxes.
+ * Motion follows things-scene: a translation channel shifts the part in the figure frame by the part's world
+ * factor; a rotation channel turns it about its own centre in its own frame (R_part·R_ch·R_part⁻¹); a joint turns
+ * everything in its frame about its sized origin, parents first (ADR-0066).
+ */
+export function v2WorldBoxes(source, scale, state = {}) {
     const base = source.base;
     const out = [];
+    const shifts = new Map();
+    const turns = new Map();
+    const jointValues = new Map();
+    const rotationOf = new Map(source.parts.map(p => [p.name, eulerXYZ(p.transform.rotation)]));
+    const apply = (channels, at) => {
+        for (const ch of channels) {
+            if (ch.path === undefined) {
+                jointValues.set(ch.target, (jointValues.get(ch.target) ?? 0) + sampleV2(ch, at));
+                continue;
+            }
+            const v = sampleV2(ch, at);
+            if (ch.path === 'translation') {
+                const s0 = shifts.get(ch.target) ?? { x: 0, y: 0, z: 0 };
+                shifts.set(ch.target, { x: s0.x + v.x, y: s0.y + v.y, z: s0.z + v.z });
+            }
+            else if (ch.path === 'rotation') {
+                const Rp = rotationOf.get(ch.target) ?? I3;
+                const Rch = eulerXYZ(v);
+                const wrapped = mm3(mm3(Rp, Rch), tr3(Rp));
+                turns.set(ch.target, mm3(turns.get(ch.target) ?? I3, wrapped));
+            }
+        }
+    };
+    for (const p of source.parameters ?? []) {
+        const value = state.parameters?.[p.name] ?? p.default ?? p.range.min;
+        const u = p.range.max > p.range.min ? (value - p.range.min) / (p.range.max - p.range.min) : 0;
+        apply(p.clip.channels, u);
+    }
+    for (const clip of source.animations ?? []) {
+        const duration = v2ClipDuration(clip);
+        const t = state.clipTime?.[clip.name] ?? 0;
+        apply(clip.channels, duration > 0 ? t % duration : 0);
+    }
+    // Joint frames: world transform per joint, parents first.
+    const partsByName = new Map(source.parts.map(p => [p.name, p]));
+    const jointByChild = new Map((source.joints ?? []).map(j => [j.child, j]));
+    const carrierOf = (name) => {
+        for (let p = partsByName.get(name); p; p = p.parent ? partsByName.get(p.parent) : undefined) {
+            const j = jointByChild.get(p.name);
+            if (j)
+                return j;
+        }
+        return undefined;
+    };
+    const worldOf = new Map();
+    const worldJoint = (j) => {
+        const known = worldOf.get(j.name);
+        if (known)
+            return known;
+        const child = partsByName.get(j.child);
+        const attach = child.parent ? partsByName.get(child.parent) : undefined;
+        const cj = { origin: { ...j.origin, y: j.origin.y - base.y / 2 } };
+        const at = jointOriginPosition(cj, attach ? withSizing(centredPart(attach, base)) : undefined, scale, base);
+        const o = [at.x * scale.x, at.y * scale.y + (base.y * scale.y) / 2, at.z * scale.z];
+        const limits = j.limits;
+        let q = jointValues.get(j.name) ?? 0;
+        if (limits)
+            q = Math.min(Math.max(q, limits.min), limits.max);
+        let local;
+        if (j.type === 'prismatic') {
+            const n = Math.hypot(j.axis.x, j.axis.y, j.axis.z);
+            local = { r: I3, t: [(j.axis.x / n) * q * scale.x, (j.axis.y / n) * q * scale.y, (j.axis.z / n) * q * scale.z] };
+        }
+        else {
+            const R = axisAngle(j.axis, q);
+            const Ro = mv3(R, o);
+            local = { r: R, t: [o[0] - Ro[0], o[1] - Ro[1], o[2] - Ro[2]] };
+        }
+        const parentJoint = attach ? carrierOf(attach.name) : undefined;
+        const world = parentJoint ? composeRT(worldJoint(parentJoint), local) : local;
+        worldOf.set(j.name, world);
+        return world;
+    };
     for (const part of source.parts) {
         const cp = withSizing(centredPart(part, base));
         const at = sizingPosition(cp, scale, base);
         const sized = sizingScale(cp, scale, base);
-        const extent = rotatedExtentOf(cp);
-        const rotation = eulerXYZ(part.transform.rotation);
+        // V2 draws a two-diameter cylinder as wide as its larger end on both cross axes, while its sizing maths reads
+        // `size` as written. The drawn body is what a converter must match.
+        const drawnSize = { ...cp.transform.size };
+        if (part.primitive === 'cylinder' && drawnSize.x !== drawnSize.z)
+            drawnSize.x = drawnSize.z = Math.max(drawnSize.x, drawnSize.z);
+        const extent = rotatedExtentOf({ transform: { ...cp.transform, size: drawnSize } });
+        let rotation = eulerXYZ(part.transform.rotation);
         const world = (a) => ({ centre: at[a] * scale[a], extent: extent[a] * sized[a] * scale[a], factor: sized[a] * scale[a] });
         const box = { x: world('x'), y: world('y'), z: world('z') };
         box.y.centre += (base.y * scale.y) / 2;
+        // A polygon is drawn where its path says, which may be off the part centre: rotation baked, then scaled per world axis.
+        if (part.primitive === 'polygon' && part.shape?.path?.length) {
+            const xs = part.shape.path.map(q => q.x), zs = part.shape.path.map(q => q.y);
+            const c = [(Math.max(...xs) + Math.min(...xs)) / 2, 0, (Math.max(...zs) + Math.min(...zs)) / 2];
+            for (const [a, axis] of AXES.entries())
+                box[axis].centre += (rotation[a][0] * c[0] + rotation[a][2] * c[2]) * box[axis].factor;
+        }
+        // Local dimensions: each local axis lands on a world axis and takes that axis's factor.
+        const perm = axisPermutation(part.transform.rotation);
+        const dims = [
+            drawnSize.x * (perm ? box[perm.x].factor : 1),
+            drawnSize.y * (perm ? box[perm.y].factor : 1),
+            drawnSize.z * (perm ? box[perm.z].factor : 1)
+        ];
+        // Motion on the part itself: shift in the figure frame by the world factor, turn about the centre.
+        const shift = shifts.get(part.name);
+        if (shift)
+            for (const a of AXES)
+                box[a].centre += shift[a] * box[a].factor;
+        const turn = turns.get(part.name);
+        if (turn)
+            rotation = mm3(turn, rotation);
+        // Then the joint frame that carries it.
+        const carrier = carrierOf(part.name);
+        const W = carrier ? worldJoint(carrier) : undefined;
         const plan = repeatPlan(cp, scale, base);
         const copies = plan ? plan.count : 1;
         for (let i = 0; i < copies; i++) {
-            const centre = { x: box.x.centre, y: box.y.centre, z: box.z.centre };
+            let centre = { x: box.x.centre, y: box.y.centre, z: box.z.centre };
             if (plan)
                 centre[plan.axis] += repeatOffset(i, plan.count, plan.pitch) * box[plan.axis].factor;
-            out.push({ part: part.name, centre, extent: { x: box.x.extent, y: box.y.extent, z: box.z.extent }, rotation });
+            let R = rotation;
+            if (W) {
+                const c = mv3(W.r, [centre.x, centre.y, centre.z]);
+                centre = { x: c[0] + W.t[0], y: c[1] + W.t[1], z: c[2] + W.t[2] };
+                R = mm3(W.r, rotation);
+            }
+            const ext = AXES.map((_, a) => dims.reduce((sum, d, i) => sum + Math.abs(R[a][i]) * d, 0));
+            out.push({ part: part.name, centre, extent: { x: ext[0], y: ext[1], z: ext[2] }, dims, rotation: R });
         }
     }
     return out;
 }
+function composeRT(a, b) {
+    const rt = mv3(a.r, b.t);
+    return { r: mm3(a.r, b.r), t: [rt[0] + a.t[0], rt[1] + a.t[1], rt[2] + a.t[2]] };
+}
 /** Where a converted V3 asset draws every part at an instance size, as world boxes. */
-export function v3WorldBoxes(asset, size) {
+export function v3WorldBoxes(asset, size, stateOverrides = {}) {
     const inputs = { ...asset.designInputs, 'size.x': size.x, 'size.y': size.y, 'size.z': size.z };
-    const evaluated = compileV3Asset({ ...asset, designInputs: inputs }).evaluate();
+    const evaluated = compileV3Asset({ ...asset, designInputs: inputs }).evaluate(stateOverrides);
     return v3WorldBoxesOf(evaluated.geometry, v3WritersOf(asset));
 }
 /** ADR-0087 decision 2 tolerances. */
 export const SAME_TOLERANCE_MM = 1;
 export const SAME_TOLERANCE_DEG = 0.1;
+/** The V3 state overrides that stand for a V2 motion state: parameters by name, drivers at their clip's time. */
+export function v3StateOverrides(asset, state) {
+    const units = new Map(asset.document.model.inputs.map(i => [i.id, i.unit]));
+    const out = {};
+    for (const [name, value] of Object.entries(state.parameters ?? {}))
+        if (units.has(name))
+            out[name] = value;
+    for (const d of asset.drivers ?? []) {
+        const clip = d.id.split('/')[0];
+        const t = state.clipTime?.[clip] ?? 0;
+        const unit = units.get(d.state);
+        out[d.state] = driverValue(d, t, unit === 'deg' || unit === 'rad' ? unit : 'other');
+    }
+    return out;
+}
 function rotationAngleDeg(a, b) {
     // The angle of a·bᵀ. Its trace is the sum of the element-wise products of a and b.
     let trace = 0;
@@ -526,23 +822,26 @@ function rotationAngleDeg(a, b) {
     return (Math.acos(c) * 180) / Math.PI;
 }
 /**
- * "The same" (ADR-0087 decision 2): the V2 source and the V3 asset draw the same parts, each at the same
- * centre and world extents within 1 mm and the same rotation within 0.1°, with the same material, at the
- * base size and at every combination of doubled axes.
+ * "The same" (ADR-0087 decision 2): the V2 source and the V3 asset draw the same parts, each with the same
+ * centre and local dimensions within 1 mm and the same rotation within 0.1° (as a relative angle), with the same
+ * material, at the base size and at every combination of doubled axes, at rest and at every motion state given.
  */
-export function compareV2WithV3(source, asset, factor = 2) {
+export function compareV2WithV3(source, asset, options = {}) {
+    const opts = typeof options === 'number' ? { factor: options } : options;
+    const factor = opts.factor ?? 2;
     const scales = [];
     for (const x of [1, factor])
         for (const y of [1, factor])
             for (const z of [1, factor])
                 scales.push({ x, y, z });
+    const states = [{ label: 'rest' }, ...(opts.states ?? [])];
     const differences = [];
     let boxesCompared = 0;
     const materials = new Map(asset.appearance.map(a => [a.target, a]));
     for (const part of source.parts) {
         const look = materials.get(part.name);
         if (!look) {
-            differences.push({ part: part.name, scale: scales[0], what: 'appearance', v2: JSON.stringify(part.material), v3: 'missing' });
+            differences.push({ part: part.name, scale: scales[0], state: 'rest', what: 'appearance', v2: JSON.stringify(part.material), v3: 'missing' });
             continue;
         }
         const expected = { token: part.material.token };
@@ -553,43 +852,352 @@ export function compareV2WithV3(source, asset, factor = 2) {
         if (part.material.emissive)
             expected.emissive = { token: part.material.emissive.token ?? part.material.token, intensity: part.material.emissive.intensity, on: part.material.emissive.on ?? false };
         if (JSON.stringify(expected) !== JSON.stringify(look.material))
-            differences.push({ part: part.name, scale: scales[0], what: 'material', v2: JSON.stringify(expected), v3: JSON.stringify(look.material) });
+            differences.push({ part: part.name, scale: scales[0], state: 'rest', what: 'material', v2: JSON.stringify(expected), v3: JSON.stringify(look.material) });
         if ((part.primitive === 'cylinder' || part.primitive === 'sphere') && look.segments !== (part.segments ?? SEG_DEFAULT))
-            differences.push({ part: part.name, scale: scales[0], what: 'segments', v2: String(part.segments ?? SEG_DEFAULT), v3: String(look.segments) });
+            differences.push({ part: part.name, scale: scales[0], state: 'rest', what: 'segments', v2: String(part.segments ?? SEG_DEFAULT), v3: String(look.segments) });
     }
-    for (const scale of scales) {
-        const size = { x: source.base.x * scale.x, y: source.base.y * scale.y, z: source.base.z * scale.z };
-        const byPart = (boxes) => {
-            const m = new Map();
-            for (const b of boxes)
-                (m.get(b.part) ?? m.set(b.part, []).get(b.part)).push(b);
-            for (const list of m.values())
-                list.sort((p, q) => p.centre.x - q.centre.x || p.centre.y - q.centre.y || p.centre.z - q.centre.z);
-            return m;
-        };
-        const v2 = byPart(v2WorldBoxes(source, scale));
-        const v3 = byPart(v3WorldBoxes(asset, size));
-        for (const name of new Set([...v2.keys(), ...v3.keys()])) {
-            const a = v2.get(name) ?? [], b = v3.get(name) ?? [];
-            if (a.length !== b.length) {
-                differences.push({ part: name, scale, what: 'copies', v2: String(a.length), v3: String(b.length) });
+    const byPart = (boxes) => {
+        const m = new Map();
+        for (const b of boxes)
+            (m.get(b.part) ?? m.set(b.part, []).get(b.part)).push(b);
+        for (const list of m.values())
+            list.sort((p, q) => p.centre.x - q.centre.x || p.centre.y - q.centre.y || p.centre.z - q.centre.z);
+        return m;
+    };
+    for (const state of states) {
+        const overrides = v3StateOverrides(asset, state);
+        for (const scale of scales) {
+            const size = { x: source.base.x * scale.x, y: source.base.y * scale.y, z: source.base.z * scale.z };
+            const v2 = byPart(v2WorldBoxes(source, scale, state));
+            const v3 = byPart(v3WorldBoxes(asset, size, overrides));
+            for (const name of new Set([...v2.keys(), ...v3.keys()])) {
+                const a = v2.get(name) ?? [], b = v3.get(name) ?? [];
+                if (a.length !== b.length) {
+                    differences.push({ part: name, scale, state: state.label, what: 'copies', v2: String(a.length), v3: String(b.length) });
+                    continue;
+                }
+                for (const [i, p] of a.entries()) {
+                    const q = b[i];
+                    boxesCompared++;
+                    const tag = a.length > 1 ? `[${i}]` : '';
+                    for (const axis of AXES)
+                        if (Math.abs(p.centre[axis] - q.centre[axis]) > SAME_TOLERANCE_MM)
+                            differences.push({ part: name, scale, state: state.label, what: `centre.${axis}${tag}`, v2: p.centre[axis].toFixed(3), v3: q.centre[axis].toFixed(3) });
+                    for (const [i, d] of p.dims.entries())
+                        if (Math.abs(d - q.dims[i]) > SAME_TOLERANCE_MM)
+                            differences.push({ part: name, scale, state: state.label, what: `dims.${AXES[i]}${tag}`, v2: d.toFixed(3), v3: q.dims[i].toFixed(3) });
+                    const turn = rotationAngleDeg(p.rotation, q.rotation);
+                    if (turn > SAME_TOLERANCE_DEG)
+                        differences.push({ part: name, scale, state: state.label, what: `rotation${tag}`, v2: JSON.stringify(p.rotation.map(r => r.map(v => +v.toFixed(4)))), v3: `${turn.toFixed(3)}° apart` });
+                }
+            }
+        }
+    }
+    return { same: differences.length === 0, scales, states: states.map(s => s.label), boxesCompared, differences };
+}
+const V2_UNIT = { '%': 'percent', deg: 'deg', rad: 'rad', mm: 'mm', cm: 'cm', m: 'm', s: 's' };
+/**
+ * Motion, per docs/v3-motion-contract.md. State inputs stand for V2 parameters (name, unit, range, default kept)
+ * and for what clips drive; joints become `attach@1(T·turn·T⁻¹)` chains parents first; part channels become a
+ * slide along an asset axis (times the part's world factor, as V2 shifted it) or a spin about the part's own axis.
+ * What the contract does not cover is refused by name; a channel that moves nothing is noted and skipped.
+ */
+function planMotion(c) {
+    const { src, g, base, size, info, spinOf, shiftsOf, frameOf, motionOf, asset, refusals, notes, ratio } = c;
+    const params = src.parameters ?? [];
+    const clips = src.animations ?? [];
+    const joints = src.joints ?? [];
+    if (!params.length && !clips.length && !joints.length)
+        return;
+    const partsByName = new Map(src.parts.map(p => [p.name, p]));
+    const jointsByName = new Map(joints.map(j => [j.name, j]));
+    // State inputs for parameters.
+    const paramUnit = new Map();
+    for (const p of params) {
+        const unit = V2_UNIT[p.range.unit];
+        if (!unit) {
+            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `unit "${p.range.unit}" has no V3 unit` });
+            continue;
+        }
+        g.input(p.name, unit, p.range.min, p.range.max, 'state');
+        asset.stateDefaults[p.name] = p.default ?? p.range.min;
+        paramUnit.set(p.name, unit);
+    }
+    /** q = v0 + (p - min)·(v1 - v0)/(max - min), written in the output unit. Null when the channel does not move. */
+    const affine = (p, v0, v1, outUnit, hint) => {
+        if (v0 === v1)
+            return null;
+        const pUnit = paramUnit.get(p.name);
+        if (!pUnit)
+            return undefined;
+        const span = p.range.max - p.range.min;
+        let slopeUnit;
+        let slope;
+        if (pUnit === outUnit) {
+            slopeUnit = 'ratio';
+            slope = (v1 - v0) / span;
+        }
+        else if (pUnit === 'percent') {
+            // A percent input reaches the kernel as a ratio (×0.01), so the slope is per ratio.
+            slopeUnit = outUnit;
+            slope = ((v1 - v0) * 100) / span;
+        }
+        else {
+            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `a ${pUnit} parameter cannot write a ${outUnit} value here` });
+            return undefined;
+        }
+        const u = g.add(`${hint}.u`, p.name, g.constant(round6(-p.range.min), pUnit, `${hint}.min`));
+        return g.add(`${hint}.q`, g.mul(`${hint}.scaled`, u, g.constant(round6(slope), slopeUnit, `${hint}.slope`)), g.constant(round6(v0), outUnit, `${hint}.v0`));
+    };
+    const twoKeyLinear = (ch, owner) => {
+        const keys = ch.keys;
+        if (keys.length !== 2 || keys[0].at !== 0 || keys[1].at !== 1 || (ch.interpolation ?? 'linear') !== 'linear') {
+            refusals.push({ code: 'PARAMETER_CURVE', part: owner, detail: `channel to ${ch.target}: only two linear keys at 0 and 1 are written into the graph` });
+            return false;
+        }
+        return true;
+    };
+    const varying = (keys) => AXES.filter(a => keys.some(k => k.value[a] !== keys[0].value[a]));
+    // Which parameter drives each joint; refuse two writers.
+    const jointWriter = new Map();
+    const partWriters = new Map(); // `${part}/${path}/${axis}` → owners
+    const claim = (key, owner, part) => {
+        const owners = partWriters.get(key) ?? new Set();
+        if (owners.size && !owners.has(owner)) {
+            refusals.push({ code: 'MOTION_MULTI_WRITER', part, detail: `${[...owners].join(', ')} and ${owner} both write ${key}; one writer per state` });
+            return false;
+        }
+        owners.add(owner);
+        partWriters.set(key, owners);
+        return true;
+    };
+    for (const p of params) {
+        if (!paramUnit.has(p.name))
+            continue;
+        for (const ch of p.clip.channels) {
+            if (ch.path === undefined) {
+                if (!jointsByName.has(ch.target)) {
+                    refusals.push({ code: 'PARAMETER_TARGET', part: p.name, detail: `channel targets "${ch.target}", which is not a joint` });
+                    continue;
+                }
+                if (!twoKeyLinear(ch, p.name))
+                    continue;
+                if (jointWriter.has(ch.target)) {
+                    refusals.push({ code: 'MOTION_MULTI_WRITER', part: ch.target, detail: `${jointWriter.get(ch.target).p.name} and ${p.name} both drive the joint` });
+                    continue;
+                }
+                const keys = ch.keys;
+                jointWriter.set(ch.target, { p, v0: keys[0].value, v1: keys[1].value });
+                continue;
+            }
+            const part = partsByName.get(ch.target);
+            if (!part) {
+                refusals.push({ code: 'PARAMETER_TARGET', part: p.name, detail: `channel targets "${ch.target}", which is not a part` });
+                continue;
+            }
+            if (!info.has(ch.target))
+                continue; // the part itself was refused above, and that refusal already names it
+            if (ch.path === 'scale') {
+                refusals.push({ code: 'ANIMATION_CHANNEL', part: ch.target, detail: `parameter ${p.name} scales the part; a scale channel is shape deformation, not covered by the motion contract` });
+                continue;
+            }
+            if (ch.pivot) {
+                refusals.push({ code: 'MOTION_PIVOT', part: ch.target, detail: 'a rotation pivot away from the part centre is not covered by the motion contract' });
+                continue;
+            }
+            const keys = ch.keys;
+            const axes = varying(keys);
+            if (axes.length === 0) {
+                notes.push({ code: 'MOTION_STATIC_CHANNEL', part: ch.target, detail: `parameter ${p.name} has a ${ch.path} channel whose keys do not change; nothing to write` });
+                continue;
+            }
+            if (axes.length > 1) {
+                refusals.push({ code: 'MOTION_COMPOUND_CHANNEL', part: ch.target, detail: `${ch.path} varies on ${axes.join(', ')} at once; one axis per channel is covered` });
+                continue;
+            }
+            if (!twoKeyLinear(ch, p.name))
+                continue;
+            const axis = axes[0];
+            if (!claim(`${ch.target}/${ch.path}/${axis}`, p.name, ch.target))
+                continue;
+            const q = affine(p, keys[0].value[axis], keys[1].value[axis], ch.path === 'rotation' ? 'deg' : 'mm', `${p.name}.${ch.target}.${ch.path}`);
+            if (q === undefined)
+                continue;
+            if (q === null)
+                continue;
+            if (ch.path === 'rotation') {
+                if (spinOf.has(ch.target)) {
+                    refusals.push({ code: 'MOTION_MULTI_WRITER', part: ch.target, detail: 'two rotation channels on one part' });
+                    continue;
+                }
+                spinOf.set(ch.target, { axis, q });
+            }
+            else {
+                // V2 shifts a part in the figure frame by the part's world factor along that axis.
+                const f = info.get(ch.target).factor[axis];
+                const scaled = f.kind === 'one' ? q : g.mul(`${p.name}.${ch.target}.shift.${axis}`, q, f.ref);
+                (shiftsOf.get(ch.target) ?? shiftsOf.set(ch.target, []).get(ch.target)).push({ axis, q: scaled });
+            }
+        }
+    }
+    // Clips: a driver per channel, writing a state input of its own.
+    const drivers = [];
+    for (const clip of clips) {
+        const duration = v2ClipDuration(clip);
+        if (!(duration > 0)) {
+            notes.push({ code: 'MOTION_STATIC_CLIP', detail: `animation "${clip.name}" has no duration; nothing to write` });
+            continue;
+        }
+        for (const ch of clip.channels) {
+            const owner = `clip ${clip.name}`;
+            if (ch.path === undefined) {
+                refusals.push({ code: 'ANIMATION_CHANNEL', part: ch.target, detail: `${owner} drives a joint directly; joints are driven by parameters in this contract` });
+                continue;
+            }
+            if (!partsByName.has(ch.target)) {
+                refusals.push({ code: 'ANIMATION_CHANNEL', part: ch.target, detail: `${owner} targets a part that does not exist` });
+                continue;
+            }
+            if (!info.has(ch.target))
+                continue; // refused above under its own name
+            if (ch.path === 'scale') {
+                refusals.push({ code: 'ANIMATION_CHANNEL', part: ch.target, detail: `${owner} scales the part; a scale channel is shape deformation, not covered` });
+                continue;
+            }
+            if (ch.pivot) {
+                refusals.push({ code: 'MOTION_PIVOT', part: ch.target, detail: 'a rotation pivot away from the part centre is not covered' });
                 continue;
             }
-            for (const [i, p] of a.entries()) {
-                const q = b[i];
-                boxesCompared++;
-                for (const axis of AXES) {
-                    if (Math.abs(p.centre[axis] - q.centre[axis]) > SAME_TOLERANCE_MM)
-                        differences.push({ part: name, scale, what: `centre.${axis}${a.length > 1 ? `[${i}]` : ''}`, v2: p.centre[axis].toFixed(3), v3: q.centre[axis].toFixed(3) });
-                    if (Math.abs(p.extent[axis] - q.extent[axis]) > SAME_TOLERANCE_MM)
-                        differences.push({ part: name, scale, what: `extent.${axis}${a.length > 1 ? `[${i}]` : ''}`, v2: p.extent[axis].toFixed(3), v3: q.extent[axis].toFixed(3) });
+            const keys = ch.keys;
+            const axes = varying(keys);
+            if (axes.length === 0) {
+                notes.push({ code: 'MOTION_STATIC_CHANNEL', part: ch.target, detail: `${owner} has a ${ch.path} channel whose keys do not change; nothing to write` });
+                continue;
+            }
+            if (axes.length > 1) {
+                refusals.push({ code: 'MOTION_COMPOUND_CHANNEL', part: ch.target, detail: `${ch.path} varies on ${axes.join(', ')} at once; one axis per channel is covered` });
+                continue;
+            }
+            const axis = axes[0];
+            if (!claim(`${ch.target}/${ch.path}/${axis}`, owner, ch.target))
+                continue;
+            const values = keys.map(k => k.value[axis]);
+            const rotation = ch.path === 'rotation';
+            const stateId = rotation ? `${ch.target}.spin` : `${ch.target}.shift.${axis}`;
+            const min = Math.min(...values), max = Math.max(...values);
+            g.input(stateId, rotation ? 'deg' : 'mm', rotation ? -180 : min, rotation ? 180 : max, 'state');
+            asset.stateDefaults[stateId] = rotation ? normalise180(values[0]) : values[0];
+            drivers.push({
+                id: `${clip.name}/${ch.target}/${ch.path}`,
+                state: stateId,
+                time: { unit: 's', duration },
+                keys: keys.map(k => ({ at: round6(k.at / duration), value: k.value[axis] })),
+                interpolation: ch.interpolation ?? 'linear',
+                loop: 'wrap',
+                accumulates: rotation
+            });
+            notes.push({ code: 'CLIP_TIME', detail: `animation "${clip.name}": V2 keys in seconds, last at ${duration} s; written as duration ${duration} s with fractional keys` });
+            if (rotation) {
+                if (spinOf.has(ch.target)) {
+                    refusals.push({ code: 'MOTION_MULTI_WRITER', part: ch.target, detail: 'two rotation channels on one part' });
+                    continue;
                 }
-                const turn = rotationAngleDeg(p.rotation, q.rotation);
-                if (turn > SAME_TOLERANCE_DEG)
-                    differences.push({ part: name, scale, what: 'rotation', v2: JSON.stringify(p.rotation.map(r => r.map(v => +v.toFixed(4)))), v3: `${turn.toFixed(3)}° apart` });
+                spinOf.set(ch.target, { axis, q: stateId });
+            }
+            else {
+                const f = info.get(ch.target).factor[axis];
+                const scaled = f.kind === 'one' ? stateId : g.mul(`${clip.name}.${ch.target}.shift.${axis}`, stateId, f.ref);
+                (shiftsOf.get(ch.target) ?? shiftsOf.set(ch.target, []).get(ch.target)).push({ axis, q: scaled });
+            }
+        }
+    }
+    if (drivers.length)
+        asset.drivers = drivers;
+    // Joints, parents first.
+    const carrierOf = (name) => {
+        for (let p = partsByName.get(name); p; p = p.parent ? partsByName.get(p.parent) : undefined) {
+            const j = joints.find(x => x.child === p.name);
+            if (j)
+                return j;
+        }
+        return undefined;
+    };
+    const depth = (j) => {
+        const child = partsByName.get(j.child);
+        const above = child?.parent ? carrierOf(child.parent) : undefined;
+        return above ? 1 + depth(above) : 0;
+    };
+    for (const j of [...joints].sort((a, b) => depth(a) - depth(b))) {
+        const child = partsByName.get(j.child);
+        if (!child || !info.has(j.child)) {
+            refusals.push({ code: 'JOINT_CHILD', part: j.name, detail: `child "${j.child}" was not converted` });
+            continue;
+        }
+        if (info.get(j.child).repeat) {
+            refusals.push({ code: 'MOTION_REPEAT', part: j.child, detail: 'a repeated part cannot be a joint child in this contract' });
+            continue;
+        }
+        // The state input: the driving parameter's affine, or the joint's own input when nothing drives it.
+        let q;
+        const writer = jointWriter.get(j.name);
+        const limits = j.limits;
+        if (writer) {
+            const r = affine(writer.p, writer.v0, writer.v1, j.type === 'prismatic' ? 'mm' : 'deg', `${writer.p.name}.${j.name}`);
+            if (r === undefined)
+                continue;
+            if (r === null) {
+                notes.push({ code: 'MOTION_STATIC_CHANNEL', part: j.name, detail: `parameter ${writer.p.name} does not change the joint; it stays at 0` });
+                q = g.constant(0, j.type === 'prismatic' ? 'mm' : 'deg', 'zeroQ');
             }
+            else
+                q = r;
+        }
+        else {
+            const [min, max] = limits ? [limits.min, limits.max] : j.type === 'continuous' ? [-180, 180] : [-1e6, 1e6];
+            q = g.input(j.name, j.type === 'prismatic' ? 'mm' : 'deg', min, max, 'state');
+            asset.stateDefaults[j.name] = 0;
         }
+        if (limits)
+            notes.push({ code: 'JOINT_LIMIT', part: j.name, detail: `V2 clamps a value outside [${limits.min}, ${limits.max}] to the limit; V3 refuses it (INPUT_RANGE)` });
+        if (j.type === 'prismatic')
+            notes.push({ code: 'PRISMATIC_TRAVEL', part: j.name, detail: 'V2 scaled the travel by the instance scale; V3 travel is the value itself, per the contract' });
+        // Sized origin: the carrying part's centre plus the rest offset scaled by that part's world factor (jointOriginPosition).
+        const attach = child.parent ? partsByName.get(child.parent) : undefined;
+        const originC = { ...j.origin, y: j.origin.y - base.y / 2 };
+        const originRef = [];
+        for (const a of AXES) {
+            let expr;
+            if (attach && info.has(attach.name)) {
+                const ai = info.get(attach.name);
+                const ac = centredPart(attach, base).transform.position;
+                const offset = c.times(`${j.name}.origin.${a}.offset`, { kind: 'const', value: round6(originC[a] - ac[a]) }, ai.factor[a]);
+                expr = { kind: 'ref', ref: g.add(`${j.name}.origin.${a}`, g.len(ai.centre[a], `${j.name}.origin.${a}.seat`), g.len(offset, `${j.name}.origin.${a}.off`)) };
+            }
+            else {
+                // No carrying part: only the instance scale moves the origin (V2 keeps the rest position).
+                const v = a === 'y' ? originC.y + base.y / 2 : originC[a];
+                expr = v === 0 ? { kind: 'const', value: 0 } : { kind: 'ref', ref: g.mul(`${j.name}.origin.${a}`, size[a], ratio(v / base[a], `${j.name}.origin.${a}.at`)) };
+            }
+            originRef.push(g.len(expr, `${j.name}.origin.${a}`));
+        }
+        const n = Math.hypot(j.axis.x, j.axis.y, j.axis.z);
+        const axisRefs = AXES.map(a => ratio(j.axis[a] / n, `${j.name}.axis.${a}`));
+        const zeroDeg = AXES.map(() => g.constant(0, 'deg', 'deg.0'));
+        const onParent = `${j.name}.onParent`, onChild = `${j.name}.onChild`;
+        const parentJoint = attach ? carrierOf(attach.name) : undefined;
+        const restFrame = 'asset.rest';
+        const toFrame = parentJoint ? restFrame : 'asset';
+        const A = g.node(`${j.name}.frameOnParent`, 'rigid@1', [...originRef, ...zeroDeg], 'pose', { from: onParent, to: toFrame });
+        const B = g.node(`${j.name}.frameOnChild`, 'rigid@1', [...originRef, ...zeroDeg], 'pose', { from: onChild, to: restFrame });
+        const O = g.node(`${j.name}.motion`, j.type === 'prismatic' ? 'axis-slide@1' : 'axis-turn@1', [...axisRefs, q], 'pose', { from: onChild, to: onParent });
+        let M = g.node(`${j.name}.attach`, 'attach@1', [A, O, B], 'pose');
+        if (parentJoint)
+            M = g.node(`${j.name}.chain`, 'compose@1', [motionOf.get(parentJoint.name), M], 'pose');
+        motionOf.set(j.name, M);
     }
-    return { same: differences.length === 0, scales, boxesCompared, differences };
+}
+function normalise180(deg) {
+    const w = ((((deg + 180) % 360) + 360) % 360) - 180;
+    return w === 180 ? -180 : w;
 }
 //# sourceMappingURL=v3-from-v2.js.map