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

package/src/storage-rack-3d.ts

@@ -198,7 +198,7 @@ export class StorageRack3D extends RealObjectGroup {
     const cellMap = rack.cellMap
     if (!cellMap) return
 
-    // rack 의 기하 파라미터 — cellMap / _ensureCellAttachObject3d 의 levelHeight
+    // rack 의 기하 파라미터 — cellMap / _ensureSlotAttachObject3d 의 levelHeight
     // 계산과 *반드시* 일치해야 함 (shelfBaseHeight > 0 일 때 stock 시각 위치와
     // crane fork target 이 어긋나는 회귀 차단).
     const rs: any = this.component.state

package/src/storage-rack.ts

@@ -173,6 +173,21 @@ export default class Rack
   static align: Alignment = 'bottom'
   static defaultDepth = (h: Heights) => h.ceiling - h.floor
 
+  // Phase Auto-Nav (AN-PR-2) — Obstacle 자격.
+  get isObstacle(): boolean {
+    return (this.state as any)?.isObstacle !== false
+  }
+  obstacleBoundingBox(): { left: number; top: number; width: number; height: number; y?: number; zHeight?: number } | null {
+    const s: any = this.state
+    if (typeof s?.left !== 'number') return null
+    return {
+      left: s.left, top: s.top,
+      width: s.width, height: s.height,
+      y: typeof s.zPos === 'number' ? s.zPos : 0,
+      zHeight: typeof s.depth === 'number' ? s.depth : 0
+    }
+  }
+
   get nature() {
     return NATURE
   }
@@ -183,7 +198,7 @@ export default class Rack
 
   /**
    * Runtime — bays / levels 변경 시 anchor 캐시 무효화. cell 위치가 바뀌므로 다음
-   * `_ensureCellAttachObject3d` 호출이 새 좌표로 갱신.
+   * `_ensureSlotAttachObject3d` 호출이 새 좌표로 갱신.
    */
   onchange(after: Record<string, unknown>, _before: Record<string, unknown>): void {
     super.onchange?.(after, _before)
@@ -195,7 +210,7 @@ export default class Rack
       'height' in after ||
       'depth' in after
     ) {
-      this._attachAnchorByCell.clear()
+      this._attachAnchorBySlot.clear()
     }
     if ('hideHorizontalFrame' in after) {
       ;(this._realObject as any)?.applyFrameVisibility?.()
@@ -269,7 +284,7 @@ export default class Rack
     // 명시 시 (Carriable + CarrierHolder.reparent 모두) 그대로 anchor origin 에 snap.
     const cellId = (carrier as any)?.state?.cellId as string | undefined
     if (cellId) {
-      const obj = this._ensureCellAttachObject3d(cellId)
+      const obj = this._ensureSlotAttachObject3d(cellId)
       if (obj) return { attach: obj, localPosition: { x: 0, y: 0, z: 0 } }
     }
     // Fallback — cellId 없는 (legacy) 호출 시 rack root.
@@ -302,13 +317,95 @@ export default class Rack
   /**
    * 1-based (bay, row, level) → 0-based cellId 문자열.
    *
-   *   rack.cellIdOf(1, 1, 6)  →  '0-0-5'
-   *   rack.cellIdOf(3, 1, 4)  →  '2-0-3'
+   *   rack.slotIdOf(1, 1, 6)  →  '0-0-5'
+   *   rack.slotIdOf(3, 1, 4)  →  '2-0-3'
    */
-  cellIdOf(bay: number, row: number = 1, level: number = 1): string {
+  slotIdOf(bay: number, row: number = 1, level: number = 1): string {
     return `${bay - 1}-${row - 1}-${level - 1}`
   }
 
+  /**
+   * 모든 slot id 의 목록 (Plan A 의 *cell* = slot 통일). bays × rows × levels 전 조합.
+   * storage-rack 의 rows 는 항상 1 (단일 row) 이므로 실제론 bays × levels.
+   *
+   * SlottedHolder.slotIds — capability 기반 enumeration entry point.
+   */
+  slotIds(): ReadonlyArray<string> {
+    const bays = Math.max(1, Math.floor((this.state as any)?.bays ?? 5))
+    const levels = Math.max(1, Math.floor((this.state as any)?.levels ?? 4))
+    const ids: string[] = []
+    for (let bay = 1; bay <= bays; bay++) {
+      for (let level = 1; level <= levels; level++) {
+        ids.push(this.slotIdOf(bay, 1, level))
+      }
+    }
+    return ids
+  }
+
+  /**
+   * 점유된 slot 의 id 목록 — state.data record + *carrier* children 둘 다.
+   * RackCell (시각 proxy) 같은 *carrier 아닌 자식* 은 제외 (isCarriable 검사).
+   *
+   * @param filter  predicate — 통과하는 slotId 만. sweep 중 즉시 reject.
+   */
+  occupiedSlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string> {
+    const set = new Set<string>()
+    for (const r of this.records) {
+      const cid = r?.cellId
+      if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+    }
+    for (const c of (this as any).components ?? []) {
+      if (!(c as any)?.isCarriable) continue
+      const cid = (c as any)?.state?.cellId
+      if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+    }
+    return Array.from(set)
+  }
+
+  /** 비어있는 slot 의 id 목록 — slotIds() - occupiedSlotIds(). filter 도 동일. */
+  emptySlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string> {
+    const occ = new Set(this.occupiedSlotIds())
+    const result: string[] = []
+    for (const id of this.slotIds()) {
+      if (occ.has(id)) continue
+      if (filter && !filter(id)) continue
+      result.push(id)
+    }
+    return result
+  }
+
+  /**
+   * slot 의 *world position* — anchor object3d *생성 없이* 직접 계산. crane 의
+   * reach 검사 등 *match 전 단계* 에서 *anchor 생성 0* 으로 사용.
+   */
+  slotWorldPosition(cellId: string): { x: number; y: number; z: number } | undefined {
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return undefined
+    const cell = this.cellMap?.findById(cellId)
+    if (!cell) return undefined
+
+    const rs: any = this.state
+    const rackWidth = rs?.width || 1000
+    const rackDepth = rs?.depth || 3000
+    const rackHeight = rs?.height || 600
+    const bays = Math.max(1, Math.floor(rs?.bays || 5))
+    const levels = Math.max(1, Math.floor(rs?.levels || 4))
+    const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 0, rackDepth * 0.9))
+    const shelfZone = rackDepth - shelfBase
+    const bayWidth = rackWidth / bays
+    const levelHeight = shelfZone / levels
+    const stockD = levelHeight * 0.7
+    const rowDepth = rackHeight
+
+    const x = cell.localPosition.x + bayWidth / 2 - rackWidth / 2
+    const y = cell.localPosition.y - rackDepth / 2 + stockD / 2
+    const z = cell.localPosition.z + rowDepth / 2 - rackHeight / 2
+
+    const v = new THREE.Vector3(x, y, z)
+    ro.object3d.localToWorld(v)
+    return { x: v.x, y: v.y, z: v.z }
+  }
+
   /** cellId 에 carrier 가 있는가 — child carrier 또는 state.data record 어느 쪽이든. */
   hasCarrierAt(cellId: string): boolean {
     if (this._carrierChildAt(cellId)) return true
@@ -337,7 +434,7 @@ export default class Rack
   obtainCarrier(idOrBay: string | number, row?: number, level?: number): Component | null {
     const cellId = typeof idOrBay === 'string'
       ? idOrBay
-      : this.cellIdOf(idOrBay, row ?? 1, level ?? 1)
+      : this.slotIdOf(idOrBay, row ?? 1, level ?? 1)
     const existing = this._carrierChildAt(cellId)
     if (existing) return existing
 
@@ -528,7 +625,7 @@ export default class Rack
    * 이걸 attach frame 으로 사용 (transit 중 carrier 가 slot 위치에 정렬).
    */
   getSlotAttachObject3d(cellId: string): THREE.Object3D | undefined {
-    return this._ensureCellAttachObject3d(cellId)
+    return this._ensureSlotAttachObject3d(cellId)
   }
 
   /**
@@ -546,7 +643,7 @@ export default class Rack
   getSlotSize(cellId: string): { width: number; height: number; depth: number } | undefined {
     const cell = this.cellMap?.findById(cellId)
     if (!cell) return undefined
-    const stockD = cell.size.height * 0.7   // matches _ensureCellAttachObject3d + storage-rack-3d.rebuildStockMesh
+    const stockD = cell.size.height * 0.7   // matches _ensureSlotAttachObject3d + storage-rack-3d.rebuildStockMesh
     return {
       width: cell.size.width,
       height: cell.size.depth,    // 2D height = Z extent (front-back)
@@ -564,7 +661,7 @@ export default class Rack
   slotTargetAt(idOrBay: string | number, row?: number, level?: number): SlotTarget {
     const cellId = typeof idOrBay === 'string'
       ? idOrBay
-      : this.cellIdOf(idOrBay, row ?? 1, level ?? 1)
+      : this.slotIdOf(idOrBay, row ?? 1, level ?? 1)
     return new SlotTarget(this, cellId)
   }
 
@@ -609,7 +706,7 @@ export default class Rack
   }
 
   /** cellId 별 attach anchor object3d cache (rack.object3d 의 자식). */
-  private _attachAnchorByCell: Map<string, THREE.Object3D> = new Map()
+  private _attachAnchorBySlot: Map<string, THREE.Object3D> = new Map()
 
   /**
    * cellId 위치에 lightweight anchor object3d 를 *singleton 으로* 보장 + 갱신.
@@ -619,16 +716,16 @@ export default class Rack
    *   - 두 용도가 *같은 object3d* 를 공유해 carrier 가 transient 동안 SlotTarget 의
    *     pose 와 정확히 동기화.
    */
-  private _ensureCellAttachObject3d(cellId: string): THREE.Object3D | undefined {
+  private _ensureSlotAttachObject3d(cellId: string): THREE.Object3D | undefined {
     const ro: any = (this as any)._realObject
     if (!ro?.object3d) return undefined
 
-    let obj = this._attachAnchorByCell.get(cellId)
+    let obj = this._attachAnchorBySlot.get(cellId)
     if (!obj) {
       obj = new THREE.Object3D()
       obj.name = `rack-slot-anchor:${cellId}`
       ro.object3d.add(obj)
-      this._attachAnchorByCell.set(cellId, obj)
+      this._attachAnchorBySlot.set(cellId, obj)
     }
 
     const cell = this.cellMap?.findById(cellId)

package/test/test-coord-alignment.ts

@@ -4,7 +4,7 @@
  *
  * 두 공식이 *동일 cellId 에 대해 동일 결과* 를 반환해야 함:
  *   - storage-rack-3d.rebuildStockMesh: InstancedMesh instance 의 위치
- *   - storage-rack._ensureCellAttachObject3d: anchor (SlotTarget._realObject.object3d) 위치
+ *   - storage-rack._ensureSlotAttachObject3d: anchor (SlotTarget._realObject.object3d) 위치
  *
  * 불일치 = Crane fork 가 stock 시각 위치와 어긋남.
  *
@@ -47,7 +47,7 @@ function computeAnchorPosition(
   const stockD = levelHeight * 0.7
   const rowDepth = height
 
-  // storage-rack.ts _ensureCellAttachObject3d 공식
+  // storage-rack.ts _ensureSlotAttachObject3d 공식
   const x = cell.localPosition.x + bayWidth / 2 - width / 2
   const y = cell.localPosition.y - depth / 2 + stockD / 2
   const z = cell.localPosition.z + rowDepth / 2 - height / 2

package/test/test-crane-bay-match.ts

@@ -0,0 +1,130 @@
+/*
+ * Crane.findAdjacentSlots — bound scope 매칭 검증.
+ *
+ * 사용자 핵심 의도:
+ *   "rail 끝에서 끝까지가 carriage 도달 범위" — bound rack 의 X 영역 전체
+ *   가 reach. crane 자체 폭 (state.width) 무관. Z (fork tip) 만 검사.
+ *
+ * (col, row) 단위 정밀 매칭 — 같은 col 의 다른 row 는 Z 별도 검사. 매칭 통과
+ * 한 (col, row) 의 모든 shelves 가 adjacent.
+ */
+
+import 'should'
+
+// findAdjacentSlots 의 bay 단위 매칭 로직 격리.
+function mockBayMatch(opts: {
+  bayKey: string
+  representativeSlotsWorld: Array<{ x: number; y: number; z: number }>
+  craneWorld: { x: number; z: number }
+  zHalf: number
+  useBoundScope: boolean
+  xHalf?: number
+}): boolean {
+  for (const pos of opts.representativeSlotsWorld) {
+    const dz = Math.abs(pos.z - opts.craneWorld.z)
+    const xOk = opts.useBoundScope ? true : Math.abs(pos.x - opts.craneWorld.x) <= (opts.xHalf ?? 0)
+    if (xOk && dz <= opts.zHalf) return true
+  }
+  return false
+}
+
+describe('Crane.findAdjacentSlots — bound scope 시 X 무관, Z 만 검사', () => {
+  it('bound scope true — X 가 매우 멀어도 Z reach 안 이면 통과', () => {
+    const matched = mockBayMatch({
+      bayKey: '0-0',
+      representativeSlotsWorld: [{ x: 99999, y: 0, z: 100 }],
+      craneWorld: { x: 0, z: 0 },
+      zHalf: 500,
+      useBoundScope: true
+    })
+    matched.should.be.true()
+  })
+
+  it('bound scope true — Z 가 fork reach 밖 면 매칭 X', () => {
+    const matched = mockBayMatch({
+      bayKey: '0-0',
+      representativeSlotsWorld: [{ x: 100, y: 0, z: 800 }],
+      craneWorld: { x: 0, z: 0 },
+      zHalf: 500,
+      useBoundScope: true
+    })
+    matched.should.be.false()
+  })
+
+  it('bound scope false (fallback) — X + Z 둘 다 검사', () => {
+    const matched = mockBayMatch({
+      bayKey: '0-0',
+      representativeSlotsWorld: [{ x: 9999, y: 0, z: 100 }],
+      craneWorld: { x: 0, z: 0 },
+      zHalf: 500,
+      useBoundScope: false,
+      xHalf: 500   // 매우 좁은 fallback
+    })
+    matched.should.be.false()   // X 9999 > 500 → fail
+  })
+
+  it('row 별 Z 다른 경우 — 어느 row 든 reach 안 이면 col 매칭', () => {
+    const matched = mockBayMatch({
+      bayKey: '0',   // first segment = col only (사용자 의도 시 row 통합 매칭)
+      representativeSlotsWorld: [
+        { x: 100, y: 0, z: 800 },    // row=0, Z 밖
+        { x: 100, y: 0, z: 100 },    // row=1, Z 안 ← match
+        { x: 100, y: 0, z: -700 }    // row=2, Z 밖
+      ],
+      craneWorld: { x: 0, z: 0 },
+      zHalf: 500,
+      useBoundScope: true
+    })
+    matched.should.be.true()
+  })
+
+  it('모든 row 의 Z 가 reach 밖 — col 매칭 X', () => {
+    const matched = mockBayMatch({
+      bayKey: '0',
+      representativeSlotsWorld: [
+        { x: 100, y: 0, z: 800 },
+        { x: 100, y: 0, z: -700 }
+      ],
+      craneWorld: { x: 0, z: 0 },
+      zHalf: 500,
+      useBoundScope: true
+    })
+    matched.should.be.false()
+  })
+})
+
+describe('rail 의 *전체 X 영역* 활용 — 사용자 의도 시뮬레이션', () => {
+  // RackGrid 의 여러 col + carrier 분포 — carriage 가 X 전체 visit.
+  // simulate 의 X variance 가 모델 의 *carrier 분포 range* 와 같은지.
+
+  it('5 col × records 분포 → carriage X variance 가 모든 col cover', () => {
+    // RackGrid 5 col, bayW=200, width=1000. col 별 X = -400, -200, 0, 200, 400.
+    const colX = [-400, -200, 0, 200, 400]
+    const records = colX.map(x => ({ cellId: `${(x + 400) / 200}-0-0`, worldX: x }))
+
+    // crane 의 random source pick — 충분한 횟수면 모든 col visit.
+    const visitedX = new Set<number>()
+    for (let i = 0; i < 100; i++) {
+      const r = records[Math.floor(Math.random() * records.length)]
+      visitedX.add(r.worldX)
+    }
+    // 100 회 random pick 에서 5 col 모두 적어도 1회씩 visit (high probability)
+    visitedX.size.should.be.greaterThanOrEqual(4)
+  })
+
+  it('한 col 만 record 있음 — carriage 가 그 col 만 visit (narrow 정상)', () => {
+    // 사용자 모델 가정: record 가 한 col 에만 분포 시 carriage X variance narrow.
+    // 이건 *모델 데이터 결과 — 코드 책임 X*.
+    const records = [
+      { cellId: '0-0-0', worldX: -400 },
+      { cellId: '0-0-1', worldX: -400 },
+      { cellId: '0-0-2', worldX: -400 }
+    ]
+    const visitedX = new Set<number>()
+    for (let i = 0; i < 50; i++) {
+      const r = records[Math.floor(Math.random() * records.length)]
+      visitedX.add(r.worldX)
+    }
+    visitedX.size.should.equal(1)   // narrow — 한 col 만
+  })
+})

package/test/test-crane-binding-resolve.ts

@@ -0,0 +1,168 @@
+/*
+ * Crane.boundHolderInstances() — binding scope 의 resolve 정확성 검증.
+ *
+ * 입력 형식 분기 + scene findById 호출 + isSlottedHolder duck-type 통과 검사.
+ * 명시 binding 시 그 list 만 사용, 미명시 시 auto-detect cache (별도 test).
+ */
+
+import 'should'
+
+// 핵심 로직만 격리 (실 Crane 인스턴스 build 의존 X).
+function mockBoundHolderResolve(opts: {
+  rawState: string | string[] | undefined
+  findById: (id: string) => any
+  isSlottedHolder: (x: any) => boolean
+}): any[] {
+  const raw = opts.rawState
+  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) return []
+  const result: any[] = []
+  for (const id of ids) {
+    const c = opts.findById(id)
+    if (c && opts.isSlottedHolder(c)) result.push(c)
+  }
+  return result
+}
+
+describe('Crane.boundHolderInstances — csv / array 입력 분기 + scene lookup', () => {
+  const fakeRack1 = { id: 'rack-1', isSlot: true }
+  const fakeRack2 = { id: 'rack-2', isSlot: true }
+  const fakeNonSlot = { id: 'wire-1', isSlot: false }
+
+  const scene = new Map<string, any>([
+    ['rack-1', fakeRack1],
+    ['rack-2', fakeRack2],
+    ['wire-1', fakeNonSlot]
+  ])
+  const findById = (id: string) => scene.get(id)
+  const isSlottedHolder = (x: any) => !!x?.isSlot
+
+  it('csv string — comma-separated id resolve', () => {
+    const r = mockBoundHolderResolve({
+      rawState: 'rack-1, rack-2',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+    r[0].should.equal(fakeRack1)
+    r[1].should.equal(fakeRack2)
+  })
+
+  it('array of string — id list resolve', () => {
+    const r = mockBoundHolderResolve({
+      rawState: ['rack-1', 'rack-2'],
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+  })
+
+  it('미명시 (undefined) — empty list', () => {
+    const r = mockBoundHolderResolve({
+      rawState: undefined,
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(0)
+  })
+
+  it('빈 csv ("") — empty list', () => {
+    const r = mockBoundHolderResolve({
+      rawState: '',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(0)
+  })
+
+  it('빈 array — empty list', () => {
+    const r = mockBoundHolderResolve({
+      rawState: [],
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(0)
+  })
+
+  it('잘못된 id — scene findById 가 undefined 반환 시 skip', () => {
+    const r = mockBoundHolderResolve({
+      rawState: 'rack-1, nonexistent, rack-2',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+  })
+
+  it('isSlottedHolder 안 통과 — skip', () => {
+    const r = mockBoundHolderResolve({
+      rawState: 'rack-1, wire-1, rack-2',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+    r.should.not.containEql(fakeNonSlot)
+  })
+
+  it('csv 공백 처리 — trim', () => {
+    const r = mockBoundHolderResolve({
+      rawState: '  rack-1  ,   rack-2  ',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+  })
+
+  it('csv 빈 항목 — filter out', () => {
+    const r = mockBoundHolderResolve({
+      rawState: 'rack-1, , rack-2,',
+      findById, isSlottedHolder
+    })
+    r.length.should.equal(2)
+  })
+})
+
+describe('detectBoundHolders 의 Z (fork) 만 검사 — X 무관 매칭', () => {
+  // detectBoundHolders 의 핵심: holder.slotIds() 중 어느 한 slot 의 world.z
+  // 가 *crane.world.z ± forkLen* 안인지. X 무관.
+
+  function mockDetectMatch(opts: {
+    craneZ: number
+    forkLen: number
+    holderSlotsWorld: Array<{ x: number; y: number; z: number }>
+  }): boolean {
+    const zHalf = opts.forkLen
+    for (const pos of opts.holderSlotsWorld) {
+      if (Math.abs(pos.z - opts.craneZ) <= zHalf) return true
+    }
+    return false
+  }
+
+  it('어느 한 slot 이 *Z reach 안* — 매칭 통과', () => {
+    const matched = mockDetectMatch({
+      craneZ: 0, forkLen: 500,
+      holderSlotsWorld: [
+        { x: 9999, y: 0, z: 300 },   // X 무관, Z reach 안
+        { x: -9999, y: 0, z: -200 }
+      ]
+    })
+    matched.should.be.true()
+  })
+
+  it('모든 slot 의 Z 가 *reach 밖* — 매칭 X', () => {
+    const matched = mockDetectMatch({
+      craneZ: 0, forkLen: 500,
+      holderSlotsWorld: [
+        { x: 100, y: 0, z: 800 },     // |800| > 500
+        { x: 200, y: 0, z: -700 }     // |700| > 500
+      ]
+    })
+    matched.should.be.false()
+  })
+
+  it('X 가 매우 멀어도 *Z reach* 면 통과 — X 무관 확인', () => {
+    const matched = mockDetectMatch({
+      craneZ: 0, forkLen: 100,
+      holderSlotsWorld: [
+        { x: 100000, y: 0, z: 50 }
+      ]
+    })
+    matched.should.be.true()
+  })
+})

package/test/test-crane-duration.ts

@@ -0,0 +1,90 @@
+/*
+ * Crane.moveTo 의 duration 계산 — 거리 비례 + state.speed 기반.
+ *
+ * 회귀 시나리오:
+ *   1500ms 고정 → 모든 pickAndPlace 가 같은 시간. 거리 1 cell 이든 rail 끝~끝
+ *   이든 동일. 여러 crane 의 cycle 이 비현실적 동기. 사용자 보고:
+ *   "왜 모든 크레인이 동시에 움직이는거지? 현실성 없이?"
+ *
+ * Fix 의도:
+ *   - duration = max(X 운동 거리, Y 운동 거리) / speed * 1000.
+ *   - speed = state.speed | options.speed | 500 (DEFAULT_SPEED).
+ *   - duration 최소 200ms (teleport 느낌 방지).
+ *   - options.duration 명시 시 override.
+ */
+
+import 'should'
+
+function calcDuration(opts: {
+  curCP: number; curCH: number
+  newCP: number; newCH?: number
+  stateSpeed?: number
+  optionDuration?: number
+  optionSpeed?: number
+}): number {
+  if (typeof opts.optionDuration === 'number') return opts.optionDuration
+  const dxRail = Math.abs(opts.newCP - opts.curCP)
+  const dyMast = typeof opts.newCH === 'number' ? Math.abs(opts.newCH - opts.curCH) : 0
+  const dist = Math.max(dxRail, dyMast)
+  const speed = opts.optionSpeed ?? opts.stateSpeed ?? 250
+  return speed > 0 ? Math.max(200, (dist / speed) * 1000) : 1500
+}
+
+describe('Crane.moveTo duration — 거리 비례 + speed 기반', () => {
+  it('1 cell 이동 (50 units) at default speed 250 — duration = 200ms (min)', () => {
+    const d = calcDuration({ curCP: 100, curCH: 50, newCP: 150, newCH: 50 })
+    // (50 / 250) * 1000 = 200ms.
+    d.should.equal(200)
+  })
+
+  it('rail 끝~끝 이동 (500 units) at default speed 250 — duration = 2000ms', () => {
+    const d = calcDuration({ curCP: 0, curCH: 50, newCP: 500, newCH: 50 })
+    d.should.equal(2000)
+  })
+
+  it('Y 운동도 포함 — max(X, Y) 거리 사용', () => {
+    // X 이동 100 (400ms), Y 이동 400 (1600ms) → max = 1600ms.
+    const d = calcDuration({ curCP: 0, curCH: 0, newCP: 100, newCH: 400 })
+    d.should.equal(1600)
+  })
+
+  it('state.speed = 250 (느린 crane) — 같은 거리 2 배 시간', () => {
+    const d = calcDuration({ curCP: 0, curCH: 0, newCP: 500, newCH: 0, stateSpeed: 250 })
+    d.should.equal(2000)
+  })
+
+  it('state.speed = 1000 (빠른 crane) — 같은 거리 절반 시간', () => {
+    const d = calcDuration({ curCP: 0, curCH: 0, newCP: 500, newCH: 0, stateSpeed: 1000 })
+    d.should.equal(500)
+  })
+
+  it('options.duration 명시 시 override', () => {
+    const d = calcDuration({ curCP: 0, curCH: 0, newCP: 500, newCH: 0, optionDuration: 333 })
+    d.should.equal(333)
+  })
+
+  it('options.speed 가 state.speed 보다 우선', () => {
+    const d = calcDuration({ curCP: 0, curCH: 0, newCP: 500, stateSpeed: 250, optionSpeed: 1000 })
+    d.should.equal(500)
+  })
+})
+
+describe('여러 crane cycle 비동기 검증 — 거리 + speed + idle random 결합', () => {
+  it('★ 핵심 ★ 같은 cycle path 라도 *crane 별 speed + 거리* 다르면 총 시간 다양', () => {
+    // 시나리오: 3 crane, 각자 다른 source/dest 거리, 다른 speed.
+    const c1Duration = calcDuration({ curCP: 0, curCH: 0, newCP: 100, newCH: 50, stateSpeed: 500 })  // 100/500*1000 = 200ms (min)
+    const c2Duration = calcDuration({ curCP: 200, curCH: 0, newCP: 0, newCH: 200, stateSpeed: 300 })  // 200/300*1000 = 667ms
+    const c3Duration = calcDuration({ curCP: 0, curCH: 0, newCP: 500, newCH: 100, stateSpeed: 1000 }) // 500/1000*1000 = 500ms
+    // 셋 다 다름 → cycle 비동기.
+    const set = new Set([c1Duration, c2Duration, c3Duration])
+    set.size.should.equal(3)
+  })
+
+  it('★ 사용자 보고 1500ms 고정 회귀 ★ — 거리 무관 모두 같은 시간이면 동시 동기화', () => {
+    // legacy 식: const duration = options.duration ?? 1500
+    const legacy1 = 1500   // 1 cell 이동
+    const legacy2 = 1500   // rail 끝~끝
+    const legacy3 = 1500   // 다양한 거리
+    new Set([legacy1, legacy2, legacy3]).size.should.equal(1)   // 모두 동일 → 동기화
+  })
+})