@fmsim/machine 2.0.0-beta.85 → 2.0.0-beta.87

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fmsim/machine",
   "description": "Layout View를 구성하는 설비(machine)들과 유닛을 구현한 모듈입니다.",
   "author": "heartyoh",
-  "version": "2.0.0-beta.85",
+  "version": "2.0.0-beta.87",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "things-scene": true,
@@ -55,5 +55,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "3ff0a6795182a63df8316412d63e48751cdc737e"
+  "gitHead": "3d1cc31e42d90dc514506aa1e85b34660144d89f"
 }

package/src/carrier-manager.ts

@@ -2,7 +2,30 @@ import { Model } from '@hatiolab/things-scene'
 import type Carrier from './carrier'
 import type MCSCarrierHolder from './mcs-carrier-holder'
 
-const DYING_TIMEOUT = 1000
+// 사라진 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()
@@ -17,58 +40,137 @@ export default class CarrierManager {
     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 afterName = after?.CARRIERNAME
-    const beforeName = before?.CARRIERNAME
+    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))
 
-    // 이전에는 캐리어가 있었는데 새 데이터에는 없다 → dying 후보
-    if (beforeName && (beforeName !== afterName || !afterName)) {
-      const carrier = this.carriers.get(beforeName)
+    // 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(beforeName)
+        this.scheduleDying(name)
       }
-      return
     }
 
-    if (!afterName) {
-      return
-    }
+    // 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?.()
+      }
+    })
+  }
 
-    // dying 상태면 구출
-    const wasDying = this.dyingTimers.has(afterName)
-    this.cancelDying(afterName)
-
-    const { width, height } = holder.state
-    let carrier = this.carriers.get(afterName)
-
-    if (!carrier) {
-      // 새로 생성
-      carrier = Model.compile(
-        {
-          id: afterName,
-          type: 'Carrier',
-          left: 0,
-          top: 0,
-          width,
-          height,
-          showText: holder.getState('showCarrierText') || false
-        },
-        this.root.app
-      ) as unknown as Carrier
-
-      this.carriers.set(afterName, carrier)
-      carrier.data = after
-      holder.addComponent(carrier, { silent: true })
-    } else if (carrier.parent !== holder && (!beforeName && afterName)) {
-      // CARRIERNAME이 새로 나타남 (이전엔 없었음) → 다른 holder로 이동
-      ;(holder as any).reparent(carrier, { animated: true, duration: 2000, ease: 'inout' })
+  /**
+   * data.CARRIERNAME (대표) + data.ADDITIONS[] 를 하나의 stack list 로 정규화.
+   * 적층 순서: ADDITIONS[0..n-1] (bottom → up) + 대표 (top, 맨 마지막).
+   */
+  private _buildStack(data: any): CarrierStackItem[] {
+    if (!data) return []
+
+    const stack: CarrierStackItem[] = []
+
+    if (Array.isArray(data.ADDITIONS)) {
+      for (const a of data.ADDITIONS) {
+        if (a && typeof a === 'object' && a.CARRIERNAME) {
+          // 항목 *원본 그대로* — 외부 시스템이 임의 키를 추가로 보낼 수 있고,
+          // 누락된 4 키는 default 없이 그대로 비워둔다 (carrier.data 에 흘리는
+          // 가공 최소화 — F03 같은 기존 테스트의 raw shape 기대와도 정합).
+          stack.push({ ...a } as CarrierStackItem)
+        }
+      }
     }
 
-    if (carrier.parent === holder) {
-      carrier.data = after
+    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)
 

package/src/carrier.ts

@@ -13,6 +13,7 @@ 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
@@ -59,7 +60,11 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
   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) {
@@ -270,6 +275,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)

package/src/crane.ts

@@ -1,4 +1,4 @@
-import { Component, ComponentNature, 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'
 
@@ -11,6 +11,33 @@ const NATURE: ComponentNature = {
 
 const GAP = 2
 
+/** 좌표 보간 기본 duration (ms). data.DURATION_MS 가 없으면 이 값 사용. */
+const DEFAULT_DURATION_MS = 1000
+
+function clamp01(v: number): number {
+  return Math.max(0, Math.min(100, Number(v) || 0))
+}
+
+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() {
@@ -25,6 +52,149 @@ export default class Crane extends MCSVehicle {
     return (this.root as any).craneLegendTheme || super.getLegendFallback()
   }
 
+  private _posAnimator?: CranePositionAnimator
+
+  /**
+   * data.POSITION = { X, Y, Z } (각 0~100 정규화) 분기. Stocker 부모 기준으로
+   * 실 좌표 (state.left/top) 와 forkZ 로 변환해 lerp 시작. 보간 중 새 값이
+   * 들어오면 *현재 보간 위치* 를 from 으로 잡고 새 target 으로 새 lerp 시작.
+   * NODEID 경로는 super (MCSVehicle.onchangeData) 가 처리 — POSITION 만 있는
+   * 데이터에선 NODEID 가 없어 자연스럽게 noop.
+   */
+  onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    const afterData = after?.data
+    const beforeData = before?.data
+    const afterPos = afterData?.POSITION
+    if (afterPos && typeof afterPos === 'object') {
+      const beforePos = beforeData?.POSITION
+      const changed =
+        afterPos.X !== beforePos?.X ||
+        afterPos.Y !== beforePos?.Y ||
+        afterPos.Z !== beforePos?.Z
+      if (changed) {
+        this._startPositionAnimation(afterPos, afterData?.DURATION_MS)
+      }
+    }
+    super.onchangeData(after, before)
+  }
+
+  dispose() {
+    if (this._posAnimator) {
+      this._posAnimator.unsubscribe()
+      this._posAnimator = undefined
+    }
+    super.dispose()
+  }
+
+  private _startPositionAnimation(
+    pos: { X: number; Y: number; Z: number },
+    durationMs?: number
+  ): void {
+    const target = this._normalizedToReal(pos)
+    if (!target) return // 부모가 Stocker 아니면 변환 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
+    }
+  }
+
+  /**
+   * 0~100 정규화 좌표 → state.left/top + forkZ.
+   *
+   * 부모 오브젝트 (보통은 Stocker 이지만 다른 컨테이너일 수도) 의 width/height
+   * 만 사용해 좌표 매핑 — 타입 무관 일반화. 가상 rail 은 host 의 긴쪽 중심부
+   * 가정:
+   *   - 데이터.X → host 의 긴쪽 (자동 판별: max(width, height))
+   *   - 데이터.Y → 짧은쪽 (rail 중심 = 50 근처가 일반적)
+   *   - 데이터.Z → forkZ (state 에 0~100 그대로 저장, 3D 측에서 mast 비율로 매핑)
+   *
+   * 참조는 ParentObjectMixin 이 제공하는 `parentObject` 사용 —
+   * state.parentObjectId 명시 시 그것, 미명시 시 this.parent 자동 fallback.
+   */
+  private _normalizedToReal(
+    pos: { X: number; Y: number; Z: number }
+  ): { 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 longIsWidth = hw >= hh
+    const longLen = longIsWidth ? hw : hh
+    const shortLen = longIsWidth ? hh : hw
+    const craneLongSize = longIsWidth ? cw : ch
+    const craneShortSize = longIsWidth ? ch : cw
+
+    const X = clamp01(pos.X)
+    const Y = clamp01(pos.Y)
+
+    // crane 의 *center* 가 (X/100)*longLen, (Y/100)*shortLen 에 오도록.
+    // state.left/top 은 top-left 기준이므로 size/2 차감.
+    const longPos = (X / 100) * longLen - craneLongSize / 2
+    const shortPos = (Y / 100) * shortLen - craneShortSize / 2
+
+    return {
+      left: longIsWidth ? longPos : shortPos,
+      top: longIsWidth ? shortPos : longPos,
+      forkZ: clamp01(pos.Z)
+    }
+  }
+
   render(ctx: CanvasRenderingContext2D) {
     var { left, top, width, height } = this.bounds
     const { x: cx, y: cy } = this.center

package/src/factories/crane-3d.ts

@@ -22,11 +22,29 @@ const FORK_COLOR = 0x999999
 const DEFAULT_BODY_COLOR = 0xcc8844
 
 export class Crane3D extends RealObjectGroup {
+  /** 캐리지 포크 group — Crane.state.forkZ (0~100) 가 변하면 position.y 만 lerp.
+   *  build() 시 inner 에 add 되고, *_mastBaseY 와 mastH 를 함께 보관* 해서
+   *  setForkZ 가 비율 계산에 사용. */
+  private forkGroup?: THREE.Group
+  private forkMastBaseY = 0
+  private forkMastH = 0
+
   get effectiveDepth(): number {
     const { depth } = this.component.state
     return depth || 5 * TRANSPORT_SURFACE_HEIGHT - 2
   }
 
+  /**
+   * 0~100 정규화 z (= state.forkZ) 를 mast 높이 비율로 변환해서 포크 group 의
+   * three-up y 위치 갱신. build() 가 안 끝났으면 noop — build 가 forkZ 를 다시
+   * 반영하면서 끝난다.
+   */
+  applyForkZ(z: number): void {
+    if (!this.forkGroup) return
+    const clamped = Math.max(0, Math.min(100, Number(z) || 0))
+    this.forkGroup.position.y = this.forkMastBaseY + (clamped / 100) * this.forkMastH
+  }
+
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -115,8 +133,10 @@ export class Crane3D extends RealObjectGroup {
     mastMesh.castShadow = true
     inner.add(mastMesh)
 
-    // ── 3. 캐리지 포크 (마스트 40% 높이, 양쪽으로 뻗는 포크 암) ──
-    const forkY = mastBaseY + mastH * 0.4
+    // ── 3. 캐리지 포크 (별도 group — state.forkZ 변경 시 group.position.y lerp) ──
+    // 포크 geometry 는 *_mastBaseY 기준 local 0 에 둠* — 즉 group.position.y = 0
+    // 일 때 mast 바닥 자리에. forkZ 0~100 에 따라 group.position.y 만 변경하면
+    // mast 따라 위/아래 이동. mesh 재구축 불필요.
     const forkMat = new THREE.MeshStandardMaterial({
       color: FORK_COLOR,
       roughness: 0.4,
@@ -125,15 +145,13 @@ export class Crane3D extends RealObjectGroup {
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
-    // 캐리지 중심 플레이트 (마스트에 부착, 양쪽 포크의 베이스)
     const plateW = w * 0.9
     const plateH = d * 0.08
     const plateD = pillarThick * 0.8
     const centerPlate = new THREE.BoxGeometry(plateW, plateH, plateD)
-    centerPlate.translate(0, forkY + plateH / 2, 0)
+    centerPlate.translate(0, plateH / 2, 0) // local 0 = mast 바닥
     forkGeometries.push(centerPlate)
 
-    // 양쪽 포크 암 (좌/우 선반 방향으로 뻗음)
     const armW = pillarThick * 0.6
     const armH = plateH * 0.4
     const armD = h * 0.6
@@ -142,14 +160,27 @@ export class Crane3D extends RealObjectGroup {
     for (const zSign of [-1, 1]) {
       for (const xSign of [-1, 1]) {
         const arm = new THREE.BoxGeometry(armW, armH, armD)
-        arm.translate(xSign * (armSpacing / 2), forkY + armH / 2, zSign * (plateD / 2 + armD / 2))
+        arm.translate(xSign * (armSpacing / 2), armH / 2, zSign * (plateD / 2 + armD / 2))
         forkGeometries.push(arm)
       }
     }
 
     const forkMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(forkGeometries), forkMat)
     forkMesh.castShadow = true
-    inner.add(forkMesh)
+
+    const forkGroup = new THREE.Group()
+    forkGroup.add(forkMesh)
+    inner.add(forkGroup)
+    this.forkGroup = forkGroup
+    this.forkMastBaseY = mastBaseY
+    // forkZ=100 시점에 mast 의 *_위쪽 한계*. 포크 자체 두께 (plateH) 만큼은 마스트
+    // 안에 머무르도록 limit 보정 — 그렇지 않으면 forkZ=100 일 때 포크가 상단
+    // 클램프와 충돌. mastH * 0.92 로 약간 보수적 (= 마스트 본체 92% 까지만 이동).
+    this.forkMastH = mastH * 0.92
+
+    // 초기 forkZ 반영 — state.forkZ 가 이미 set 되어 있으면 그 위치에 배치
+    const initialForkZ = Number((this.component.state as any).forkZ)
+    this.applyForkZ(Number.isFinite(initialForkZ) ? initialForkZ : 0)
 
     // ── 4. 상단 클램프 (천장 레일에 물리는 가이드부) ──
     const topClampGeo = new THREE.BoxGeometry(clampW, clampH, clampD)
@@ -162,11 +193,23 @@ export class Crane3D extends RealObjectGroup {
   updateDimension() {}
   updateAlpha() {}
 
+  /** build() 직전 호출. forkGroup 참조를 깨끗이 비워둔다 — 새 build 가 다시 set. */
+  clear() {
+    this.forkGroup = undefined
+    super.clear()
+  }
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after || 'fillStyle' in after || 'strokeStyle' in after) {
       this.update()
       return
     }
+    // forkZ 는 mesh 재구축 없이 group.position.y 만 갱신. 같은 onchange 에서
+    // left/top 도 함께 변경될 수 있으므로 super 도 반드시 호출해 본체 transform
+    // 갱신 path (state.left/top → obj3d.position.x/z) 가 동작하게 함.
+    if ('forkZ' in after) {
+      this.applyForkZ(Number(after.forkZ) || 0)
+    }
     super.onchange(after, before)
   }
 }

package/src/factories/machine-3d.ts

@@ -770,7 +770,7 @@ class StockerRealObject3D extends MCSRealObject3D {
         const max = Number(data.MAXCAPACITY) || 100
         const fullup = data.FULLUP === 'T'
         const usage = Math.round((cur / max) * 100)
-        const legend = (this.component as any).root?.style?.LEGEND_CAPACITY || LEGEND_CAPACITY
+        const legend = (this.component as any).root?.stockerCapacityLegendTheme || LEGEND_CAPACITY
         const color = fullup ? 'red' : (getValueOnRanges(usage, legend) || '#44aa44')
         return {
           segments: [{ ratio: usage / 100, color }],
@@ -852,10 +852,48 @@ const CARRIER_CONFIG: MCS3DConfig = {
   // Carrier 는 이동 entity — default OBJECTS(0). zPriority 미설정.
 }
 
+/**
+ * 적층 시 다음 carrier 의 z-position 이 *_이전 carrier 의 effectiveDepth × N*
+ * 만큼 위에 놓인다. N=1 이면 carrier 들이 맞붙어 적층 (기존), N<1 이면 부분
+ * overlap (3D box 들이 겹쳐서 적층). 사용자 의도 — carrier 두께는 두꺼워도
+ * 적층 시 *_compact 하게 보이도록* — N 을 작게.
+ */
+const CARRIER_STACK_STEP_RATIO = 0.9
+
 class CarrierRealObject3D extends MCSRealObject3D {
   constructor(component: Component) {
     super(component, CARRIER_CONFIG)
   }
+
+  /**
+   * cz override — *carrier 자기 결정* 의 적층 위치.
+   * parent.components 안 자기 index 까지의 형제 carrier 들의 effectiveDepth
+   * 누적합을 base cz 위에 더한다. holder 측에 별도 layout 책임을 두지 않고,
+   * carrier 가 자기 stack 위치를 알아서 결정.
+   */
+  override get cz(): number {
+    const base = super.cz
+    const parent = this.component.parent as any
+    if (!parent?.components) return base
+    const siblings = parent.components as any[]
+    const idx = siblings.indexOf(this.component)
+    if (idx <= 0) return base
+    let offset = 0
+    for (let i = 0; i < idx; i++) {
+      const ro = siblings[i]?._realObject
+      const eff = Number(ro?.effectiveDepth)
+      const d = Number.isFinite(eff) && eff > 0 ? eff : 1
+      offset += d * CARRIER_STACK_STEP_RATIO
+    }
+    // 적층 방향 — placement (= 부모 holder 타입) 에 따라 결정.
+    // OHT 처럼 그리퍼 아래에 매달리는 holder 는 carrier 가 *_아래로_* 누적,
+    // 그 외 (Port / Shelf / Shuttle / Vehicle) 는 위로 누적.
+    // MCSRealObject3D.syncZPosOffset 의 OHT 분기 (-effectiveDepth + halfD) 와
+    // 같은 방향성 일관 적용.
+    const parentType = parent?.state?.type
+    const dir = parentType === 'OHT' ? -1 : 1
+    return base + dir * offset
+  }
 }
 
 registerRealObjectFactory('Carrier', (component: Component) => new CarrierRealObject3D(component))

package/src/features/mcs-status-default.ts

@@ -64,7 +64,8 @@ export const LEGEND_CARRIER: Legend = {
 export const LEGEND_CAPACITY: Legend = {
   '0~20': '#5630D0',
   '20~80': '#8BDA5B',
-  '80~100': '#FD9B00',
+  '80~': '#FD9B00',     // 80% 이상 (= 100% 초과도 포함). 'from~' 형식이라
+                        // getValueOnRanges 가 value >= 80 매칭.
   default: '#F0F0F0'
 }