@hatiolab/figure-model 0.1.32 → 0.1.34

package/dist/v3-from-v2.js

@@ -0,0 +1,1203 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+/*
+ * V2 → V3 converter (ADR-0087 decisions 1 and 2).
+ *
+ * A V2 source describes each part by an authored box and a per-axis rule that says how the part
+ * follows the instance size: `scale`, `fixed`/`min`/`max`/`center`, `span`, `aspect-*`, and `repeat`.
+ * Every one of those rules is a first-degree expression in the instance size (`src/sizing.ts`), so the
+ * same placement can be written as a V3 graph of `add@1`, `mul@1`, `div@1` and `fit-pitch@1` nodes.
+ * 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 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 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
+ * every combination of doubled axes.
+ */
+import { compileV3Asset } from "./v3-asset.js";
+import { v3WorldBoxesOf, v3WritersOf } from "./v3-gate.js";
+import { V3ContractError } from "./v3-contract.js";
+import { validate } from "./validate.js";
+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. */
+const SIZE_RANGE = 10;
+const ONE = { kind: 'one' };
+const SEG_DEFAULT = 12;
+const RIGHT_ANGLE_TOLERANCE = 1e-9;
+/** Builds the V3 graph value by value. Constants are shared by value; node ids stay readable. */
+class GraphBuilder {
+    graph = { version: 'r3-spatial-1', inputs: [], constants: [], nodes: [] };
+    ids = new Set();
+    constants = new Map();
+    claim(id, path) {
+        if (this.ids.has(id))
+            throw new V3ContractError('DUPLICATE_WRITER', path, `${id} already exists`);
+        this.ids.add(id);
+        return id;
+    }
+    input(id, unit, min, max, role) {
+        this.graph.inputs.push({ id: this.claim(id, 'input'), unit, min, max, role });
+        return id;
+    }
+    constant(raw, unit, hint) {
+        const value = raw === 0 ? 0 : raw; // -0 would not survive JSON
+        const key = `${unit}:${value}`;
+        const known = this.constants.get(key);
+        if (known)
+            return known;
+        let id = `k.${hint}`;
+        for (let n = 2; this.ids.has(id); n++)
+            id = `k.${hint}.${n}`;
+        this.claim(id, 'constant');
+        this.graph.constants.push({ id, unit, value });
+        this.constants.set(key, id);
+        return id;
+    }
+    node(id, op, args, port, params) {
+        const out = `${id}.value`;
+        const node = { id: this.claim(id, 'node'), op, args, outputs: { [port]: this.claim(out, id) } };
+        if (params)
+            node.params = params;
+        this.graph.nodes.push(node);
+        return out;
+    }
+    add(id, a, b) {
+        return this.node(id, 'add@1', [a, b], 'value');
+    }
+    mul(id, a, b) {
+        return this.node(id, 'mul@1', [a, b], 'value');
+    }
+    div(id, a, b) {
+        return this.node(id, 'div@1', [a, b], 'value');
+    }
+    /** A length as a graph reference: constants become shared constant entries. */
+    len(v, hint) {
+        return v.kind === 'ref' ? v.ref : this.constant(v.value, 'mm', hint);
+    }
+}
+function round6(v) {
+    return Math.round(v * 1e6) / 1e6;
+}
+function isRightAngle(deg) {
+    const turns = deg / 90;
+    return Math.abs(turns - Math.round(turns)) < RIGHT_ANGLE_TOLERANCE;
+}
+/** Rx·Ry·Rz for degrees, the order V2 (`three` 'XYZ') and V3 `rigid@1` share. */
+export function eulerXYZ(rotation) {
+    const rad = Math.PI / 180;
+    const cx = Math.cos((rotation?.x ?? 0) * rad), sx = Math.sin((rotation?.x ?? 0) * rad);
+    const cy = Math.cos((rotation?.y ?? 0) * rad), sy = Math.sin((rotation?.y ?? 0) * rad);
+    const cz = Math.cos((rotation?.z ?? 0) * rad), sz = Math.sin((rotation?.z ?? 0) * rad);
+    return [
+        [cy * cz, -cy * sz, sy],
+        [sx * sy * cz + cx * sz, -sx * sy * sz + cx * cz, -sx * cy],
+        [-cx * sy * cz + sx * sz, cx * sy * sz + sx * cz, cx * cy]
+    ];
+}
+/** 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)))
+        return null;
+    const r = eulerXYZ(rotation);
+    const out = {};
+    for (const [i, local] of AXES.entries()) {
+        const world = AXES.find((_, a) => Math.abs(r[a][i]) > 0.5);
+        if (!world)
+            return null;
+        out[local] = world;
+    }
+    return out;
+}
+function materialOf(part, palette) {
+    const m = part.material ?? {};
+    const known = ['token', 'preset', 'transparent', 'emissive'];
+    const extra = Object.keys(m).filter(k => !known.includes(k));
+    if (extra.length)
+        return { refusal: { code: 'MATERIAL_FIELD', part: part.name, detail: `V3 material has no ${extra.join(', ')}` } };
+    if (!m.token)
+        return { refusal: { code: 'MATERIAL_TOKEN', part: part.name, detail: 'material has no palette token' } };
+    if (!Object.hasOwn(palette, m.token))
+        return { refusal: { code: 'PALETTE_TOKEN', part: part.name, detail: `no colour for ${m.token}` } };
+    const material = { token: m.token };
+    if (m.preset !== undefined)
+        material.preset = m.preset;
+    if (m.transparent !== undefined)
+        material.transparent = m.transparent;
+    if (m.emissive) {
+        const token = m.emissive.token ?? m.token;
+        if (!Object.hasOwn(palette, token))
+            return { refusal: { code: 'PALETTE_TOKEN', part: part.name, detail: `no colour for emissive ${token}` } };
+        // V2 reads a missing `on` as off (`keys.ts`); V3 wants it written down.
+        material.emissive = { token, intensity: m.emissive.intensity, on: m.emissive.on ?? false };
+    }
+    return { material };
+}
+/**
+ * Convert one validated V2 source to a V3 asset that places every part where V2 places it, at every
+ * instance size in the input range. See the file comment for what is refused and what is listed as lost.
+ */
+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,
+            notes
+        };
+    }
+    const src = source;
+    const base = src.base;
+    const palette = options.palette;
+    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)
+        lost.push({ code: 'STYLE_KIT', detail: `styleKit "${src.styleKit}" has no V3 field` });
+    const g = new GraphBuilder();
+    const asset = {
+        version: 'figure-v3-asset-1',
+        name: options.name ?? src.type,
+        document: {
+            version: 'figure-v3-prototype-1',
+            model: g.graph,
+            capabilities: {
+                version: 'r3-capability-3',
+                assetFrame: 'asset',
+                bindings: [],
+                // ADR-0051 ④: the names travel; V3 checks them against the same list V2 did.
+                ...(src.capabilities?.length ? { names: [...src.capabilities] } : {})
+            }
+        },
+        designInputs: {},
+        stateDefaults: {},
+        palette: {},
+        appearance: [],
+        // ADR-0044 · ADR-0045: the V2 base box and placement become the declared occupancy; V2 read a missing placement as floor.
+        occupancy: { extent: { ...V3_SIZE_INPUTS }, placement: src.placement ?? 'floor' }
+    };
+    // Instance size inputs. The range starts at the pitch on a spreading repeat axis (V2 draws at least one
+    // copy below that; `fit-pitch@1` draws none) and stops where V2 would silently clamp the copy count.
+    const sizeMin = { x: 1, y: 1, z: 1 };
+    const sizeMax = { x: base.x * SIZE_RANGE, y: base.y * SIZE_RANGE, z: base.z * SIZE_RANGE };
+    const parts = src.parts.map(p => centredPart(p, base));
+    for (const cp of parts) {
+        if (cp.sizing !== 'repeat' || !cp.repeat)
+            continue;
+        const axis = cp.repeat.axis;
+        if (anchorOf(withSizing(cp), base, axis) === 'scale')
+            continue;
+        sizeMin[axis] = Math.max(sizeMin[axis], cp.repeat.pitch);
+        const cap = REPEAT_LIMIT * cp.repeat.pitch;
+        if (sizeMax[axis] > cap) {
+            sizeMax[axis] = cap;
+            lost.push({
+                code: 'REPEAT_LIMIT',
+                part: cp.name,
+                detail: `V2 clamps the copy count at ${REPEAT_LIMIT}; the V3 input ${V3_SIZE_INPUTS[axis]} stops at ${cap} mm instead`
+            });
+        }
+    }
+    const size = {};
+    for (const a of AXES) {
+        size[a] = g.input(V3_SIZE_INPUTS[a], 'mm', sizeMin[a], sizeMax[a], 'design');
+        asset.designInputs[V3_SIZE_INPUTS[a]] = base[a];
+    }
+    const ratio = (v, hint) => g.constant(round6(v), 'ratio', hint);
+    const scaleFactor = new Map();
+    const factorOfScale = (a) => {
+        let f = scaleFactor.get(a);
+        if (!f) {
+            f = { kind: 'ref', ref: g.div(`scale.${a}`, size[a], g.constant(base[a], 'mm', `base.${a}`)), sig: `scale.${a}` };
+            scaleFactor.set(a, f);
+        }
+        return f;
+    };
+    const times = (id, v, f) => {
+        if (f.kind === 'one')
+            return v;
+        if (v.kind === 'const' && v.value === 0)
+            return v;
+        return { kind: 'ref', ref: g.mul(id, g.len(v, id), f.ref) };
+    };
+    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)) {
+            refusals.push({ code: 'PART_ID', part: name, detail: 'V3 ids start with a letter and use letters, digits, _ . -' });
+            continue;
+        }
+        if (seen.has(name)) {
+            refusals.push({ code: 'PART_ID', part: name, detail: 'duplicate part name' });
+            continue;
+        }
+        seen.add(name);
+        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)
+            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' });
+        const { material, refusal } = materialOf(cp, palette);
+        if (refusal) {
+            refusals.push(refusal);
+            continue;
+        }
+        for (const token of [material.token, material.emissive?.token])
+            if (token)
+                asset.palette[token] = palette[token];
+        if (cp.primitive === 'wall')
+            lost.push({ code: 'WALL_KIND', part: name, detail: 'drawn as a box; the "wall" kind has no V3 field' });
+        const hollow = cp.shape?.hollow && cp.shape.hollow.wall > 0 ? cp.shape.hollow : null;
+        if (hollow && cp.primitive !== 'rect') {
+            refusals.push({ code: 'NO_PROVIDER', part: name, detail: `V3 has no hollow ${cp.primitive}` });
+            continue;
+        }
+        // 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') {
+            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);
+            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_SIZE_MISMATCH',
+                    part: name,
+                    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' });
+        }
+        // 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(', ')}` });
+            continue;
+        }
+        const subject = withSizing(cp);
+        const extent = rotatedExtentOf(cp);
+        const rules = { x: anchorOf(subject, base, 'x'), y: anchorOf(subject, base, 'y'), z: anchorOf(subject, base, 'z') };
+        const repeat = cp.sizing === 'repeat' && cp.repeat ? cp.repeat : null;
+        // World factor per axis: how much the rotated part's extent along that axis follows the instance.
+        const factor = {};
+        const centre = {};
+        const pending = [];
+        for (const a of AXES) {
+            const rule = rules[a];
+            const gaps = clearance(subject, base, a);
+            const reach = extent[a] / 2;
+            const pos = cp.transform.position[a];
+            if (rule === 'scale') {
+                factor[a] = factorOfScale(a);
+                centre[a] = pos === 0 ? { kind: 'const', value: 0 } : { kind: 'ref', ref: g.mul(`${name}.${a}.centre`, size[a], ratio(pos / base[a], `${name}.${a}.at`)) };
+            }
+            else if (rule === 'span') {
+                const free = g.add(`${name}.${a}.free`, size[a], g.constant(round6(-(gaps.min + gaps.max)), 'mm', `${name}.${a}.gaps`));
+                factor[a] = { kind: 'ref', ref: g.div(`${name}.${a}.factor`, free, g.constant(extent[a], 'mm', `${name}.${a}.own`)), sig: `span.${name}.${a}` };
+                centre[a] = { kind: 'const', value: round6((gaps.min - gaps.max) / 2) };
+            }
+            else if (rule === 'min') {
+                factor[a] = ONE;
+                centre[a] = { kind: 'ref', ref: g.add(`${name}.${a}.centre`, g.mul(`${name}.${a}.half`, size[a], ratio(-0.5, 'minusHalf')), g.constant(round6(gaps.min + reach), 'mm', `${name}.${a}.fromMin`)) };
+            }
+            else if (rule === 'max') {
+                factor[a] = ONE;
+                centre[a] = { kind: 'ref', ref: g.add(`${name}.${a}.centre`, g.mul(`${name}.${a}.half`, size[a], ratio(0.5, 'half')), g.constant(round6(-(gaps.max + reach)), 'mm', `${name}.${a}.fromMax`)) };
+            }
+            else if (rule === 'center') {
+                factor[a] = ONE;
+                centre[a] = { kind: 'const', value: pos };
+            }
+            else {
+                pending.push(a); // aspect-*: follows another axis, settled below
+            }
+        }
+        // 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.
+        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] ?? 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);
+                const even = { kind: 'ref', ref: g.node(`${name}.round`, 'geomean@1', fs.map(asRef), 'value'), sig: `round.${name}` };
+                for (const a of across)
+                    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' });
+            continue;
+        }
+        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' && 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() });
+        }
+        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() });
+        }
+        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() });
+        }
+        else if (cp.primitive === 'rect') {
+            // 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')];
+            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() });
+        }
+        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() });
+        }
+        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 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');
+                }
+            });
+            continue;
+        }
+        // Repeat: copies pitch apart in the world (times the world factor of that axis), centred on the authored
+        // position, count = floor(room / pitch) with room = the instance size when the row spreads, else the base.
+        const axis = repeat.axis;
+        const spreads = rules[axis] !== 'scale';
+        const itemFrame = `${name}.item`;
+        plans.push({
+            appearance,
+            nodes: () => {
+                const s = shape();
+                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;
+                let rowStart;
+                if (spreads) {
+                    const zero = g.constant(0, 'mm', 'zero');
+                    const pitch = g.constant(repeat.pitch, 'mm', `${name}.pitch`);
+                    layout = g.node(`${name}.layout`, 'fit-pitch@1', [size[axis], zero, zero, pitch, pitch, ratio(0.5, 'half'), g.constant(REPEAT_LIMIT, 'count', 'repeatLimit')], 'layout');
+                    rowStart = g.add(`${name}.rowStart`, g.len(centre[axis], `${name}.${axis}`), g.mul(`${name}.halfRow`, size[axis], ratio(-0.5, 'minusHalf')));
+                }
+                else {
+                    // A fixed count spread pitch·factor apart: `fixed-count@1` spaces `count` items evenly over L - e,
+                    // so L = (count - 1)·pitch·factor + e with a 1 mm item extent, and the row starts e/2 before the first copy.
+                    const count = Math.max(1, Math.min(REPEAT_LIMIT, Math.floor(base[axis] / repeat.pitch)));
+                    const e = g.constant(1, 'mm', 'one');
+                    const row = times(`${name}.row`, { kind: 'const', value: (count - 1) * repeat.pitch }, factor[axis]);
+                    const L = g.add(`${name}.rowLength`, g.len(row, `${name}.row`), e);
+                    layout = g.node(`${name}.layout`, 'fixed-count@1', [g.constant(count, 'count', `${name}.count`), L, g.constant(0, 'mm', 'zero'), g.constant(0, 'mm', 'zero'), e, ratio(0.5, 'half'), g.constant(REPEAT_LIMIT, 'count', 'repeatLimit')], 'layout');
+                    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'));
+                }
+                // 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, notes };
+    for (const plan of plans) {
+        plan.nodes();
+        asset.appearance.push(plan.appearance);
+    }
+    try {
+        compileV3Asset(asset);
+    }
+    catch (e) {
+        const err = e;
+        return { status: 'refused', refusals: [{ code: `V3_${err.code ?? 'COMPILE'}`, part: err.path, detail: err.message }], lost, notes };
+    }
+    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' };
+}
+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);
+        // 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++) {
+            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;
+            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, stateOverrides = {}) {
+    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));
+}
+/** 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;
+    for (let i = 0; i < 3; i++)
+        for (let k = 0; k < 3; k++)
+            trace += a[i][k] * b[i][k];
+    const c = Math.min(1, Math.max(-1, (trace - 1) / 2));
+    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 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, 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], state: 'rest', what: 'appearance', v2: JSON.stringify(part.material), v3: 'missing' });
+            continue;
+        }
+        const expected = { token: part.material.token };
+        if (part.material.preset !== undefined)
+            expected.preset = part.material.preset;
+        if (part.material.transparent !== undefined)
+            expected.transparent = part.material.transparent;
+        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], 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], state: 'rest', what: 'segments', v2: String(part.segments ?? SEG_DEFAULT), v3: String(look.segments) });
+    }
+    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;
+            }
+            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;
+                }
+                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);
+    }
+}
+function normalise180(deg) {
+    const w = ((((deg + 180) % 360) + 360) % 360) - 180;
+    return w === 180 ? -180 : w;
+}
+//# sourceMappingURL=v3-from-v2.js.map