@operato/scene-manufacturing 10.0.0-beta.2 → 10.0.0-beta.22

package/dist/robot-arm-3d.js

@@ -0,0 +1,971 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Robot arm 3D — articulated chain renderer.
+ *
+ * Build pipeline:
+ *   1. Resolve chain (state.chain | preset | default 6-axis-industrial).
+ *   2. Resolve style (state.style preset, with per-property overrides).
+ *   3. Resolve joint values (state.joints array OR object map; missing
+ *      entries default to 0 and clamp to chain[i].range).
+ *   4. If state.target is present, run CCDIK to solve joint values
+ *      reaching that target; commit the solved values back via the
+ *      smoothing controller (next tick converges to them).
+ *   5. Forward-kinematics walk → emit one Object3D per joint frame,
+ *      each carrying its joint housing mesh + the link mesh extending
+ *      along local +Z to the next frame.
+ *   6. Add gripper at the end-effector frame.
+ *   7. Optional reach sphere (wireframe).
+ *
+ * Joint frames are real Object3D children, so the rotation set via
+ * `frame.rotation.<axis> = jointValue` on each frame produces the right
+ * world-space pose without explicit matrix math at render time. CCDIK
+ * runs in matrix math (separate from this scene-graph walk) when needed.
+ */
+import * as THREE from 'three';
+import { RealObjectGroup, resolveMaterial3d, applyMaterial3dProps } from '@hatiolab/things-scene';
+import { STYLES, CHAIN_PRESETS, DEFAULT_GRIPPER } from './robot-arm-styles.js';
+import { solveCCDIK, maxReach, isSixAxisZYYZYZ, resolveBaseYaw, analyticalIk6Axis } from './robot-arm-ik.js';
+const _AXIS_VEC = {
+    x: new THREE.Vector3(1, 0, 0),
+    y: new THREE.Vector3(0, 1, 0),
+    z: new THREE.Vector3(0, 0, 1)
+};
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+/**
+ * Length (chain-local units) of the virtual end-extension used to bias
+ * CCDIK toward "gripper pointing world-down". Longer = stronger orientation
+ * bias but reduces effective reach; shorter = closer to position-only.
+ * 30 is a moderate default that handles typical pick-and-place poses
+ * without sacrificing reach for normal-sized arms.
+ */
+const DESCENT_BIAS = 30;
+/** Raycast no-op — assigned to non-interactive helper meshes (e.g. the
+ *  reach-sphere visualization) so clicks pass through to the real body. */
+const NO_RAYCAST = () => { };
+export class RobotArm3D extends RealObjectGroup {
+    _smoothing;
+    _animFrame;
+    _isAnimating = false;
+    _chain = [];
+    _jointFrames = [];
+    build() {
+        super.build();
+        const state = this.component.state;
+        // Geometry mapping (per user contract):
+        //   width × height = robot footprint (the base pedestal occupies this)
+        //   depth          = robot height (= max reach when fully extended up)
+        //
+        // The chain preset's lengths are treated as PROPORTIONS — we scale them
+        // so the sum matches `effectiveDepth` (with a small base-height
+        // reservation). User can still override by passing absolute lengths via
+        // `state.chain[i].length`; the same scale is applied so `depth` stays
+        // the source of truth for overall robot height.
+        const baseHeight = this._baseHeight(state);
+        const targetReach = Math.max(this.effectiveDepth - baseHeight, 1);
+        const chain = this._resolveChain(state, targetReach);
+        const style = this._resolveStyle(state);
+        let joints = this._resolveJoints(chain, state);
+        // If a target is set, solve IK and use the solved joint values as the
+        // smoothing-controller's new target. CCDIK works in radians; convert
+        // both the input joints and the output back to user-facing units
+        // (degrees for revolute) before storing.
+        //
+        // CRITICAL: IK starts from smoothing.current (the visual joint pose
+        // mid-transit) when present, NOT from state-derived joints. CCDIK is
+        // path-dependent — different start poses converge to different valid
+        // solutions reaching the same TCP. If a rebuild happens DURING transit
+        // (e.g. `set('gripper', state:1)` closing the gripper after pick),
+        // re-solving from state joints (typically 0,0,0...) would produce a
+        // *different* solution than the path the arm was already on, snapping
+        // smoothing.target onto a new joint configuration. The arm — and any
+        // carried box — would then race toward that alternate solution,
+        // sometimes hitting `allReached` almost instantly (if the alternate
+        // happens to be close to current), which fires `tcp-reached`
+        // prematurely and makes pickAndPlace reparent the carrier to the
+        // place holder long before the arm has actually traveled there.
+        const target = state.target;
+        if (target && Number.isFinite(target.x) && Number.isFinite(target.y) && Number.isFinite(target.z)) {
+            const targetVec = new THREE.Vector3(target.x, target.y, target.z);
+            const targetYaw = Number.isFinite(target.yaw) ? target.yaw : undefined;
+            const ikStart = this._smoothing?.current?.slice() ?? joints;
+            const radJoints = this._toRadians(chain, ikStart);
+            const ikValues = this._solveIkDescent(chain, radJoints, targetVec, targetYaw);
+            const solvedUser = this._fromRadians(chain, ikValues);
+            this._smoothing = {
+                current: ikStart.slice(),
+                target: solvedUser.slice(),
+                speed: this._jointSpeed(state)
+            };
+            // visible position = current (interpolated by tick)
+            joints = ikStart.slice();
+        }
+        else if (this._smoothing) {
+            // no target — freeze where we are, NOT animate toward stale state
+            // joints (which may be 0,0,0... and unrelated to the visual pose).
+            this._smoothing.target = this._smoothing.current.slice();
+        }
+        this._chain = chain;
+        this._buildArm(chain, style, joints, baseHeight);
+        this._buildGripper(chain, style, state);
+        this._buildReachSphere(chain, state, baseHeight);
+        this._buildBase(state, style, baseHeight);
+        // Animation lifecycle (smooths joint values toward solved target).
+        this._stopAnimation();
+        if (this._smoothing) {
+            this._startAnimation();
+        }
+        // Re-mount any Carriable child whose object3d was orphaned by the
+        // build's `clear()`. Without this, ANY structural change while a
+        // carrier is held (most commonly the gripper-close `set('gripper',
+        // {state:1})` inside pickAndPlace) tears down `_endFrame` along with
+        // the carrier mounted onto it — the box vanishes mid-flight.
+        //
+        // The component-side child list survives a 3D rebuild (only the
+        // scene-graph was reset), so we walk it and re-execute the holder's
+        // attach-point policy. Uses `add()` (not `attach()`) because the
+        // orphaned object3d's matrixWorld is stale; we want the explicit
+        // localPosition/localRotation, not whatever world pose was last
+        // computed on the old gripper frame.
+        this._remountCarriers();
+    }
+    _remountCarriers() {
+        const holder = this.component;
+        if (typeof holder.attachPointFor !== 'function')
+            return;
+        const children = holder.components ?? holder.children ?? [];
+        for (const child of children) {
+            if (!child?.isCarriable)
+                continue;
+            const obj3d = child._realObject?.object3d;
+            if (!obj3d)
+                continue;
+            const point = holder.attachPointFor(child);
+            if (!point?.attach)
+                continue;
+            point.attach.add(obj3d);
+            const lp = point.localPosition ?? { x: 0, y: 0, z: 0 };
+            obj3d.position.set(lp.x, lp.y, lp.z);
+            if (point.localRotation) {
+                obj3d.rotation.set(point.localRotation.x, point.localRotation.y, point.localRotation.z);
+            }
+            else {
+                obj3d.quaternion.identity();
+            }
+        }
+    }
+    /**
+     * IK with a "point gripper downward" bias.
+     *
+     * CCDIK is position-only — it solves for joint values that put the
+     * end-effector at the target, without constraining the gripper's
+     * orientation. With no orientation constraint, valid solutions
+     * include twisted poses (gripper sideways / upside-down) — typical
+     * pick-and-place tasks then look broken: the box gets gripped at a
+     * wrong angle, or after release the carrier "launches" off because
+     * the gripper was facing some weird direction at the moment of
+     * release. The arm can also visibly "lock" near joint limits trying
+     * to satisfy a position-only target through a contorted path.
+     *
+     * Trick — augment the chain with a virtual rigid extension along the
+     * last frame's +Z, length L. When CCDIK puts this extended end at
+     * `target + L * (-Ẑ_chainLocal)` (i.e. the original target shifted
+     * downward by L in chain-local), the only way the chain can satisfy
+     * both placements simultaneously is by orienting the last frame's +Z
+     * to point in the chain-local -Z direction = world -Y direction =
+     * gripper pointing straight DOWN. Best-effort even when CCDIK can't
+     * fully converge — the solver pushes the chain in the right
+     * orientation, which matches what a real pick-and-place arm does.
+     */
+    _gripperTcpZ(style, state) {
+        const cfg = {
+            ...DEFAULT_GRIPPER,
+            ...(state.gripper ?? {}),
+            ...(state.gripperType ? { type: state.gripperType } : {})
+        };
+        if (cfg.type === 'none')
+            return 0;
+        const linkRadius = style.linkRadius;
+        switch (cfg.type) {
+            case 'parallel': {
+                const stroke = cfg.stroke ?? linkRadius * 1.8;
+                const fingerWidth = cfg.fingerWidth ?? linkRadius * 0.45;
+                const fingerLength = stroke * 1.2;
+                return fingerWidth * 1.8 + fingerLength;
+            }
+            case 'three-finger': {
+                const stroke = cfg.stroke ?? linkRadius * 1.5;
+                const fingerWidth = cfg.fingerWidth ?? linkRadius * 0.4;
+                const fingerLength = stroke * 1.2;
+                return fingerWidth * 1.5 + fingerLength;
+            }
+            case 'suction': {
+                const diameter = cfg.diameter ?? linkRadius * 2.4;
+                return diameter * 0.9;
+            }
+            case 'magnetic': {
+                const diameter = cfg.diameter ?? linkRadius * 2.6;
+                return diameter * 0.25;
+            }
+        }
+        return 0;
+    }
+    _solveIkDescent(chain, radJoints, targetVec, targetYaw) {
+        const state = this.component.state;
+        const style = this._resolveStyle(state);
+        const tcpZ = this._gripperTcpZ(style, state);
+        const augChain = chain.map((c, i) => i === chain.length - 1 ? { ...c, length: c.length + tcpZ } : c);
+        // Fast path: analytical IK for the standard 6-axis Z-Y-Y-Z-Y-Z chain
+        // (industrial + cobot presets). CCDIK is greedy and produces twisted
+        // poses; analytical IK is closed-form, deterministic, and gives the
+        // natural "elbow up, gripper straight down" pose every time.
+        //
+        // The implementation lives in `./robot-arm-ik.js` so the unit tests
+        // exercise THE SAME code that runs at scene-time. (An earlier version
+        // of this file kept a private duplicate, which silently drifted from
+        // the tested implementation — easy to introduce subtle bugs that
+        // tests miss.)
+        if (isSixAxisZYYZYZ(augChain)) {
+            const analytical = analyticalIk6Axis(augChain, targetVec, radJoints, targetYaw);
+            if (analytical)
+                return analytical;
+        }
+        const radChain = augChain.map((c, i) => {
+            const isLast = i === chain.length - 1;
+            const radRanges = c.type === 'revolute'
+                ? [c.range[0] * DEG2RAD, c.range[1] * DEG2RAD]
+                : c.range;
+            return {
+                ...c,
+                length: isLast ? c.length + DESCENT_BIAS : c.length,
+                range: radRanges
+            };
+        });
+        // Shift target downward (chain-local -Z = world -Y) by the bias length.
+        const augTarget = new THREE.Vector3(targetVec.x, targetVec.y, targetVec.z - DESCENT_BIAS);
+        // ── Lock joint 0 (base yaw) at the right value, run CCDIK on the rest ──
+        //
+        // CCDIK has two compounding weaknesses with joint 0 (base yaw, axis
+        // = chain-local Z):
+        //
+        //   (a) Singularity when chain is straight along Z: v1 = tip - origin
+        //       is parallel to the joint axis, projects to zero length on the
+        //       perpendicular plane, and CCDIK SKIPs the joint entirely.
+        //
+        //   (b) Even with the chain bent, CCDIK walking end→base may settle
+        //       on a contorted solution where downstream joints (typically
+        //       the wrist) compensate for an under-rotated joint 0 — the arm
+        //       "self-pierces" reaching backwards over its own base instead
+        //       of cleanly rotating to face the target.
+        //
+        // Fix: split into two phases.
+        //   1. Compute the base yaw analytically: `atan2(target.y, target.x)`
+        //      — the unique angle that points the chain's pitch plane through
+        //      the target.
+        //   2. Run CCDIK on the SUB-chain (joints 1..N-1) with a baseMatrix
+        //      that already includes joint 0's rotation + the first link
+        //      translation. Joint 0 is fixed — CCDIK can't unwind it.
+        //
+        // Result: base yaw is always correctly oriented, and the remaining
+        // joints handle pitch + wrist + descent bias on top of that.
+        const seedJoint0 = chain.length > 0 && chain[0].type === 'revolute' && chain[0].axis === 'z'
+            ? resolveBaseYaw(targetVec, radChain[0].range, radJoints[0] ?? 0)
+            : null;
+        if (seedJoint0 === null) {
+            // Chain doesn't have a Z-axis joint at index 0 (e.g. SCARA, prismatic
+            // first joint) — fall back to plain CCDIK on the full chain. The
+            // singularity above doesn't apply when joint 0 isn't around Z.
+            return solveCCDIK(radChain, radJoints, augTarget, undefined, {
+                maxIterations: 40,
+                damping: 0.5
+            }).values;
+        }
+        // Build base matrix: rotate around Z by seedJoint0, then translate
+        // along Z by chain[0].length (joint 0's link). This places the
+        // sub-chain's origin at frame 1.
+        const baseMatrix = new THREE.Matrix4()
+            .makeRotationZ(seedJoint0)
+            .multiply(new THREE.Matrix4().makeTranslation(0, 0, radChain[0].length));
+        const subChain = radChain.slice(1);
+        const subSeed = radJoints.slice(1);
+        const result = solveCCDIK(subChain, subSeed, augTarget, baseMatrix, {
+            maxIterations: 40,
+            damping: 0.5
+        });
+        return [seedJoint0, ...result.values];
+    }
+    // NOTE: `analyticalIk6Axis` and `resolveBaseYaw` previously lived as
+    // private duplicates here. They've been hoisted to `./robot-arm-ik.ts`
+    // so the unit tests in `test/ik-unit.test.mjs` exercise the same
+    // implementation that runs at scene-time. Don't reintroduce private
+    // copies — drift between "tested" and "shipping" code was a real
+    // source of bugs in this file's history.
+    // ─── Resolution helpers ──────────────────────────────────────────────
+    _resolveChain(state, targetReach) {
+        let raw;
+        if (Array.isArray(state.chain) && state.chain.length > 0) {
+            raw = state.chain;
+        }
+        else {
+            const presetName = (state.chainPreset ?? '6-axis-industrial');
+            raw = CHAIN_PRESETS[presetName] ?? CHAIN_PRESETS['6-axis-industrial'];
+        }
+        // Scale every link.length proportionally so the chain's total reach
+        // matches the requested depth. Preserves preset proportions (a SCARA
+        // stays SCARA-shaped at any depth). Prismatic ranges scale too —
+        // their travel distance is in the same length units.
+        const nominal = raw.reduce((s, c) => s + (c.length || 0), 0);
+        if (nominal <= 0)
+            return raw;
+        const scale = targetReach / nominal;
+        return raw.map(c => ({
+            ...c,
+            length: c.length * scale,
+            range: c.type === 'prismatic' ? [c.range[0] * scale, c.range[1] * scale] : c.range
+        }));
+    }
+    /**
+     * Base pedestal height — small reservation at the bottom of `depth` so
+     * the chain doesn't start at z=0 (which would clip into the floor).
+     * About 12% of depth, clamped to a sane range.
+     */
+    _baseHeight(state) {
+        const depth = this.effectiveDepth;
+        return Math.max(2, Math.min(depth * 0.12, 30));
+    }
+    /**
+     * Color resolution priority (high → low):
+     *   1. `state.fillStyle`  → main link color (overrides style preset)
+     *   2. `state.color`      → legacy / explicit hex int
+     *   3. style preset color
+     * Same for accent: state.strokeStyle → state.accentColor → preset accent.
+     * This way the user can keep a SCARA's box-link shape but recolor it via
+     * the standard fillStyle property without dropping into custom presets.
+     */
+    _resolveStyle(state) {
+        const baseStyle = STYLES[(state.style ?? 'industrial')] ?? STYLES.industrial;
+        return {
+            linkShape: state.linkShape ?? baseStyle.linkShape,
+            jointHousing: state.jointHousing ?? baseStyle.jointHousing,
+            color: pickColorish(state.fillStyle, state.color, baseStyle.color),
+            accentColor: pickColorish(state.strokeStyle, state.accentColor, baseStyle.accentColor),
+            linkRadius: typeof state.linkRadius === 'number' && Number.isFinite(state.linkRadius) && state.linkRadius > 0
+                ? state.linkRadius
+                : baseStyle.linkRadius
+        };
+    }
+    /**
+     * Resolution priority for each joint i:
+     *   1. state.jointN (e.g. state.joint0, state.joint1, ...)  — written
+     *      by the property panel's per-joint number inputs (one row per
+     *      joint, range-clamped slider).
+     *   2. state.joints[i]  — array form, useful for programmatic batch set.
+     *   3. state.joints[i]  — object form ({0: v, 1: v, ...}).
+     *   4. 0  — fallback.
+     * Final value is range-clamped against the joint's own limits.
+     */
+    _resolveJoints(chain, state) {
+        const out = [];
+        const src = state.joints;
+        for (let i = 0; i < chain.length; i++) {
+            let v;
+            const flatKey = state[`joint${i}`];
+            if (Number.isFinite(flatKey)) {
+                v = flatKey;
+            }
+            else if (Array.isArray(src) && Number.isFinite(src[i])) {
+                v = src[i];
+            }
+            else if (src && typeof src === 'object' && Number.isFinite(src[i] ?? src[String(i)])) {
+                v = Number(src[i] ?? src[String(i)]);
+            }
+            else {
+                v = 0;
+            }
+            if (!Number.isFinite(v))
+                v = 0;
+            v = Math.max(chain[i].range[0], Math.min(chain[i].range[1], v));
+            out.push(v);
+        }
+        return out;
+    }
+    _jointSpeed(state) {
+        // Degrees per second the joint can travel during smoothing.
+        // Length-unit prismatic joints reuse this value as units/sec —
+        // typical smoothing speed scales similarly for both axis types.
+        //
+        // Default 45 deg/s — chosen to feel like a real industrial arm
+        // executing a careful pick-and-place rather than a fly-by. Higher
+        // speeds (90+) read as "rushed / unsafe" in a 3D scene where the
+        // viewer expects measured motion. User can override via
+        // `state.jointSpeed`.
+        const v = Number(state.jointSpeed ?? 45);
+        return Number.isFinite(v) && v > 0 ? v : 45;
+    }
+    /** Convert revolute joint values from degrees → radians. Prismatic
+     *  values pass through untouched. */
+    _toRadians(chain, joints) {
+        return joints.map((v, i) => (chain[i].type === 'revolute' ? v * DEG2RAD : v));
+    }
+    /** Inverse of `_toRadians` — radians → degrees for revolute. */
+    _fromRadians(chain, joints) {
+        return joints.map((v, i) => (chain[i].type === 'revolute' ? v * RAD2DEG : v));
+    }
+    // ─── Geometry builders ───────────────────────────────────────────────
+    /**
+     * Build the chain as a tree of nested Object3Ds. Each link extends
+     * along its parent's +Z by `length` — applying the joint rotation BEFORE
+     * the translation. This way `rotateAround joint axis = rotate the
+     * downstream subtree`, which matches real arm kinematics.
+     */
+    _buildArm(chain, style, joints, baseHeight) {
+        const state = this.component.state;
+        const resolved = resolveMaterial3d(state.material3d);
+        const alpha = clamp(numOr(state.alpha, 1), 0, 1);
+        const linkMat = new THREE.MeshStandardMaterial({
+            color: style.color,
+            metalness: 0.45,
+            roughness: 0.45,
+            transparent: alpha < 1,
+            opacity: alpha
+        });
+        applyMaterial3dProps(linkMat, resolved);
+        const housingMat = new THREE.MeshStandardMaterial({
+            color: style.accentColor,
+            metalness: 0.55,
+            roughness: 0.4,
+            transparent: alpha < 1,
+            opacity: alpha
+        });
+        applyMaterial3dProps(housingMat, resolved);
+        // Three.js convention is +Y up — but our forward kinematics + CCDIK
+        // module is +Z up (matches IK math conventions). Wrap the whole arm
+        // in a group rotated -90° around X so chain-local +Z maps to world +Y.
+        // Lift by baseHeight so the chain origin sits ON TOP of the pedestal.
+        const armRoot = new THREE.Group();
+        armRoot.rotation.x = -Math.PI / 2;
+        armRoot.position.y = -this.effectiveDepth / 2 + baseHeight;
+        this.object3d.add(armRoot);
+        // Cache for worldToChainLocal — IK targets must be in this frame.
+        this._armRoot = armRoot;
+        this._jointFrames = [];
+        let currentParent = armRoot;
+        for (let i = 0; i < chain.length; i++) {
+            const link = chain[i];
+            // Joint frame — sits at the start of link i, rotates by jointValue.
+            const frame = new THREE.Object3D();
+            currentParent.add(frame);
+            this._jointFrames.push(frame);
+            this._applyJointValue(frame, link, joints[i]);
+            // Joint housing at the joint origin (frame's local origin).
+            const housing = this._buildJointHousing(style.jointHousing, style.linkRadius, housingMat);
+            if (housing)
+                frame.add(housing);
+            // Link mesh extends along local +Z by link.length. We mount it as a
+            // child of the frame so it inherits the joint rotation. The link
+            // itself sits with its base at z=0 and grows toward +Z.
+            const linkMesh = this._buildLinkMesh(style.linkShape, style.linkRadius, link.length, linkMat);
+            if (linkMesh)
+                frame.add(linkMesh);
+            // The next frame's parent is a translation forward by link.length.
+            const next = new THREE.Object3D();
+            next.position.set(0, 0, link.length);
+            frame.add(next);
+            currentParent = next;
+        }
+        // Save the end-effector parent so the gripper builder can mount onto it.
+        // Also exposed via `getGripperFrame()` so CarrierHolder.attachPointFor
+        // can return it — making any Carriable child mount onto the moving
+        // gripper TCP and follow IK automatically.
+        ;
+        this._endFrame = currentParent;
+    }
+    /**
+     * Frame at the gripper TCP (Tool Center Point) — the working point of
+     * the gripper, NOT the wrist. For jaw grippers this is the mid-point
+     * between finger tips; for suction/magnetic it's the contact face.
+     * Carriers held by the arm parent here so they sit at the gripping
+     * interface, not buried inside the gripper meshes.
+     *
+     * Falls back to `_endFrame` (wrist) until `_buildGripper` has run.
+     */
+    getGripperFrame() {
+        return this._tcpFrame ?? this._endFrame;
+    }
+    /**
+     * Convert a world-space point to the IK module's chain-local frame.
+     *
+     * Why this matters: CCDIK + forwardKinematics operate in `armRoot`'s
+     * local space (base joint at origin, +Z up — the IK math convention).
+     * `state.target` is interpreted in *that* frame. If a caller hands in
+     * a world position from another component (a parcel sitting somewhere
+     * in the scene), it must be projected through `armRoot`'s inverse
+     * world matrix first, otherwise the arm reaches toward "as if the
+     * world coords were base-relative" — a totally wrong direction once
+     * the robot itself isn't at the world origin.
+     *
+     * Returns the same `{x, y, z}` shape `state.target` accepts, which is
+     * already in chain-local space (no further conversion needed by
+     * pickAndPlace).
+     */
+    worldToChainLocal(worldX, worldY, worldZ) {
+        if (!this._armRoot)
+            return { x: 0, y: 0, z: 0 };
+        this._armRoot.updateWorldMatrix(true, false);
+        const v = new THREE.Vector3(worldX, worldY, worldZ);
+        v.applyMatrix4(new THREE.Matrix4().copy(this._armRoot.matrixWorld).invert());
+        return { x: v.x, y: v.y, z: v.z };
+    }
+    _armRoot;
+    /**
+     * Apply a joint value to its scene-graph frame. `value` is in *user
+     * units* (degrees for revolute, scene units for prismatic) — convert
+     * to radians at the math boundary.
+     */
+    _applyJointValue(frame, link, value) {
+        if (link.type === 'revolute') {
+            const ax = _AXIS_VEC[link.axis];
+            frame.quaternion.setFromAxisAngle(ax, value * DEG2RAD);
+        }
+        else {
+            frame.position.copy(_AXIS_VEC[link.axis]).multiplyScalar(value);
+        }
+    }
+    /** Cheap path: just refresh joint orientations without rebuilding the
+     *  geometry tree. Used when only joint values changed. */
+    _refreshJointPoses(joints) {
+        for (let i = 0; i < this._chain.length; i++) {
+            const frame = this._jointFrames[i];
+            if (frame)
+                this._applyJointValue(frame, this._chain[i], joints[i]);
+        }
+    }
+    _buildJointHousing(kind, r, mat) {
+        const radius = r * 1.15;
+        switch (kind) {
+            case 'disk': {
+                const geo = new THREE.CylinderGeometry(radius, radius, r * 0.7, 24);
+                // disk axis = local Y by default; we want it perpendicular to the
+                // link's growth direction. Leaving it on local Y reads as a "wrist
+                // band" between two link segments — which is what cobot disks do.
+                return new THREE.Mesh(geo, mat);
+            }
+            case 'sphere': {
+                const geo = new THREE.SphereGeometry(radius, 16, 12);
+                return new THREE.Mesh(geo, mat);
+            }
+            case 'knuckle': {
+                // Asymmetric box — wider in two axes, narrow in third. Reads as
+                // industrial cast joint.
+                const geo = new THREE.BoxGeometry(radius * 2.1, radius * 1.4, radius * 1.8);
+                return new THREE.Mesh(geo, mat);
+            }
+            case 'none':
+            default:
+                return null;
+        }
+    }
+    _buildLinkMesh(shape, radius, length, mat) {
+        if (length <= 0.5)
+            return null;
+        let geo;
+        switch (shape) {
+            case 'cylinder':
+                geo = new THREE.CylinderGeometry(radius, radius, length, 16);
+                break;
+            case 'tapered':
+                geo = new THREE.CylinderGeometry(radius * 0.7, radius, length, 16);
+                break;
+            case 'tube':
+                geo = new THREE.CylinderGeometry(radius * 0.5, radius * 0.5, length, 12);
+                break;
+            case 'box':
+                geo = new THREE.BoxGeometry(radius * 1.6, radius * 1.6, length);
+                break;
+            case 'gltf':
+                // Placeholder — full GLTF link replacement is a v2 feature.
+                // Fall back to cylinder so the chain doesn't break visually.
+                geo = new THREE.CylinderGeometry(radius, radius, length, 16);
+                break;
+            default:
+                geo = new THREE.CylinderGeometry(radius, radius, length, 16);
+        }
+        // Three.js cylinder/box default axis = local +Y. Rotate to grow along
+        // local +Z (the chain-forward direction) and shift so the BASE sits at
+        // z=0 (rather than centered).
+        if (shape !== 'box') {
+            geo.rotateX(Math.PI / 2);
+        }
+        geo.translate(0, 0, length / 2);
+        const mesh = new THREE.Mesh(geo, mat);
+        mesh.castShadow = true;
+        return mesh;
+    }
+    // ─── Gripper ──────────────────────────────────────────────────────────
+    /**
+     * Build the gripper meshes onto `_endFrame` and place a TCP frame at
+     * the gripper's working point (between the finger tips for jaw types,
+     * at the cup/disk distal face for surface types). Carriers held by the
+     * arm mount onto this TCP frame, NOT onto `_endFrame` — `_endFrame` is
+     * the wrist (chain end-of-link) and the gripper extends from it in +Z,
+     * so a carrier at `_endFrame` origin would visually overlap the gripper
+     * meshes (the fingers/cup would pierce through the box).
+     */
+    _buildGripper(chain, style, state) {
+        const endFrame = this._endFrame;
+        if (!endFrame)
+            return;
+        // TCP frame — added unconditionally (even for gripper.type='none' or
+        // missing gripper) so carrier mount logic always has a stable target.
+        // Default at wrist (z=0); per-type builders override below.
+        const tcp = new THREE.Object3D();
+        endFrame.add(tcp);
+        this._tcpFrame = tcp;
+        const cfg = {
+            ...DEFAULT_GRIPPER,
+            ...(state.gripper ?? {}),
+            // gripperType nature property is a shortcut for {gripper: {type}} —
+            // expose it so the property panel's <select> works without nested object editing.
+            ...(state.gripperType ? { type: state.gripperType } : {})
+        };
+        if (cfg.type === 'none')
+            return;
+        const color = pickColorish(cfg.color, style.accentColor);
+        const resolved = resolveMaterial3d(state.material3d);
+        const alpha = clamp(numOr(state.alpha, 1), 0, 1);
+        const mat = new THREE.MeshStandardMaterial({
+            color,
+            metalness: 0.55,
+            roughness: 0.4,
+            transparent: alpha < 1,
+            opacity: alpha
+        });
+        applyMaterial3dProps(mat, resolved);
+        let tcpZ = 0;
+        switch (cfg.type) {
+            case 'parallel':
+                tcpZ = this._buildParallelGripper(endFrame, cfg, mat, style.linkRadius);
+                break;
+            case 'three-finger':
+                tcpZ = this._buildThreeFingerGripper(endFrame, cfg, mat, style.linkRadius);
+                break;
+            case 'suction':
+                tcpZ = this._buildSuctionGripper(endFrame, cfg, mat, style.linkRadius);
+                break;
+            case 'magnetic':
+                tcpZ = this._buildMagneticGripper(endFrame, cfg, mat, style.linkRadius);
+                break;
+        }
+        tcp.position.z = tcpZ;
+    }
+    _tcpFrame;
+    /**
+     * Each gripper sub-builder returns its TCP z-offset (in `_endFrame`'s
+     * local coordinates) — the point in space where a held carrier's grip
+     * face should land. The caller positions `_tcpFrame` at that z so
+     * carriers attach there directly.
+     */
+    _buildParallelGripper(parent, cfg, mat, linkRadius) {
+        // Default sizes scale with linkRadius so the gripper looks proportional
+        // to the arm. A heavy industrial 6-axis (linkRadius ~10) gets a chunky
+        // gripper; a slim cobot wrist (linkRadius ~3) gets a small one. User
+        // can still override via cfg.stroke / cfg.fingerWidth.
+        const stroke = cfg.stroke ?? linkRadius * 1.8;
+        const fingerWidth = cfg.fingerWidth ?? linkRadius * 0.45;
+        const fingerLength = stroke * 1.2;
+        const closure = THREE.MathUtils.clamp(cfg.state ?? 0, 0, 1); // 0 = open, 1 = closed
+        // Wrist plate
+        const plate = new THREE.Mesh(new THREE.BoxGeometry(stroke * 1.6, fingerWidth * 1.2, fingerWidth * 1.8), mat);
+        plate.position.set(0, 0, fingerWidth * 0.9);
+        parent.add(plate);
+        // Two fingers, opening width = stroke when state=0, fingerWidth when state=1
+        const halfOpen = (stroke / 2) * (1 - closure) + (fingerWidth / 2) * closure;
+        for (const sign of [-1, 1]) {
+            const finger = new THREE.Mesh(new THREE.BoxGeometry(fingerWidth, fingerWidth, fingerLength), mat);
+            finger.position.set(sign * halfOpen, 0, fingerWidth * 1.8 + fingerLength / 2);
+            parent.add(finger);
+        }
+        // TCP = finger-tip plane (carrier's top face docks against it).
+        return fingerWidth * 1.8 + fingerLength;
+    }
+    _buildThreeFingerGripper(parent, cfg, mat, linkRadius) {
+        const stroke = cfg.stroke ?? linkRadius * 1.5;
+        const fingerWidth = cfg.fingerWidth ?? linkRadius * 0.4;
+        const fingerLength = stroke * 1.2;
+        const closure = THREE.MathUtils.clamp(cfg.state ?? 0, 0, 1);
+        const radius = (stroke / 2) * (1 - closure) + (fingerWidth / 2) * closure;
+        // Wrist hub
+        const hub = new THREE.Mesh(new THREE.CylinderGeometry(stroke * 0.55, stroke * 0.55, fingerWidth * 1.5, 16), mat);
+        hub.rotation.x = Math.PI / 2;
+        hub.position.set(0, 0, fingerWidth * 0.75);
+        parent.add(hub);
+        // Three fingers around the axis
+        for (let i = 0; i < 3; i++) {
+            const angle = (i / 3) * Math.PI * 2;
+            const finger = new THREE.Mesh(new THREE.BoxGeometry(fingerWidth, fingerWidth, fingerLength), mat);
+            finger.position.set(Math.cos(angle) * radius, Math.sin(angle) * radius, fingerWidth * 1.5 + fingerLength / 2);
+            parent.add(finger);
+        }
+        return fingerWidth * 1.5 + fingerLength;
+    }
+    _buildSuctionGripper(parent, cfg, mat, linkRadius) {
+        const diameter = cfg.diameter ?? linkRadius * 2.4;
+        // Mounting stem
+        const stem = new THREE.Mesh(new THREE.CylinderGeometry(diameter * 0.25, diameter * 0.25, diameter * 0.5, 12), mat);
+        stem.rotation.x = Math.PI / 2;
+        stem.position.set(0, 0, diameter * 0.25);
+        parent.add(stem);
+        // Suction cup (cone, narrow end at the stem)
+        const cup = new THREE.Mesh(new THREE.CylinderGeometry(diameter / 2, diameter * 0.3, diameter * 0.4, 24, 1, true), mat);
+        cup.rotation.x = Math.PI / 2;
+        cup.position.set(0, 0, diameter * 0.5 + diameter * 0.2);
+        parent.add(cup);
+        // TCP = cup distal face (suction surface contacts the carrier here).
+        return diameter * 0.9;
+    }
+    _buildMagneticGripper(parent, cfg, mat, linkRadius) {
+        const diameter = cfg.diameter ?? linkRadius * 2.6;
+        // Disk magnet at the end
+        const disk = new THREE.Mesh(new THREE.CylinderGeometry(diameter / 2, diameter / 2, diameter * 0.25, 24), mat);
+        disk.rotation.x = Math.PI / 2;
+        disk.position.set(0, 0, diameter * 0.125);
+        parent.add(disk);
+        // TCP = disk distal face (magnet contacts the carrier here).
+        return diameter * 0.25;
+    }
+    // ─── Reach sphere visualization ──────────────────────────────────────
+    _buildReachSphere(chain, state, baseHeight) {
+        if (!state.showReachSphere)
+            return;
+        const reach = maxReach(chain);
+        if (reach <= 0)
+            return;
+        const geo = new THREE.SphereGeometry(reach, 24, 16);
+        const wire = new THREE.WireframeGeometry(geo);
+        const mat = new THREE.LineBasicMaterial({
+            color: 0x44aacc,
+            transparent: true,
+            opacity: 0.18
+        });
+        const wireMesh = new THREE.LineSegments(wire, mat);
+        // Center on the base joint (top of pedestal), in world-space y.
+        wireMesh.position.y = -this.effectiveDepth / 2 + baseHeight;
+        // Visualization-only — must not catch raycasts. The reach sphere
+        // surrounds the arm in 3D and would intercept clicks meant for the
+        // actual robot body. NO_RAYCAST keeps it visible but click-through.
+        wireMesh.raycast = NO_RAYCAST;
+        this.object3d.add(wireMesh);
+        geo.dispose();
+    }
+    // ─── Base / pedestal ─────────────────────────────────────────────────
+    /**
+     * Pedestal — sized from `state.width × state.height` (the 2D footprint).
+     * Cylindrical base whose radius fills ~90% of the smaller footprint
+     * dimension; a flared bottom (1.2× radius) gives the visual weight of
+     * a real industrial robot anchor.
+     */
+    _buildBase(state, style, baseHeight) {
+        const w = Math.max(Math.abs(numOr(state.width, 100)), 1);
+        const h2d = Math.max(Math.abs(numOr(state.height, 100)), 1);
+        const r = (Math.min(w, h2d) / 2) * 0.9;
+        const resolved = resolveMaterial3d(state.material3d);
+        const alpha = clamp(numOr(state.alpha, 1), 0, 1);
+        const mat = new THREE.MeshStandardMaterial({
+            color: style.accentColor,
+            metalness: 0.6,
+            roughness: 0.4,
+            transparent: alpha < 1,
+            opacity: alpha
+        });
+        applyMaterial3dProps(mat, resolved);
+        const base = new THREE.Mesh(new THREE.CylinderGeometry(r, r * 1.2, baseHeight, 24), mat);
+        base.position.set(0, -this.effectiveDepth / 2 + baseHeight / 2, 0);
+        base.castShadow = resolved.castShadow;
+        base.receiveShadow = resolved.receiveShadow;
+        this.object3d.add(base);
+    }
+    // ─── Animation: smooth joint values toward solved target ─────────────
+    _startAnimation() {
+        this._isAnimating = true;
+        let lastTime = performance.now();
+        const tick = () => {
+            if (!this._isAnimating || !this._smoothing)
+                return;
+            const now = performance.now();
+            const dt = Math.min((now - lastTime) / 1000, 0.1); // clamp for stability
+            lastTime = now;
+            const { current, target, speed } = this._smoothing;
+            const maxStep = speed * dt;
+            let allReached = true;
+            for (let i = 0; i < current.length; i++) {
+                const diff = (target[i] ?? 0) - current[i];
+                if (Math.abs(diff) > 1e-4)
+                    allReached = false;
+                const step = Math.sign(diff) * Math.min(Math.abs(diff), maxStep);
+                current[i] += step;
+                // apply to live frame
+                const frame = this._jointFrames[i];
+                const link = this._chain[i];
+                if (frame && link)
+                    this._applyJointValue(frame, link, current[i]);
+            }
+            this.component.invalidate?.();
+            if (allReached) {
+                this._stopAnimation();
+                this.component.trigger?.('tcp-reached', { component: this.component });
+                return;
+            }
+            this._animFrame = requestAnimationFrame(tick);
+        };
+        this._animFrame = requestAnimationFrame(tick);
+    }
+    _stopAnimation() {
+        this._isAnimating = false;
+        if (this._animFrame !== undefined) {
+            cancelAnimationFrame(this._animFrame);
+            this._animFrame = undefined;
+        }
+    }
+    /**
+     * Re-run IK toward a new target without rebuilding the scene graph.
+     *
+     * Mirrors the IK block of `build()` but operates on the *existing*
+     * joint frames and meshes. Critically does NOT call `update()` /
+     * `clear()` — those tear down `this.object3d`'s children, which would
+     * also detach the gripper frame and any Carriable currently mounted
+     * onto it. A pickAndPlace operation would lose its held carrier the
+     * instant the place target is committed.
+     *
+     * Falls back to a full `update()` only when the cached chain hasn't
+     * been built yet (build pre-condition).
+     */
+    _retargetIk() {
+        if (this._chain.length === 0 || this._jointFrames.length !== this._chain.length) {
+            this.update();
+            return;
+        }
+        const state = this.component.state;
+        const chain = this._chain;
+        const target = state.target;
+        const speed = this._jointSpeed(state);
+        // Starting pose for IK = where smoothing currently is (mid-flight)
+        // or the resolved joint values from state. Using mid-flight values
+        // makes consecutive `pnp` calls chain smoothly without snap-back.
+        const previous = this._smoothing?.current?.slice() ?? this._resolveJoints(chain, state);
+        if (target && Number.isFinite(target.x) && Number.isFinite(target.y) && Number.isFinite(target.z)) {
+            const targetVec = new THREE.Vector3(target.x, target.y, target.z);
+            const targetYaw = Number.isFinite(target.yaw) ? target.yaw : undefined;
+            const radJoints = this._toRadians(chain, previous);
+            const ikValues = this._solveIkDescent(chain, radJoints, targetVec, targetYaw);
+            const solvedUser = this._fromRadians(chain, ikValues);
+            this._smoothing = {
+                current: previous,
+                target: solvedUser.slice(),
+                speed
+            };
+            // Snap visible pose to the smoothing's "current" (= previous IK
+            // position). Without this, if external code mutated joint frames
+            // between ticks, the first tick would jump.
+            this._refreshJointPoses(previous);
+            this._stopAnimation();
+            this._startAnimation();
+        }
+        else {
+            // Target cleared — stop animating, freeze where we are.
+            if (this._smoothing) {
+                this._smoothing.target = this._smoothing.current.slice();
+                this._smoothing.speed = speed;
+            }
+            this._stopAnimation();
+        }
+    }
+    updateDimension() { }
+    onchange(after, before) {
+        // Structural changes — full rebuild.
+        if ('style' in after ||
+            'chainPreset' in after ||
+            'chain' in after ||
+            'linkShape' in after ||
+            'jointHousing' in after ||
+            'linkRadius' in after ||
+            'color' in after ||
+            'accentColor' in after ||
+            'fillStyle' in after ||
+            'strokeStyle' in after ||
+            'alpha' in after ||
+            'material3d' in after ||
+            'gripper' in after ||
+            'gripperType' in after ||
+            'showReachSphere' in after ||
+            'width' in after ||
+            'height' in after ||
+            'depth' in after) {
+            this.update();
+            return;
+        }
+        // Target change → re-run IK + restart smoothing on the EXISTING
+        // scene graph. Critically NOT a full rebuild — `update()` calls
+        // `clear()` which detaches every child of `this.object3d`, including
+        // any Carriable currently mounted on the gripper frame. A pickAndPlace
+        // call would invisibly drop the held carrier the moment we set the
+        // place target, leaving no mesh between pick and place.
+        if ('target' in after || 'jointSpeed' in after) {
+            this._retargetIk();
+            return;
+        }
+        // Joint value change (state.joint0, state.joint1, ... or state.joints
+        // batch) — fast path: just refresh joint poses on the existing scene
+        // graph. NO mesh rebuild. This is what makes property-panel slider
+        // edits feel live. The match must be done explicitly because dynamic
+        // joint property names (joint0, joint1, ...) aren't in any static list.
+        const hasJoint = 'joints' in after || Object.keys(after).some(k => /^joint\d+$/.test(k));
+        if (hasJoint) {
+            const state = this.component.state;
+            // chain might be empty if build hasn't run yet (e.g. component just
+            // attached). Defer to a full update in that case.
+            if (this._chain.length === 0 || this._jointFrames.length !== this._chain.length) {
+                this.update();
+                return;
+            }
+            const joints = this._resolveJoints(this._chain, state);
+            this._refreshJointPoses(joints);
+            // smoothing's "current" should track the user's manual edits so the
+            // next IK target solves from where the user left things.
+            if (this._smoothing)
+                this._smoothing.current = joints.slice();
+            return;
+        }
+        super.onchange(after, before);
+    }
+    dispose() {
+        this._stopAnimation();
+        super.dispose();
+    }
+    updateAlpha() { }
+}
+/** Returns `v` if a finite number, otherwise `dflt`. */
+function numOr(v, dflt) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : dflt;
+}
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+/**
+ * Pick the first valid color in priority order. Accepts both color strings
+ * (CSS / hex) and hex int numbers — both are valid `THREE.ColorRepresentation`.
+ * Treats 'transparent' / empty strings as "skip me".
+ */
+/** Returns a number-or-string color (StyleColor). Both flavors are valid
+ *  THREE.ColorRepresentation, so they pass through to MeshStandardMaterial
+ *  without conversion. */
+function pickColorish(...candidates) {
+    for (const c of candidates) {
+        if (typeof c === 'string' && c && c !== 'transparent')
+            return c;
+        if (typeof c === 'number' && Number.isFinite(c))
+            return c;
+    }
+    return 0x888888;
+}
+//# sourceMappingURL=robot-arm-3d.js.map