@fmsim/machine 2.0.0-beta.10 → 2.0.0-beta.101

package/src/carrier-manager.ts

@@ -0,0 +1,223 @@
+import { Model } from '@hatiolab/things-scene'
+import type Carrier from './carrier'
+import type MCSCarrierHolder from './mcs-carrier-holder'
+import { parseIfJsonString } from './utils/data-value'
+
+// 사라진 carrier 의 dispose 지연. 같은 macrotask 안에서 holder A 의 사라짐
+// 보고와 holder B 의 등장 보고가 순차로 들어오는 reparent 시나리오 (= 같은
+// frame snapshot 의 여러 record 적용) 를 보호하기 위해 setTimeout(0) 의
+// next-macrotask delay 만 둔다. 과거 1000ms grace 가 있었으나 seek 시 2단계
+// 갱신 (1초 후 carrier 사라짐) 부작용이 명확하고 frame 누락 bouncing 깜빡임
+// 보호 효용은 작다 판단되어 0 으로 단축 (2026-06-09).
+const DYING_TIMEOUT = 0
+
+/**
+ * Carrier 가 들고 있는 4 키 묶음. data.CARRIERNAME 의 형제 키 (CARRIERTYPE,
+ * EMPTYTYPE, CARRIERSTATUS) 를 한 item 으로 묶는다. holder.data 의 *대표*
+ * 와 ADDITIONS 의 *각 항목* 모두 동일 shape 으로 정규화돼 stack diff 에
+ * 들어간다.
+ *
+ * 주의 — 외부 시스템이 ADDITIONS 의 각 항목 키를 다른 이름으로 (예:
+ * NAME / TYPE / EMPTY / STATUS) 줄 가능성에 대비해 이 build 함수가 단일
+ * 정규화 지점이 된다. 키 매핑 변경은 여기 한 곳만 손대면 된다.
+ */
+export interface CarrierStackItem {
+  CARRIERNAME: string
+  CARRIERTYPE?: string
+  EMPTYTYPE?: string
+  CARRIERSTATUS?: string
+}
+
+export default class CarrierManager {
+  private carriers: Map<string, Carrier> = new Map()
+  private dyingTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  private root: any
+
+  constructor(root: any) {
+    this.root = root
+  }
+
+  get(carrierName: string): Carrier | undefined {
+    return this.carriers.get(carrierName)
+  }
+
+  /**
+   * Holder 의 data 변경에 대응해 carrier pool 을 동기화.
+   *
+   * 정책:
+   *   - holder.data 가 *single source of truth*. 대표(CARRIERNAME) +
+   *     ADDITIONS[] 를 하나의 *stack list* 로 정규화한 뒤 before/after 의
+   *     이름 set diff 로 추가/제거/유지 분기.
+   *   - "대표" 와 "ADDITIONS" 는 *holder.data 안의 키 위치 차이일 뿐* 이고,
+   *     carrier 인스턴스끼리는 **종속/그룹 관계 없음 — 모두 독립 동등**.
+   *     stack 안의 위치 (stackIndex) 만 carrier.state 에 주입한다. 2D render
+   *     skip 등의 판정은 *위치 (= parent.components 의 마지막 여부)* 로 한다.
+   *   - 동일 CARRIERNAME 이 *다른 holder* 에 새로 등장하면 reparent (애니메이션).
+   *     *해당 carrier 만 이동* — 같은 stack 의 다른 carrier 는 따라가지 않는다.
+   *   - 사라진 carrier 는 next-macrotask 에 dispose. 같은 macrotask 안에서 다른
+   *     holder 가 같은 이름을 보고하면 cancel 되어 reparent 로 전환.
+   */
+  update(holder: MCSCarrierHolder, after: Record<string, any>, before: Record<string, any>): void {
+    const afterStack = this._buildStack(after)
+    const beforeStack = this._buildStack(before)
+
+    const afterNames = new Set(afterStack.map(i => i.CARRIERNAME))
+    const beforeNames = new Set(beforeStack.map(i => i.CARRIERNAME))
+
+    // 1) 사라진 것 → dying schedule (자기 holder 의 자식인 carrier 만)
+    for (const name of beforeNames) {
+      if (afterNames.has(name)) continue
+      const carrier = this.carriers.get(name)
+      if (carrier && carrier.parent === holder) {
+        this.scheduleDying(name)
+      }
+    }
+
+    // 2) afterStack 의 *순서대로* 처리 — bottom (ADDITIONS[0]) 부터 top (대표)
+    //    그래야 parent.components 가 자연스럽게 같은 순서로 정렬되어 stack index
+    //    가 일관된다.
+    afterStack.forEach((item, idx) => {
+      const name = item.CARRIERNAME
+      this.cancelDying(name)
+
+      let carrier = this.carriers.get(name)
+      const { width, height } = holder.state
+
+      if (!carrier) {
+        carrier = Model.compile(
+          {
+            id: name,
+            type: 'Carrier',
+            left: 0,
+            top: 0,
+            width,
+            height,
+            showText: holder.getState('showCarrierText') || false,
+            stackIndex: idx
+          },
+          this.root.app
+        ) as unknown as Carrier
+
+        this.carriers.set(name, carrier)
+        carrier.data = item
+        holder.addComponent(carrier, { silent: true })
+      } else if (carrier.parent !== holder && !beforeNames.has(name)) {
+        // 다른 holder 에 있던 carrier 가 이번 update 에서 *새로 등장* 한 경우만
+        // reparent. before 에도 같은 이름이 있었으면 ping-pong (옛 시점의
+        // 반복 보고) 이므로 trigger 하지 않는다. (F05 의 bouncing 방지)
+        ;(holder as any).reparent(carrier, { animated: true, duration: 2000, ease: 'inout' })
+      }
+
+      if (carrier.parent === holder) {
+        carrier.setState('stackIndex', idx)
+        carrier.data = item
+      }
+    })
+
+    // *_모든 carrier 추가 완료 후* — 각자의 transform 강제 갱신. 한 줄로 처리
+    // 안 되는 이유: cz override 의 offset 계산이 *형제 carrier 의 _realObject.
+    // effectiveDepth 누적*에 의존하는데, 첫 iteration 시점엔 자기 뒤 carrier 의
+    // _realObject 가 아직 없어 offset 이 부족하게 평가될 수 있다. 모두 빌드된
+    // 뒤 한 번 더 갱신해야 적층 정확.
+    afterStack.forEach(item => {
+      const carrier = this.carriers.get(item.CARRIERNAME)
+      if (carrier && carrier.parent === holder) {
+        ;(carrier as any)._realObject?.updateTransform?.()
+      }
+    })
+  }
+
+  /**
+   * data.CARRIERNAME (대표) + data.MULTICARRIERS[] 를 하나의 stack list 로 정규화.
+   * 적층 순서: multiCarriers[0..n-1] (bottom → up) + 대표 (top, 맨 마지막).
+   * (데이터 키는 모두 대문자 전제 — 케이스 정규화 없이 직접 읽는다)
+   */
+  private _buildStack(data: any): CarrierStackItem[] {
+    if (!data) return []
+
+    const stack: CarrierStackItem[] = []
+
+    // MULTICARRIERS 값이 JSON 문자열로 올 수 있어 파싱 후 처리.
+    const list = parseIfJsonString(data.MULTICARRIERS)
+    if (Array.isArray(list)) {
+      for (const a of list) {
+        if (a && typeof a === 'object' && a.CARRIERNAME) {
+          // 항목 *원본 그대로* — 외부 시스템이 임의 키를 추가로 보낼 수 있고,
+          // 누락된 4 키는 default 없이 그대로 비워둔다 (carrier.data 에 흘리는
+          // 가공 최소화 — F03 같은 기존 테스트의 raw shape 기대와도 정합).
+          stack.push({ ...a } as CarrierStackItem)
+        }
+      }
+    }
+
+    if (data.CARRIERNAME) {
+      // 대표는 *holder.data 의 carrier 관련 키만 추출* — showText / carrierDepth
+      // 같은 holder 자체 속성은 carrier 로 흘리지 않는다. 명시되지 않은 키는
+      // 생략 (default 안 채움).
+      const repr: any = { CARRIERNAME: data.CARRIERNAME }
+      if ('CARRIERTYPE' in data) repr.CARRIERTYPE = data.CARRIERTYPE
+      if ('EMPTYTYPE' in data) repr.EMPTYTYPE = data.EMPTYTYPE
+      if ('CARRIERSTATUS' in data) repr.CARRIERSTATUS = data.CARRIERSTATUS
+      stack.push(repr)
+    }
+
+    return stack
+  }
+
+  /**
+   * carrier dispose 를 *next macrotask* 로 미룬다. 동기 즉시 dispose 가 아닌
+   * 이유: 같은 macrotask 안에서 holder A 의 사라짐 보고가 step 1 에 들어오고
+   * holder B 의 등장 보고가 (별도 carrier-manager.update 호출의) step 2 에
+   * 들어오는 reparent 시나리오를 보호하기 위함. 즉시 dispose 면 step 1 에서
+   * carrier 인스턴스가 파괴돼 step 2 의 reparent 분기가 *새 인스턴스 생성*
+   * 으로 떨어지고, 3D mesh 재구축 + 이동 애니메이션 손실이 발생.
+   *
+   * 같은 macrotask 안에서 cancelDying 호출이 도달하면 clearTimeout 으로
+   * dispose 회수 → reparent 정상.
+   */
+  private scheduleDying(carrierName: string): void {
+    this.cancelDying(carrierName)
+
+    const timer = setTimeout(() => {
+      this.dyingTimers.delete(carrierName)
+
+      const carrier = this.carriers.get(carrierName)
+      if (carrier) {
+        this.carriers.delete(carrierName)
+        if (!carrier.disposed) {
+          carrier.removeSelf(true)
+        }
+      }
+    }, DYING_TIMEOUT)
+
+    this.dyingTimers.set(carrierName, timer)
+  }
+
+  private cancelDying(carrierName: string): void {
+    const timer = this.dyingTimers.get(carrierName)
+    if (timer) {
+      clearTimeout(timer)
+      this.dyingTimers.delete(carrierName)
+    }
+  }
+
+  onCarrierDisposed(carrierName: string): void {
+    this.cancelDying(carrierName)
+    this.carriers.delete(carrierName)
+  }
+
+  dispose(): void {
+    for (const timer of this.dyingTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.dyingTimers.clear()
+
+    for (const carrier of this.carriers.values()) {
+      if (!carrier.disposed) {
+        carrier.removeSelf(true)
+      }
+    }
+
+    this.carriers.clear()
+  }
+}

package/src/carrier.ts

@@ -4,7 +4,7 @@ import { getPopupData } from '@fmsim/api'
 import { BOUNDS, Component, ComponentNature, Properties, Shape, sceneComponent } from '@hatiolab/things-scene'
 import { ANIMATION_DEFAULT, AnimationPreset, AnimationConfig } from './features/animation-default.js'
 import { ParentObjectMixin } from './features/parent-object-mixin.js'
-import { LEGEND_CARRIER, Legend } from './features/mcs-status-default.js'
+import { Legend, resolveCarrierLegend } from './features/mcs-status-default.js'
 import { MCSStatusMixin } from './features/mcs-status-mixin.js'
 
 const NATURE: ComponentNature = {
@@ -13,12 +13,31 @@ const NATURE: ComponentNature = {
   rotatable: false
 }
 
+
+/**
+ * Feature flag — keep status text (F / E / X) screen-axis-aligned even
+ * when the carrier (or its parent holder, or an in-flight reparent
+ * tween) is rotated. Counter-rotates ONLY the text; the polygon path
+ * still rotates with the carrier as before.
+ *
+ * ROLLBACK procedure (if customer decides to revert):
+ *   1. Flip this flag to `false`           — text rotates with carrier again.
+ *   2. Or delete this constant and the     — fully strip the feature: keep
+ *      `if (STATUS_TEXT_COUNTER_ROTATE)`     only the `else` branch in
+ *      branch in `render()`.                 `render()` (the original code).
+ */
+const STATUS_TEXT_COUNTER_ROTATE = true
+
 @sceneComponent('Carrier')
 export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
   static get nature() {
     return NATURE
   }
 
+  get decorators() {
+    return ['decotag']
+  }
+
   get path() {
     if (!this.parent) {
       return []
@@ -37,6 +56,44 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
 
   set path(path) {}
 
+
+  added(parent: any) {
+    super.added(parent)
+
+    // 새 부모에 맞춰 크기 및 상태 갱신 — width/height 만. depth 는 *절대로
+    // 건드리지 않는다*. machine-3d.ts 의 CARRIER_CONFIG + MCSRealObject3D.
+    // effectiveDepth 가 depthRatio(0.5) × min(w,h) 로 자동 결정한다.
+    // 여기서 state.depth 를 명시 set 하면 그 resolution chain 의 step 1 에
+    // 걸려 본래 두께가 덮어써진다 (= 사용자 호소 "두께가 줄어들었다" 의 원인).
+    if (parent) {
+      const { width, height } = parent.state || {}
+      if (width && height) {
+        this.set({ width, height })
+      }
+    }
+
+    this.syncStateFromData()
+
+    // 3D 오브젝트 최초 생성 (동기적 — reparent()에서 _realObject 필요)
+    if ((this.root as any)?.threed && !this._realObject) {
+      ;(this.root as any).model_layer?._threeCapability?.addObject(this)
+    }
+
+    // reparent 애니메이션은 things-scene의 reparent()가 처리
+  }
+
+  /**
+   * data로부터 carrier 상태를 동기화 (생성 시, 부모 변경 시 공통 사용)
+   */
+  private syncStateFromData(): void {
+    const { CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS } = this.data || {}
+
+    this.setState('id', CARRIERNAME)
+    this.setState('EMPTYTYPE', EMPTYTYPE)
+    this.setState('CARRIERTYPE', CARRIERTYPE)
+    this.setState('CARRIERSTATUS', CARRIERSTATUS)
+  }
+
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
     const { CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS } = this.data || {}
 
@@ -99,13 +156,8 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
   }
 
   get legend(): Legend {
-    const { carrierLegendName } = this.parent?.state || {}
-
-    if (carrierLegendName) {
-      return (this.root as any)?.style[carrierLegendName]
-    }
-
-    return (this.root as any)?.carrierLegendTheme || LEGEND_CARRIER
+    // carrier·스토커 게이지(2D/3D) 공유 단일 소스.
+    return resolveCarrierLegend(this)
   }
 
   getAnimationConfig(carrierStatus): AnimationConfig | null {
@@ -129,8 +181,14 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
       }
 
       // 캐시에 없으면 파싱하고 저장
-      const theme = (this.root as any)?.style?.[carrierAnimationName]
+      let theme = (this.root as any)?.style?.[carrierAnimationName]
       if (theme) {
+        // theme이 string이면 먼저 파싱
+        if (typeof theme === 'string') {
+          try { theme = JSON5.parse(theme) } catch { return ANIMATION_DEFAULT }
+        }
+        if (typeof theme !== 'object' || theme === null) return ANIMATION_DEFAULT
+
         // 문자열 형태의 설정들을 미리 파싱
         const parsedTheme = {}
         for (const [status, config] of Object.entries(theme)) {
@@ -212,6 +270,18 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
       return
     }
 
+    // 2D 에서는 stack 의 *맨 위 (= parent.components 의 마지막)* 1개만 그린다.
+    // ADDITIONS 의 carrier 들도 인스턴스로는 살아있어 조회/reparent 가 가능하지만
+    // 2D 시각에는 노출하지 않는다 — 정책: "2D 는 현행처럼" (대표 1개만).
+    // 판단 기준은 *위치* — carrier 간 그룹/종속 정보는 두지 않는다.
+    const parent = this.parent
+    if (parent && parent.components && parent.components.length > 1) {
+      const siblings = parent.components
+      if (siblings[siblings.length - 1] !== this) {
+        return
+      }
+    }
+
     const { width, height } = this.bounds
     const path = this.path
     const round = Math.round(Math.min(width, height) * 0.1)
@@ -244,11 +314,34 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
         ctx.textAlign = 'center'
         ctx.textBaseline = 'middle'
 
-        ctx.fillText(text, cx - width / 8, cy + height / 8)
+        if (STATUS_TEXT_COUNTER_ROTATE) {
+          // Counter-rotate so the status label stays screen-axis-aligned
+          // even when the carrier (or its parent holder, or an in-flight
+          // reparent transition) is rotated. Reading the current cumulative
+          // rotation from the canvas transform handles all sources of
+          // rotation uniformly (state.rotation, parent transforms,
+          // animation tweens) — no need to enumerate them.
+          const m = ctx.getTransform()
+          const cumulRotation = Math.atan2(m.b, m.a)
+          ctx.save()
+          ctx.translate(cx, cy)
+          ctx.rotate(-cumulRotation)
+          ctx.fillText(text, -width / 8, height / 8)
+          ctx.restore()
+        } else {
+          // Original — text rotates with the carrier.
+          ctx.fillText(text, cx - width / 8, cy + height / 8)
+        }
       }
     }
   }
 
+  dispose(): void {
+    ;(this.root as any)?.carrierManager?.onCarrierDisposed(this.state.id)
+
+    super.dispose()
+  }
+
   async detailInfo() {
     const { type, id } = this.state
 

package/src/conveyor-join.ts

@@ -119,8 +119,11 @@ export default class ConveyorJoin extends ConveyorMixin(MCSTransport) {
     if (normx * normx + normy * normy < 0.25 && ratiox * ratiox + ratioy * ratioy > 0.25) {
       const angle = normalizeAngle(Math.atan2(-normy, normx) - Math.PI / 2)
 
-      if (angle >= startAngle && angle <= endAngle) {
-        return true
+      if (startAngle <= endAngle) {
+        if (angle >= startAngle && angle <= endAngle) return true
+      } else {
+        // wraparound: startAngle > endAngle (예: π → 0)
+        if (angle >= startAngle || angle <= endAngle) return true
       }
     }
 

package/src/conveyor.ts

@@ -14,6 +14,14 @@ const NATURE: ComponentNature = {
         options: ['', 'conveyor', 'belt', 'rail']
       }
     },
+    {
+      type: 'select',
+      label: 'conveyor-orientation',
+      name: 'orientation',
+      property: {
+        options: ['', 'horizontal', 'vertical']
+      }
+    },
     ...MCSTransport.properties
   ]
 }

package/src/crane.ts

@@ -1,6 +1,12 @@
-import { Component, ComponentNature, Properties, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, sceneComponent, frameClock } from '@hatiolab/things-scene'
 import MCSVehicle from './mcs-vehicle'
 import { LEGEND_CRANE } from './features/mcs-status-default'
+import {
+  axisRatio,
+  mapCraneLocalPosition,
+  normalizeCranePosition,
+  type CranePositionData
+} from './utils/crane-position'
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -11,6 +17,29 @@ const NATURE: ComponentNature = {
 
 const GAP = 2
 
+/** 좌표 보간 기본 duration (ms). data.DURATION_MS 가 없으면 이 값 사용. */
+const DEFAULT_DURATION_MS = 1000
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+function easeInOut(t: number): number {
+  return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2
+}
+
+interface CranePositionAnimator {
+  fromLeft: number
+  fromTop: number
+  fromForkZ: number
+  toLeft: number
+  toTop: number
+  toForkZ: number
+  startTime: number
+  duration: number
+  unsubscribe: () => void
+}
+
 @sceneComponent('Crane')
 export default class Crane extends MCSVehicle {
   static get nature() {
@@ -21,10 +50,161 @@ export default class Crane extends MCSVehicle {
     return 'black'
   }
 
+  /** Crane 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   getLegendFallback() {
     return (this.root as any).craneLegendTheme || super.getLegendFallback()
   }
 
+  private _posAnimator?: CranePositionAnimator
+
+  /**
+   * data.cranePosition = { current: {x,y,z}, limit: {x|y|z:{min,max}} } 분기.
+   * current 를 limit 범위 안의 0~1 비율로 환산한 뒤, 부모 (보통 Stocker) 기준으로
+   * 실 좌표 (state.left/top) 와 forkZ 로 변환해 lerp 시작. x→host 긴쪽, y→짧은쪽,
+   * z→포크 높이. 보간 중 새 값이 들어오면 *현재 보간 위치* 를 from 으로 잡고 새
+   * target 으로 새 lerp 시작.
+   * NODEID 경로는 super (MCSVehicle.onchangeData) 가 처리 — cranePosition 만 있는
+   * 데이터에선 NODEID 가 없어 자연스럽게 noop.
+   */
+  onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    const afterData = after?.data
+    // 데이터 키는 모두 대문자 전제. CRANEPOSITION 의 중첩 키(CURRENT/LIMIT/X/Y/Z/MIN/MAX)는
+    // normalizeCranePosition 이 내부 표준형(소문자)으로 변환. DURATION_MS 는 사용하지 않음.
+    const afterCP = normalizeCranePosition(afterData?.CRANEPOSITION)
+    if (afterCP) {
+      const beforeCP = normalizeCranePosition(before?.data?.CRANEPOSITION)
+      if (this._cranePositionChanged(afterCP, beforeCP)) {
+        this._startPositionAnimation(afterCP)
+      }
+    }
+    super.onchangeData(after, before)
+  }
+
+  /** current 또는 limit 중 하나라도 바뀌면 재계산 필요 (limit 변화도 실 위치를 바꿈). */
+  private _cranePositionChanged(a: CranePositionData, b?: CranePositionData): boolean {
+    if (!b) return true
+    return (
+      JSON.stringify(a?.current ?? null) !== JSON.stringify(b?.current ?? null) ||
+      JSON.stringify(a?.limit ?? null) !== JSON.stringify(b?.limit ?? null)
+    )
+  }
+
+  dispose() {
+    if (this._posAnimator) {
+      this._posAnimator.unsubscribe()
+      this._posAnimator = undefined
+    }
+    super.dispose()
+  }
+
+  private _startPositionAnimation(cranePosition: CranePositionData, durationMs?: number): void {
+    const target = this._ratioToReal(cranePosition)
+    if (!target) return // 부모(host) 없거나 크기 0 이면 변환 skip
+
+    const now = frameClock.simTime
+    const duration = Math.max(1, Number(durationMs) || DEFAULT_DURATION_MS)
+
+    // 현재 위치 — 보간 중이면 그 시점 보간값을 from 으로
+    let fromLeft = Number(this.state.left) || 0
+    let fromTop = Number(this.state.top) || 0
+    let fromForkZ = Number((this.state as any).forkZ) || 0
+
+    if (this._posAnimator) {
+      const a = this._posAnimator
+      const t = Math.min(1, Math.max(0, (now - a.startTime) / a.duration))
+      const e = easeInOut(t)
+      fromLeft = lerp(a.fromLeft, a.toLeft, e)
+      fromTop = lerp(a.fromTop, a.toTop, e)
+      fromForkZ = lerp(a.fromForkZ, a.toForkZ, e)
+      a.unsubscribe()
+      this._posAnimator = undefined
+    }
+
+    const unsubscribe = frameClock.subscribe(
+      (_dt: number, simTime: number) => this._tickPositionAnimation(simTime),
+      { description: 'crane-position', component: this }
+    )
+
+    this._posAnimator = {
+      fromLeft,
+      fromTop,
+      fromForkZ,
+      toLeft: target.left,
+      toTop: target.top,
+      toForkZ: target.forkZ,
+      startTime: now,
+      duration,
+      unsubscribe
+    }
+    // 즉시 첫 frame 반영 (t=0) — set 한 번 호출. paused 환경에서도 from→target
+    // 진입 시점이 명확.
+    this._tickPositionAnimation(now)
+  }
+
+  private _tickPositionAnimation(simTime: number): void {
+    const a = this._posAnimator
+    if (!a) return
+    const t = Math.min(1, Math.max(0, (simTime - a.startTime) / a.duration))
+    const e = easeInOut(t)
+    this.set({
+      left: lerp(a.fromLeft, a.toLeft, e),
+      top: lerp(a.fromTop, a.toTop, e),
+      forkZ: lerp(a.fromForkZ, a.toForkZ, e)
+    })
+    if (t >= 1) {
+      a.unsubscribe()
+      this._posAnimator = undefined
+    }
+  }
+
+  /**
+   * cranePosition (current + limit) → state.left/top + forkZ.
+   *
+   * 부모 오브젝트 (보통은 Stocker 이지만 다른 컨테이너일 수도) 의 width/height
+   * 만 사용해 좌표 매핑 — 타입 무관 일반화. 가상 rail 은 host 의 긴쪽:
+   *   - current.x → host 의 긴쪽 (자동 판별: max(width, height))
+   *   - current.y → 짧은쪽
+   *   - current.z → forkZ (state 에 0~100 으로 저장, 3D 측에서 mast 비율로 매핑)
+   *
+   * 각 축 비율 = (current - limit.min) / (limit.max - limit.min) ∈ [0,1].
+   *
+   * **스토커 안쪽 오프셋**: 크레인의 폭/두께를 감안해, 크레인 *전체* 가 host 안에
+   * 머무르도록 top-left 좌표를 [0, hostLen - craneLen] 범위로 매핑한다 (= 양끝에서
+   * craneLen/2 만큼 inset 된 중심선 위를 움직임). 크레인이 host 보다 크면 span 0
+   * 으로 떨어져 host 모서리에 정렬.
+   *
+   * 참조는 ParentObjectMixin 이 제공하는 `parentObject` 사용 —
+   * state.parentObjectId 명시 시 그것, 미명시 시 this.parent 자동 fallback.
+   */
+  private _ratioToReal(
+    cp: CranePositionData
+  ): { left: number; top: number; forkZ: number } | undefined {
+    const host: any = (this as any).parentObject
+    if (!host) return undefined
+
+    const hw = Number(host.state?.width) || 0
+    const hh = Number(host.state?.height) || 0
+    const cw = Number(this.state.width) || 0
+    const ch = Number(this.state.height) || 0
+    if (!hw || !hh) return undefined
+
+    const rx = axisRatio(cp.current?.x, cp.limit?.x)
+    const ry = axisRatio(cp.current?.y, cp.limit?.y)
+    const rz = axisRatio(cp.current?.z, cp.limit?.z)
+
+    const { left, top } = mapCraneLocalPosition(hw, hh, cw, ch, rx, ry)
+
+    return {
+      left,
+      top,
+      forkZ: rz * 100 // forkZ 0~100, 3D 측 (crane-3d) 에서 mast 비율로 매핑
+    }
+  }
+
   render(ctx: CanvasRenderingContext2D) {
     var { left, top, width, height } = this.bounds
     const { x: cx, y: cy } = this.center