@hatiolab/figure-model 0.1.34 → 0.1.36

package/dist/v3-from-v2.js

@@ -14,6 +14,7 @@
  *   - 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)
+ *   - a scale channel (a state input moving a dimension), until the shape-dimension contract §2 is implemented
  *   - joints and parameters, until `docs/v3-motion-contract.md` is implemented
  *
  * What it normalises on purpose it lists in `notes` with the value before and after: a corner radius V2 clamped
@@ -33,6 +34,7 @@ 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 { hausdorff, scalePoints, transformPoints, v2BodyPoints } from "./v3-mesh-compare.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) {
@@ -46,6 +48,11 @@ export function paletteHash(palette) {
 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. */
 const SIZE_RANGE = 10;
+/**
+ * The step above a spanned part's room at which its evaluated length is still positive in double precision at the
+ * sizes figures have (mm, up to 10⁵). A numerical stability bound, not a minimum part size (designer's ruling 2).
+ */
+const SPAN_POSITIVE_STEP = 1e-6;
 const ONE = { kind: 'one' };
 const SEG_DEFAULT = 12;
 const RIGHT_ANGLE_TOLERANCE = 1e-9;
@@ -119,6 +126,28 @@ export function eulerXYZ(rotation) {
         [-cx * sy * cz + sx * sz, cx * sy * sz + sx * cz, cx * cy]
     ];
 }
+/**
+ * Which world axis each local axis lies nearest to, for any rotation; null when two local axes claim one world axis
+ * (a 45° turn). Used only when re-authoring a rotated part without shear.
+ */
+function nearestAxisPermutation(rotation) {
+    const r = eulerXYZ(rotation);
+    const out = {};
+    const taken = new Set();
+    for (const [i, local] of AXES.entries()) {
+        let best = 'x', size = -1;
+        for (const [a, world] of AXES.entries()) {
+            const v = Math.abs(r[a][i]);
+            if (v > size)
+                (size = v), (best = world);
+        }
+        if (taken.has(best))
+            return null;
+        taken.add(best);
+        out[local] = best;
+    }
+    return out;
+}
 /** Which world axis each local axis lands on, when the rotation is a multiple of 90° on every axis. */
 function axisPermutation(rotation) {
     if (!AXES.every(a => isRightAngle(rotation?.[a] ?? 0)))
@@ -165,12 +194,15 @@ export function convertV2ToV3(source, options) {
     const lost = [];
     const refusals = [];
     const notes = [];
+    const rangeChanges = [];
+    let method = 'mechanical';
     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,
+            rangeChanges,
             notes
         };
     }
@@ -219,13 +251,39 @@ export function convertV2ToV3(source, options) {
         const cap = REPEAT_LIMIT * cp.repeat.pitch;
         if (sizeMax[axis] > cap) {
             sizeMax[axis] = cap;
-            lost.push({
-                code: 'REPEAT_LIMIT',
+            rangeChanges.push({
+                input: V3_SIZE_INPUTS[axis],
                 part: cp.name,
-                detail: `V2 clamps the copy count at ${REPEAT_LIMIT}; the V3 input ${V3_SIZE_INPUTS[axis]} stops at ${cap} mm instead`
+                v2: `any size; above ${cap} mm V2 stopped adding copies at ${REPEAT_LIMIT} and drew the rest as a shorter row`,
+                v3: { min: sizeMin[axis], max: cap },
+                reason: `V3 refuses a size whose repeat count would exceed ${REPEAT_LIMIT} (fit-pitch@1 RESOURCE_LIMIT) instead of clamping the count`
             });
         }
     }
+    // A spanned part fills the room between its two gaps. Below that room V2 draws a 0.001 mm sliver (`sizing.ts`
+    // SLIVER); V3 refuses a non-positive dimension. The condition is length > 0, nothing more: the size input's
+    // minimum is the room itself plus the smallest step that keeps the evaluated length positive in double precision.
+    // Shrinking the accepted range is a behaviour change and is recorded as one (designer's ruling 2).
+    for (const cp of parts) {
+        const subject = withSizing(cp);
+        for (const a of AXES) {
+            if (anchorOf(subject, base, a) !== 'span')
+                continue;
+            const gaps = clearance(subject, base, a);
+            const room = gaps.min + gaps.max;
+            const floor = room + SPAN_POSITIVE_STEP;
+            if (floor > sizeMin[a]) {
+                sizeMin[a] = floor;
+                rangeChanges.push({
+                    input: V3_SIZE_INPUTS[a],
+                    part: cp.name,
+                    v2: `any size; at or below ${round6(room)} mm the spanned part was drawn as a 0.001 mm sliver`,
+                    v3: { min: floor, max: sizeMax[a] },
+                    reason: `the spanned part must keep a positive length (${SPAN_POSITIVE_STEP} mm is the numerical step above zero, not a minimum part size)`
+                });
+            }
+        }
+    }
     const size = {};
     for (const a of AXES) {
         size[a] = g.input(V3_SIZE_INPUTS[a], 'mm', sizeMin[a], sizeMax[a], 'design');
@@ -254,6 +312,8 @@ export function convertV2ToV3(source, options) {
     const info = new Map();
     const spinOf = new Map();
     const shiftsOf = new Map();
+    // A scale channel: per local axis, a ratio the part's dimensions are multiplied by (contract §2: dims × affine(p)).
+    const scaleOf = 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]));
@@ -289,7 +349,7 @@ export function convertV2ToV3(source, options) {
         if (cp.materialSlot)
             lost.push({ code: 'MATERIAL_SLOT', part: name, detail: 'materialSlot has no V3 field' });
         if (cp.capability)
-            lost.push({ code: 'PART_CAPABILITY', part: name, detail: 'slot/port role is not carried as a V3 binding' });
+            lost.push({ code: 'PART_CAPABILITY', part: name, detail: 'a capability anchor: V2 never draws it; its slot/port role is not carried as a V3 binding yet, so it is placed nowhere' });
         const { material, refusal } = materialOf(cp, palette);
         if (refusal) {
             refusals.push(refusal);
@@ -334,8 +394,6 @@ export function convertV2ToV3(source, options) {
             if (cp.shape?.round)
                 lost.push({ code: 'POLYGON_ROUND', part: name, detail: 'V2 ignores round on a polygon; so does V3' });
         }
-        // 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(', ')}` });
@@ -379,6 +437,13 @@ export function convertV2ToV3(source, options) {
                 pending.push(a); // aspect-*: follows another axis, settled below
             }
         }
+        // A capability anchor is a place, not a body: V2 compiles it apart from the drawn groups and never renders it
+        // (the independent check against the V2 renderer found the converter drawing one). Its position is kept for
+        // joints that attach to it; nothing is placed.
+        if (cp.capability) {
+            info.set(name, { centre, factor, repeat: false });
+            continue;
+        }
         // 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. V2 does this before an aspect axis copies its neighbour, so the copy sees the mean.
@@ -414,60 +479,78 @@ export function convertV2ToV3(source, options) {
             }
         }
         // 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;
-            }
-        }
+        let perm = axisPermutation(cp.transform.rotation);
         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' });
-            continue;
+            const nearest = options.reauthor?.rotatedFollows === 'nearest-axis' ? nearestAxisPermutation(cp.transform.rotation) : null;
+            if (!nearest) {
+                refusals.push({ code: 'ROTATED_FOLLOWS', part: name, detail: 'rotated off the axes and its size follows the instance; V2 shears it, V3 cannot' });
+                continue;
+            }
+            perm = nearest;
+            method = 're-authored';
+            const rot = cp.transform.rotation ?? {};
+            notes.push({
+                code: 'RE_AUTHORED_ROTATED',
+                part: name,
+                detail: `rotated (${AXES.map(a => `${a}:${rot[a] ?? 0}°`).join(', ')}) and its size follows the instance; V2 sheared the mesh. Re-authored rigid: each local dimension follows the world axis it lies nearest to (${AXES.map(a => `${a}→${nearest[a]}`).join(', ')}). Same as V2 where the factors on the in-plane axes agree; different elsewhere, by design`
+            });
         }
-        const dim = (local) => times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE);
+        // A channel scale is planned after the parts and read when the shape node is written, so `dim` is called
+        // inside the shape closures only.
+        const withChannel = (v, local, hint) => {
+            const sc = scaleOf.get(name)?.[local];
+            if (!sc)
+                return v;
+            return { kind: 'ref', ref: g.mul(`${name}.${hint}.scaled`, g.len(v, `${name}.${hint}`), sc) };
+        };
+        const dim = (local) => withChannel(times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE), local, `dim.${local}`);
+        const channelSplits = () => {
+            const sc = scaleOf.get(name);
+            return !!sc && (sc.x ?? null) !== (sc.z ?? null);
+        };
         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' && 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: shapeFrame() });
+        if (cp.primitive === 'cylinder') {
+            // V2 builds every cylinder from a unit cylinder with equal end radii and scales it by size (things-scene
+            // geometry-bank): size.x ≠ size.z, or two cross factors that differ with keepRound off, is an elliptic
+            // cylinder, never a frustum. Equal radii by the same expression stay on cylinder-shape@1.
+            const fx = perm ? factor[perm.x] : ONE, fz = perm ? factor[perm.z] : ONE;
+            const sameFactor = (fx.kind === 'one' && fz.kind === 'one') || (fx.kind === 'ref' && fz.kind === 'ref' && fx.sig === fz.sig);
+            const equalSizes = Math.abs(cp.transform.size.x - cp.transform.size.z) <= 1e-9;
+            if (!(sameFactor && equalSizes))
+                notes.push({ code: 'ELLIPTIC_SECTION', part: name, detail: `section is not a circle (${!equalSizes ? `size.x ${cp.transform.size.x} ≠ size.z ${cp.transform.size.z}` : 'keepRound is off and the two cross axes follow the instance differently'}); written as cylinder-shape@2 with radiusX and radiusZ, as V2 drew it` });
+            shape = () => {
+                const radiusX = withChannel(times(`${name}.dim.radiusX`, { kind: 'const', value: cp.transform.size.x / 2 }, fx), 'x', 'radiusX');
+                const radiusZ = withChannel(times(`${name}.dim.radiusZ`, { kind: 'const', value: cp.transform.size.z / 2 }, fz), 'z', 'radiusZ');
+                const length = dim('y');
+                const round = sameFactor && equalSizes && !channelSplits();
+                return round
+                    ? g.node(`${name}.shape`, 'cylinder-shape@1', [g.len(radiusX, `${name}.radius`), g.len(length, `${name}.length`)], 'shape', { frame: shapeFrame() })
+                    : g.node(`${name}.shape`, 'cylinder-shape@2', [g.len(radiusX, `${name}.radiusX`), g.len(radiusZ, `${name}.radiusZ`), 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: shapeFrame() });
+            const r = (local) => withChannel(times(`${name}.dim.radius${local.toUpperCase()}`, { kind: 'const', value: cp.transform.size[local] / 2 }, perm ? factor[perm[local]] : ONE), local, `radius${local.toUpperCase()}`);
+            shape = () => {
+                const [rx, ry, rz] = [r('x'), r('y'), r('z')];
+                return 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');
             const fx = perm ? factor[perm.x] : ONE, fz = perm ? factor[perm.z] : ONE;
-            const points = path.flatMap((q, i) => [
-                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: shapeFrame() });
+            shape = () => {
+                const h = dim('y');
+                const points = path.flatMap((q, i) => [
+                    withChannel(times(`${name}.p${i}.x`, { kind: 'const', value: q.x }, fx), 'x', `p${i}.x`),
+                    withChannel(times(`${name}.p${i}.z`, { kind: 'const', value: q.y }, fz), 'z', `p${i}.z`)
+                ]);
+                return 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') {
             // V2 draws the corner with min(round, width/2, depth/2) (things-scene roundedRect). Write what was drawn.
@@ -475,23 +558,36 @@ export function convertV2ToV3(source, options) {
             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')];
-            if (hollow) {
-                // V2 scales the finished mesh, so a wall's thickness follows the axis it lies across and the floor follows the height.
-                const fx = perm ? factor[perm.x] : ONE, fy = perm ? factor[perm.y] : ONE, fz = perm ? factor[perm.z] : ONE;
-                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: 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: shapeFrame() });
+            // V2 scales the finished mesh per world axis, so a corner drawn with radius r becomes an elliptic arc with
+            // semi-axes r·fx, r·fz (shape-dimension contract §1). When the two factors are one expression, @1 is enough.
+            const fx = perm ? factor[perm.x] : ONE, fy = perm ? factor[perm.y] : ONE, fz = perm ? factor[perm.z] : ONE;
+            const sameFactor = (fx.kind === 'one' && fz.kind === 'one') || (fx.kind === 'ref' && fz.kind === 'ref' && fx.sig === fz.sig);
+            if (round > 0 && !sameFactor)
+                notes.push({ code: 'CORNER_PER_AXIS', part: name, detail: `corner radius ${round} mm follows x and z differently under sizing; written with per-axis corner semi-axes, as V2 drew it` });
+            shape = () => {
+                const roundX = withChannel(times(`${name}.roundX`, { kind: 'const', value: round }, fx), 'x', 'roundX');
+                const roundZ = withChannel(times(`${name}.roundZ`, { kind: 'const', value: round }, fz), 'z', 'roundZ');
+                const perAxis = round > 0 && (!sameFactor || channelSplits());
+                const [w, h, d] = [dim('x'), dim('y'), dim('z')];
+                if (hollow) {
+                    // A wall's thickness follows the axis it lies across and the floor follows the height.
+                    const wallX = withChannel(times(`${name}.wallX`, { kind: 'const', value: hollow.wall }, fx), 'x', 'wallX');
+                    const wallZ = withChannel(times(`${name}.wallZ`, { kind: 'const', value: hollow.wall }, fz), 'z', 'wallZ');
+                    const floor = withChannel(times(`${name}.floor`, { kind: 'const', value: hollow.floor ?? hollow.wall }, fy), 'y', 'floor');
+                    return perAxis
+                        ? g.node(`${name}.shape`, 'hollow-box@2', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.len(roundX, `${name}.roundX`), g.len(roundZ, `${name}.roundZ`), g.len(wallX, `${name}.wallX`), g.len(wallZ, `${name}.wallZ`), g.len(floor, `${name}.floor`)], 'shape', { frame: shapeFrame() })
+                        : g.node(`${name}.shape`, 'hollow-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.len(roundX, `${name}.round`), g.len(wallX, `${name}.wallX`), g.len(wallZ, `${name}.wallZ`), g.len(floor, `${name}.floor`)], 'shape', { frame: shapeFrame() });
+                }
+                return perAxis
+                    ? g.node(`${name}.shape`, 'rounded-box@2', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.len(roundX, `${name}.roundX`), g.len(roundZ, `${name}.roundZ`)], 'shape', { frame: shapeFrame() })
+                    : g.node(`${name}.shape`, 'rounded-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.len(roundX, `${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: shapeFrame() });
+            shape = () => {
+                const [w, h, d] = [dim('x'), dim('y'), dim('z')];
+                return 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')
@@ -579,9 +675,9 @@ export function convertV2ToV3(source, options) {
             }
         });
     }
-    planMotion({ src, g, base, size, info, spinOf, shiftsOf, frameOf, motionOf, asset, refusals, notes, ratio, times, factorOfScale });
+    planMotion({ src, g, base, size, info, spinOf, shiftsOf, scaleOf, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio, times, factorOfScale });
     if (refusals.length)
-        return { status: 'refused', refusals, lost, notes };
+        return { status: 'refused', refusals, lost, rangeChanges, notes };
     for (const plan of plans) {
         plan.nodes();
         asset.appearance.push(plan.appearance);
@@ -591,9 +687,9 @@ 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, notes };
+        return { status: 'refused', refusals: [{ code: `V3_${err.code ?? 'COMPILE'}`, part: err.path, detail: err.message }], lost, rangeChanges, notes };
     }
-    return { status: 'converted', asset, lost, notes };
+    return { status: 'converted', method, asset, lost, rangeChanges, notes };
 }
 /** The subject the sizing rules read: `sizing` filled in like the blueprint does. */
 function withSizing(cp) {
@@ -651,10 +747,11 @@ export function v2ClipDuration(clip) {
  * 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 = {}) {
+export function v2WorldBoxes(source, scale, state = {}, options = {}) {
     const base = source.base;
     const out = [];
     const shifts = new Map();
+    const scales = new Map();
     const turns = new Map();
     const jointValues = new Map();
     const rotationOf = new Map(source.parts.map(p => [p.name, eulerXYZ(p.transform.rotation)]));
@@ -665,7 +762,11 @@ export function v2WorldBoxes(source, scale, state = {}) {
                 continue;
             }
             const v = sampleV2(ch, at);
-            if (ch.path === 'translation') {
+            if (ch.path === 'scale') {
+                const s0 = scales.get(ch.target) ?? { x: 1, y: 1, z: 1 };
+                scales.set(ch.target, { x: s0.x * v.x, y: s0.y * v.y, z: s0.z * v.z });
+            }
+            else 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 });
             }
@@ -728,32 +829,41 @@ export function v2WorldBoxes(source, scale, state = {}) {
         return world;
     };
     for (const part of source.parts) {
+        // Capability anchors are not drawn by V2 (blueprint `anchors`, not `groups`).
+        if (part.capability)
+            continue;
         const cp = withSizing(centredPart(part, base));
         const at = sizingPosition(cp, scale, base);
         const sized = sizingScale(cp, scale, base);
-        // 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 } });
+        const extent = rotatedExtentOf(cp);
         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.
+        let bodyPath = part.shape?.path;
         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;
+            // The sampled body is centred on its drawn centre, so the path is taken about that centre.
+            bodyPath = part.shape.path.map(q => ({ x: q.x - c[0], y: q.y - c[2] }));
         }
-        // Local dimensions: each local axis lands on a world axis and takes that axis's factor.
+        // A scale channel multiplies the part's own dimensions about its centre (V2 pose.scale in the part frame).
+        const chScale = scales.get(part.name) ?? { x: 1, y: 1, z: 1 };
+        // Surface points: body in its own frame → channel scale → baked rotation → scaled per world axis → motion → centre.
+        const localPoints = options.points
+            ? scalePoints(transformPoints(scalePoints(v2BodyPoints({ primitive: part.primitive, size: drawnSize, segments: part.segments ?? SEG_DEFAULT, round: part.shape?.round, hollow: part.shape?.hollow, path: bodyPath }), chScale), rotation, [0, 0, 0]), { x: box.x.factor, y: box.y.factor, z: box.z.factor })
+            : null;
+        // Local dimensions: each local axis lands on a world axis and takes that axis's factor, times any channel scale
+        // (V2 applies pose.scale in the part's own frame, about its centre).
         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)
+            drawnSize.x * (perm ? box[perm.x].factor : 1) * chScale.x,
+            drawnSize.y * (perm ? box[perm.y].factor : 1) * chScale.y,
+            drawnSize.z * (perm ? box[perm.z].factor : 1) * chScale.z
         ];
         // Motion on the part itself: shift in the figure frame by the world factor, turn about the centre.
         const shift = shifts.get(part.name);
@@ -761,8 +871,11 @@ export function v2WorldBoxes(source, scale, state = {}) {
             for (const a of AXES)
                 box[a].centre += shift[a] * box[a].factor;
         const turn = turns.get(part.name);
-        if (turn)
+        let motionRotation = I3;
+        if (turn) {
             rotation = mm3(turn, rotation);
+            motionRotation = turn;
+        }
         // Then the joint frame that carries it.
         const carrier = carrierOf(part.name);
         const W = carrier ? worldJoint(carrier) : undefined;
@@ -773,13 +886,18 @@ export function v2WorldBoxes(source, scale, state = {}) {
             if (plan)
                 centre[plan.axis] += repeatOffset(i, plan.count, plan.pitch) * box[plan.axis].factor;
             let R = rotation;
+            let M = motionRotation;
             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);
+                M = mm3(W.r, motionRotation);
             }
             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 });
+            const box2 = { part: part.name, centre, extent: { x: ext[0], y: ext[1], z: ext[2] }, dims, rotation: R };
+            if (localPoints)
+                box2.points = transformPoints(localPoints, M, [centre.x, centre.y, centre.z]);
+            out.push(box2);
         }
     }
     return out;
@@ -789,10 +907,32 @@ function composeRT(a, b) {
     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, stateOverrides = {}) {
+export function v3WorldBoxes(asset, size, stateOverrides = {}, options = {}) {
     const inputs = { ...asset.designInputs, 'size.x': size.x, 'size.y': size.y, 'size.z': size.z };
     const evaluated = compileV3Asset({ ...asset, designInputs: inputs }).evaluate(stateOverrides);
-    return v3WorldBoxesOf(evaluated.geometry, v3WritersOf(asset));
+    return v3WorldBoxesOf(evaluated.geometry, v3WritersOf(asset), options);
+}
+/**
+ * Instance scales at which a repeated part's copy count changes, one just below and one just above each
+ * boundary near the base count (completion criterion: repeat-count boundaries).
+ */
+export function repeatBoundaryScales(source) {
+    const out = [];
+    for (const part of source.parts) {
+        if (part.sizing !== 'repeat' || !part.repeat)
+            continue;
+        const axis = part.repeat.axis, pitch = part.repeat.pitch, length = source.base[axis];
+        const count = Math.floor(length / pitch);
+        for (const k of [count, count + 1]) {
+            for (const delta of [-0.5, 0.5]) {
+                const L = k * pitch + delta;
+                if (L <= 0)
+                    continue;
+                out.push({ x: 1, y: 1, z: 1, [axis]: L / length });
+            }
+        }
+    }
+    return out;
 }
 /** ADR-0087 decision 2 tolerances. */
 export const SAME_TOLERANCE_MM = 1;
@@ -829,16 +969,21 @@ function rotationAngleDeg(a, b) {
 export function compareV2WithV3(source, asset, options = {}) {
     const opts = typeof options === 'number' ? { factor: options } : options;
     const factor = opts.factor ?? 2;
+    const mesh = opts.mesh ?? true;
+    const steps = opts.shrink ? [1, factor, 1 / factor] : [1, factor];
     const scales = [];
-    for (const x of [1, factor])
-        for (const y of [1, factor])
-            for (const z of [1, factor])
+    for (const x of steps)
+        for (const y of steps)
+            for (const z of steps)
                 scales.push({ x, y, z });
+    scales.push(...(opts.extraScales ?? []));
     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) {
+        if (part.capability)
+            continue; // an anchor has no body on either side
         const look = materials.get(part.name);
         if (!look) {
             differences.push({ part: part.name, scale: scales[0], state: 'rest', what: 'appearance', v2: JSON.stringify(part.material), v3: 'missing' });
@@ -868,8 +1013,17 @@ export function compareV2WithV3(source, asset, options = {}) {
         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));
+            const v2 = byPart(v2WorldBoxes(source, scale, state, { points: mesh }));
+            let v3;
+            try {
+                v3 = byPart(v3WorldBoxes(asset, size, overrides, { points: mesh }));
+            }
+            catch (e) {
+                // V3 refuses what V2 drew anyway (a collapsed span as a sliver, a joint value past its limit). Recorded, not thrown.
+                const err = e;
+                differences.push({ part: '*', scale, state: state.label, what: `refused:${err.code}`, v2: 'draws it', v3: err.message });
+                continue;
+            }
             for (const name of new Set([...v2.keys(), ...v3.keys()])) {
                 const a = v2.get(name) ?? [], b = v3.get(name) ?? [];
                 if (a.length !== b.length) {
@@ -889,11 +1043,23 @@ export function compareV2WithV3(source, asset, options = {}) {
                     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` });
+                    if (mesh && p.points && q.points) {
+                        const gap = hausdorff(p.points, q.points);
+                        if (gap > SAME_TOLERANCE_MM)
+                            differences.push({ part: name, scale, state: state.label, what: `mesh${tag}`, v2: `${p.points.length} points`, v3: `surface ${gap.toFixed(3)} mm apart` });
+                    }
                 }
             }
         }
     }
-    return { same: differences.length === 0, scales, states: states.map(s => s.label), boxesCompared, differences };
+    return {
+        same: differences.length === 0,
+        scales,
+        states: states.map(s => s.label),
+        boxesCompared,
+        sampling: { toleranceMm: SAME_TOLERANCE_MM, toleranceDeg: SAME_TOLERANCE_DEG, mesh, cornerDivisions: SEGMENT_PRESETS[0], sphereGrid: '6 rings × 12 around + poles', cylinderSegments: "the part's own segment count, both rims" },
+        differences
+    };
 }
 const V2_UNIT = { '%': 'percent', deg: 'deg', rad: 'rad', mm: 'mm', cm: 'cm', m: 'm', s: 's' };
 /**
@@ -903,7 +1069,7 @@ const V2_UNIT = { '%': 'percent', deg: 'deg', rad: 'rad', mm: 'mm', cm: 'cm', m:
  * 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 { src, g, base, size, info, spinOf, shiftsOf, scaleOf, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio } = c;
     const params = src.parameters ?? [];
     const clips = src.animations ?? [];
     const joints = src.joints ?? [];
@@ -919,6 +1085,12 @@ function planMotion(c) {
             refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `unit "${p.range.unit}" has no V3 unit` });
             continue;
         }
+        // V2 keeps parameters, parts and joints in separate name spaces; a V3 graph has one. The parameter keeps its
+        // name (motion contract), so a clash is refused rather than renamed behind the author's back.
+        if (partsByName.has(p.name) || jointsByName.has(p.name) && joints.some(j => j.name === p.name && j.child === p.name)) {
+            refusals.push({ code: 'NAME_COLLISION', part: p.name, detail: `parameter "${p.name}" shares its name with a part; V3 state inputs and parts share one name space` });
+            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);
@@ -949,6 +1121,55 @@ function planMotion(c) {
         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`));
     };
+    /** A dimensionless factor f = s0 + (p - min)·(s1 - s0)/(max - min), for a scale channel. */
+    const affineRatio = (p, s0, s1, hint) => {
+        const pUnit = paramUnit.get(p.name);
+        if (!pUnit)
+            return undefined;
+        const span = p.range.max - p.range.min;
+        if (pUnit !== 'percent' && pUnit !== 'ratio') {
+            // A slope in ratio-per-<unit> has no V3 unit; only dimensionless parameters may scale a dimension.
+            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `a ${pUnit} parameter cannot scale a dimension; a percent or ratio parameter can` });
+            return undefined;
+        }
+        const slope = pUnit === 'percent' ? ((s1 - s0) * 100) / span : (s1 - s0) / span;
+        const u = g.add(`${hint}.u`, p.name, g.constant(round6(-p.range.min), pUnit, `${hint}.min`));
+        return g.add(`${hint}.f`, g.mul(`${hint}.scaled`, u, g.constant(round6(slope), 'ratio', `${hint}.slope`)), g.constant(round6(s0), 'ratio', `${hint}.s0`));
+    };
+    /**
+     * A dimensionless factor through every key of a linear channel: f = curve(u, at₀,s₀, at₁,s₁, …) with u = (p − min)/span
+     * as a ratio in [0, 1], the keys' `at` in the same ratio (piecewise-linear curves, V3 designer's approval
+     * 2026-09-22). Two keys at 0 and 1 take the affine form instead, so earlier assets keep their graphs.
+     */
+    const curveRatio = (p, keys, hint) => {
+        const pUnit = paramUnit.get(p.name);
+        if (!pUnit)
+            return undefined;
+        const span = p.range.max - p.range.min;
+        if (pUnit !== 'percent' && pUnit !== 'ratio') {
+            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `a ${pUnit} parameter cannot scale a dimension; a percent or ratio parameter can` });
+            return undefined;
+        }
+        const slope = pUnit === 'percent' ? 100 / span : 1 / span;
+        const u = g.add(`${hint}.u`, p.name, g.constant(round6(-p.range.min), pUnit, `${hint}.min`));
+        const u01 = g.mul(`${hint}.u01`, u, g.constant(round6(slope), 'ratio', `${hint}.perSpan`));
+        const args = [u01];
+        keys.forEach((k, i) => args.push(g.constant(round6(k.at), 'ratio', `${hint}.at${i}`), g.constant(round6(k.value), 'ratio', `${hint}.s${i}`)));
+        return g.node(`${hint}.curve`, 'curve@1', args, 'value');
+    };
+    /** A linear channel with keys in order inside [0, 1]; anything else is refused by name. */
+    const linearKeys = (ch, owner) => {
+        const keys = ch.keys;
+        if ((ch.interpolation ?? 'linear') !== 'linear') {
+            refusals.push({ code: 'PARAMETER_CURVE', part: owner, detail: `channel to ${ch.target}: ${ch.interpolation} interpolation is not written into the graph; linear keys are` });
+            return false;
+        }
+        if (keys.length < 2 || keys.some((k, i) => i > 0 && !(k.at > keys[i - 1].at)) || keys[0].at < 0 || keys[keys.length - 1].at > 1) {
+            refusals.push({ code: 'PARAMETER_CURVE', part: owner, detail: `channel to ${ch.target}: keys must be two or more, strictly increasing, inside [0, 1]` });
+            return false;
+        }
+        return true;
+    };
     const twoKeyLinear = (ch, owner) => {
         const keys = ch.keys;
         if (keys.length !== 2 || keys[0].at !== 0 || keys[1].at !== 1 || (ch.interpolation ?? 'linear') !== 'linear') {
@@ -997,16 +1218,57 @@ function planMotion(c) {
             }
             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 (ch.path === 'scale') {
+                // Shape-dimension contract §2: a state input may change a dimension. Each varying axis of the part gets a
+                // ratio factor affine in the parameter; the part's centre does not move (V2 scaled about the centre).
+                if (axes.length === 0) {
+                    notes.push({ code: 'MOTION_STATIC_CHANNEL', part: ch.target, detail: `parameter ${p.name} has a scale channel whose keys do not change; nothing to write` });
+                    continue;
+                }
+                if (!linearKeys(ch, p.name))
+                    continue;
+                if (!axisPermutation(partsByName.get(ch.target).transform.rotation)) {
+                    refusals.push({ code: 'ROTATED_FOLLOWS', part: ch.target, detail: 'a scale channel on a part rotated off the axes would shear it; not covered' });
+                    continue;
+                }
+                // A scale of 0 is how V2 hides a part (the lamp glow before it lights). A V3 dimension must be positive, so
+                // this is refused until the designer rules on the rule for it (a floor as for span, or a visibility channel).
+                const zero = axes.find(axis => keys.some(k => k.value[axis] <= 0));
+                if (zero) {
+                    refusals.push({ code: 'SCALE_ZERO', part: ch.target, detail: `parameter ${p.name} scales ${zero} to ${Math.min(...keys.map(k => k.value[zero]))}; V2 draws nothing there, a V3 dimension must be positive` });
+                    continue;
+                }
+                const twoKeys = keys.length === 2 && keys[0].at === 0 && keys[1].at === 1;
+                const entry = scaleOf.get(ch.target) ?? {};
+                let ok = true;
+                for (const axis of axes) {
+                    if (!claim(`${ch.target}/scale/${axis}`, p.name, ch.target)) {
+                        ok = false;
+                        break;
+                    }
+                    const hint = `${p.name}.${ch.target}.scale.${axis}`;
+                    const f = twoKeys
+                        ? affineRatio(p, keys[0].value[axis], keys[1].value[axis], hint)
+                        : curveRatio(p, keys.map(k => ({ at: k.at, value: k.value[axis] })), hint);
+                    if (f === undefined) {
+                        ok = false;
+                        break;
+                    }
+                    entry[axis] = f;
+                }
+                if (!ok)
+                    continue;
+                scaleOf.set(ch.target, entry);
+                const shape = twoKeys ? `${keys[0].value[axes[0]]} → ${keys[1].value[axes[0]]} on ${axes[0]}` : `${keys.length} keys on ${axes[0]}: ${keys.map(k => `${k.at}:${k.value[axes[0]]}`).join(' ')}`;
+                notes.push({ code: 'STATE_DIMENSION', part: ch.target, detail: `dimensions on ${axes.join(', ')} follow parameter ${p.name} (${shape}); the occupancy must hold over its range` });
+                continue;
+            }
             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;
@@ -1157,8 +1419,10 @@ function planMotion(c) {
             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 (limits && !writer)
+            rangeChanges.push({ input: j.name, part: j.name, v2: `any value; outside [${limits.min}, ${limits.max}] V2 clamped it to the limit`, v3: { min: limits.min, max: limits.max }, reason: 'V3 refuses a joint value outside its limits (INPUT_RANGE) instead of clamping' });
+        if (limits && writer)
+            notes.push({ code: 'JOINT_LIMIT', part: j.name, detail: `the joint's limits [${limits.min}, ${limits.max}] are carried by the parameter ${writer.p.name}'s own range; V3 refuses a value outside it where V2 clamped` });
         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).
@@ -1181,7 +1445,8 @@ function planMotion(c) {
             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}`));
+        // Full precision: the kernel accepts a unit axis to 1e-6 and normalises, but the converter does not round it.
+        const axisRefs = AXES.map(a => g.constant(j.axis[a] / n, 'ratio', `${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;