@operato/scene-manufacturing 10.0.0-beta.30 → 10.0.0-beta.32

package/dist/robot-arm.d.ts

@@ -1,8 +1,44 @@
 import * as THREE from 'three';
 import { Component, ComponentNature, RealObject } from '@hatiolab/things-scene';
-import type { SlotDef } from '@hatiolab/things-scene';
+import type { SlotDef, State, Material3D } from '@hatiolab/things-scene';
 import { type Alignment, type Heights, type LegendBinding, type MoveOptions, type PlacementArchetype } from '@operato/scene-base';
+import { RobotArm3D } from './robot-arm-3d.js';
+import { type ChainPresetName } from './robot-arm-styles.js';
+import type { ChainElement } from './robot-arm-ik.js';
+import type { GripperConfig, LinkShape, JointHousing, StyleName } from './robot-arm-styles.js';
+declare module '@hatiolab/things-scene' {
+    interface ComponentEventMap {
+        /** TCP 가 목표 도달 시 발생 (pickAndPlace 시퀀싱용). */
+        'tcp-reached': [info: {
+            component: Component;
+        }];
+    }
+}
 export type RobotArmStatus = 'idle' | 'moving' | 'gripping' | 'warn' | 'error';
+/** RobotArm 컴포넌트 state */
+export interface RobotArmState extends State {
+    style?: StyleName;
+    chainPreset?: ChainPresetName;
+    chain?: ChainElement[];
+    joints?: number[] | Record<string, number>;
+    linkShape?: LinkShape;
+    jointHousing?: JointHousing;
+    linkRadius?: number;
+    color?: string | number;
+    accentColor?: string | number;
+    gripper?: GripperConfig;
+    gripperType?: GripperConfig['type'];
+    target?: {
+        x: number;
+        y: number;
+        z: number;
+        yaw?: number;
+    };
+    showReachSphere?: boolean;
+    jointSpeed?: number;
+    status?: RobotArmStatus;
+    material3d?: Material3D;
+}
 declare const Base: typeof Component & {
     new (...args: any[]): Component & {
         isMover: boolean;
@@ -12,6 +48,17 @@ declare const Base: typeof Component & {
     };
 };
 export default class RobotArm extends Base {
+    get state(): RobotArmState;
+    _realObject: RobotArm3D | undefined;
+    /**
+     * Phase H — pickup contract 호환성 검사용. 보편적 'gripper' type — vacuum,
+     * 2-finger, 3-finger 등 다양한 gripper 모두 이 type 으로 매칭. carrier 가
+     * 더 세분화된 호환성을 원하면 `pickupFramesFor` override 로 size 등 추가 검증.
+     *
+     * (override 키워드 미사용 — Base 캐스트가 Mover 의 toolType 을 노출하지 않아
+     *  TS4113 회피.)
+     */
+    get toolType(): string;
     static legends: Record<string, LegendBinding>;
     /**
      * Robot arms sit on the floor (or mount to a ceiling/wall — that's a
@@ -132,13 +179,20 @@ export default class RobotArm extends Base {
      *
      *   1. TCP → APPROACH above place (carrier's xy, +clearance)
      *   2. TCP → place (descend straight down to drop point)
-     *   3. open gripper + reparent(carrier → holder)
+     *   3. open gripper + dispatch (carrier → holder)
      *
      * Pose resolution: TCP lands at where the carrier's top WILL BE after
      * the drop, so the carrier lands with its bottom on the holder's attach
      * surface. Computed as `holder.attachFrame.world.y + carrier.depth` (so
      * yOffset = carrierDepth, not halfDepth like pick).
      *
+     * Handoff: if this arm has `dispatch` (ContainerCapacity) and the holder
+     * exposes `receive`, route via dispatch — slot tracking, `transfer-received`
+     * trigger (which downstream conveyance components like InductStation listen
+     * to for belt-animation kickoff), and `canReceive` pre-flight all flow
+     * through the standard contract. Falls back to raw `holder.reparent()` for
+     * holders without ContainerCapacity (plain Spot, etc.). Mirrors Mover.place.
+     *
      * @see pick — same option semantics.
      */
     place(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>;
@@ -158,13 +212,42 @@ export default class RobotArm extends Base {
      */
     /** Short alias for `pickAndPlace`. Same arguments, same behavior. */
     pnp(carrier: Component, placeHolder: Component, options?: MoveOptions): Promise<void>;
+    /**
+     * Return all joints to the configured home pose (state.joints / state.jointN).
+     *
+     * IK target 을 클리어하고 forward joint 제어로 부드럽게 휴식 포즈로 복귀.
+     * `pickAndPlace` 의 마지막 단계로 자동 호출되며, 사용자가 명시적으로 호출도 가능.
+     *
+     * **인터럽트 가능**: 집에 도달하기 전에 새 `pick`/`place` 가 호출되면 (`set('target', ...)`)
+     * `_retargetIk()` 가 발동되어 smoothing 이 home 으로 가던 걸 멈추고 새 IK target 쪽으로
+     * redirect. mid-flight joint 값을 새 IK 의 시작점으로 사용해 끊김 없이 전환. tcp-reached
+     * 가 redirect 후의 새 target 에서 발생하면 goHome 의 await 도 함께 resolve (정상).
+     * 즉 "집으로 가다가 다음 pick 으로 자연스럽게 이어진다".
+     *
+     * @param options.timeoutMs  joint smoothing 의 'tcp-reached' 대기 timeout (default 15000ms).
+     */
+    goHome(options?: MoveOptions): Promise<void>;
+    /**
+     * pick → place → goHome 시퀀스. 마지막에 home pose 복귀가 robot-arm 의
+     * pickAndPlace 표준 동작. (Mover mixin 의 default 는 pick + place 만)
+     */
+    pickAndPlace(carrier: Component, holder: Component, options?: MoveOptions): Promise<void>;
     /**
      * Resolve a TCP position in this arm's chain-local frame.
      *
-     * For a CarrierHolder (has `attachPointFor`), uses the holder's own
-     * attach frame as the base — that's the canonical "where carriers
-     * sit on me" point (top of Spot's pad, gripper TCP for another arm,
-     * etc.). For a plain carrier, uses its world center.
+     * Resolution priority:
+     *   1. `attachPointFor` (CarrierHolder) — canonical TCP frame for arms /
+     *      Spot pads / gripper-on-gripper.
+     *   2. `deliveryWorldPosition` (Phase G9 — Holder contract). Holder 가
+     *      ContainerCapacity 의 default 또는 자체 override 로 정확한 도달
+     *      world XYZ 를 직접 제공. 이전 SCAFFOLDING 의 cz 공식 역연산이
+     *      여기로 이전됨.
+     *   3. Component's own `_realObject.object3d` world center.
+     *   4. 2D bounds center (only before 3D builds).
+     *
+     * `carrierForDelivery` 가 주어지면 (place 케이스) `component` 를 holder 로
+     * 간주하고 `component.deliveryWorldPosition(carrierForDelivery)` 를 query.
+     * 미지정 (pick 케이스 — `component` 자체가 carrier) 시 #3 으로.
      *
      * `worldYOffset` is added to the resolved world Y before projecting
      * back to chain-local — used by pickAndPlace to lift the TCP above
@@ -180,5 +263,17 @@ export default class RobotArm extends Base {
      * moment of reparent.
      */
     private _yawOf;
+    /**
+     * Phase G5.2 — Delivery yaw 결정.
+     *
+     * holder 가 ContainerCapacity contract 의 deliveryWorldRotation 을 노출하면
+     * 그 world quaternion 에서 yaw 를 추출 (carrier 가 acceptance pose 와 일치
+     * 한 채 release 되도록). InductStation 같은 holder 가 sorter forward 방향을
+     * 자기 acceptanceRotation 으로 선언하면 자동으로 그 방향이 TCP yaw 가 됨.
+     *
+     * holder 가 deliveryWorldRotation 을 안 노출하거나 _realObject 미빌드 시
+     * 기존 동작 (holder 자체의 world yaw) 으로 fallback.
+     */
+    private _deliveryYawOf;
 }
 export {};

package/dist/robot-arm.js

@@ -33,7 +33,7 @@
  */
 import { __decorate } from "tslib";
 import * as THREE from 'three';
-import { ContainerAbstract, ContainerCapacity, sceneComponent } from '@hatiolab/things-scene';
+import { ContainerAbstract, ContainerCapacity, frameClock, sceneComponent } from '@hatiolab/things-scene';
 import { CarrierHolder, Legendable, Mover, Placeable } from '@operato/scene-base';
 import { RobotArm3D } from './robot-arm-3d.js';
 import { CHAIN_PRESETS } from './robot-arm-styles.js';
@@ -145,6 +145,23 @@ const STATIC_PROPERTIES = [
 // CarrierHolder.attachPointFor() (overridden below) provides 3D TCP positioning.
 const Base = Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract)))));
 let RobotArm = class RobotArm extends Base {
+    // `Base` is cast through `typeof Component` so TS sees `state` as an
+    // accessor; `declare state: …` would conflict with TS2610. Override the
+    // getter instead — runtime behavior is identical (just delegates to super).
+    get state() {
+        return super.state;
+    }
+    /**
+     * Phase H — pickup contract 호환성 검사용. 보편적 'gripper' type — vacuum,
+     * 2-finger, 3-finger 등 다양한 gripper 모두 이 type 으로 매칭. carrier 가
+     * 더 세분화된 호환성을 원하면 `pickupFramesFor` override 로 size 등 추가 검증.
+     *
+     * (override 키워드 미사용 — Base 캐스트가 Mover 의 toolType 을 노출하지 않아
+     *  TS4113 회피.)
+     */
+    get toolType() {
+        return 'gripper';
+    }
     static legends = {
         bodyColor: { from: 'status', legend: BODY_LEGEND },
         borderColor: { from: 'status', legend: BORDER_LEGEND },
@@ -287,8 +304,7 @@ let RobotArm = class RobotArm extends Base {
             'status' in after ||
             'bodyColor' in after ||
             'borderColor' in after) {
-            ;
-            this.clearCache?.('fillStyle');
+            this.clearCache('fillStyle');
             this.invalidate();
         }
         super.onchange(after, before);
@@ -396,13 +412,20 @@ let RobotArm = class RobotArm extends Base {
      *
      *   1. TCP → APPROACH above place (carrier's xy, +clearance)
      *   2. TCP → place (descend straight down to drop point)
-     *   3. open gripper + reparent(carrier → holder)
+     *   3. open gripper + dispatch (carrier → holder)
      *
      * Pose resolution: TCP lands at where the carrier's top WILL BE after
      * the drop, so the carrier lands with its bottom on the holder's attach
      * surface. Computed as `holder.attachFrame.world.y + carrier.depth` (so
      * yOffset = carrierDepth, not halfDepth like pick).
      *
+     * Handoff: if this arm has `dispatch` (ContainerCapacity) and the holder
+     * exposes `receive`, route via dispatch — slot tracking, `transfer-received`
+     * trigger (which downstream conveyance components like InductStation listen
+     * to for belt-animation kickoff), and `canReceive` pre-flight all flow
+     * through the standard contract. Falls back to raw `holder.reparent()` for
+     * holders without ContainerCapacity (plain Spot, etc.). Mirrors Mover.place.
+     *
      * @see pick — same option semantics.
      */
     async place(carrier, holder, options = {}) {
@@ -410,14 +433,29 @@ let RobotArm = class RobotArm extends Base {
         const reparentDuration = options.reparentDuration ?? 800;
         const clearance = options.approachClearance ?? 10;
         const carrierDepth = resolveDepth(carrier);
-        const yaw = this._yawOf(holder);
-        const target = this._targetFor(holder, carrierDepth, yaw); // top-of-carrier after drop
-        const approach = this._targetFor(holder, carrierDepth + clearance, yaw);
+        // Phase G5.2 — holder 가 acceptanceRotation 을 선언하면 그 world equivalent
+        // (deliveryWorldRotation) 의 yaw 를 TCP yaw 로 사용. 그러면 carrier 가 holder
+        // 의 acceptance pose 와 정확히 일치한 채 release 되어 handoff 시 zero-delta
+        // (시각적 점프 없음). holder 가 미정의면 holder 자체의 world yaw 사용
+        // (이전 동작).
+        const yaw = this._deliveryYawOf(holder, carrier);
+        // Phase G9 — carrier 도 함께 전달해 holder 의 deliveryWorldPosition 을 정확히
+        // query. holder 가 contract 노출 안 하면 fallback (object3d 원점) 으로.
+        const target = this._targetFor(holder, carrierDepth, yaw, carrier); // top-of-carrier after drop
+        const approach = this._targetFor(holder, carrierDepth + clearance, yaw, carrier);
         this.set('target', approach);
         await waitForTcpReached(this, timeoutMs);
         this.set('target', target);
         await waitForTcpReached(this, timeoutMs);
-        holder.reparent?.(carrier, { animated: true, duration: reparentDuration });
+        const xferOptions = { animated: true, duration: reparentDuration };
+        const canDispatch = typeof this.dispatch === 'function' && typeof holder.receive === 'function';
+        if (canDispatch) {
+            await this.dispatch(carrier, holder, xferOptions);
+        }
+        else {
+            ;
+            holder.reparent?.(carrier, xferOptions);
+        }
         this.set('gripper', { ...(this.state.gripper ?? {}), state: 0 });
         await sleep(reparentDuration);
     }
@@ -439,20 +477,63 @@ let RobotArm = class RobotArm extends Base {
     pnp(carrier, placeHolder, options) {
         return this.pickAndPlace(carrier, placeHolder, options);
     }
+    /**
+     * Return all joints to the configured home pose (state.joints / state.jointN).
+     *
+     * IK target 을 클리어하고 forward joint 제어로 부드럽게 휴식 포즈로 복귀.
+     * `pickAndPlace` 의 마지막 단계로 자동 호출되며, 사용자가 명시적으로 호출도 가능.
+     *
+     * **인터럽트 가능**: 집에 도달하기 전에 새 `pick`/`place` 가 호출되면 (`set('target', ...)`)
+     * `_retargetIk()` 가 발동되어 smoothing 이 home 으로 가던 걸 멈추고 새 IK target 쪽으로
+     * redirect. mid-flight joint 값을 새 IK 의 시작점으로 사용해 끊김 없이 전환. tcp-reached
+     * 가 redirect 후의 새 target 에서 발생하면 goHome 의 await 도 함께 resolve (정상).
+     * 즉 "집으로 가다가 다음 pick 으로 자연스럽게 이어진다".
+     *
+     * @param options.timeoutMs  joint smoothing 의 'tcp-reached' 대기 timeout (default 15000ms).
+     */
+    async goHome(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 15000;
+        const ro = this._realObject;
+        if (!ro?.moveJointsTo || !ro?.getHomeJoints)
+            return;
+        // IK target 제거 — 다음 rebuild 시 _smoothing.target 이 IK 로 다시 풀리지 않도록.
+        // 외부에서 set('target', ...) 호출하면 다시 IK 모드로 전환되며 redirect.
+        this.set('target', undefined);
+        ro.moveJointsTo(ro.getHomeJoints());
+        await waitForTcpReached(this, timeoutMs);
+    }
+    /**
+     * pick → place → goHome 시퀀스. 마지막에 home pose 복귀가 robot-arm 의
+     * pickAndPlace 표준 동작. (Mover mixin 의 default 는 pick + place 만)
+     */
+    async pickAndPlace(carrier, holder, options = {}) {
+        await this.pick(carrier, options);
+        await this.place(carrier, holder, options);
+        await this.goHome(options);
+    }
     /**
      * Resolve a TCP position in this arm's chain-local frame.
      *
-     * For a CarrierHolder (has `attachPointFor`), uses the holder's own
-     * attach frame as the base — that's the canonical "where carriers
-     * sit on me" point (top of Spot's pad, gripper TCP for another arm,
-     * etc.). For a plain carrier, uses its world center.
+     * Resolution priority:
+     *   1. `attachPointFor` (CarrierHolder) — canonical TCP frame for arms /
+     *      Spot pads / gripper-on-gripper.
+     *   2. `deliveryWorldPosition` (Phase G9 — Holder contract). Holder 가
+     *      ContainerCapacity 의 default 또는 자체 override 로 정확한 도달
+     *      world XYZ 를 직접 제공. 이전 SCAFFOLDING 의 cz 공식 역연산이
+     *      여기로 이전됨.
+     *   3. Component's own `_realObject.object3d` world center.
+     *   4. 2D bounds center (only before 3D builds).
+     *
+     * `carrierForDelivery` 가 주어지면 (place 케이스) `component` 를 holder 로
+     * 간주하고 `component.deliveryWorldPosition(carrierForDelivery)` 를 query.
+     * 미지정 (pick 케이스 — `component` 자체가 carrier) 시 #3 으로.
      *
      * `worldYOffset` is added to the resolved world Y before projecting
      * back to chain-local — used by pickAndPlace to lift the TCP above
      * the target (approach waypoints) and to land it on the carrier's
      * top face rather than its volumetric center.
      */
-    _targetFor(component, worldYOffset = 0, yaw) {
+    _targetFor(component, worldYOffset = 0, yaw, carrierForDelivery) {
         const ro3d = this._realObject;
         let baseWp;
         // Prefer holder's attach frame when available.
@@ -465,10 +546,24 @@ let RobotArm = class RobotArm extends Base {
             }
         }
         if (!baseWp) {
-            const obj = component._realObject?.object3d;
-            if (obj) {
-                obj.updateWorldMatrix(true, false);
-                baseWp = obj.getWorldPosition(new THREE.Vector3());
+            // Phase G9 — Holder.deliveryWorldPosition contract 를 우선 사용 (place
+            // 케이스: carrierForDelivery 가 주어진 경우). ContainerCapacity 가 default
+            // 로 receivingSurfaceY/geometricOffsetY 보정 + 표면 변환을 제공하므로
+            // robot-arm 이 cz 공식 역연산을 직접 알지 않아도 됨.
+            if (carrierForDelivery) {
+                const deliveryPos = component.deliveryWorldPosition?.(carrierForDelivery);
+                if (deliveryPos) {
+                    baseWp = new THREE.Vector3(deliveryPos.x, deliveryPos.y, deliveryPos.z);
+                }
+            }
+            // Fallback (pick 케이스 또는 holder 가 contract 미노출): component 자체의
+            // obj3d world center.
+            if (!baseWp) {
+                const obj = component._realObject?.object3d;
+                if (obj) {
+                    obj.updateWorldMatrix(true, false);
+                    baseWp = obj.getWorldPosition(new THREE.Vector3());
+                }
             }
         }
         if (!ro3d || !baseWp) {
@@ -496,34 +591,87 @@ let RobotArm = class RobotArm extends Base {
         const e = new THREE.Euler().setFromQuaternion(q, 'YXZ');
         return e.y;
     }
+    /**
+     * Phase G5.2 — Delivery yaw 결정.
+     *
+     * holder 가 ContainerCapacity contract 의 deliveryWorldRotation 을 노출하면
+     * 그 world quaternion 에서 yaw 를 추출 (carrier 가 acceptance pose 와 일치
+     * 한 채 release 되도록). InductStation 같은 holder 가 sorter forward 방향을
+     * 자기 acceptanceRotation 으로 선언하면 자동으로 그 방향이 TCP yaw 가 됨.
+     *
+     * holder 가 deliveryWorldRotation 을 안 노출하거나 _realObject 미빌드 시
+     * 기존 동작 (holder 자체의 world yaw) 으로 fallback.
+     */
+    _deliveryYawOf(holder, carrier) {
+        const deliveryRot = holder.deliveryWorldRotation?.(carrier);
+        if (deliveryRot) {
+            const q = new THREE.Quaternion(deliveryRot.x, deliveryRot.y, deliveryRot.z, deliveryRot.w);
+            const e = new THREE.Euler().setFromQuaternion(q, 'YXZ');
+            return e.y;
+        }
+        return this._yawOf(holder);
+    }
 };
 RobotArm = __decorate([
     sceneComponent('robot-arm')
 ], RobotArm);
 export default RobotArm;
 /**
- * Resolve when the robot arm fires `tcp-reached`, reject on timeout.
- * The 3D side fires this event on smoothing completion (last joint
- * value within threshold of its target).
+ * Resolve when the robot arm fires `tcp-reached`, reject on **simulation-time**
+ * timeout. 3D smoothing 은 frameClock 의 simDt 로 진행 (sim-time-driven),
+ * 따라서 timeout 도 sim-time 으로 누적해야 sim speed 변경에 일관 동작:
+ *   - speed=1   → sim time = real time (기존과 동일)
+ *   - speed=2   → IK 도 2× 빨라지고 timeout 도 2× 빠르게 도달 (real time 기준)
+ *   - speed=0.5 → IK 가 2× 느려지지만 timeout 도 sim 기준이라 spurious
+ *                  reject 없음 (이전 real-time setTimeout 으로는 1 미만 speed
+ *                  에서 IK 도달 전에 timeout 발화하던 버그 수정)
+ *   - paused    → simDt=0 누적도 정지 → 일시정지 동안 무한 대기 (의도)
  */
 function waitForTcpReached(component, timeoutMs) {
     return new Promise((resolve, reject) => {
-        let timer;
+        let elapsedSim = 0;
+        let unsub = null;
+        const cleanup = () => {
+            component.off('tcp-reached', onReached);
+            if (unsub) {
+                unsub();
+                unsub = null;
+            }
+        };
         const onReached = () => {
-            clearTimeout(timer);
-            component.off?.('tcp-reached', onReached);
+            cleanup();
             resolve();
         };
-        timer = setTimeout(() => {
-            ;
-            component.off?.('tcp-reached', onReached);
-            reject(new Error('TCP reach timeout'));
-        }, timeoutMs);
-        component.on?.('tcp-reached', onReached);
+        component.on('tcp-reached', onReached);
+        unsub = frameClock.subscribe(simDt => {
+            elapsedSim += simDt;
+            if (elapsedSim >= timeoutMs) {
+                cleanup();
+                reject(new Error('TCP reach timeout'));
+            }
+        }, { description: 'robot-arm tcp-reached timeout', component });
     });
 }
+/**
+ * sim-time aware sleep — frameClock 의 simDt 를 누적해 ms 도달 시 resolve.
+ * speed=0.5 이면 real time 으로 2배 걸리지만 sim time 으로는 동일 — animation
+ * 시간과 일관. paused 시 무한 대기 (의도). waitForTcpReached 와 같은 시간축.
+ */
 function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+    return new Promise(resolve => {
+        let elapsedSim = 0;
+        let unsub = null;
+        unsub = frameClock.subscribe(simDt => {
+            elapsedSim += simDt;
+            if (elapsedSim >= ms) {
+                if (unsub) {
+                    unsub();
+                    unsub = null;
+                }
+                resolve();
+            }
+        }, { description: 'robot-arm sim-sleep' });
+    });
 }
 function numOr(v, dflt) {
     return typeof v === 'number' && Number.isFinite(v) ? v : dflt;