@operato/scene-storage 10.0.0-beta.44 → 10.0.0-beta.47

package/dist/crane.js

@@ -3,7 +3,8 @@ import { __decorate } from "tslib";
  * Copyright © HatioLab Inc. All rights reserved.
  */
 import { ContainerAbstract, ContainerCapacity, Transfer, getWorldPose, sceneComponent } from '@hatiolab/things-scene';
-import { CarrierHolder, Legendable, Mover, Placeable } from '@operato/scene-base';
+import { CarrierHolder, Legendable, Mover, Placeable, isSlottedHolder, findDispatcher, resolveTransferTarget } from '@operato/scene-base';
+import * as THREE from 'three';
 import { Crane3D } from './crane-3d.js';
 const BODY_LEGEND = {
     idle: '#888',
@@ -45,6 +46,12 @@ const NATURE = {
             label: 'simulate',
             name: 'simulate'
         },
+        {
+            type: 'string',
+            label: 'bound-holders',
+            name: 'boundHolders',
+            placeholder: 'SlottedHolder id (rack-1, rack-2, ...). 미명시 시 scene 전체 fallback.'
+        },
         {
             type: 'number',
             label: 'carriage-position',
@@ -69,6 +76,12 @@ const NATURE = {
             name: 'forkLength',
             placeholder: 'mm — fork prong 최대 신축 길이 (default 600)'
         },
+        {
+            type: 'number',
+            label: 'speed',
+            name: 'speed',
+            placeholder: 'scene units/sec — carriage 운동 속도 (default 250)'
+        },
         {
             type: 'number',
             label: 'fork-extension',
@@ -155,6 +168,12 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
      * 미설정 = state-driven) 에 carrier 가 *지하* 로 가는 결함.
      */
     get slots() {
+        // Phase Z PR-4: 사용자가 state.forkSlots 명시 시 그대로 활용. 미명시 시 단일
+        // 'forks' default (backward compat). multi-fork crane (twin / quad) 모델링
+        // 가능 — [{ id: 'fork-L', ... }, { id: 'fork-R', ... }] 형태로.
+        const custom = this.state?.forkSlots;
+        if (Array.isArray(custom) && custom.length > 0)
+            return custom;
         return [{ id: 'forks', maxCount: 1, localPosition: { x: 0, y: 0, z: 0 } }];
     }
     /**
@@ -272,12 +291,36 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
             : 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;
+        // Rail axis 결정 — *2D state.rotation 무관*. 실제 3D scene 안의 crane mesh 가
+        // *어떤 방향* 에 놓였든 *그 visual rail 방향* 따라 carriage 운동. crane.object3d
+        // 의 matrixWorld 에서 local X axis (= rail mesh 의 long axis = BoxGeometry(width,..)
+        // 의 X 방향) 의 world 방향 벡터 추출. 2D rotation→3D 매핑 컨벤션 (.rotation.y vs
+        // rotation.z, 부호) 영향 0 — 실 visual 방향 그대로 사용.
+        const ro = this._realObject;
+        const obj3d = ro?.object3d;
+        let railLocalX;
+        if (obj3d) {
+            obj3d.updateMatrixWorld(true);
+            const m = obj3d.matrixWorld.elements;
+            // 3D world frame: local X axis = (m[0], m[1], m[2]). 2D Y == 3D Z 매핑.
+            // 사용자 (dx, dy) = 2D scene 좌표 차이 = 3D (X, Z) 차이.
+            const axisX = m[0];
+            const axisZ = m[2];
+            const len = Math.hypot(axisX, axisZ);
+            if (len > 1e-9) {
+                const ux = axisX / len;
+                const uz = axisZ / len;
+                railLocalX = dx * ux + dy * uz;
+            }
+            else {
+                railLocalX = dx;
+            }
+        }
+        else {
+            railLocalX = dx;
+        }
         const cw = this.state.carriageWidth ?? W * 0.1;
         const minPos = cw / 2;
         const maxPos = W - cw / 2;
@@ -290,7 +333,9 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         const tween = { carriagePosition: newCarriagePos };
         const targetBottomWorldY = resolveCarrierBottomY(target);
         if (targetBottomWorldY !== null) {
-            const isHoldingCarrier = this.components?.some?.((c) => c?._transferSlotId === 'forks') ?? false;
+            // Phase Z PR-4: 임의 slot 의 carrier 검사 (multi-fork 대비). 단일 'forks'
+            // 가정 제거 — c._transferSlotId 가 set 됐으면 어떤 slot 이든 holding.
+            const isHoldingCarrier = this.components?.some?.((c) => c?._transferSlotId != null) ?? false;
             const liftH = numOr(this.state.forkLift, 30);
             const approachWorldY = targetBottomWorldY + (isHoldingCarrier ? liftH : 0);
             const ro = this._realObject;
@@ -302,8 +347,35 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
             else {
                 tween.carriageHeight = approachWorldY;
             }
+            // Mast 높이 한계 (= crane.state.depth) 초과 시 carriageHeight 가 *clamp* 되어
+            // fork 가 *상한까지만* 도달 → 더 높은 cell 은 *한 층 아래에서 포킹*. 데이터
+            // 결함 (rack 보다 짧은 crane) 을 silent 무시 안 하도록 명시 경고.
+            const mastMax = numOr(this.state.depth, Math.max(numOr(this.state.width, 200), numOr(this.state.height, 200)) * 4);
+            if (typeof tween.carriageHeight === 'number' && tween.carriageHeight > mastMax) {
+                console.warn(`[crane] carriageHeight=${tween.carriageHeight.toFixed(1)} > mast max=${mastMax.toFixed(1)} (state.depth)` +
+                    ` — fork 가 mast 상한에서 멈춰 target 한 층 아래에서 포킹 가능. crane.state.depth 증가 필요.`);
+            }
+        }
+        // Duration = *carriage 실 운동 거리 / speed*. 한 cycle 이 이동 거리 비례 시간.
+        //  - X 운동 거리 = |newCarriagePos - 현재 carriagePosition|
+        //  - Y 운동 거리 = |tween.carriageHeight - 현재 carriageHeight| (carrier 있는 경우)
+        //  - 두 운동은 *동시 lerp* → max 거리 만큼 시간 소요.
+        // options.duration 명시 시 그 값 우선. 미명시 시 state.speed 또는 default.
+        let duration;
+        if (typeof options.duration === 'number') {
+            duration = options.duration;
+        }
+        else {
+            const curCP = numOr(this.state.carriagePosition, this._canonicalDefault('carriagePosition'));
+            const curCH = numOr(this.state.carriageHeight, this._canonicalDefault('carriageHeight'));
+            const dxRail = Math.abs(tween.carriagePosition - curCP);
+            const dyMast = typeof tween.carriageHeight === 'number' ? Math.abs(tween.carriageHeight - curCH) : 0;
+            const dist = Math.max(dxRail, dyMast);
+            const speed = (typeof options.speed === 'number' ? options.speed : undefined) ??
+                (typeof this.state.speed === 'number' ? this.state.speed : undefined) ??
+                250; // DEFAULT_SPEED — scene units/sec (이전 500 → 사용자 체감 빠름 → 절반)
+            duration = speed > 0 ? Math.max(200, (dist / speed) * 1000) : 1500;
         }
-        const duration = options.duration ?? 1500;
         this.setState({ status: 'moving' });
         await this._tween(tween, duration);
         this.setState({ status: 'idle' });
@@ -386,8 +458,9 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
             // 2. carrier lower — forkLiftRT liftH → 0. carrier 가 cell 바닥 안착.
             await this._tween({ forkLiftRT: 0 }, D_LIFT);
             // 3. dispatch — carrier world 위치 = cell 내 attach 위치, jump 없음. Transfer 추적.
+            // Phase Z PR-4: 임의 slot 의 carrier 검사 (multi-fork 대비).
             const comps = this.components;
-            const carrier = comps?.find?.((c) => c?._transferSlotId === 'forks')
+            const carrier = comps?.find?.((c) => c?._transferSlotId != null)
                 ?? comps?.[0];
             if (carrier) {
                 try {
@@ -415,6 +488,321 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
     deposit(carrier, cell, options) {
         return this.place(carrier, cell, options);
     }
+    // ── Capability-based adjacency discovery ──────────────────────────────────
+    /**
+     * scene 의 모든 SlottedHolder 의 *slot 중에서 crane 의 작업 reach 안에 들어
+     * 오는 slot 들* 을 반환. 자동 simulate / WCS-less 시나리오의 enumeration entry.
+     *
+     * 매칭 알고리즘 (공간 reach 박스):
+     *  - crane.world center (axis-aligned 가정 — rotation 무시)
+     *  - 각 slot.anchor.world position 이
+     *      |x - cx| ≤ width/2 + reachXZ  AND  |z - cz| ≤ height/2 + reachXZ
+     *      AND  |y - cy| ≤ depth/2 + reachY
+     *    범위 안인가
+     *  - reachXZ = `crane.state.height` (fork forward 폭). reachY = `crane.state.depth`/2.
+     *
+     * RackGrid 의 *isEmpty aisle 통로 자리에 crane 이 배치* 된 케이스도 자동 cover —
+     * 통로 양옆 bay 의 slot anchor world 가 reach 안에 자연히 들어옴.
+     *
+     * @param opts.includeSelf  자기 자신을 holder 로 포함할지 (default false — crane
+     *                          은 SlottedHolder 아니지만 안전 차원).
+     */
+    /**
+     * Cycle 단위 cache 없음 — **매 cycle 협의** (capability negotiation 의 본질).
+     * crane.carriagePosition 변경 / rack 추가-이동 / 동적 forkLength 등 *runtime
+     * 변화 대응*. cost 는 *slotWorldPosition (anchor 0 생성) + canReach (cheap
+     * 좌표 비교)* — 매 cycle 호출 부담 작음.
+     *
+     * 이 field 는 *_oneCycle 사용을 위한 *호출 당 임시 holder grouping** —
+     * findAdjacentSlots 결과의 byHolder mapping. caller (_oneCycle) 가 사용 후
+     * 폐기.
+     */
+    _adjacentByHolder;
+    /** Cache 없음 — invalidate 호출도 no-op (호환 차원 keep). */
+    invalidateAdjacentSlots() {
+        this._adjacentByHolder = undefined;
+    }
+    /**
+     * 자동 detect 결과 cache — *boundHolders 미명시 시* 사용. crane / rack 위치가
+     * 정적이라 *1회 detect 후 영구 cache 안전*. 위치/회전/차원 변경 시 invalidate.
+     */
+    _autoBoundCache;
+    /** Auto bound cache invalidate — crane state 변경 시 호출. */
+    invalidateBoundCache() {
+        this._autoBoundCache = undefined;
+    }
+    /**
+     * Scene traverse + reach 검사 — 어느 slot 1개라도 reach 안인 holder 들 list.
+     * boundHolders 미명시 시 *runtime auto-detect* 결과. crane/rack 정적 위치
+     * 가정 — 1회 호출 후 cache.
+     */
+    detectBoundHolders() {
+        const ro = this._realObject;
+        const obj3d = ro?.object3d;
+        if (!obj3d)
+            return [];
+        const craneWorld = new THREE.Vector3();
+        obj3d.getWorldPosition(craneWorld);
+        const s = this.state;
+        const craneW = typeof s?.width === 'number' && Number.isFinite(s.width) ? s.width : 1000;
+        const craneH = typeof s?.height === 'number' && Number.isFinite(s.height) ? s.height : 600;
+        const forkLen = typeof s?.forkLength === 'number' && Number.isFinite(s.forkLength)
+            ? s.forkLength : craneH * 0.6;
+        const xHalf = craneW / 2;
+        const zHalf = forkLen;
+        const root = this.root;
+        if (!root)
+            return [];
+        const result = [];
+        const seen = new Set();
+        const visit = (component) => {
+            if (!component || seen.has(component))
+                return;
+            seen.add(component);
+            if (component !== this && isSlottedHolder(component)) {
+                const holder = component;
+                const slots = holder.slotIds?.();
+                if (slots && slots.length > 0) {
+                    const getPos = holder.slotWorldPosition?.bind(holder);
+                    // 랙 자동 인식 — *fork 가 닿는 Z 거리* 만 검사. X 는 무관 — 사용자 의도:
+                    // 크레인 옆 (포크가 닿는 거리) 에 있는 랙은 *X 방향 어디에 있든* 담당.
+                    // rail 의 실 X 길이 = 그 랙의 X 길이 (자동 정렬 모델링 가정).
+                    let matched = false;
+                    for (const slotId of slots) {
+                        let pos;
+                        if (getPos) {
+                            pos = getPos(slotId);
+                        }
+                        else {
+                            const anchor = holder.getSlotAttachObject3d(slotId);
+                            if (anchor) {
+                                const w = new THREE.Vector3();
+                                anchor.getWorldPosition(w);
+                                pos = { x: w.x, y: w.y, z: w.z };
+                            }
+                        }
+                        if (!pos)
+                            continue;
+                        if (Math.abs(pos.z - craneWorld.z) <= zHalf) {
+                            matched = true;
+                            break;
+                        }
+                    }
+                    if (matched)
+                        result.push(holder);
+                }
+            }
+            const children = component.components;
+            if (Array.isArray(children))
+                for (const c of children)
+                    visit(c);
+        };
+        visit(root);
+        return result;
+    }
+    /**
+     * Bound holder instance resolve.
+     *  1. boundHolders state 명시 → 그 id list resolve (explicit binding)
+     *  2. 미명시 → detectBoundHolders() 1회 + auto-cache (implicit binding,
+     *     crane / rack 정적 위치 가정)
+     *
+     * 둘 다 *binding scope* — findAdjacentSlots 가 그 list 만 traverse.
+     */
+    boundHolderInstances() {
+        const raw = this.state?.boundHolders;
+        let ids = [];
+        if (typeof raw === 'string') {
+            ids = raw.split(',').map(s => s.trim()).filter(s => s.length > 0);
+        }
+        else if (Array.isArray(raw)) {
+            ids = raw.filter((x) => typeof x === 'string' && x.length > 0);
+        }
+        if (ids.length > 0) {
+            // 명시 binding — explicit list resolve
+            const root = this.root;
+            if (!root)
+                return [];
+            const result = [];
+            for (const id of ids) {
+                const c = typeof root.findById === 'function' ? root.findById(id) : undefined;
+                if (c && isSlottedHolder(c))
+                    result.push(c);
+            }
+            return result;
+        }
+        // 미명시 — auto-detect cache
+        if (this._autoBoundCache === undefined) {
+            this._autoBoundCache = this.detectBoundHolders();
+        }
+        return this._autoBoundCache;
+    }
+    findAdjacentSlots(opts = {}) {
+        const ro = this._realObject;
+        const obj3d = ro?.object3d;
+        if (!obj3d)
+            return [];
+        // crane 은 고정 rail 따라 움직임 (회전 없음) — axis-aligned 박스 비교.
+        const craneWorld = new THREE.Vector3();
+        obj3d.getWorldPosition(craneWorld);
+        const s = this.state;
+        const craneW = typeof s?.width === 'number' && Number.isFinite(s.width) ? s.width : 1000;
+        const craneH = typeof s?.height === 'number' && Number.isFinite(s.height) ? s.height : 600;
+        const forkLen = typeof s?.forkLength === 'number' && Number.isFinite(s.forkLength)
+            ? s.forkLength : craneH * 0.6;
+        // X reach 정책:
+        //  - bound holder 명시/auto-detect 시 → *X 무관*. bound 자체가 scope 정의 —
+        //    bound rack 의 *X 영역 전체* 가 rail 의 실 X 영역. carriage 가 그 X 안
+        //    의 모든 bay 까지 자동 도달.
+        //  - 미bound 시 → state.width 기반 axis-aligned (fallback).
+        const boundCandidates = this.boundHolderInstances();
+        // slotId format = "{col-or-bay}-{row}-{shelf-or-level}" (양쪽 holder 동일).
+        // 매칭 단위 = (col, row) pair = *last '-' 앞 부분*. row 별로 Z 좌표 다르고
+        // crane.fork 의 reach 가 row 마다 도달 여부 다름 → *(col, row) 단위 정밀
+        // 매칭*. 통과한 (col, row) 의 *모든 shelves slot* 만 adjacent.
+        const bayKeyOf = (slotId) => {
+            const i = slotId.lastIndexOf('-');
+            return i > 0 ? slotId.substring(0, i) : slotId;
+        };
+        // Reach 박스 — *crane mesh 의 실 visual 방향* 따라 검사 (2D state.rotation 무관).
+        //  rail axis  (X) = crane.width / 2 — carriage 도달 범위.
+        //  perpendicular (Z) = forkLength    — fork tip extend.
+        // matrixWorld 의 local X axis vector 로 projection — Crane.moveTo 와 동일 식.
+        const xHalf = craneW / 2;
+        const zHalf = forkLen;
+        obj3d.updateMatrixWorld(true);
+        const _mc = obj3d.matrixWorld.elements;
+        const _axisX = _mc[0], _axisZ = _mc[2];
+        const _len = Math.hypot(_axisX, _axisZ);
+        const ux = _len > 1e-9 ? _axisX / _len : 1;
+        const uz = _len > 1e-9 ? _axisZ / _len : 0;
+        // rail-perpendicular axis (= fork 방향) = rail axis 90° rotated (XZ 평면).
+        const px = -uz;
+        const pz = ux;
+        const root = this.root;
+        if (!root)
+            return [];
+        const result = [];
+        const byHolder = new Map();
+        // *binding scope* — boundHolders 명시 시 그 holder 만 traverse (broad scan 0).
+        // 미명시 시 scene 전체 traverse fallback (BC, 기존 모델 호환).
+        const bound = this.boundHolderInstances();
+        const candidates = bound.length > 0 ? bound : [];
+        const visit = (component) => {
+            if (!component)
+                return;
+            if ((opts.includeSelf || component !== this) && isSlottedHolder(component)) {
+                const holder = component;
+                const ids = holder.slotIds?.();
+                if (ids && ids.length > 0) {
+                    // col 별: 모든 row 의 *대표 (shelf=0) slot* 추출 + col 안 모든 id 목록.
+                    // bay 매칭 시 *어느 row 의 대표 anchor 라도 reach 안* 이면 그 col 전체
+                    // 매칭 (row 별 z 가 달라도 *crane 의 fork 가 ±Z extend 로 모두 도달*).
+                    const repsByBay = new Map();
+                    const allByBay = new Map();
+                    for (const id of ids) {
+                        const bay = bayKeyOf(id);
+                        const lastIdx = id.lastIndexOf('-');
+                        const lastSeg = lastIdx >= 0 ? id.substring(lastIdx + 1) : id;
+                        let allList = allByBay.get(bay);
+                        if (!allList) {
+                            allList = [];
+                            allByBay.set(bay, allList);
+                        }
+                        allList.push(id);
+                        // shelf=0 (또는 level=0) 인 것만 대표
+                        if (lastSeg === '0') {
+                            let reps = repsByBay.get(bay);
+                            if (!reps) {
+                                reps = [];
+                                repsByBay.set(bay, reps);
+                            }
+                            reps.push(id);
+                        }
+                    }
+                    // bay 가 *대표 없음* (shelf=0 미존재) — fallback: 첫 id 사용
+                    for (const [bay, allList] of allByBay) {
+                        if (!repsByBay.has(bay))
+                            repsByBay.set(bay, [allList[0]]);
+                    }
+                    const adjSet = new Set();
+                    // *holder.slotWorldPosition* 지원 시 *anchor 생성 0* — match 전 단계의
+                    // 직접 좌표 계산 path. 미지원 holder 는 fallback 으로 getSlotAttachObject3d.
+                    const getPos = holder.slotWorldPosition?.bind(holder);
+                    // X 매칭 정책:
+                    //  - bound holder 존재 시: *X 무관* (bound 자체가 reach scope — rail 의
+                    //    실 X 영역 = bound rack 의 X 영역. carriage 가 그 전체 X 까지 도달).
+                    //    Z (fork) 만 검사 — fork tip 도달 여부.
+                    //  - 미bound 시: state.width 기반 axis-aligned 박스 (fallback).
+                    const useBoundScope = boundCandidates.length > 0;
+                    for (const [bay, reps] of repsByBay) {
+                        let matched = false;
+                        let matchedX = 0, matchedY = 0, matchedZ = 0;
+                        for (const repId of reps) {
+                            let pos;
+                            if (getPos) {
+                                pos = getPos(repId);
+                            }
+                            else {
+                                const anchor = holder.getSlotAttachObject3d(repId);
+                                if (anchor) {
+                                    const w = new THREE.Vector3();
+                                    anchor.getWorldPosition(w);
+                                    pos = { x: w.x, y: w.y, z: w.z };
+                                }
+                            }
+                            if (!pos)
+                                continue;
+                            // *visual rail 의 실제 world 방향* 따라 projection — 2D rotation 매핑 무관.
+                            // rail-local X = (pos - crane) · rail axis. rail-local Z = (pos - crane) · perp axis.
+                            const ddx = pos.x - craneWorld.x;
+                            const ddz = pos.z - craneWorld.z;
+                            const railLocal = ddx * ux + ddz * uz;
+                            const perpLocal = ddx * px + ddz * pz;
+                            const xOk = Math.abs(railLocal) <= xHalf;
+                            const zOk = Math.abs(perpLocal) <= zHalf;
+                            if (xOk && zOk) {
+                                matched = true;
+                                matchedX = pos.x;
+                                matchedY = pos.y;
+                                matchedZ = pos.z;
+                                break;
+                            }
+                        }
+                        if (matched) {
+                            const all = allByBay.get(bay) ?? [];
+                            const sharedWorld = new THREE.Vector3(matchedX, matchedY, matchedZ);
+                            // result 의 anchor field 는 *lazy*. 사용처가 *실제 attach 필요* 시
+                            // holder.getSlotAttachObject3d(slotId) 별도 호출 (그때 lazy 생성).
+                            // match 검사 자체에선 anchor 0 생성.
+                            for (const id of all) {
+                                adjSet.add(id);
+                                result.push({ holder, slotId: id, anchor: undefined, world: sharedWorld });
+                            }
+                        }
+                    }
+                    if (adjSet.size > 0)
+                        byHolder.set(holder, adjSet);
+                }
+            }
+            const children = component.components;
+            if (Array.isArray(children)) {
+                for (const c of children)
+                    visit(c);
+            }
+        };
+        // binding scope 우선 — bound 시 그 list 만 visit (broad scan 0). 미명시
+        // 시 scene root 부터 fallback traverse.
+        if (candidates.length > 0) {
+            for (const c of candidates)
+                visit(c);
+        }
+        else {
+            visit(root);
+        }
+        // 매 cycle 협의 — cache 없음. _oneCycle 가 *바로 *byHolder 사용 후 폐기*.
+        this._adjacentByHolder = byHolder;
+        return result;
+    }
     // ── 2D rendering ─────────────────────────────────────────────────────────
     /**
      * 2D top-down 표현 — 크레인으로 명확히 인식되도록 핵심 부품 그림:
@@ -587,11 +975,13 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         }
         if (Object.keys(init).length > 0)
             this.setState(init);
-        // state.simulate === true 명시 시만 자동 시작. mode 연동은 board view layer
-        // 책임 — 컴포넌트 자체는 simulate state 만 본다 (sorter/conveyor 등 다른
-        // 시뮬 컴포넌트와 동일 패턴).
+        // state.simulate === true + *view mode* 모두 만족 시만 자동 시작. modeler
+        // 모드에서 simulate 진행 시 *_oneCycle 의 obtainCarrier 가 RackGrid 자식 추가
+        // + state.data 변경* — 모델 영구 변형 위험. mode 검사로 차단.
         if (this.state.simulate !== true)
             return;
+        if (!this.app?.isViewMode)
+            return;
         this._startAutoSimulate();
     }
     /**
@@ -622,6 +1012,9 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         this._simStarted = true;
         // 초기 지연 800~2800ms 사이 random — 여러 crane 이 동기적으로 시작하지 않도록.
         const initialDelay = 800 + Math.random() * 2000;
+        // prefetch 제거 — 너무 일찍 (rack 의 _realObject 미빌드) 호출 시 0 매칭이
+        // cache 됐던 회귀. 0 결과 cache 안 함으로 fix됐지만, prefetch 자체도 불필요
+        // (_oneCycle 첫 호출에 자동 cache).
         setTimeout(() => {
             if (this._simAbort || this.state.simulate !== true)
                 return;
@@ -645,14 +1038,30 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
             ;
             this.invalidate?.();
         }
+        // crane 또는 rack 의 위치/회전/차원 변경 시 adjacent slot cache + bound
+        // holder cache 둘 다 invalidate. boundHolders 명시 변경 시도 bound cache
+        // 무관 (명시 우선) — but invalidate 안전.
+        if ('left' in after ||
+            'top' in after ||
+            'rotation' in after ||
+            'width' in after ||
+            'height' in after ||
+            'depth' in after ||
+            'forkLength' in after ||
+            'boundHolders' in after) {
+            this.invalidateAdjacentSlots();
+            this.invalidateBoundCache();
+        }
         if ('simulate' in after) {
             if (after.simulate === true) {
-                // 명시 true → 자동 시작 (이미 시작 중이면 noop). mode gating 은
-                // frameClock (animate 의 simTime) 이 자동 처리 — modeler 면 simTime
-                // 안 흐름, _tween step 호출 안 됨.
+                // simulate=true 명시 — *view mode 일 때만 자동 시작*. modeler 모드 시
+                // 시작 시 _oneCycle 의 obtainCarrier 가 RackGrid 자식/state.data 변형
+                // 위험. _oneCycle 도 매번 isViewMode 재검사 (mode 전환 대응).
                 this._simAbort = false;
                 this._simStarted = false;
-                this._startAutoSimulate();
+                if (this.app?.isViewMode) {
+                    this._startAutoSimulate();
+                }
             }
             else {
                 this._simAbort = true;
@@ -676,7 +1085,16 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
     _railMin = NaN; // local-X 축 rail offset min
     _railMax = NaN; // local-X 축 rail offset max
     _targetSide = 1; // +Z (fork +Z 로 뻗어야 하나) / -Z
-    /** Continuous random pick → transport → place cycles. Visual smoke test. */
+    /**
+     * Main loop — 통합 처리.
+     *
+     *   1. dispatcher 의 명시 작업 take → execute (priority 큰 작업 우선)
+     *   2. dispatcher 작업 없음 + state.simulate=true → 기존 random fallback (_oneCycle)
+     *   3. 둘 다 없음 → longer idle (dispatcher 작업 enqueue 대기)
+     *
+     * Phase Z 통합 — 사용자 application 의 `holder.putaway / picking` 호출이 즉시 자연
+     * 처리. simulate=true 시 큐 비면 random visual smoke 도 유지. 작업 사이 자연 idle.
+     */
     async simulate() {
         if (this._simRunning)
             return;
@@ -685,13 +1103,85 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         try {
             this._initRailRange();
             while (!this._simAbort) {
-                await this._oneCycle();
+                // Modeling 모드 진입 시 즉시 중단
+                if (!this.app?.isViewMode) {
+                    this._simAbort = true;
+                    break;
+                }
+                // 1. Dispatcher 의 명시 작업 우선 take
+                const dispatcher = findDispatcher(this);
+                const ticket = dispatcher?.takeNextFor(this) ?? null;
+                if (ticket) {
+                    await this._executeTicket(ticket, dispatcher);
+                    // 작업 사이 짧은 idle — 명시 작업 중심 처리 → 다음 작업 빠르게
+                    await new Promise(r => setTimeout(r, 200 + Math.random() * 600));
+                    continue;
+                }
+                // 2. Dispatcher 작업 없음 — state.simulate 켜져 있으면 random fallback
+                if (this.state.simulate === true) {
+                    await this._oneCycle();
+                    continue;
+                }
+                // 3. simulate OFF + 큐 비어있음 — 작업 들어오기 기다림. 긴 idle.
+                await new Promise(r => setTimeout(r, 500 + Math.random() * 2500));
             }
         }
         finally {
             this._simRunning = false;
         }
     }
+    /**
+     * Dispatcher 가 할당한 ticket 처리. lifecycle:
+     *   assigned (이미 takeNextFor 가 set) → in_progress → completed / failed
+     *
+     * 흐름:
+     *   1. request.from / to 를 resolve (string id → SlotTarget, SlotTarget 그대로 등)
+     *   2. carrier obtain — request.carrier 명시 시 그것, 미명시 시 from.holder.obtainCarrier
+     *   3. pickAndPlace(carrier, dest)
+     *   4. ticket status notify
+     *
+     * 실패 처리:
+     *   - target resolve 실패 → failed (resolve-target)
+     *   - carrier obtain 실패 → failed (no-carrier)
+     *   - pickAndPlace throw → failed (그 error)
+     */
+    async _executeTicket(ticket, dispatcher) {
+        const req = ticket.request;
+        try {
+            dispatcher.notifyInProgress?.(ticket) ?? ticket._setStatus('in_progress');
+            // resolve source / dest
+            const source = resolveTransferTarget(req.from, dispatcher);
+            const dest = resolveTransferTarget(req.to, dispatcher);
+            if (!source || !dest) {
+                const err = new Error('resolve-target');
+                dispatcher.notifyFailed?.(ticket, err) ?? ticket._setStatus('failed', { error: err });
+                return;
+            }
+            // carrier obtain — 명시 carrier 우선
+            let carrier = req.carrier ?? null;
+            if (!carrier) {
+                // source 가 SlotTarget — holder.obtainCarrier(slotId)
+                const holder = source.holder;
+                const slotId = source.slotId;
+                if (holder && slotId) {
+                    carrier = holder.obtainCarrier(slotId) ?? null;
+                }
+            }
+            if (!carrier) {
+                const err = new Error('no-carrier');
+                dispatcher.notifyFailed?.(ticket, err) ?? ticket._setStatus('failed', { error: err });
+                return;
+            }
+            // pickAndPlace
+            await this.pickAndPlace(carrier, dest);
+            // 성공
+            dispatcher.notifyCompleted?.(ticket) ?? ticket._setStatus('completed');
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            dispatcher.notifyFailed?.(ticket, err) ?? ticket._setStatus('failed', { error: err });
+        }
+    }
     /**
      * state.target bbox 를 crane 의 *로컬 X 축* 으로 projection 해서 rail range 1회 계산.
      * Rotation 적용된 crane 의 local X (= rail) 방향으로 움직이도록 cos/sin 캐시.
@@ -777,38 +1267,78 @@ let Crane = class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable
         this.stopSimulate();
         super.dispose?.();
     }
+    /**
+     * 1 cycle = *capability 기반 random transfer*.
+     *
+     *   1. findAdjacentSlots()        — scene 의 인접 SlottedHolder 의 slot 들
+     *   2. occupied / empty 분리       — hasCarrierAt / canReceiveAt
+     *   3. random source / dest 선택   — 같은 slot 자가 transfer 회피
+     *   4. obtainCarrier + pickAndPlace — Mover.pickAndPlace 가 pick + place 진행
+     *
+     * 인접 slot / occupied / empty 어느 하나라도 비어있으면 짧은 delay 후 next.
+     * 진짜 carrier 가 fork 위 visible 로 이동 — 시각 simulate 가 *동시에 *진짜
+     * 데이타 전환* 도 수행 (Plan A: 데이타 → 실물 → 데이타 atomic 전환).
+     */
     async _oneCycle() {
-        const W = numOr(this.state.width, 100);
-        const H = numOr(this.state.height, 100);
-        const D = numOr(this.state.depth, W * 4);
-        const forkLen = numOr(this.state.forkLength, H * 0.6);
-        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);
-        // 양쪽 rack 모두 서비스 — source/dest 각각 ±Z random (cycle 별 다름).
-        const sideA = Math.random() < 0.5 ? -1 : +1;
-        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);
-        // 이동: 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({ forkLiftRT: liftH }, jitter(400));
-        await this._tween({ forkExtension: 0 }, jitter(700));
-        await this._tween({ status: 'moving', carriagePosition: destPos, carriageHeight: destCH }, jitter(1500));
-        await this._tween({ status: 'unloading', forkExtension: sideB * forkLen }, jitter(700));
-        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));
+        // *Modeling 모드 진입 시 즉시 정지* — runtime 에서 mode 전환 (view → modeler)
+        // 대응. obtainCarrier / pickAndPlace 가 modeler 에서 발동하면 *RackGrid 자식
+        // 추가 + state.data 변경* = 모델 영구 변형. 매 cycle 검사 안전.
+        if (!this.app?.isViewMode) {
+            this._simAbort = true;
+            return;
+        }
+        this.findAdjacentSlots(); // cache 채우기 (already-cached 면 no-op)
+        const byHolder = this._adjacentByHolder;
+        if (!byHolder || byHolder.size === 0) {
+            await new Promise(r => setTimeout(r, 800 + Math.random() * 800));
+            return;
+        }
+        // holder 단위로 *occupiedSlotIds / emptySlotIds* 한 번에 조회 + adjacent set
+        // 와 교집합. holder 내부 sweep (records + child) 이라 *slot.length × records.
+        // length* iteration 없이 *records + children* 1 회 sweep.
+        // holder.occupiedSlotIds / emptySlotIds 에 *adjacent set 멤버 predicate* 전달
+        // — holder 가 sweep 중 즉시 reject. crane 측은 *holder 결과 그대로 사용*.
+        const occupied = [];
+        const empty = [];
+        for (const [holder, adjSet] of byHolder) {
+            const inAdj = (id) => adjSet.has(id);
+            for (const id of holder.occupiedSlotIds(inAdj))
+                occupied.push({ holder, slotId: id });
+            for (const id of holder.emptySlotIds(inAdj))
+                empty.push({ holder, slotId: id });
+        }
+        if (occupied.length === 0 || empty.length === 0) {
+            await new Promise(r => setTimeout(r, 500 + Math.random() * 800));
+            return;
+        }
+        const source = occupied[Math.floor(Math.random() * occupied.length)];
+        // dest 선택 — source 와 같은 (holder, slotId) 회피. attempts 제한.
+        let dest = empty[Math.floor(Math.random() * empty.length)];
+        let attempts = 0;
+        while (dest.holder === source.holder && dest.slotId === source.slotId && attempts < 10) {
+            dest = empty[Math.floor(Math.random() * empty.length)];
+            attempts++;
+        }
+        if (dest.holder === source.holder && dest.slotId === source.slotId) {
+            await new Promise(r => setTimeout(r, 500));
+            return;
+        }
+        try {
+            const carrier = source.holder.obtainCarrier(source.slotId);
+            if (!carrier) {
+                await new Promise(r => setTimeout(r, 400));
+                return;
+            }
+            const destTarget = dest.holder.slotTargetAt(dest.slotId);
+            await this.pickAndPlace(carrier, destTarget);
+        }
+        catch (e) {
+            // 한 cycle 실패해도 simulate 루프는 계속. 다음 cycle 에서 다른 source/dest 시도.
+            // (Mover.pickAndPlace 내부 rollback 이 carrier 복귀 시도함.)
+        }
+        // 사이클 사이 idle — 여러 crane 의 phase 자연 분산 (= 동시 동기화 회귀 차단).
+        // 범위 확장 (500~3500ms) — duration 거리 비례와 결합되어 cycle 총 시간 다양.
+        await new Promise(r => setTimeout(r, 500 + Math.random() * 3000));
     }
     /**
      * frameClock 기반 tween — things-scene 의 표준 `Component.animate()` 사용.