@hatiolab/figure-model 0.1.32 → 0.1.33

package/dist/v3-from-v2.js

@@ -0,0 +1,595 @@
+/*
+ * 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 cylinder with two radii, a polygon whose path
+ *     does not fill its declared size about the centre (V2 itself draws that one off-centre)
+ *   - a part rotated off the axes whose size still follows the instance (V2 shears it; V3 cannot)
+ *   - joints and parameters (motion semantics are not converted here)
+ *
+ * What it converts but does not carry, it lists in `lost` so the caller can show it. Nothing is dropped
+ * without being named there.
+ *
+ * `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";
+/** 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 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
+        };
+    }
+    const src = source;
+    const base = src.base;
+    const palette = options.palette;
+    if (src.joints?.length)
+        refusals.push({ code: 'JOINTS', detail: `${src.joints.length} joints; motion is not converted` });
+    if (src.parameters?.length)
+        refusals.push({ code: 'PARAMETERS', detail: `${src.parameters.length} parameters; motion is not converted` });
+    for (const clip of src.animations ?? [])
+        lost.push({ code: 'ANIMATION', detail: `animation "${clip.name}" (${clip.channels.length} channels) is not carried` });
+    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();
+    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)
+            lost.push({ code: 'PARENT', part: name, detail: `attached to "${cp.parent}"; V3 places it in the asset frame` });
+        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;
+        }
+        const path = cp.primitive === 'polygon' ? cp.shape?.path ?? [] : [];
+        if (cp.primitive === 'polygon') {
+            // V2 sizing reads `size`, but draws the path as written. The two agree only when the path fills the
+            // size box symmetrically about the part centre; otherwise V2 itself draws the part off its declared centre.
+            const xs = path.map(q => q.x), zs = path.map(q => q.y);
+            const spanX = Math.max(...xs) - Math.min(...xs), spanZ = Math.max(...zs) - Math.min(...zs);
+            const midX = (Math.max(...xs) + Math.min(...xs)) / 2, midZ = (Math.max(...zs) + Math.min(...zs)) / 2;
+            if (path.length < 3 || Math.abs(spanX - cp.transform.size.x) > 1e-6 || Math.abs(spanZ - cp.transform.size.z) > 1e-6 || Math.abs(midX) > 1e-6 || Math.abs(midZ) > 1e-6) {
+                refusals.push({
+                    code: 'POLYGON_OFF_CENTRE',
+                    part: name,
+                    detail: `path spans ${spanX}×${spanZ} about (${midX}, ${midZ}); size says ${cp.transform.size.x}×${cp.transform.size.z} about the centre`
+                });
+                continue;
+            }
+            if (cp.shape?.round)
+                lost.push({ code: 'POLYGON_ROUND', part: name, detail: 'V2 ignores round on a polygon; so does V3' });
+        }
+        if (cp.primitive === 'cylinder' && Math.abs(cp.transform.size.x - cp.transform.size.z) > 1e-9) {
+            refusals.push({ code: 'CONE', part: name, detail: `size.x ${cp.transform.size.x} ≠ size.z ${cp.transform.size.z}; V3 cylinders have one radius` });
+            continue;
+        }
+        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
+            }
+        }
+        for (const a of pending) {
+            const named = rules[a].slice('aspect-'.length);
+            factor[a] = factor[named];
+            centre[a] = times(`${name}.${a}.centre`, { kind: 'const', value: cp.transform.position[a] }, factor[named]);
+        }
+        // The V3 asset frame has its origin at the bottom of the box (ADR-0065); V2 sizing works from the centre.
+        centre.y = { kind: 'ref', ref: g.add(`${name}.y.fromBottom`, g.len(centre.y, `${name}.y.centred`), g.mul(`${name}.y.lift`, size.y, ratio(0.5, 'half'))) };
+        // A curved part keeps a round section: both cross axes take the geometric mean of their two factors
+        // (`sizing.ts` keepRound). When the two are the same expression the mean is that expression; otherwise
+        // it is a `geomean@1` node.
+        if ((cp.primitive === 'cylinder' || cp.primitive === 'sphere') && cp.keepRound !== false) {
+            const spin = cp.primitive === 'sphere' ? null : longAxis(subject);
+            const across = AXES.filter(a => a !== spin);
+            const fs = across.map(a => factor[a]);
+            const 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;
+            }
+        }
+        // Local dimensions scale by the factor of the world axis each local axis lands on.
+        const 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 dim = (local) => times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE);
+        const localFrame = `${name}.local`;
+        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') {
+            const radius = times(`${name}.dim.radius`, { kind: 'const', value: cp.transform.size.x / 2 }, perm ? factor[perm.x] : ONE);
+            const length = dim('y');
+            shape = () => g.node(`${name}.shape`, 'cylinder-shape@1', [g.len(radius, `${name}.radius`), g.len(length, `${name}.length`)], 'shape', { frame: localFrame });
+        }
+        else if (cp.primitive === 'sphere') {
+            const r = (local) => times(`${name}.dim.radius${local.toUpperCase()}`, { kind: 'const', value: cp.transform.size[local] / 2 }, perm ? factor[perm[local]] : ONE);
+            const [rx, ry, rz] = [r('x'), r('y'), r('z')];
+            shape = () => g.node(`${name}.shape`, 'sphere-shape@1', [g.len(rx, `${name}.rx`), g.len(ry, `${name}.ry`), g.len(rz, `${name}.rz`)], 'shape', { frame: localFrame });
+        }
+        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: localFrame });
+        }
+        else if (cp.primitive === 'rect') {
+            const round = cp.shape?.round ?? 0;
+            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: localFrame });
+            }
+            else
+                shape = () => g.node(`${name}.shape`, 'rounded-box@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`), g.constant(round, 'mm', `${name}.round`)], 'shape', { frame: localFrame });
+        }
+        else {
+            const [w, h, d] = [dim('x'), dim('y'), dim('z')];
+            shape = () => g.node(`${name}.shape`, 'box-shape@1', [g.len(w, `${name}.w`), g.len(h, `${name}.h`), g.len(d, `${name}.d`)], 'shape', { frame: localFrame });
+        }
+        const appearance = { target: name, material: material };
+        if (cp.primitive === 'cylinder' || cp.primitive === 'sphere')
+            appearance.segments = segments;
+        if (!repeat) {
+            plans.push({
+                appearance,
+                nodes: () => {
+                    const s = shape();
+                    const pose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => g.len(centre[a], `${name}.${a}`)), ...rotationRefs], 'pose', { from: localFrame, to: 'asset' });
+                    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();
+                const memberPose = g.node(`${name}.pose`, 'rigid@1', [...AXES.map(a => (a === axis ? g.constant(0, 'mm', 'zero') : g.len(centre[a], `${name}.${a}`))), ...rotationRefs], 'pose', { from: localFrame, to: itemFrame });
+                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'));
+                }
+                const rootPose = g.node(`${name}.root`, 'rigid@1', [...AXES.map(a => (a === axis ? rowStart : g.constant(0, 'mm', 'zero'))), ...AXES.map(() => g.constant(0, 'deg', 'deg.0'))], 'pose', { from: itemFrame, to: 'asset' });
+                g.node(`${name}.repeat`, 'repeat@1', [layout, assembly, rootPose], 'collection', { axis });
+            }
+        });
+    }
+    if (refusals.length)
+        return { status: 'refused', refusals, lost };
+    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 };
+    }
+    return { status: 'converted', asset, lost };
+}
+/** The subject the sizing rules read: `sizing` filled in like the blueprint does. */
+function withSizing(cp) {
+    return { ...cp, sizing: cp.sizing ?? 'scale' };
+}
+/** Where V2 draws every part (and copy) at an instance scale, as world boxes. */
+export function v2WorldBoxes(source, scale) {
+    const base = source.base;
+    const out = [];
+    for (const part of source.parts) {
+        const cp = withSizing(centredPart(part, base));
+        const at = sizingPosition(cp, scale, base);
+        const sized = sizingScale(cp, scale, base);
+        const extent = rotatedExtentOf(cp);
+        const rotation = eulerXYZ(part.transform.rotation);
+        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;
+        const plan = repeatPlan(cp, scale, base);
+        const copies = plan ? plan.count : 1;
+        for (let i = 0; i < copies; i++) {
+            const centre = { x: box.x.centre, y: box.y.centre, z: box.z.centre };
+            if (plan)
+                centre[plan.axis] += repeatOffset(i, plan.count, plan.pitch) * box[plan.axis].factor;
+            out.push({ part: part.name, centre, extent: { x: box.x.extent, y: box.y.extent, z: box.z.extent }, rotation });
+        }
+    }
+    return out;
+}
+/** Where a converted V3 asset draws every part at an instance size, as world boxes. */
+export function v3WorldBoxes(asset, size) {
+    const inputs = { ...asset.designInputs, 'size.x': size.x, 'size.y': size.y, 'size.z': size.z };
+    const evaluated = compileV3Asset({ ...asset, designInputs: inputs }).evaluate();
+    return v3WorldBoxesOf(evaluated.geometry, v3WritersOf(asset));
+}
+/** ADR-0087 decision 2 tolerances. */
+export const SAME_TOLERANCE_MM = 1;
+export const SAME_TOLERANCE_DEG = 0.1;
+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 at the same
+ * centre and world extents within 1 mm and the same rotation within 0.1°, with the same material, at the
+ * base size and at every combination of doubled axes.
+ */
+export function compareV2WithV3(source, asset, 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 differences = [];
+    let boxesCompared = 0;
+    const materials = new Map(asset.appearance.map(a => [a.target, a]));
+    for (const part of source.parts) {
+        const look = materials.get(part.name);
+        if (!look) {
+            differences.push({ part: part.name, scale: scales[0], what: 'appearance', v2: JSON.stringify(part.material), v3: 'missing' });
+            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], what: 'material', v2: JSON.stringify(expected), v3: JSON.stringify(look.material) });
+        if ((part.primitive === 'cylinder' || part.primitive === 'sphere') && look.segments !== (part.segments ?? SEG_DEFAULT))
+            differences.push({ part: part.name, scale: scales[0], what: 'segments', v2: String(part.segments ?? SEG_DEFAULT), v3: String(look.segments) });
+    }
+    for (const scale of scales) {
+        const size = { x: source.base.x * scale.x, y: source.base.y * scale.y, z: source.base.z * scale.z };
+        const byPart = (boxes) => {
+            const m = new Map();
+            for (const b of boxes)
+                (m.get(b.part) ?? m.set(b.part, []).get(b.part)).push(b);
+            for (const list of m.values())
+                list.sort((p, q) => p.centre.x - q.centre.x || p.centre.y - q.centre.y || p.centre.z - q.centre.z);
+            return m;
+        };
+        const v2 = byPart(v2WorldBoxes(source, scale));
+        const v3 = byPart(v3WorldBoxes(asset, size));
+        for (const name of new Set([...v2.keys(), ...v3.keys()])) {
+            const a = v2.get(name) ?? [], b = v3.get(name) ?? [];
+            if (a.length !== b.length) {
+                differences.push({ part: name, scale, what: 'copies', v2: String(a.length), v3: String(b.length) });
+                continue;
+            }
+            for (const [i, p] of a.entries()) {
+                const q = b[i];
+                boxesCompared++;
+                for (const axis of AXES) {
+                    if (Math.abs(p.centre[axis] - q.centre[axis]) > SAME_TOLERANCE_MM)
+                        differences.push({ part: name, scale, what: `centre.${axis}${a.length > 1 ? `[${i}]` : ''}`, v2: p.centre[axis].toFixed(3), v3: q.centre[axis].toFixed(3) });
+                    if (Math.abs(p.extent[axis] - q.extent[axis]) > SAME_TOLERANCE_MM)
+                        differences.push({ part: name, scale, what: `extent.${axis}${a.length > 1 ? `[${i}]` : ''}`, v2: p.extent[axis].toFixed(3), v3: q.extent[axis].toFixed(3) });
+                }
+                const turn = rotationAngleDeg(p.rotation, q.rotation);
+                if (turn > SAME_TOLERANCE_DEG)
+                    differences.push({ part: name, scale, what: 'rotation', v2: JSON.stringify(p.rotation.map(r => r.map(v => +v.toFixed(4)))), v3: `${turn.toFixed(3)}° apart` });
+            }
+        }
+    }
+    return { same: differences.length === 0, scales, boxesCompared, differences };
+}
+//# sourceMappingURL=v3-from-v2.js.map