@hatiolab/figure-model 0.1.36 → 0.1.37

package/dist/v3-from-v2.js

@@ -53,6 +53,8 @@ const SIZE_RANGE = 10;
  * sizes figures have (mm, up to 10⁵). A numerical stability bound, not a minimum part size (designer's ruling 2).
  */
 const SPAN_POSITIVE_STEP = 1e-6;
+/** Above this many state inputs the corners are not enumerated for the declared volume; the resting pose stands. */
+const OCCUPANCY_STATE_CAP = 10;
 const ONE = { kind: 'one' };
 const SEG_DEFAULT = 12;
 const RIGHT_ANGLE_TOLERANCE = 1e-9;
@@ -148,6 +150,31 @@ function nearestAxisPermutation(rotation) {
     }
     return out;
 }
+/**
+ * Does scaling per world axis commute with this rotation?
+ *
+ * V2 bakes the rotation into the mesh and then scales it per world axis: the drawn body is `S·R·v`. A rigid V3
+ * part scales its own dimensions and then rotates: `R·S·v`. Those are the same body exactly when `S` and `R`
+ * commute, and diag(f) commutes with R when every pair of axes the rotation mixes carries the same factor.
+ *
+ * This is not a corner case. ROLL_CRADLE's pads are turned 41° about X and follow the instance on Y and Z with
+ * the same factor (`anchor: y scale, z aspect-y`), so V2 never sheared them — it scaled them uniformly inside
+ * the plane the rotation turns in. Such a part converts exactly, with each local dimension taking its own axis's
+ * factor, and needs no re-authoring.
+ */
+function scalingCommutesWithRotation(rotation, same) {
+    const R = eulerXYZ(rotation);
+    for (const [i, a] of AXES.entries())
+        for (const [j, b] of AXES.entries()) {
+            if (i === j)
+                continue;
+            if (Math.abs(R[i][j]) > MIXING_TOLERANCE && !same(a, b))
+                return false;
+        }
+    return true;
+}
+/** Below this, a rotation does not mix two axes enough to tell a shear from a uniform scale at figure sizes. */
+const MIXING_TOLERANCE = 1e-9;
 /** 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)))
@@ -233,8 +260,9 @@ export function convertV2ToV3(source, options) {
         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' }
+        // ADR-0044 · ADR-0045: the V2 base box and placement become the declared volume, written as the reach on
+        // each side of the origin (designer's ruling 2026-09-23). V2 read a missing placement as floor.
+        occupancy: { bounds: null, 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.
@@ -314,6 +342,14 @@ export function convertV2ToV3(source, options) {
     const shiftsOf = new Map();
     // A scale channel: per local axis, a ratio the part's dimensions are multiplied by (contract §2: dims × affine(p)).
     const scaleOf = new Map();
+    /** part name → the flag value saying whether it is shown. Written by a channel that V2 spelled as scale 0. */
+    const visibilityOf = new Map();
+    /** Per part and axis: how far a state channel stretches or shrinks it, from the channel's own keys. */
+    const scaleRangeOf = new Map();
+    /** Per part: where it sits, how big it is, and whether it moves on its own. Read when the volume is declared. */
+    const reachOf = new Map();
+    /** Per joint: the three length values of its origin, and the joint above it. */
+    const jointOriginOf = 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]));
@@ -481,6 +517,75 @@ export function convertV2ToV3(source, options) {
         // Local dimensions scale by the factor of the world axis each local axis lands on.
         let perm = axisPermutation(cp.transform.rotation);
         const follows = AXES.some(a => factor[a].kind !== 'one');
+        // Fastened to another part: rigid, with the centre riding that part's face (designer's ruling 2026-09-22).
+        const fastening = options.reauthor?.attach?.find(x => x.part === name);
+        if (fastening) {
+            const mount = parts.find(x => x.name === fastening.to);
+            if (!mount) {
+                refusals.push({ code: 'ATTACH_TARGET', part: name, detail: `it is to be fastened to "${fastening.to}", which is not a part of this figure` });
+                continue;
+            }
+            /*
+              Which face it is fastened to: the one it stands out through. A panel set into its housing still counts,
+              which is how the notching machine's control panel is drawn — it is sunk into the enclosure and only its
+              front shows. Exactly one face must qualify, or there is nothing to call the mounting.
+            */
+            const reachOf = (q, a) => ({ lo: q.transform.position[a] - q.transform.size[a] / 2, hi: q.transform.position[a] + q.transform.size[a] / 2 });
+            const held = [];
+            for (const a of AXES) {
+                const mine = reachOf(cp, a), theirs = reachOf(mount, a);
+                if (mine.hi > theirs.hi + 1e-9)
+                    held.push({ axis: a, face: theirs.hi, offset: cp.transform.position[a] - theirs.hi });
+                else if (mine.lo < theirs.lo - 1e-9)
+                    held.push({ axis: a, face: theirs.lo, offset: cp.transform.position[a] - theirs.lo });
+            }
+            if (held.length !== 1) {
+                refusals.push({
+                    code: 'ATTACH_FACE',
+                    part: name,
+                    detail: held.length
+                        ? `it stands out of "${fastening.to}" on ${held.map(h => h.axis).join(' and ')}; which face holds it cannot be read from the drawing`
+                        : `it is wholly inside "${fastening.to}", so there is no face it stands out through`
+                });
+                continue;
+            }
+            const face = held[0];
+            if (anchorOf(withSizing(mount), base, face.axis) !== 'scale') {
+                refusals.push({ code: 'ATTACH_MOUNT', part: name, detail: `"${fastening.to}" does not follow the instance proportionally on ${face.axis}, so its face is not a ratio of the size` });
+                continue;
+            }
+            // The mount's face is that ratio of the instance size; the gap the author drew is kept as it is.
+            const faceRatio = face.face / base[face.axis];
+            const rideTo = g.add(`${name}.${face.axis}.fastened`, g.mul(`${name}.${face.axis}.face`, size[face.axis], ratio(round6(faceRatio), `${name}.${face.axis}.faceAt`)), g.constant(round6(face.offset), 'mm', `${name}.${face.axis}.gap`));
+            for (const a of AXES)
+                factor[a] = ONE;
+            centre[face.axis] = { kind: 'ref', ref: rideTo };
+            perm = { x: 'x', y: 'y', z: 'z' };
+            method = 're-authored';
+            notes.push({
+                code: 'RE_AUTHORED_FASTENED',
+                part: name,
+                detail: `tilted (${AXES.map(a => `${a}:${cp.transform.rotation?.[a] ?? 0}°`).join(', ')}) and following the instance, which V2 shears. Re-authored: it keeps its authored dimensions and tilt, and its centre rides the ${face.axis} face of "${fastening.to}" at the ${face.offset.toFixed(1)} mm the author drew. The gap between them is the same at every instance size`
+            });
+        }
+        if (!perm && follows) {
+            // A rotation that only mixes axes carrying the same factor is not a shear: scaling and rotating commute,
+            // so each local axis keeps its own axis's factor and the body is the one V2 draws.
+            const sameFactor = (a, b) => {
+                const x = factor[a], y = factor[b];
+                if (x.kind === 'one' && y.kind === 'one')
+                    return true;
+                return x.kind === 'ref' && y.kind === 'ref' && x.sig !== undefined && x.sig === y.sig;
+            };
+            if (scalingCommutesWithRotation(cp.transform.rotation, sameFactor)) {
+                perm = { x: 'x', y: 'y', z: 'z' };
+                notes.push({
+                    code: 'ROTATED_UNIFORM_PLANE',
+                    part: name,
+                    detail: `turned off the axes and following the instance, but every pair of axes the rotation mixes carries the same factor, so scaling and rotating commute. V2 scaled it uniformly inside the plane it turns in rather than shearing it; converted as V2 draws it, with no re-authoring`
+                });
+            }
+        }
         if (!perm && follows) {
             const nearest = options.reauthor?.rotatedFollows === 'nearest-axis' ? nearestAxisPermutation(cp.transform.rotation) : null;
             if (!nearest) {
@@ -504,7 +609,12 @@ export function convertV2ToV3(source, options) {
                 return v;
             return { kind: 'ref', ref: g.mul(`${name}.${hint}.scaled`, g.len(v, `${name}.${hint}`), sc) };
         };
-        const dim = (local) => withChannel(times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE), local, `dim.${local}`);
+        // Memoised: the shape writes it and the declared volume reads it, and a node id may only be claimed once.
+        const dims = {};
+        const raws = {};
+        /** The dimension before any state channel scales it. The declared volume measures from this. */
+        const rawDim = (local) => (raws[local] ??= times(`${name}.dim.${local}`, { kind: 'const', value: cp.transform.size[local] }, perm ? factor[perm[local]] : ONE));
+        const dim = (local) => (dims[local] ??= withChannel(rawDim(local), local, `dim.${local}`));
         const channelSplits = () => {
             const sc = scaleOf.get(name);
             return !!sc && (sc.x ?? null) !== (sc.z ?? null);
@@ -593,6 +703,64 @@ export function convertV2ToV3(source, options) {
         if (cp.primitive === 'cylinder' || cp.primitive === 'sphere')
             appearance.segments = segments;
         info.set(name, { centre, factor, repeat: !!repeat });
+        /** The widest this body's side can be: its own dimension, times the most a state channel stretches it. */
+        const widestOf = (a) => {
+            const range = scaleRangeOf.get(name)?.[a];
+            if (!scaleOf.get(name)?.[a])
+                return dim(a);
+            if (!range)
+                return null; // a channel whose reach is not known; the volume cannot be produced from it
+            const k = Math.max(Math.abs(range.min), Math.abs(range.max));
+            return k === 1 ? rawDim(a) : times(`${name}.widest.${a}`, rawDim(a), { kind: 'ref', ref: ratio(round6(k), `${name}.widest.${a}.k`), sig: `widest.${name}.${a}` });
+        };
+        /*
+          A part's dimensions are its own, measured along its own axes; the declared volume is measured along the
+          asset's. A body turned by its authored rotation fills, on one asset axis, the sum of its three sides
+          weighted by how much each leans onto that axis — the box around the turned box. For a quarter turn that is
+          a plain swap, and for anything between it is wider than the body, which is the direction to be wrong in.
+          Reading the local side as if it were the world side is how a motor lying on its side came to be declared
+          15 mm short.
+        */
+        const rotationMatrix = eulerXYZ(cp.transform.rotation);
+        const worldSpan = (a) => {
+            const row = rotationMatrix[AXES.indexOf(a)];
+            /*
+              A bound that rounds inward is not a bound, so every weight that stays is rounded away from zero.
+      
+              A weight too small to be worth its own node is not moved onto another axis: the axes carry different
+              sides, and 5e-10 of a 100000 mm side is not covered by 5e-10 more of a 0.01 mm one (V3 designer's
+              counterexample 2026-09-23). It is dropped only when its own side is a fixed length, and then its whole
+              contribution in millimetres is added on, rounded up. A side that follows the instance keeps its term.
+            */
+            const terms = [];
+            let extraMm = 0;
+            for (const [i, local] of AXES.entries()) {
+                const k = Math.abs(row[i]);
+                if (k === 0)
+                    continue;
+                const side = widestOf(local);
+                if (!side)
+                    return null;
+                const up = Math.ceil(k * 1e6) / 1e6;
+                if (k < 1e-9 && side.kind === 'const') {
+                    extraMm += Math.ceil(up * side.value * 1e6) / 1e6;
+                    continue;
+                }
+                terms.push({ k: up, len: side });
+            }
+            return { terms, extraMm };
+        };
+        // The declared volume is built from the structure, so it needs each body's own reach and where it sits.
+        reachOf.set(name, {
+            centre,
+            dim,
+            turns: () => spinOf.has(name),
+            widest: widestOf,
+            worldSpan,
+            slides: () => (shiftsOf.get(name) ?? [])
+                .filter(sh => sh.travel)
+                .map(sh => ({ axis: sh.axis, factor: factor[sh.axis], travel: sh.travel }))
+        });
         if (!repeat) {
             plans.push({
                 appearance,
@@ -675,12 +843,35 @@ export function convertV2ToV3(source, options) {
             }
         });
     }
-    planMotion({ src, g, base, size, info, spinOf, shiftsOf, scaleOf, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio, times, factorOfScale });
+    asset.occupancy.bounds = {
+        x: { min: g.mul('occupancy.x.min', size.x, ratio(-0.5, 'minusHalf')), max: g.mul('occupancy.x.max', size.x, ratio(0.5, 'half')) },
+        y: { min: g.constant(0, 'mm', 'zero'), max: V3_SIZE_INPUTS.y },
+        z: { min: g.mul('occupancy.z.min', size.z, ratio(-0.5, 'minusHalf')), max: g.mul('occupancy.z.max', size.z, ratio(0.5, 'half')) }
+    };
+    const motion = planMotion({ src, g, base, size, info, spinOf, shiftsOf, scaleOf, scaleRangeOf, visibilityOf, jointOriginOf, lost, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio, times, factorOfScale });
+    if (motion.reauthored)
+        method = 're-authored';
     if (refusals.length)
         return { status: 'refused', refusals, lost, rangeChanges, notes };
     for (const plan of plans) {
         plan.nodes();
-        asset.appearance.push(plan.appearance);
+        const shown = visibilityOf.get(plan.appearance.target);
+        asset.appearance.push(shown ? { ...plan.appearance, visibility: shown } : plan.appearance);
+    }
+    if (options.occupancy === 'measured') {
+        /** Which joint carries a part: the nearest one above it in the parent chain. */
+        const jointsByChild = new Map((src.joints ?? []).map(j => [j.child, j.name]));
+        const carrierOfPart = (name) => {
+            for (let p = partsByName.get(name); p; p = p.parent ? partsByName.get(p.parent) : undefined) {
+                const j = jointsByChild.get(p.name);
+                if (j)
+                    return j;
+            }
+            return undefined;
+        };
+        declareOccupancy({ g, parts, reachOf, jointOriginOf, carrierOf: carrierOfPart, base, designInputs: asset.designInputs, asset, refusals, notes });
+        if (refusals.length)
+            return { status: 'refused', refusals, lost, rangeChanges, notes };
     }
     try {
         compileV3Asset(asset);
@@ -691,6 +882,307 @@ export function convertV2ToV3(source, options) {
     }
     return { status: 'converted', method, asset, lost, rangeChanges, notes };
 }
+/**
+ * Declares the volume the figure occupies, from the structure of the figure rather than from measurements.
+ *
+ * V2 had one box for two jobs: the size a figure is authored and placed at, and the room it takes up. In V3
+ * they are separate (V3 designer's ruling 2026-09-22), and the volume is the reach on each side of the origin
+ * (ruling 2026-09-23), so it can describe a part below the mounting plane or off one side only.
+ *
+ * **Why not measure it.** An earlier version sampled the reach at three instance sizes on one axis and fitted a
+ * straight line. That says nothing between or beyond those sizes, nothing about changing two axes together, and
+ * nothing about the poses between the state corners it happened to visit. Passing the third point proved
+ * nothing (designer's ruling 2026-09-23).
+ *
+ * **What is built instead.** For every body, a bound that holds in every allowed state because of how the
+ * figure is put together, written as graph values so it is right at every instance size by construction:
+ *
+ *   a body that does not move        exactly its own box
+ *   a body that turns where it sits  its centre, give or take its own reach
+ *   a body carried by joints         the outermost joint's origin, give or take the chain: the distance out
+ *                                    to each joint below it, any sliding travel those joints allow, and the
+ *                                    body's own reach
+ *
+ * A turning joint can point what hangs below it in any direction, so the chain is summed as lengths and applied
+ * to every axis. That is wider than the true swept volume; it is a bound that can be explained, not a guess.
+ * Joint angle ranges can tighten it later. This is arithmetic about where the parts can be, not a claim about
+ * collisions, loads or safety, and it applies to a revolving door and a lift the same way it applies to an arm.
+ *
+ * A length is summed as `|dx| + |dy| + |dz|`, which is at least the straight-line distance, so the bound stays
+ * on the safe side. `|x|` is `max(x, -x)`.
+ */
+/**
+ * A value read as `base + Σ slope_a · size_a`, or null when it is not of that shape.
+ *
+ * This reads the graph, it does not sample it, so what it returns is the value at every instance size and not
+ * a fit through a few of them. It is how the declaration knows which parts can never leave the authored box:
+ * every size input is positive, so a difference whose base and slopes are all non-negative is never negative.
+ */
+function affineInSize(g, designInputs, ref) {
+    const zero = () => ({ x: 0, y: 0, z: 0 });
+    const constants = new Map(g.graph.constants.map(k => [k.id, k.value * (k.unit === 'cm' ? 10 : k.unit === 'm' ? 1000 : k.unit === 'percent' ? 0.01 : 1)]));
+    const writers = new Map();
+    for (const n of g.graph.nodes)
+        for (const out of Object.values(n.outputs))
+            writers.set(out, n);
+    const seen = new Set();
+    const walk = (r) => {
+        if (seen.has(r))
+            return null;
+        seen.add(r);
+        try {
+            for (const a of AXES)
+                if (r === V3_SIZE_INPUTS[a])
+                    return { base: 0, slope: { ...zero(), [a]: 1 } };
+            if (constants.has(r))
+                return { base: constants.get(r), slope: zero() };
+            if (Object.hasOwn(designInputs, r))
+                return { base: designInputs[r], slope: zero() };
+            const n = writers.get(r);
+            if (!n)
+                return null;
+            if (n.op === 'add@1') {
+                const a = walk(n.args[0]), b = walk(n.args[1]);
+                return a && b ? { base: a.base + b.base, slope: { x: a.slope.x + b.slope.x, y: a.slope.y + b.slope.y, z: a.slope.z + b.slope.z } } : null;
+            }
+            if (n.op === 'div@1') {
+                const a = walk(n.args[0]), b = walk(n.args[1]);
+                // Only a constant denominator keeps the value affine; a span's factor is (size − gaps) / a fixed length.
+                if (!a || !b || AXES.some(x => b.slope[x] !== 0) || b.base === 0)
+                    return null;
+                return { base: a.base / b.base, slope: { x: a.slope.x / b.base, y: a.slope.y / b.base, z: a.slope.z / b.base } };
+            }
+            if (n.op === 'mul@1') {
+                const a = walk(n.args[0]), b = walk(n.args[1]);
+                if (!a || !b)
+                    return null;
+                const flat = (v) => AXES.every(x => v.slope[x] === 0);
+                if (flat(b))
+                    return { base: a.base * b.base, slope: { x: a.slope.x * b.base, y: a.slope.y * b.base, z: a.slope.z * b.base } };
+                if (flat(a))
+                    return { base: a.base * b.base, slope: { x: b.slope.x * a.base, y: b.slope.y * a.base, z: b.slope.z * a.base } };
+                return null;
+            }
+            return null;
+        }
+        finally {
+            seen.delete(r);
+        }
+    };
+    return walk(ref);
+}
+function declareOccupancy(c) {
+    const { g, parts, reachOf, jointOriginOf, carrierOf, base, designInputs, asset, refusals, notes } = c;
+    const authoredBounds = asset.occupancy.bounds;
+    const affOfLen = (l) => (l.kind === 'const' ? { base: l.value, slope: { x: 0, y: 0, z: 0 } } : affineInSize(g, designInputs, l.ref));
+    const affAdd = (a, b, k = 1) => ({
+        base: a.base + k * b.base,
+        slope: AXES.reduce((o, x) => ((o[x] = a.slope[x] + k * b.slope[x]), o), {})
+    });
+    const affScale = (a, k) => ({ base: a.base * k, slope: AXES.reduce((o, x) => ((o[x] = a.slope[x] * k), o), {}) });
+    /** Is this value never past the authored bound on that side, at any instance size? Read from the graph. */
+    const neverPast = (mine, a, side) => {
+        const theirs = affineInSize(g, designInputs, authoredBounds[a][side]);
+        if (!mine || !theirs)
+            return false;
+        // min side: authored − mine ≤ 0 everywhere. max side: mine − authored ≤ 0 everywhere.
+        const d = side === 'min'
+            ? { base: theirs.base - mine.base, slope: AXES.reduce((o, x) => ((o[x] = theirs.slope[x] - mine.slope[x]), o), {}) }
+            : { base: mine.base - theirs.base, slope: AXES.reduce((o, x) => ((o[x] = mine.slope[x] - theirs.slope[x]), o), {}) };
+        // Only the slack that floating point itself needs. SAME_TOLERANCE_MM is how close V2 and V3 must draw the
+        // same body; borrowing it here let a part hang 1 mm outside the volume that is supposed to hold it.
+        return d.base <= FLOAT_SLACK_MM && AXES.every(x => d.slope[x] <= FLOAT_SLACK_MM * 1e-3);
+    };
+    let seq = 0;
+    const id = () => `occ.v${seq++}`;
+    const isNum = (v) => 'n' in v;
+    const ref = (v, hint) => (isNum(v) ? g.constant(round6(v.n), 'mm', hint) : v.ref);
+    const ofLen = (l) => (l.kind === 'const' ? { n: l.value } : { ref: l.ref });
+    /*
+      The same sum turns up again and again: every body on a shelf is half its own depth from the same place, and
+      every joint in a chain is measured from the one above it by parts that share it. Writing each of those once
+      is what keeps a twenty-part figure inside the document's node limit, and it changes no value.
+    */
+    const shared = new Map();
+    const once = (key, build) => {
+        const known = shared.get(key);
+        if (known)
+            return known;
+        const made = build();
+        shared.set(key, made);
+        return made;
+    };
+    const add = (a, b) => {
+        if (isNum(a) && isNum(b))
+            return { n: a.n + b.n };
+        if (isNum(a) && a.n === 0)
+            return b;
+        if (isNum(b) && b.n === 0)
+            return a;
+        const ra = ref(a, id()), rb = ref(b, id());
+        const key = `+|${[ra, rb].sort().join('|')}`;
+        return { ref: once(key, () => g.add(id(), ra, rb)) };
+    };
+    const scale = (a, k) => {
+        if (isNum(a))
+            return { n: a.n * k };
+        if (k === 1)
+            return a;
+        const key = `*|${a.ref}|${round6(k)}`;
+        return { ref: once(key, () => g.mul(id(), a.ref, g.constant(k, 'ratio', `occ.k${round6(k)}`))) };
+    };
+    const abs = (a) => {
+        if (isNum(a))
+            return { n: Math.abs(a.n) };
+        const negated = ref(scale(a, -1), id());
+        return { ref: once(`abs|${a.ref}`, () => g.node(id(), 'max@1', [a.ref, negated], 'value')) };
+    };
+    const sum = (vs) => vs.reduce(add, { n: 0 });
+    /** |a − b| summed over the three axes: at least the straight-line distance between two places. */
+    const spread = (a, b) => sum(a.map((v, i) => abs(add(v, scale(b[i], -1)))));
+    const low = { x: [], y: [], z: [] };
+    const high = { x: [], y: [], z: [] };
+    /** The reach of a chain of joints, shared by every part that hangs from it. */
+    const chainReach = new Map();
+    /** Per chain: how far each body hanging from it reaches, so only the furthest is written. */
+    const furthest = new Map();
+    const originVals = (j) => jointOriginOf.get(j).origin.map(r => ({ ref: r }));
+    const reachOfChain = (chain) => {
+        const key = chain.join('/');
+        const known = chainReach.get(key);
+        if (known)
+            return known;
+        const below = chain.length > 1 ? reachOfChain(chain.slice(0, -1)) : { n: 0 };
+        const step = chain.length > 1 ? spread(originVals(chain[chain.length - 2]), originVals(chain[chain.length - 1])) : { n: 0 };
+        const travel = { n: jointOriginOf.get(chain[chain.length - 1]).slide };
+        const out = sum([below, step, travel]);
+        chainReach.set(key, out);
+        return out;
+    };
+    for (const cp of parts) {
+        const own = reachOf.get(cp.name);
+        if (!own)
+            continue; // a capability anchor or a refused part: nothing is drawn for it
+        /*
+          A body whose size follows a state input is measured at the widest that channel allows, from the channel's
+          own keys, so the declared volume stands still while the figure moves (shape-dimension contract §2). A
+          channel whose reach is not known is reported rather than guessed at.
+        */
+        if (AXES.some(a => own.widest(a) === null || own.worldSpan(a) === null)) {
+            refusals.push({
+                code: 'OCCUPANCY_STATE_SIZED',
+                part: cp.name,
+                detail: `its size follows a state channel whose reach is not known, so the volume cannot be produced from it; a declared volume has to stand still while the figure moves`
+            });
+            continue;
+        }
+        const centre = AXES.map(a => ofLen(own.centre[a]));
+        // Built only where it is used: a body needs either its own half-sides or its reach in any direction, not both.
+        const halfCache = {};
+        const half = (a) => {
+            const span = own.worldSpan(a);
+            return (halfCache[a] ??= scale(add(sum(span.terms.map(t => scale(ofLen(t.len), t.k))), { n: span.extraMm }), 0.5));
+        };
+        /** Half of all three sides together: at least the way from the centre to any corner, however it is turned. */
+        let anyWayCache = null;
+        const anyWay = () => (anyWayCache ??= scale(sum(AXES.map(a => ofLen(own.widest(a)))), 0.5));
+        const chain = [];
+        for (let j = carrierOf(cp.name); j; j = jointOriginOf.get(j)?.above) {
+            if (chain.includes(j))
+                break;
+            chain.unshift(j);
+        }
+        if (!chain.length) {
+            /*
+              It stays in one frame. Turning where it sits is covered by its own reach in every direction; sliding is
+              covered by an interval along the axis it slides on, which handles a negative direction and an
+              asymmetric range without widening the other axes (designer's ruling 2026-09-23). Nothing above it
+              rotates, so the axis it slides along is the axis it slides along at every pose.
+      
+              There is no shortcut here for a part that looks like it stays inside. `neverPast` decides that, by
+              reading the value rather than by trusting that position and shape scale together — keepRound, a fixed
+              section and a repeat all break that, and an overhang tolerated at the authored size grows with it.
+            */
+            const round = own.turns() ? anyWay() : null;
+            const travelOn = (a) => {
+                let lo = { n: 0 }, hi = { n: 0 };
+                for (const sl of own.slides()) {
+                    if (sl.axis !== a)
+                        continue;
+                    /*
+                      Every world factor the converter writes is positive, so the interval keeps the travel's own order.
+                      The travel is a length, so it enters as millimetres; the factor is the ratio it is stretched by.
+                    */
+                    const fac = sl.factor;
+                    const f = (v) => fac.kind === 'one'
+                        ? { n: v }
+                        : { ref: once(`travel|${fac.ref}|${round6(v)}`, () => g.mul(id(), g.constant(round6(v), 'mm', `occ.travel${round6(v)}`), fac.ref)) };
+                    lo = add(lo, f(Math.min(sl.travel.min, sl.travel.max)));
+                    hi = add(hi, f(Math.max(sl.travel.min, sl.travel.max)));
+                }
+                return { lo, hi };
+            };
+            const affCentre = AXES.map(a => affOfLen(own.centre[a]));
+            const affHalf = AXES.map(a => {
+                const d = affOfLen(own.widest(a));
+                return d && affScale(d, 0.5);
+            });
+            const affRound = own.turns()
+                ? affHalf.reduce((acc, h) => (acc && h ? affAdd(acc, h) : null), { base: 0, slope: { x: 0, y: 0, z: 0 } })
+                : null;
+            for (const [i, a] of AXES.entries()) {
+                const rAff = own.turns() ? affRound : affHalf[i];
+                const t = travelOn(a);
+                const tAff = (v) => (isNum(v) ? { base: v.n, slope: { x: 0, y: 0, z: 0 } } : affineInSize(g, designInputs, v.ref));
+                const cA = affCentre[i];
+                const tLo = tAff(t.lo), tHi = tAff(t.hi);
+                const loAff = cA && rAff && tLo ? affAdd(affAdd(cA, rAff, -1), tLo) : null;
+                const hiAff = cA && rAff && tHi ? affAdd(affAdd(cA, rAff), tHi) : null;
+                const reach = own.turns() ? round : half(a);
+                if (!neverPast(loAff, a, 'min'))
+                    low[a].push(add(add(centre[i], scale(reach, -1)), t.lo));
+                if (!neverPast(hiAff, a, 'max'))
+                    high[a].push(add(add(centre[i], reach), t.hi));
+            }
+            continue;
+        }
+        /*
+          Every body on one chain swings about the same place, so the chain keeps the furthest of them and writes
+          one pair of bounds. A pair for each body would say the same thing, only more of it.
+        */
+        const radius = sum([reachOfChain(chain), spread(originVals(chain[chain.length - 1]), centre), anyWay()]);
+        const key = chain.join('/');
+        const held = furthest.get(key);
+        furthest.set(key, held ? { chain, radius: [...held.radius, radius] } : { chain, radius: [radius] });
+        notes.push({
+            code: 'OCCUPANCY_FROM_STRUCTURE',
+            part: cp.name,
+            detail: `carried by ${chain.join(' → ')}, so it can be anywhere within that chain's reach of ${chain[0]}: the way out to each joint below it, any sliding travel they allow, and its own size. The declared volume holds that at every instance size, without measuring a pose`
+        });
+    }
+    for (const { chain, radius } of furthest.values()) {
+        const anchor = originVals(chain[0]);
+        const worst = radius.every(isNum)
+            ? { n: Math.max(...radius.map(r => r.n)) }
+            : radius.length === 1
+                ? radius[0]
+                : { ref: g.node(id(), 'max@1', radius.map((r, i) => ref(r, `occ.r${i}`)), 'value') };
+        for (const [i, a] of AXES.entries()) {
+            low[a].push(add(anchor[i], scale(worst, -1)));
+            high[a].push(add(anchor[i], worst));
+        }
+    }
+    if (!reachOf.size) {
+        refusals.push({ code: 'OCCUPANCY_NO_BODIES', part: '*', detail: 'nothing is drawn, so there is no volume to declare' });
+        return;
+    }
+    for (const a of AXES) {
+        if (low[a].length)
+            asset.occupancy.bounds[a].min = g.node(`occupancy.${a}.min.held`, 'min@1', [authoredBounds[a].min, ...low[a].map((v, i) => ref(v, `occ.${a}.lo${i}`))], 'value');
+        if (high[a].length)
+            asset.occupancy.bounds[a].max = g.node(`occupancy.${a}.max.held`, 'max@1', [authoredBounds[a].max, ...high[a].map((v, i) => ref(v, `occ.${a}.hi${i}`))], 'value');
+    }
+}
 /** The subject the sizing rules read: `sizing` filled in like the blueprint does. */
 function withSizing(cp) {
     return { ...cp, sizing: cp.sizing ?? 'scale' };
@@ -859,7 +1351,17 @@ export function v2WorldBoxes(source, scale, state = {}, options = {}) {
             : null;
         // Local dimensions: each local axis lands on a world axis and takes that axis's factor, times any channel scale
         // (V2 applies pose.scale in the part's own frame, about its centre).
-        const perm = axisPermutation(part.transform.rotation);
+        /*
+          Which world axis each local axis takes its factor from. A right-angle rotation permutes them. A rotation
+          that only mixes axes carrying the same factor commutes with the scaling, so each local axis keeps its own
+          (`scalingCommutesWithRotation`). Anything else is a real shear: the drawn body is not a box, so there are no
+          local dimensions to report and the unscaled ones stand in. The surface points are sampled from the sheared
+          body either way, so a shear is still caught by the mesh comparison.
+        */
+        const perm = axisPermutation(part.transform.rotation) ??
+            (scalingCommutesWithRotation(part.transform.rotation, (a, b) => Math.abs(box[a].factor - box[b].factor) <= 1e-9)
+                ? { x: 'x', y: 'y', z: 'z' }
+                : null);
         const dims = [
             drawnSize.x * (perm ? box[perm.x].factor : 1) * chScale.x,
             drawnSize.y * (perm ? box[perm.y].factor : 1) * chScale.y,
@@ -893,6 +1395,9 @@ export function v2WorldBoxes(source, scale, state = {}, options = {}) {
                 R = mm3(W.r, rotation);
                 M = mm3(W.r, motionRotation);
             }
+            // V2 hides a part by scaling it to nothing. Nothing is drawn there, so it is not a drawn body.
+            if (dims.some(d => d <= 0))
+                continue;
             const ext = AXES.map((_, a) => dims.reduce((sum, d, i) => sum + Math.abs(R[a][i]) * d, 0));
             const box2 = { part: part.name, centre, extent: { x: ext[0], y: ext[1], z: ext[2] }, dims, rotation: R };
             if (localPoints)
@@ -935,6 +1440,8 @@ export function repeatBoundaryScales(source) {
     return out;
 }
 /** ADR-0087 decision 2 tolerances. */
+/** The only slack a bound may have: what double arithmetic leaves behind, not a product tolerance. */
+const FLOAT_SLACK_MM = 1e-9;
 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. */
@@ -945,8 +1452,7 @@ export function v3StateOverrides(asset, state) {
         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 t = state.clipTime?.[d.clip] ?? 0;
         const unit = units.get(d.state);
         out[d.state] = driverValue(d, t, unit === 'deg' || unit === 'rad' ? unit : 'other');
     }
@@ -1069,12 +1575,13 @@ const V2_UNIT = { '%': 'percent', deg: 'deg', rad: 'rad', mm: 'mm', cm: 'cm', m:
  * What the contract does not cover is refused by name; a channel that moves nothing is noted and skipped.
  */
 function planMotion(c) {
-    const { src, g, base, size, info, spinOf, shiftsOf, scaleOf, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio } = c;
+    const { src, g, base, size, info, spinOf, shiftsOf, scaleOf, scaleRangeOf, visibilityOf, jointOriginOf, lost, frameOf, motionOf, asset, refusals, notes, rangeChanges, ratio } = c;
+    let reauthored = false;
     const params = src.parameters ?? [];
     const clips = src.animations ?? [];
     const joints = src.joints ?? [];
     if (!params.length && !clips.length && !joints.length)
-        return;
+        return { reauthored };
     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.
@@ -1094,6 +1601,18 @@ function planMotion(c) {
         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);
+        /*
+          What a person sees for this input, and how fast the figure travels to a new value for it. Both are kept
+          (V3 designer's ruling 2026-09-22): the label is display metadata beside the stable id, and the sweep is
+          the asset's own statement about its movement — a gripper that closes over 0.6 s must not close at once.
+        */
+        const policy = {};
+        if (p.label)
+            policy.label = p.label;
+        if (p.clip?.duration !== undefined && Number.isFinite(p.clip.duration) && p.clip.duration >= 0)
+            policy.sweep = p.clip.duration;
+        if (Object.keys(policy).length)
+            (asset.stateInputs ??= {})[p.name] = policy;
     }
     /** 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) => {
@@ -1141,18 +1660,24 @@ function planMotion(c) {
      * as a ratio in [0, 1], the keys' `at` in the same ratio (piecewise-linear curves, V3 designer's approval
      * 2026-09-22). Two keys at 0 and 1 take the affine form instead, so earlier assets keep their graphs.
      */
-    const curveRatio = (p, keys, hint) => {
+    /** The parameter mapped onto 0..1 as a ratio, the axis every key's `at` is measured on. */
+    const unitPosition = (p, hint) => {
         const pUnit = paramUnit.get(p.name);
         if (!pUnit)
             return undefined;
-        const span = p.range.max - p.range.min;
         if (pUnit !== 'percent' && pUnit !== 'ratio') {
-            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `a ${pUnit} parameter cannot scale a dimension; a percent or ratio parameter can` });
+            refusals.push({ code: 'PARAMETER_UNIT', part: p.name, detail: `a ${pUnit} parameter cannot scale or hide a part; a percent or ratio parameter can` });
             return undefined;
         }
+        const span = p.range.max - p.range.min;
         const slope = pUnit === 'percent' ? 100 / span : 1 / span;
         const u = g.add(`${hint}.u`, p.name, g.constant(round6(-p.range.min), pUnit, `${hint}.min`));
-        const u01 = g.mul(`${hint}.u01`, u, g.constant(round6(slope), 'ratio', `${hint}.perSpan`));
+        return g.mul(`${hint}.u01`, u, g.constant(round6(slope), 'ratio', `${hint}.perSpan`));
+    };
+    const curveRatio = (p, keys, hint) => {
+        const u01 = unitPosition(p, hint);
+        if (u01 === undefined)
+            return undefined;
         const args = [u01];
         keys.forEach((k, i) => args.push(g.constant(round6(k.at), 'ratio', `${hint}.at${i}`), g.constant(round6(k.value), 'ratio', `${hint}.s${i}`)));
         return g.node(`${hint}.curve`, 'curve@1', args, 'value');
@@ -1237,11 +1762,49 @@ function planMotion(c) {
                     refusals.push({ code: 'ROTATED_FOLLOWS', part: ch.target, detail: 'a scale channel on a part rotated off the axes would shear it; not covered' });
                     continue;
                 }
-                // A scale of 0 is how V2 hides a part (the lamp glow before it lights). A V3 dimension must be positive, so
-                // this is refused until the designer rules on the rule for it (a floor as for span, or a visibility channel).
-                const zero = axes.find(axis => keys.some(k => k.value[axis] <= 0));
-                if (zero) {
-                    refusals.push({ code: 'SCALE_ZERO', part: ch.target, detail: `parameter ${p.name} scales ${zero} to ${Math.min(...keys.map(k => k.value[zero]))}; V2 draws nothing there, a V3 dimension must be positive` });
+                /*
+                  A scale of 0 is how V2 hides a part: the lamp glow is scaled to nothing until the gate opens. A V3
+                  dimension stays positive (designer's ruling 2026-09-22), so this is not a size at all — it is
+                  visibility, and it becomes a flag. Covered shape: the channel starts at 0 on every varying axis and,
+                  from its first non-zero key on, sits at exactly 1 (the part's declared size) on all of them. The part
+                  then keeps its own dimensions and is shown from that key onwards.
+        
+                  Anything else — a channel that hides and also resizes — is refused by name. Writing it as a floored
+                  size would make "not visible" mean "very small", which is the thing that was refused.
+                */
+                const hidesAt = keys.findIndex(k => axes.every(a => k.value[a] > 0));
+                if (keys.some(k => axes.some(a => k.value[a] <= 0))) {
+                    const shaped = hidesAt > 0 &&
+                        keys.slice(0, hidesAt).every(k => axes.every(a => k.value[a] === 0)) &&
+                        keys.slice(hidesAt).every(k => axes.every(a => k.value[a] === 1));
+                    if (!shaped) {
+                        refusals.push({ code: 'SCALE_ZERO', part: ch.target, detail: `parameter ${p.name} scales ${ch.target} to zero and to sizes other than its own; hiding and resizing in one channel is not covered` });
+                        continue;
+                    }
+                    if (visibilityOf.has(ch.target)) {
+                        refusals.push({ code: 'MOTION_MULTI_WRITER', part: ch.target, detail: `two channels decide whether ${ch.target} is shown` });
+                        continue;
+                    }
+                    let claimed = true;
+                    for (const axis of axes)
+                        if (!claim(`${ch.target}/scale/${axis}`, p.name, ch.target)) {
+                            claimed = false;
+                            break;
+                        }
+                    if (!claimed)
+                        continue;
+                    const hint = `${p.name}.${ch.target}.shown`;
+                    const u01 = unitPosition(p, hint);
+                    if (u01 === undefined)
+                        continue;
+                    const at = keys[hidesAt].at;
+                    visibilityOf.set(ch.target, g.node(`${hint}.flag`, 'at-least@1', [u01, g.constant(round6(at), 'ratio', `${hint}.at`)], 'value'));
+                    reauthored = true;
+                    notes.push({
+                        code: 'RE_AUTHORED_VISIBILITY',
+                        part: ch.target,
+                        detail: `V2 hid ${ch.target} by scaling it to 0 and grew it to full size between ${keys[hidesAt - 1].at} and ${at} of parameter ${p.name}. V3 gives the part its own dimensions at all times and a visibility flag that turns on at ${at}. Identical to V2 below ${keys[hidesAt - 1].at} (hidden) and at ${at} and above (full size); inside that band V2 drew a growing part and V3 draws none. The growth was a way of spelling on and off, so it is re-authored, not floored to a small size`
+                    });
                     continue;
                 }
                 const twoKeys = keys.length === 2 && keys[0].at === 0 && keys[1].at === 1;
@@ -1265,6 +1828,12 @@ function planMotion(c) {
                 if (!ok)
                     continue;
                 scaleOf.set(ch.target, entry);
+                const ranges = scaleRangeOf.get(ch.target) ?? {};
+                for (const axis of axes) {
+                    const vs = keys.map(k => k.value[axis]);
+                    ranges[axis] = { min: Math.min(...vs), max: Math.max(...vs) };
+                }
+                scaleRangeOf.set(ch.target, ranges);
                 const shape = twoKeys ? `${keys[0].value[axes[0]]} → ${keys[1].value[axes[0]]} on ${axes[0]}` : `${keys.length} keys on ${axes[0]}: ${keys.map(k => `${k.at}:${k.value[axes[0]]}`).join(' ')}`;
                 notes.push({ code: 'STATE_DIMENSION', part: ch.target, detail: `dimensions on ${axes.join(', ')} follow parameter ${p.name} (${shape}); the occupancy must hold over its range` });
                 continue;
@@ -1298,7 +1867,8 @@ function planMotion(c) {
                 // 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 });
+                const ends = [keys[0].value[axis], keys[1].value[axis]];
+                (shiftsOf.get(ch.target) ?? shiftsOf.set(ch.target, []).get(ch.target)).push({ axis, q: scaled, travel: { min: Math.min(...ends), max: Math.max(...ends) } });
             }
         }
     }
@@ -1351,6 +1921,7 @@ function planMotion(c) {
             asset.stateDefaults[stateId] = rotation ? normalise180(values[0]) : values[0];
             drivers.push({
                 id: `${clip.name}/${ch.target}/${ch.path}`,
+                clip: clip.name,
                 state: stateId,
                 time: { unit: 's', duration },
                 keys: keys.map(k => ({ at: round6(k.at / duration), value: k.value[axis] })),
@@ -1369,7 +1940,7 @@ function planMotion(c) {
             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 });
+                (shiftsOf.get(ch.target) ?? shiftsOf.set(ch.target, []).get(ch.target)).push({ axis, q: scaled, travel: { min, max } });
             }
         }
     }
@@ -1450,6 +2021,11 @@ function planMotion(c) {
         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;
+        jointOriginOf.set(j.name, {
+            origin: [...originRef],
+            ...(parentJoint ? { above: parentJoint.name } : {}),
+            slide: j.type === 'prismatic' ? Math.max(Math.abs(limits?.min ?? 0), Math.abs(limits?.max ?? 0)) : 0
+        });
         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 });
@@ -1460,6 +2036,7 @@ function planMotion(c) {
             M = g.node(`${j.name}.chain`, 'compose@1', [motionOf.get(parentJoint.name), M], 'pose');
         motionOf.set(j.name, M);
     }
+    return { reauthored };
 }
 function normalise180(deg) {
     const w = ((((deg + 180) % 360) + 360) % 360) - 180;