@operato/scene-storage 10.0.0-beta.38 → 10.0.0-beta.41

package/dist/crane.js

@@ -2,7 +2,7 @@ import { __decorate } from "tslib";
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { ContainerAbstract, ContainerCapacity, sceneComponent } from '@hatiolab/things-scene';
+import { ContainerAbstract, ContainerCapacity, Transfer, getWorldPose, sceneComponent } from '@hatiolab/things-scene';
 import { CarrierHolder, Legendable, Mover, Placeable } from '@operato/scene-base';
 import { Crane3D } from './crane-3d.js';
 const BODY_LEGEND = {
@@ -41,10 +41,21 @@ const NATURE = {
             }
         },
         {
-            type: 'string',
-            label: 'target',
-            name: 'target',
-            placeholder: 'refid of target (e.g., a RackGrid) — crane serves only its cells'
+            type: 'checkbox',
+            label: 'simulate',
+            name: 'simulate'
+        },
+        {
+            type: 'number',
+            label: 'carriage-position',
+            name: 'carriagePosition',
+            placeholder: 'rail-local X (0 ~ rail width). Crane.moveTo 가 lerp.'
+        },
+        {
+            type: 'number',
+            label: 'carriage-width',
+            name: 'carriageWidth',
+            placeholder: 'rail-local 폭 (mm). 미명시 rail width × 10%.'
         },
         {
             type: 'number',
@@ -134,9 +145,57 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         return [];
     }
     // ── ContainerCapacity ─────────────────────────────────────────────────────
-    /** Stacker crane carries at most one load at a time on its forks. */
+    /**
+     * Stacker crane carries at most one load at a time on its forks.
+     *
+     * localPosition.z = 0 명시 — ContainerCapacity.receive 의 atomic setState 가
+     * `carrier.state.zPos = slot.localPosition.z + parentGeoOffset = 0` 강제.
+     * 미명시 시 zPos update skip → carrier 의 *이전 holder 또는 board model 의
+     * 임의 zPos (음수 가능)* 그대로 → _realObject 미빌드 시점 (transient placement
+     * 미설정 = state-driven) 에 carrier 가 *지하* 로 가는 결함.
+     */
     get slots() {
-        return [{ id: 'forks', maxCount: 1 }];
+        return [{ id: 'forks', maxCount: 1, localPosition: { x: 0, y: 0, z: 0 } }];
+    }
+    /**
+     * Acceptance rotation — carrier 가 crane.fork 에 attach 시 *crane 의 local
+     * axis (전방)* 으로 정렬. identity quaternion 반환 → atomic setState 가
+     * carrier.state.rotation/X/Y = 0 강제. _realObject 미빌드 시점 (transient
+     * placement 미설정 = state-driven) fallback 에서도 자세 정렬.
+     *
+     * follow-holder carryPolicy 와 짝 — 두 path 모두 동일 결과 (local identity).
+     */
+    acceptanceRotation(_carrier, _slot) {
+        return { x: 0, y: 0, z: 0, w: 1 };
+    }
+    /**
+     * Arrangement — carrier.state.left/top 의 *기준* 이 *crane 전체 footprint* 가
+     * 아닌 *carriage X (carriagePosition) + fork Z (bladeMidZ)*. carriage / fork
+     * 의 위치가 carrier 의 위치.
+     *
+     *   left = carriagePosition − carrier.w/2     (carriage X 중심)
+     *   top  = crane.h/2 + bladeMidZ − carrier.h/2   (fork Z 중심)
+     */
+    get arrangementStrategy() {
+        const crane = this;
+        return {
+            positionAt(_idx, _slot, _occ, component) {
+                const cw = numOr(crane.state?.width, 100);
+                const ch = numOr(crane.state?.height, 100);
+                const carrierW = numOr(component?.state?.width, 0);
+                const carrierH = numOr(component?.state?.height, 0);
+                const carriagePos = numOr(crane.state?.carriagePosition, cw / 2);
+                const bladeMidZ = numOr(crane._realObject?.bladeMidZ, 0);
+                return {
+                    x: carriagePos - carrierW / 2,
+                    y: ch / 2 + bladeMidZ - carrierH / 2,
+                    z: 0
+                };
+            },
+            capacity(slot) {
+                return slot.maxCount ?? Infinity;
+            }
+        };
     }
     // ── CarrierHolder — attach frame (carriage fork position) ─────────────────
     /**
@@ -151,21 +210,18 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
     attachPointFor(carrier) {
         const ro = this._realObject;
         const frame = ro?.getCarriageFrame?.();
-        if (frame) {
-            const carrierDepth = resolveCarrierDepth(carrier);
-            // fork blade 위 (top surface) 에 pallet pocket 끼우듯 얹힘. y = blade top + carrier/2.
-            // z = blade 중심 (forkLength 의 반쪽 위치 — pallet center 가 blade 중간에 위치).
-            const platformTopY = ro?.platformTopY ?? 0;
-            const bladeMidZ = ro?.bladeMidZ ?? 0;
-            return {
-                attach: frame,
-                localPosition: { x: 0, y: platformTopY + carrierDepth / 2, z: bladeMidZ }
-            };
-        }
-        const root = this._realObject?.object3d;
-        if (!root)
+        if (!frame)
             return null;
-        return { attach: root };
+        const carrierDepth = resolveCarrierDepth(carrier);
+        const carrierBaseY = ro?.carrierBaseY ?? 0;
+        const bladeMidZ = ro?.bladeMidZ ?? 0;
+        // carrier 외부 bottom = fork blade bottom. carryPolicy: 'follow-holder' —
+        // carrier 가 crane 의 *local axis (전방)* 정렬.
+        return {
+            attach: frame,
+            localPosition: { x: 0, y: carrierBaseY + carrierDepth / 2, z: bladeMidZ },
+            carryPolicy: 'follow-holder'
+        };
     }
     // ── Mover overrides ───────────────────────────────────────────────────────
     /**
@@ -186,18 +242,169 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
      * binding sets 'moving' in monitoring mode; override pick()/place() to
      * set it in full simulation environments.
      */
+    /**
+     * Crane.moveTo — **Crane 본체 (rail) 은 안 움직임**. *내부 carriage 의 rail-
+     * local X 위치 (carriagePosition) 만 lerp*. 실제 gantry / AS/RS crane 의
+     * 자연스러운 운동 패턴.
+     *
+     * target.center 의 world 좌표를 *crane 의 local frame (rail-aligned)* 로
+     * 변환 → rail-local X 추출 → carriagePosition setState.
+     *
+     * Crane.state.rotation = rail 방향. carriage 가 rail 위 X 만 이동.
+     */
+    async moveTo(target, options = {}) {
+        // target.center 는 *parent-local* 좌표 — child component (cell) 의 경우
+        // *rack-local*. board-absolute 변환 필요 (= toScene).
+        const tcLocal = target?.center;
+        if (!tcLocal || typeof tcLocal.x !== 'number' || typeof tcLocal.y !== 'number') {
+            return;
+        }
+        const tcAbs = typeof target.toScene === 'function'
+            ? target.toScene(tcLocal.x, tcLocal.y)
+            : tcLocal;
+        const tcx = tcAbs.x;
+        const tcy = tcAbs.y;
+        // Crane 도 자체 center 를 toScene 으로 (crane 이 다른 container 의 child 일 수도)
+        const W = this.state.width ?? 100;
+        const craneCenterLocal = this.center ?? { x: 0, y: 0 };
+        const craneCenterAbs = typeof this.toScene === 'function'
+            ? this.toScene(craneCenterLocal.x, craneCenterLocal.y)
+            : craneCenterLocal;
+        const ccx = craneCenterAbs.x;
+        const ccy = craneCenterAbs.y;
+        const rotation = this.state.rotation ?? 0;
+        const cos = Math.cos(rotation);
+        const sin = Math.sin(rotation);
+        const dx = tcx - ccx;
+        const dy = tcy - ccy;
+        const railLocalX = dx * cos + dy * sin;
+        const cw = this.state.carriageWidth ?? W * 0.1;
+        const minPos = cw / 2;
+        const maxPos = W - cw / 2;
+        const newCarriagePos = Math.max(minPos, Math.min(maxPos, railLocalX + W / 2));
+        // X + Y 동시 lerp — carriage 의 횡 (rail) + 종 (mast) 운동 동기.
+        //
+        // 진입 위치 (= fork blade bottom world Y):
+        //   pick (no holding):  cellBottom
+        //   place (holding):    cellBottom + liftH (들린 carrier 와 함께 진입)
+        const tween = { carriagePosition: newCarriagePos };
+        const targetBottomWorldY = resolveCarrierBottomY(target);
+        if (targetBottomWorldY !== null) {
+            const isHoldingCarrier = this.components?.some?.((c) => c?._transferSlotId === 'forks') ?? false;
+            const liftH = numOr(this.state.forkLift, 30);
+            const approachWorldY = targetBottomWorldY + (isHoldingCarrier ? liftH : 0);
+            const ro = this._realObject;
+            const currentForkLift = numOr(this.state.forkLiftRT, 0);
+            const solver = ro?.solveCarriageHeightForCarrierBaseWorldY;
+            if (typeof solver === 'function') {
+                tween.carriageHeight = solver.call(ro, approachWorldY, currentForkLift);
+            }
+            else {
+                tween.carriageHeight = approachWorldY;
+            }
+        }
+        const duration = options.duration ?? 1500;
+        this.setState({ status: 'moving' });
+        await this._tween(tween, duration);
+        this.setState({ status: 'idle' });
+    }
     async engage(target, kind, _options = {}) {
+        // carriageHeight 는 moveTo 안 X+Y 동시 lerp 에서 처리.
+        // engage 가 책임: fork extension → lift / drop → retract.
+        const forkLen = numOr(this.state.forkLength, 600);
+        // liftH — 사용자 설정 `forkLift` (= configured 진폭). 미설정 시 default 30mm.
+        // 시뮬 lerp 는 *forkLiftRT* (runtime current) state 에 적용 — `forkLift` 자체
+        // 는 *진폭 의미 보존* 위해 안 건드림.
+        const liftH = numOr(this.state.forkLift, 30);
+        // Fork side 결정 — target 이 crane 의 어느 *local Z 방향* (cross-rail, fork
+        // axis) 인지. things-scene 의 `getWorldPose` 로 양쪽 world pose 산출 후
+        // delta 를 crane local frame 으로 inverse-rotate → local Z 부호 = side.
+        // pick/place 동일하게 동작 (이전 코드는 carrier=cell.child 케이스에서
+        // rack-local vs world 좌표계 혼선으로 pick 시 방향 반대였음).
+        let side = +1;
+        try {
+            const cranePose = getWorldPose(this);
+            const targetPose = getWorldPose(target);
+            const dv = targetPose.position.clone().sub(cranePose.position);
+            dv.applyQuaternion(cranePose.rotation.clone().invert());
+            side = dv.z >= 0 ? +1 : -1;
+        }
+        catch {
+            // fallback — pose 계산 실패 시 +1 (rotation 무관, 의미적으로 안전한 default).
+        }
+        // Animation duration — fork extend/retract 1000ms, lift/lower 600ms.
+        // 이전 (500ms / 300ms) 보다 2배 — 시각 자연스러움 강화.
+        const D_EXT = 1000;
+        const D_LIFT = 600;
+        // fork extension target — target 의 local Z 와 _bladeMidZ 매칭. helper 가
+        // inverse-solve. mismatch 시 carrier 가 *fork tip 위치 (= local Z 미일치)*
+        // 로 jump → 텔레포트 결함. helper 가 정확 일치 보장.
+        let extTarget = side * forkLen;
+        try {
+            const cranePose = getWorldPose(this);
+            const targetPose = getWorldPose(target);
+            const dv = targetPose.position.clone().sub(cranePose.position);
+            dv.applyQuaternion(cranePose.rotation.clone().invert());
+            const localZ = dv.z;
+            const solver = this._realObject?.solveForkExtensionForLocalZ;
+            if (typeof solver === 'function') {
+                const ext = solver.call(this._realObject, localZ);
+                if (Number.isFinite(ext))
+                    extTarget = ext;
+            }
+        }
+        catch {
+            // fallback — 기존 side * forkLen.
+        }
         if (kind === 'pick') {
             this.setState({ status: 'loading' });
-            const carrierY = resolveCarrierCenterY(target);
-            if (carrierY !== null) {
-                this.setState({ carriageHeight: carrierY });
+            await this._tween({ forkExtension: extTarget }, D_EXT);
+            // Mid-engage reparent — fork 가 cell 안 도달. carrier 를 fork 위로 *즉시
+            // snap* (animated:false). Transfer 객체 통과 → monitor panel 추적.
+            const source = target.parent;
+            if (source) {
+                try {
+                    new Transfer({
+                        source,
+                        target: this,
+                        carrier: target,
+                        options: { animated: false }
+                    }).executeSync();
+                }
+                catch (e) {
+                    // Transfer 실패 — carrier 그대로. 후속 Mover.pick receive 가 처리.
+                }
             }
+            await this._tween({ forkLiftRT: liftH }, D_LIFT);
+            await this._tween({ forkExtension: 0 }, D_EXT);
         }
         else {
             this.setState({ status: 'unloading' });
+            // 1. fork extend (cell 위에서 carrier 자리 위로 진입). extTarget = inverse-
+            //    solved target.local.z 매칭 위치.
+            await this._tween({ forkExtension: extTarget }, D_EXT);
+            // 2. carrier lower — forkLiftRT liftH → 0. carrier 가 cell 바닥 안착.
+            await this._tween({ forkLiftRT: 0 }, D_LIFT);
+            // 3. dispatch — carrier world 위치 = cell 내 attach 위치, jump 없음. Transfer 추적.
+            const comps = this.components;
+            const carrier = comps?.find?.((c) => c?._transferSlotId === 'forks')
+                ?? comps?.find?.((c) => c?.state?.type !== 'storage-cell');
+            if (carrier) {
+                try {
+                    new Transfer({
+                        source: this,
+                        target: target,
+                        carrier,
+                        options: { animated: false }
+                    }).executeSync();
+                }
+                catch (e) {
+                    // dispatch 실패 — Mover.place 가 후속 처리.
+                }
+            }
+            // 4. fork retract — 빈 fork.
+            await this._tween({ forkExtension: 0 }, D_EXT);
         }
-        // In a full simulation: await carriage-motion tween here.
     }
     // ── Domain aliases ────────────────────────────────────────────────────────
     /** Fetch a carrier from a rack cell (semantically = pick). */
@@ -234,8 +441,13 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         const depth = num(state.depth, Math.max(width, height) * 4);
         const carriageHeight = clamp(num(state.carriageHeight, 0), 0, depth);
         const forkExtension = num(state.forkExtension, 0); // ± (rail 양쪽 rack)
-        const forkLift = num(state.forkLift, 0);
-        const cx = left + width / 2;
+        // forkLiftRT — *시뮬 runtime current 들림*. *configured 진폭* (state.forkLift)
+        // 와 분리. 시뮬 미진행 시 0 (carriage 가 mast 위 carriageHeight 만큼).
+        const forkLift = num(state.forkLiftRT, 0);
+        // carriagePosition: rail-local X (0 ~ width). default = rail center.
+        // 사용자 의도 — Crane 본체 (rail) 안 움직이고 carriage assembly 만 X 슬라이드.
+        const carriagePosition = clamp(num(state.carriagePosition, width / 2), 0, width);
+        const cx = left + carriagePosition; // masts/carriage/forks 의 중심 X
         const cy = top + height / 2;
         // 적재 여부 — forkLift > 0 (시뮬 중 들어올린 상태) 또는 state.loaded 명시.
         // monitoring 모드는 외부 데이터로 state.loaded 바인딩.
@@ -251,15 +463,26 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         const CARRIER = forkLift > 0 ? '#7d5530' : '#a08864';
         const CARRIER_LINE = '#3a2a18';
         ctx.save();
-        // 1. Rail — 위/아래 두 줄
-        const railW = Math.max(1.5, height * 0.03);
+        // 0. Rail footprint — 반투명 회색 fill + 외곽선. 사용자가 board 에서 crane 의
+        //    *rail 영역* 을 명확히 인식 + 편집 핸들 가능.
+        ctx.fillStyle = '#aab0b8';
+        ctx.globalAlpha = 0.15;
+        ctx.fillRect(left, top, width, height);
+        ctx.globalAlpha = 1;
+        ctx.strokeStyle = DARK;
+        ctx.lineWidth = 1;
+        ctx.strokeRect(left, top, width, height);
+        // 1. Rail — 하단 한 줄 (얇은 가이드). 톤 절제 — outer footprint 가 이미 영역 표시.
+        const railW = Math.max(1, height * 0.02);
         ctx.fillStyle = DARK;
-        ctx.fillRect(left, top, width, railW);
+        ctx.globalAlpha = 0.6;
         ctx.fillRect(left, top + height - railW, width, railW);
-        // 2. Twin masts — 두 orange 사각형. mast 길이가 *3D 의 mast height (depth)* 를
-        //    의미하므로, 그 위에 carriage 위치 indicator 를 매핑하면 1층/N층 인식 가능.
-        const mastW = Math.max(2.5, width * 0.07);
-        const mastSpacing = width * 0.75; // 넉넉히 — carrier 가 mast 잠식 안 하도록
+        ctx.globalAlpha = 1;
+        // 2. Twin masts — *carriageWidth 기반* (crane.width 와 분리). rail (= crane.width)
+        //    이 넓어져도 carriage assembly 는 *carriageWidth 만큼* 만.
+        const carriageW = num(state.carriageWidth, width * 0.1); // default rail 의 10%
+        const mastW = Math.max(2.5, carriageW * 0.15);
+        const mastSpacing = carriageW * 0.85;
         const mastY = top + railW;
         const mastH = height - railW * 2;
         const mastX1 = cx - mastSpacing / 2 - mastW / 2;
@@ -283,22 +506,21 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         ctx.fillStyle = '#5a3a00'; // 어두운 갈색 — orange mast 위에서 강한 대비
         ctx.fillRect(mastX1 - 2, indY, indWidth, indLen);
         ctx.fillRect(mastX2 - 2, indY, indWidth, indLen);
-        // 3. Carriage (= 적재 deck) — 팔레트 1200×800mm aspect 반영. *폭만* sizeMul 적용 (높이감),
-        //    길이 (Y) 고정. carrier / fork 모두 이 carriage 기준으로 derive.
-        const carriageW = (mastSpacing - mastW) * sizeMul;
+        // 3. Carriage deck — 팔레트 1200×800mm aspect 반영. *폭만* sizeMul 적용 (높이감),
+        //    길이 (Y) 고정. carrier / fork 모두 이 deck 기준으로 derive.
+        const deckW = (mastSpacing - mastW) * sizeMul;
         const carriageH = Math.min((mastSpacing - mastW) * 1.3, (height - railW * 2) * 0.55);
-        const carriageX = cx - carriageW / 2;
+        const carriageX = cx - deckW / 2;
         const carriageY = cy - carriageH / 2;
         ctx.fillStyle = CARRIAGE_C;
-        ctx.fillRect(carriageX, carriageY, carriageW, carriageH);
+        ctx.fillRect(carriageX, carriageY, deckW, carriageH);
         // 4. Fork — 좌우 균형:
         //    - 양쪽 모두 *작은 stub* 항상 표시 (crane 이 양쪽 rack 사이 있는 인상)
         //    - extension 부호 (+/-) 에 따라 active 쪽이 추가로 신축
         //    - 신축 길이 = |forkExtension| (실제 reach 만큼)
         const stubLen = Math.max(2, carriageH * 0.5);
-        // 포크 폭 — carriage 의 80% (carrier 90% 보다 약간 좁아 carrier 가 fork 양옆으로
-        // 살짝 overhang). carriage 가 sizeMul 적용된 폭이라 fork 도 자동 scale 반영.
-        const forkW = carriageW * 0.8;
+        // 포크 폭 — deck 의 80%.
+        const forkW = deckW * 0.8;
         const forkX = cx - forkW / 2;
         const extLen = Math.abs(forkExtension);
         const sign = forkExtension >= 0 ? 1 : -1;
@@ -322,26 +544,19 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         if (carrying) {
             // 팔레트 — 항상 carriage 의 90% (폭/길이 모두). carriage 가 sizeMul 적용된 폭이라
             // carrier 도 자동으로 sizeMul 반영. 길이는 carriage 길이 고정에 따라 고정.
-            const carrW = carriageW * 0.9;
+            const carrW = deckW * 0.9;
             const carrH = carriageH * 0.9;
-            let carrCenterY;
-            if (extLen > 0.5) {
-                // 포크의 *중간* 에 carrier 배치 — fork prong 이 pallet pocket 에 끼워진 자연스러운
-                // 위치 (현실 AS/RS 에서 pallet 이 fork 끝이 아닌 fork 길이 중간 부근에 안착).
-                const forkMid = (stubLen + extLen) / 2;
-                carrCenterY = sign > 0
-                    ? carriageY + carriageH + forkMid
-                    : carriageY - forkMid;
-            }
-            else {
-                carrCenterY = cy; // transit
-            }
+            // Carrier 2D 위치 — 3D _bladeMidZ 와 동일 공식 (sign * extLen).
+            //   extLen=0 → carriage 정중앙. extLen 증가 → cell 방향 으로 진출.
+            const offset = extLen;
+            const carrCenterY = sign > 0
+                ? carriageY + carriageH / 2 + offset
+                : carriageY + carriageH / 2 - offset;
             const carrX = cx - carrW / 2;
             const carrY = carrCenterY - carrH / 2;
             // 들린 상태 — drop shadow 로 *떠 있는* 인상 (forkLift > 0). offset 비율 = lift 강도.
             if (forkLift > 0) {
-                const forkLengthRef = num(state.forkLength, height * 0.4);
-                const liftMax = Math.max(forkLengthRef * 0.05, 20); // forkLift 정상 범위
+                const liftMax = Math.max(num(state.forkLift, 30), 20); // configured 진폭
                 const liftRatio = clamp(forkLift / liftMax, 0.3, 1); // 최소 30% 표시 (있다는 것만 보이게)
                 const shadowOff = Math.max(2, Math.min(carrW, carrH) * 0.14) * liftRatio;
                 ctx.fillStyle = 'rgba(0, 0, 0, 0.4)';
@@ -362,17 +577,88 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
     // ── Lifecycle — simulate() 자동 시작 ────────────────────────────────────
     added(parent) {
         super.added?.(parent);
+        // state ↔ visual single source of truth. state 미설정 시 _canonicalDefault
+        // 로 명시 초기화 — build / _tween / 외부 read 모두 동일 값.
+        const init = {};
+        for (const k of ['carriagePosition', 'carriageHeight', 'forkExtension', 'forkLiftRT']) {
+            if (typeof this.state[k] !== 'number') {
+                init[k] = this._canonicalDefault(k);
+            }
+        }
+        if (Object.keys(init).length > 0)
+            this.setState(init);
+        // state.simulate === true 명시 시만 자동 시작. mode 연동은 board view layer
+        // 책임 — 컴포넌트 자체는 simulate state 만 본다 (sorter/conveyor 등 다른
+        // 시뮬 컴포넌트와 동일 패턴).
+        if (this.state.simulate !== true)
+            return;
+        this._startAutoSimulate();
+    }
+    /**
+     * Actuator state 의 *canonical default*. state 미설정 시 모든 read 경로
+     * (build / _tween / 외부) 가 *동일 값* 보도록.
+     *
+     * single source 패턴 — visual fallback 과 state fallback 이 *분리* 되어
+     * 첫 _tween 시 start 가 visual current 와 어긋나는 jump 결함을 근본 차단.
+     */
+    _canonicalDefault(key) {
+        const state = this.state;
+        const W = numOr(state.width, 100);
+        const H = numOr(state.height, 100);
+        const D = numOr(state.depth, Math.max(W, H) * 4);
+        switch (key) {
+            case 'carriagePosition': return W / 2;
+            case 'carriageHeight': return D * 0.4;
+            case 'forkExtension':
+            case 'forkLiftRT':
+            case 'forkLift':
+                return 0;
+            default: return 0;
+        }
+    }
+    _startAutoSimulate() {
         if (this._simStarted)
             return;
         this._simStarted = true;
         // 초기 지연 800~2800ms 사이 random — 여러 crane 이 동기적으로 시작하지 않도록.
-        // added 에서 시작 → 2D/3D 모드 무관. buildRealObject 는 3D 진입 시만 호출돼 시점이
-        // 늦거나 누락될 수 있으므로 부적합.
         const initialDelay = 800 + Math.random() * 2000;
         setTimeout(() => {
+            if (this._simAbort || this.state.simulate !== true)
+                return;
             this.simulate().catch(e => console.error('[Crane] simulate', e));
         }, initialDelay);
     }
+    /**
+     * state.simulate 변경 시 자동 simulate 시작/중단. application 이 런타임 toggle
+     * 가능 (예: editor 에서 simulate off, view 에서 on).
+     */
+    onchange(after, before) {
+        super.onchange(after, before);
+        // carriage 관련 state 변경 시 2D render 명시 invalidate. things-scene 의
+        // setState → trigger change 가 render queue 에 자동 등록 못 하는 케이스 방어.
+        if ('carriagePosition' in after ||
+            'carriageWidth' in after ||
+            'carriageHeight' in after ||
+            'forkExtension' in after ||
+            'forkLift' in after ||
+            'forkLiftRT' in after) {
+            ;
+            this.invalidate?.();
+        }
+        if ('simulate' in after) {
+            if (after.simulate === true) {
+                // 명시 true → 자동 시작 (이미 시작 중이면 noop). mode gating 은
+                // frameClock (animate 의 simTime) 이 자동 처리 — modeler 면 simTime
+                // 안 흐름, _tween step 호출 안 됨.
+                this._simAbort = false;
+                this._simStarted = false;
+                this._startAutoSimulate();
+            }
+            else {
+                this._simAbort = true;
+            }
+        }
+    }
     // ── 3D ───────────────────────────────────────────────────────────────────
     buildRealObject() {
         return new Crane3D(this);
@@ -412,17 +698,14 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
      */
     _initRailRange() {
         this._railMin = this._railMax = NaN;
-        // 1순위: state.target refid 로 명시. 2순위: crane 의 parent 컴포넌트 (자연스러운
-        // "이 컨테이너 안에서만 움직여" 기본값).
-        const targetRefId = this.state.target;
+        // simulate cycle 의 random pickAndPlace range — crane 의 parent 컨테이너
+        // (= 보통 rack 또는 board) 의 bbox 를 기준으로. parent 가 top-level
+        // (root/model-layer) 이면 bbox 의미 없음 → skip.
         const root = this.root;
-        let target = targetRefId ? root?.findById?.(targetRefId) : null;
-        if (!target) {
-            const parent = this.parent;
-            // parent 가 root/model-layer 같은 top-level 이면 bbox 가 의미없음 → skip
-            if (parent && parent !== root && parent.state?.width > 0) {
-                target = parent;
-            }
+        const parent = this.parent;
+        let target = null;
+        if (parent && parent !== root && parent.state?.width > 0) {
+            target = parent;
         }
         if (!target)
             return;
@@ -499,17 +782,14 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         const H = numOr(this.state.height, 100);
         const D = numOr(this.state.depth, W * 4);
         const forkLen = numOr(this.state.forkLength, H * 0.6);
-        if (!Number.isFinite(this._railMin) || !Number.isFinite(this._railMax)) {
-            await new Promise(r => setTimeout(r, 800));
-            return;
-        }
-        const pickRail = () => this._railMin + Math.random() * Math.max(0, this._railMax - this._railMin);
-        const toLeftTop = (rail) => ({
-            left: this._railOriginX + rail * this._railCos - W / 2,
-            top: this._railOriginY + rail * this._railSin - H / 2
-        });
-        const source = toLeftTop(pickRail());
-        const dest = toLeftTop(pickRail());
+        const cw = numOr(this.state.carriageWidth, W * 0.1);
+        // carriagePosition 의 valid range — rail 안 [cw/2, W - cw/2].
+        // crane 본체 (rail) 는 안 움직임 — *carriage assembly 만* X 슬라이드.
+        const minPos = cw / 2;
+        const maxPos = Math.max(minPos, W - cw / 2);
+        const pickPos = () => minPos + Math.random() * (maxPos - minPos);
+        const sourcePos = pickPos();
+        const destPos = pickPos();
         const sourceCH = Math.random() * D * 0.75;
         const destCH = Math.random() * D * 0.75;
         const liftH = Math.max(20, D * 0.02);
@@ -518,21 +798,22 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         const sideB = Math.random() < 0.5 ? -1 : +1;
         // Tween duration 은 base 의 70~130% 사이 random — 여러 crane 이 같은 타이밍으로 안 보이도록.
         const jitter = (base) => base * (0.7 + Math.random() * 0.6);
-        // 이동: crane local X 방향 → canvas (left, top) 둘 다 동시 변경 (rotation 적용 시 diagonal)
-        await this._tween({ status: 'moving', left: source.left, top: source.top, carriageHeight: sourceCH }, jitter(1500));
+        // 이동: carriagePosition 만 변경 (crane.left/top 안 건드림).
+        await this._tween({ status: 'moving', carriagePosition: sourcePos, carriageHeight: sourceCH }, jitter(1500));
         await this._tween({ status: 'loading', forkExtension: sideA * forkLen }, jitter(700));
-        await this._tween({ forkLift: liftH }, jitter(400));
+        await this._tween({ forkLiftRT: liftH }, jitter(400));
         await this._tween({ forkExtension: 0 }, jitter(700));
-        await this._tween({ status: 'moving', left: dest.left, top: dest.top, carriageHeight: destCH }, jitter(1500));
+        await this._tween({ status: 'moving', carriagePosition: destPos, carriageHeight: destCH }, jitter(1500));
         await this._tween({ status: 'unloading', forkExtension: sideB * forkLen }, jitter(700));
-        await this._tween({ forkLift: 0 }, jitter(400));
+        await this._tween({ forkLiftRT: 0 }, jitter(400));
         await this._tween({ status: 'idle', forkExtension: 0 }, jitter(700));
         // 사이클 사이 짧은 idle (200~1000ms) — 자연스러운 phase 분산
         await new Promise(r => setTimeout(r, 200 + Math.random() * 800));
     }
     /**
-     * things-scene 의 `component.animate()` 로 한 구간 tween. step 콜백에서 setState 호출.
-     * frameClock.simTime 기반이라 scene pause / speed change / suppressAnimations 모두 자동 대응.
+     * frameClock 기반 tween — things-scene 의 표준 `Component.animate()` 사용.
+     * frameClock.simTime 진행 (view mode + scene 활성) 시에만 step 호출 → modeler
+     * 또는 paused 시 자동 정지. scene.simulationSpeed 도 자동 대응.
      */
     _tween(targets, duration) {
         const start = {};
@@ -540,7 +821,7 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
             if (k === 'status')
                 continue;
             const v = this.state[k];
-            start[k] = typeof v === 'number' && Number.isFinite(v) ? v : 0;
+            start[k] = typeof v === 'number' && Number.isFinite(v) ? v : this._canonicalDefault(k);
         }
         if (typeof targets.status === 'string') {
             this.setState({ status: targets.status });
@@ -558,10 +839,6 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
                 ease: 'inout',
                 delta: 'quad',
                 step: (dx) => {
-                    if (this._simAbort) {
-                        controller.stop?.();
-                        return finish();
-                    }
                     const update = {};
                     for (const k of Object.keys(start)) {
                         const tgt = targets[k];
@@ -587,15 +864,33 @@ function resolveCarrierDepth(c) {
         return eff;
     return numOr(c?.state?.depth, 0);
 }
-function resolveCarrierCenterY(c) {
-    const pos = c.state;
-    if (!pos)
+/**
+ * Target 의 *world bottom Y* — fork blade 가 위치해야 할 높이.
+ *
+ * `getWorldPose(c).position.y` 는 *center Y*. fork 는 carrier 의 *바닥* (pallet
+ * pocket 진입 면) 에 위치해야 함 → center 에서 depth/2 만큼 빼서 bottom.
+ *
+ * `effectiveDepth` 는 RealObject 가 자동 계산한 실제 3D Y 키. 미가용 시 state.
+ * depth fallback.
+ */
+function resolveCarrierBottomY(c) {
+    if (!c)
         return null;
-    // zPos is the 3D Y center of a Placeable component in things-scene
-    const zPos = numOr(pos.zPos, NaN);
-    if (!Number.isNaN(zPos))
-        return zPos;
-    return null;
+    try {
+        const pose = getWorldPose(c);
+        const centerY = pose?.position?.y;
+        if (typeof centerY !== 'number' || !Number.isFinite(centerY))
+            return null;
+        const ro = c._realObject;
+        const eff = ro?.effectiveDepth;
+        const depth = typeof eff === 'number' && Number.isFinite(eff)
+            ? eff
+            : numOr(c?.state?.depth, 0);
+        return centerY - depth / 2;
+    }
+    catch {
+        return null;
+    }
 }
 function numOr(v, dflt) {
     return typeof v === 'number' && Number.isFinite(v) ? v : dflt;