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

package/src/crane.ts

@@ -8,16 +8,34 @@ import {
   Legendable,
   Mover,
   Placeable,
+  isSlottedHolder,
+  findDispatcher,
+  resolveTransferTarget,
   type AttachFrame,
   type Alignment,
+  type Dispatcher,
   type Heights,
   type LegendBinding,
   type MoveOptions,
-  type PlacementArchetype
+  type PlacementArchetype,
+  type SlottedHolder,
+  type TransferTicket
 } from '@operato/scene-base'
+import * as THREE from 'three'
 
 import { Crane3D } from './crane-3d.js'
 
+/**
+ * AdjacentSlot — crane 의 작업 reach 영역 안에 있는 slot 의 정보. simulate /
+ * 자동 transfer 의 source/dest 후보.
+ */
+export interface AdjacentSlot {
+  holder: SlottedHolder & { state?: any }
+  slotId: string
+  anchor: THREE.Object3D
+  world: THREE.Vector3
+}
+
 /**
  * Crane status — the operating state of a stacker crane.
  *
@@ -70,13 +88,25 @@ export interface CraneState extends State {
   forkLiftRT?: number
 
   /**
-   * 자동 random simulate (visual smoke test) 시작 여부.
-   * - `undefined` 또는 `false` (default): 자동 시작 안 함. application 이 crane.
-   *   pickAndPlace 등 직접 제어 시 사용.
-   * - `true`: added() 시 자동 시작.
+   * 자동 random simulate 시작 여부. capability 기반 — crane.findAdjacentSlots()
+   * 으로 인접 SlottedHolder 발견 후 random source/dest transfer.
+   *  - `undefined` 또는 `false` (default): 자동 시작 안 함. application 이 crane.
+   *    pickAndPlace 등 직접 제어 시 사용.
+   *  - `true`: added() 시 자동 시작 + state runtime toggle 가능.
    */
   simulate?: boolean
 
+  /**
+   * 1:N binding — 이 crane 이 *작업 대상으로 인지할 holder id 들*. 모델링 시
+   * 사용자가 명시. 명시 시 *findAdjacentSlots 가 그 list 의 holder 만 traverse*
+   * → broad scene scan 회피. 미명시 시 *scene 전체 SlottedHolder fallback*
+   * (BC, 기존 모델 호환).
+   *
+   * 입력 형식 — comma-separated id string ("rack-1, rack-2") 또는 array.
+   * editor 의 *id-list-input* widget 부재 시 string 으로.
+   */
+  boundHolders?: string | string[]
+
   /**
    * Carriage 의 rail-local X 위치 (0 ~ crane.width). Crane.moveTo / simulate 가
    * lerp. crane 본체 (rail) 는 안 움직임 — carriage assembly (masts + carriage +
@@ -90,6 +120,16 @@ export interface CraneState extends State {
    */
   carriageWidth?: number
 
+  /**
+   * Carriage 운동 속도 (scene units / sec). 각 crane 별로 다르게 설정 가능 — 같은
+   * 거리도 crane 마다 다른 시간. 미명시 시 default 250 u/s.
+   *
+   * Crane.moveTo 가 *carriage 의 X 및 Y 운동 거리* / speed 로 duration 계산 → 한 칸
+   * 이동 vs rail 끝~끝 이동 의 시간 자연 차이. 여러 crane 의 cycle 시간 분산 → 동시
+   * 동기화 회귀 차단.
+   */
+  speed?: number
+
   // ── 3D 재질 ──
   material3d?: Material3D
 }
@@ -136,6 +176,12 @@ const NATURE: ComponentNature = {
       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',
@@ -160,6 +206,12 @@ const NATURE: ComponentNature = {
       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',
@@ -258,6 +310,11 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
    * 미설정 = state-driven) 에 carrier 가 *지하* 로 가는 결함.
    */
   get slots(): SlotDef[] {
+    // 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 as any)?.forkSlots
+    if (Array.isArray(custom) && custom.length > 0) return custom as SlotDef[]
     return [{ id: 'forks', maxCount: 1, localPosition: { x: 0, y: 0, z: 0 } }]
   }
 
@@ -381,13 +438,36 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
       : craneCenterLocal
     const ccx = craneCenterAbs.x
     const ccy = craneCenterAbs.y
-    const rotation = (this.state.rotation as number) ?? 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: any = this._realObject
+    const obj3d: THREE.Object3D | undefined = ro?.object3d
+    let railLocalX: number
+    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 as number) ?? W * 0.1
     const minPos = cw / 2
@@ -402,8 +482,10 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     const tween: Record<string, number> = { carriagePosition: newCarriagePos }
     const targetBottomWorldY = resolveCarrierBottomY(target)
     if (targetBottomWorldY !== null) {
+      // Phase Z PR-4: 임의 slot 의 carrier 검사 (multi-fork 대비). 단일 'forks'
+      // 가정 제거 — c._transferSlotId 가 set 됐으면 어떤 slot 이든 holding.
       const isHoldingCarrier = ((this as any).components as any[] | undefined)?.some?.(
-        (c: any) => c?._transferSlotId === 'forks'
+        (c: any) => c?._transferSlotId != null
       ) ?? false
       const liftH = numOr((this.state as any).forkLift, 30)
       const approachWorldY = targetBottomWorldY + (isHoldingCarrier ? liftH : 0)
@@ -416,9 +498,38 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
       } else {
         tween.carriageHeight = approachWorldY
       }
+      // Mast 높이 한계 (= crane.state.depth) 초과 시 carriageHeight 가 *clamp* 되어
+      // fork 가 *상한까지만* 도달 → 더 높은 cell 은 *한 층 아래에서 포킹*. 데이터
+      // 결함 (rack 보다 짧은 crane) 을 silent 무시 안 하도록 명시 경고.
+      const mastMax = numOr((this.state as any).depth, Math.max(numOr((this.state as any).width, 200), numOr((this.state as any).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 증가 필요.`
+        )
+      }
     }
 
-    const duration = (options.duration as number) ?? 1500
+    // Duration = *carriage 실 운동 거리 / speed*. 한 cycle 이 이동 거리 비례 시간.
+    //  - X 운동 거리 = |newCarriagePos - 현재 carriagePosition|
+    //  - Y 운동 거리 = |tween.carriageHeight - 현재 carriageHeight| (carrier 있는 경우)
+    //  - 두 운동은 *동시 lerp* → max 거리 만큼 시간 소요.
+    // options.duration 명시 시 그 값 우선. 미명시 시 state.speed 또는 default.
+    let duration: number
+    if (typeof options.duration === 'number') {
+      duration = options.duration
+    } else {
+      const curCP = numOr((this.state as any).carriagePosition, this._canonicalDefault('carriagePosition'))
+      const curCH = numOr((this.state as any).carriageHeight, this._canonicalDefault('carriageHeight'))
+      const dxRail = Math.abs((tween.carriagePosition as number) - 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 as any).speed === 'number' ? (this.state as any).speed : undefined) ??
+        250   // DEFAULT_SPEED — scene units/sec (이전 500 → 사용자 체감 빠름 → 절반)
+      duration = speed > 0 ? Math.max(200, (dist / speed) * 1000) : 1500
+    }
     this.setState({ status: 'moving' as CraneStatus })
     await this._tween(tween, duration)
     this.setState({ status: 'idle' as CraneStatus })
@@ -509,8 +620,9 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
       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 as any).components as any[] | undefined
-      const carrier = comps?.find?.((c: any) => c?._transferSlotId === 'forks')
+      const carrier = comps?.find?.((c: any) => c?._transferSlotId != null)
         ?? comps?.[0]
       if (carrier) {
         try {
@@ -542,6 +654,315 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     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) 가 사용 후
+   * 폐기.
+   */
+  private _adjacentByHolder?: Map<SlottedHolder & { state?: any }, Set<string>>
+
+  /** Cache 없음 — invalidate 호출도 no-op (호환 차원 keep). */
+  invalidateAdjacentSlots(): void {
+    this._adjacentByHolder = undefined
+  }
+
+  /**
+   * 자동 detect 결과 cache — *boundHolders 미명시 시* 사용. crane / rack 위치가
+   * 정적이라 *1회 detect 후 영구 cache 안전*. 위치/회전/차원 변경 시 invalidate.
+   */
+  private _autoBoundCache?: Array<SlottedHolder & { state?: any }>
+
+  /** Auto bound cache invalidate — crane state 변경 시 호출. */
+  invalidateBoundCache(): void {
+    this._autoBoundCache = undefined
+  }
+
+  /**
+   * Scene traverse + reach 검사 — 어느 slot 1개라도 reach 안인 holder 들 list.
+   * boundHolders 미명시 시 *runtime auto-detect* 결과. crane/rack 정적 위치
+   * 가정 — 1회 호출 후 cache.
+   */
+  detectBoundHolders(): Array<SlottedHolder & { state?: any }> {
+    const ro = this._realObject as any
+    const obj3d: THREE.Object3D | undefined = ro?.object3d
+    if (!obj3d) return []
+    const craneWorld = new THREE.Vector3()
+    obj3d.getWorldPosition(craneWorld)
+
+    const s: any = 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: number = typeof s?.forkLength === 'number' && Number.isFinite(s.forkLength)
+      ? s.forkLength : craneH * 0.6
+    const xHalf = craneW / 2
+    const zHalf = forkLen
+
+    const root: any = (this as any).root
+    if (!root) return []
+    const result: Array<SlottedHolder & { state?: any }> = []
+    const seen = new Set<any>()
+    const visit = (component: any) => {
+      if (!component || seen.has(component)) return
+      seen.add(component)
+      if (component !== this && isSlottedHolder(component)) {
+        const holder = component as SlottedHolder & { state?: any }
+        const slots = holder.slotIds?.()
+        if (slots && slots.length > 0) {
+          const getPos = (holder as any).slotWorldPosition?.bind(holder) as
+            ((id: string) => { x: number; y: number; z: number } | undefined) | undefined
+          // 랙 자동 인식 — *fork 가 닿는 Z 거리* 만 검사. X 는 무관 — 사용자 의도:
+          // 크레인 옆 (포크가 닿는 거리) 에 있는 랙은 *X 방향 어디에 있든* 담당.
+          // rail 의 실 X 길이 = 그 랙의 X 길이 (자동 정렬 모델링 가정).
+          let matched = false
+          for (const slotId of slots) {
+            let pos: { x: number; y: number; z: number } | undefined
+            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 as any).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(): Array<SlottedHolder & { state?: any }> {
+    const raw = (this.state as any)?.boundHolders
+    let ids: string[] = []
+    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: any) => typeof x === 'string' && x.length > 0)
+    }
+    if (ids.length > 0) {
+      // 명시 binding — explicit list resolve
+      const root: any = (this as any).root
+      if (!root) return []
+      const result: Array<SlottedHolder & { state?: any }> = []
+      for (const id of ids) {
+        const c = typeof root.findById === 'function' ? root.findById(id) : undefined
+        if (c && isSlottedHolder(c)) result.push(c as any)
+      }
+      return result
+    }
+    // 미명시 — auto-detect cache
+    if (this._autoBoundCache === undefined) {
+      this._autoBoundCache = this.detectBoundHolders()
+    }
+    return this._autoBoundCache
+  }
+
+  findAdjacentSlots(opts: { includeSelf?: boolean } = {}): AdjacentSlot[] {
+    const ro = this._realObject as any
+    const obj3d: THREE.Object3D | undefined = ro?.object3d
+    if (!obj3d) return []
+
+    // crane 은 고정 rail 따라 움직임 (회전 없음) — axis-aligned 박스 비교.
+    const craneWorld = new THREE.Vector3()
+    obj3d.getWorldPosition(craneWorld)
+
+    const s: any = 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: number = 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: string): string => {
+      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: any = (this as any).root
+    if (!root) return []
+
+    const result: AdjacentSlot[] = []
+    const byHolder = new Map<SlottedHolder & { state?: any }, Set<string>>()
+
+    // *binding scope* — boundHolders 명시 시 그 holder 만 traverse (broad scan 0).
+    // 미명시 시 scene 전체 traverse fallback (BC, 기존 모델 호환).
+    const bound = this.boundHolderInstances()
+    const candidates: any[] = bound.length > 0 ? bound : []
+
+    const visit = (component: any) => {
+      if (!component) return
+      if ((opts.includeSelf || component !== this) && isSlottedHolder(component)) {
+        const holder = component as SlottedHolder & { state?: any }
+        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<string, string[]>()
+          const allByBay = new Map<string, string[]>()
+          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<string>()
+          // *holder.slotWorldPosition* 지원 시 *anchor 생성 0* — match 전 단계의
+          // 직접 좌표 계산 path. 미지원 holder 는 fallback 으로 getSlotAttachObject3d.
+          const getPos = (holder as any).slotWorldPosition?.bind(holder) as
+            ((id: string) => { x: number; y: number; z: number } | undefined) | undefined
+
+          // 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: { x: number; y: number; z: number } | undefined
+              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 as any, world: sharedWorld })
+              }
+            }
+          }
+          if (adjSet.size > 0) byHolder.set(holder, adjSet)
+        }
+      }
+      const children = (component as any).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 ─────────────────────────────────────────────────────────
 
   /**
@@ -735,10 +1156,11 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     }
     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 as CraneState).simulate !== true) return
+    if (!(this as any).app?.isViewMode) return
     this._startAutoSimulate()
   }
 
@@ -770,6 +1192,9 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     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 as CraneState).simulate !== true) return
       this.simulate().catch(e => console.error('[Crane] simulate', e))
@@ -794,14 +1219,32 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     ) {
       ;(this as any).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 as any).app?.isViewMode) {
+          this._startAutoSimulate()
+        }
       } else {
         this._simAbort = true
       }
@@ -829,7 +1272,16 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
   private _railMax = NaN      // local-X 축 rail offset max
   private _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(): Promise<void> {
     if (this._simRunning) return
     this._simRunning = true
@@ -837,13 +1289,92 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     try {
       this._initRailRange()
       while (!this._simAbort) {
-        await this._oneCycle()
+        // Modeling 모드 진입 시 즉시 중단
+        if (!(this as any).app?.isViewMode) {
+          this._simAbort = true
+          break
+        }
+
+        // 1. Dispatcher 의 명시 작업 우선 take
+        const dispatcher = findDispatcher(this as any)
+        const ticket = dispatcher?.takeNextFor(this as any) ?? 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 as CraneState).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)
+   */
+  private async _executeTicket(ticket: TransferTicket, dispatcher: Dispatcher): Promise<void> {
+    const req = ticket.request
+    try {
+      dispatcher.notifyInProgress?.(ticket as any) ?? (ticket as any)._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 as any, err) ?? (ticket as any)._setStatus('failed', { error: err })
+        return
+      }
+
+      // carrier obtain — 명시 carrier 우선
+      let carrier: Component | null = req.carrier ?? null
+      if (!carrier) {
+        // source 가 SlotTarget — holder.obtainCarrier(slotId)
+        const holder = (source as any).holder as SlottedHolder | undefined
+        const slotId = (source as any).slotId as string | undefined
+        if (holder && slotId) {
+          carrier = holder.obtainCarrier(slotId) ?? null
+        }
+      }
+      if (!carrier) {
+        const err = new Error('no-carrier')
+        dispatcher.notifyFailed?.(ticket as any, err) ?? (ticket as any)._setStatus('failed', { error: err })
+        return
+      }
+
+      // pickAndPlace
+      await this.pickAndPlace(carrier, dest as Component)
+
+      // 성공
+      dispatcher.notifyCompleted?.(ticket as any) ?? (ticket as any)._setStatus('completed')
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e))
+      dispatcher.notifyFailed?.(ticket as any, err) ?? (ticket as any)._setStatus('failed', { error: err })
+    }
+  }
+
   /**
    * state.target bbox 를 crane 의 *로컬 X 축* 으로 projection 해서 rail range 1회 계산.
    * Rotation 적용된 crane 의 local X (= rail) 방향으로 움직이도록 cos/sin 캐시.
@@ -930,44 +1461,81 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     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 전환).
+   */
   private async _oneCycle(): Promise<void> {
-    const W = numOr((this.state as any).width, 100)
-    const H = numOr((this.state as any).height, 100)
-    const D = numOr((this.state as any).depth, W * 4)
-    const forkLen = numOr((this.state as any).forkLength, H * 0.6)
-    const cw = numOr((this.state as any).carriageWidth, W * 0.1)
+    // *Modeling 모드 진입 시 즉시 정지* — runtime 에서 mode 전환 (view → modeler)
+    // 대응. obtainCarrier / pickAndPlace 가 modeler 에서 발동하면 *RackGrid 자식
+    // 추가 + state.data 변경* = 모델 영구 변형. 매 cycle 검사 안전.
+    if (!(this as any).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
+    }
 
-    // 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: number): number => 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))
+    // 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: { holder: SlottedHolder & { state?: any }; slotId: string }[] = []
+    const empty: { holder: SlottedHolder & { state?: any }; slotId: string }[] = []
+    for (const [holder, adjSet] of byHolder) {
+      const inAdj = (id: string) => 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 as unknown as Component)
+    } 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))
   }
 
   /**