@fmsim/machine 2.0.0-beta.84 → 2.0.0-beta.86

package/package.json

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

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
@@ -33,6 +34,10 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
     return NATURE
   }
 
+  get decorators() {
+    return ['decotag']
+  }
+
   get path() {
     if (!this.parent) {
       return []
@@ -55,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) {
@@ -266,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/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'
 }
 

package/src/mcs-carrier-holder.ts

@@ -1,6 +1,18 @@
 import { themesColorMap, themesAnimationMap } from '@fmsim/api'
 import MCSUnit from './mcs-unit.js'
 
+/**
+ * Holder.data 변경 감지 시 carrierManager 에 전달할 4 키 묶음 + ADDITIONS 배열.
+ * 비교 결과 단 하나라도 다르면 carrierManager.update 호출.
+ */
+const CARRIER_DATA_KEYS = ['CARRIERNAME', 'CARRIERTYPE', 'EMPTYTYPE', 'CARRIERSTATUS'] as const
+
+function additionsChanged(a: any, b: any): boolean {
+  // shallow JSON 비교로 충분 — 각 항목이 4 키 primitive 만 가짐. 깊은 ref 비교
+  // 보다 빠르고 정확. 빈/누락은 같은 '[]' 직렬화로 동치 취급.
+  return JSON.stringify(a?.ADDITIONS ?? []) !== JSON.stringify(b?.ADDITIONS ?? [])
+}
+
 export default class MCSCarrierHolder extends MCSUnit {
   static get properties(): any {
     return [
@@ -26,6 +38,8 @@ export default class MCSCarrierHolder extends MCSUnit {
         label: 'show-carrier-text',
         name: 'showCarrierText'
       }
+      // 적층 두께는 carrier 측 (Carrier.added) 에서 자기 default depth 를 결정.
+      // holder 측에는 별도 carrierDepth 속성을 두지 않는다.
     ]
   }
 
@@ -48,39 +62,38 @@ export default class MCSCarrierHolder extends MCSUnit {
   async ready() {
     super.ready()
 
-    const { CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS } = this.data || {}
-    
-    if(CARRIERNAME) {
-      ;(this.root as any).carrierManager.update(this, {
-        CARRIERNAME,
-        CARRIERTYPE,
-        EMPTYTYPE,
-        CARRIERSTATUS
-      }, undefined)
+    if (this._hasCarrierData(this.data)) {
+      ;(this.root as any).carrierManager.update(this, this.data || {}, undefined)
     }
   }
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
-    // CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS 이 변경되었을 때만 캐리어 관리자에게 알린다.
-    const { CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS } = after.data || {}
-    const { CARRIERNAME: beforeCARRIERNAME, CARRIERTYPE: beforeCARRIERTYPE = '', EMPTYTYPE: beforeEMPTYTYPE, CARRIERSTATUS: beforeCARRIERSTATUS } = before.data || {}
-    if(CARRIERNAME !== beforeCARRIERNAME ||
-      CARRIERTYPE !== beforeCARRIERTYPE ||
-      EMPTYTYPE !== beforeEMPTYTYPE ||
-      CARRIERSTATUS !== beforeCARRIERSTATUS) {
-      ;(this.root as any).carrierManager.update(this, {
-        CARRIERNAME,
-        CARRIERTYPE,
-        EMPTYTYPE,
-        CARRIERSTATUS
-      }, {
-        CARRIERNAME: beforeCARRIERNAME,
-        CARRIERTYPE: beforeCARRIERTYPE,
-        EMPTYTYPE: beforeEMPTYTYPE,
-        CARRIERSTATUS: beforeCARRIERSTATUS
-      })
+    const afterData = after.data || {}
+    const beforeData = before.data || {}
+
+    let changed = false
+    for (const k of CARRIER_DATA_KEYS) {
+      if (afterData[k] !== beforeData[k]) {
+        changed = true
+        break
+      }
+    }
+    if (!changed) {
+      changed = additionsChanged(afterData, beforeData)
+    }
+
+    if (changed) {
+      ;(this.root as any).carrierManager.update(this, afterData, beforeData)
     }
 
     super.onchangeData(after, before)
   }
+
+  /** data 안에 carrier 정보 (대표 또는 ADDITIONS) 가 하나라도 있는지. */
+  private _hasCarrierData(data: any): boolean {
+    if (!data) return false
+    if (data.CARRIERNAME) return true
+    if (Array.isArray(data.ADDITIONS) && data.ADDITIONS.some((a: any) => a?.CARRIERNAME)) return true
+    return false
+  }
 }

package/src/scene/root-container-override.ts

@@ -249,124 +249,59 @@ ModelLayer.prototype.onchange = function (after: any) {
   return _origModelLayerOnchange.call(this, after)
 }
 
-Object.defineProperty(RootContainer.prototype, 'equipmentLegendTheme', {
-  get: function () {
-    const { equipmentLegendName } = this.rootModel.state
-    return equipmentLegendName && this.state.style[equipmentLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'bufferLegendTheme', {
-  get: function () {
-    const { bufferLegendName } = this.rootModel.state
-    return bufferLegendName && this.state.style[bufferLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'agvlineLegendTheme', {
-  get: function () {
-    const { agvlineLegendName } = this.rootModel.state
-    return agvlineLegendName && this.state.style[agvlineLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'ohtlineLegendTheme', {
-  get: function () {
-    const { ohtlineLegendName } = this.rootModel.state
-    return ohtlineLegendName && this.state.style[ohtlineLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'conveyorLegendTheme', {
-  get: function () {
-    const { conveyorLegendName } = this.rootModel.state
-    return conveyorLegendName && this.state.style[conveyorLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'stokerLegendTheme', {
-  get: function () {
-    const { stokerLegendName } = this.rootModel.state
-    return stokerLegendName && this.state.style[stokerLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'agvLegendTheme', {
-  get: function () {
-    const { agvLegendName } = this.rootModel.state
-    return agvLegendName && this.state.style[agvLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'ohtLegendTheme', {
-  get: function () {
-    const { ohtLegendName } = this.rootModel.state
-    return ohtLegendName && this.state.style[ohtLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'shuttleLegendTheme', {
-  get: function () {
-    const { shuttleLegendName } = this.rootModel.state
-    return shuttleLegendName && this.state.style[shuttleLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'craneLegendTheme', {
-  get: function () {
-    const { craneLegendName } = this.rootModel.state
-    return craneLegendName && this.state.style[craneLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'shelfLegendTheme', {
-  get: function () {
-    const { shelfLegendName } = this.rootModel.state
-    return shelfLegendName && this.state.style[shelfLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'portLegendTheme', {
-  get: function () {
-    const { portLegendName } = this.rootModel.state
-    return portLegendName && this.state.style[portLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'carrierLegendTheme', {
-  get: function () {
-    const { carrierLegendName } = this.rootModel.state
-    return carrierLegendName && this.state.style[carrierLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'carrierAnimationTheme', {
-  get: function () {
-    const { carrierAnimationName } = this.rootModel.state
-    return carrierAnimationName && this.state.style[carrierAnimationName]
-  }
-})
+// === LegendTheme / AnimationTheme value resolve ===
+//
+// rootModel.state.style[name] 에 저장된 legend/animation 값은 보드 직렬화
+// 형태에 따라 (a) 정상 object 또는 (b) JSON 문자열 둘 다로 나타난다 (2026-06-09
+// 진단 — consumer 인 carrier.ts:animationPreset 이 같은 이유로 typeof string
+// 분기 + JSON5.parse 처리하는 선례 존재). LegendTheme getter 들이 이 분기를
+// 두지 않아 string 통과 → getValueOnRanges 매칭 실패 → 3D gauge 의 색상이
+// fallback 으로만 결정되던 증상.
+//
+// fix 는 getter 한 곳에서 lazy parse. WeakMap<state, Map<rawString, parsed>>
+// 으로 *raw string 자체를 key* — 보드 편집으로 raw 가 바뀌면 자연 무효화,
+// 같은 raw 의 반복 lookup 은 O(1). root 가 GC 되면 cache 도 같이 GC.
+const _legendParseCache = new WeakMap<object, Map<string, any>>()
 
-Object.defineProperty(RootContainer.prototype, 'stockerCapacityLegendTheme', {
-  get: function () {
-    const { stockerCapacityLegendName } = this.rootModel.state
-    return stockerCapacityLegendName && this.state.style[stockerCapacityLegendName]
+function parseLegendIfString(state: any, raw: any): any {
+  if (typeof raw !== 'string') return raw
+  let cache = _legendParseCache.get(state)
+  if (!cache) {
+    cache = new Map()
+    _legendParseCache.set(state, cache)
   }
-})
+  if (cache.has(raw)) return cache.get(raw)
+  let parsed: any
+  try { parsed = JSON.parse(raw) } catch { parsed = raw } // parse 실패 시 raw 보존
+  cache.set(raw, parsed)
+  return parsed
+}
 
-Object.defineProperty(RootContainer.prototype, 'zoneCapacityLegendTheme', {
-  get: function () {
-    const { zoneCapacityLegendName } = this.rootModel.state
-    return zoneCapacityLegendName && this.state.style[zoneCapacityLegendName]
+function legendThemeGetter(stateKey: string) {
+  return function (this: any) {
+    const name = this.rootModel.state[stateKey]
+    const raw = name && this.state.style[name]
+    return parseLegendIfString(this.state, raw)
   }
-})
+}
 
-Object.defineProperty(RootContainer.prototype, 'batteryRateLegendTheme', {
-  get: function () {
-    const { batteryRateLegendName } = this.rootModel.state
-    return batteryRateLegendName && this.state.style[batteryRateLegendName]
-  }
-})
+Object.defineProperty(RootContainer.prototype, 'equipmentLegendTheme', { get: legendThemeGetter('equipmentLegendName') })
+Object.defineProperty(RootContainer.prototype, 'bufferLegendTheme', { get: legendThemeGetter('bufferLegendName') })
+Object.defineProperty(RootContainer.prototype, 'agvlineLegendTheme', { get: legendThemeGetter('agvlineLegendName') })
+Object.defineProperty(RootContainer.prototype, 'ohtlineLegendTheme', { get: legendThemeGetter('ohtlineLegendName') })
+Object.defineProperty(RootContainer.prototype, 'conveyorLegendTheme', { get: legendThemeGetter('conveyorLegendName') })
+Object.defineProperty(RootContainer.prototype, 'stokerLegendTheme', { get: legendThemeGetter('stokerLegendName') })
+Object.defineProperty(RootContainer.prototype, 'agvLegendTheme', { get: legendThemeGetter('agvLegendName') })
+Object.defineProperty(RootContainer.prototype, 'ohtLegendTheme', { get: legendThemeGetter('ohtLegendName') })
+Object.defineProperty(RootContainer.prototype, 'shuttleLegendTheme', { get: legendThemeGetter('shuttleLegendName') })
+Object.defineProperty(RootContainer.prototype, 'craneLegendTheme', { get: legendThemeGetter('craneLegendName') })
+Object.defineProperty(RootContainer.prototype, 'shelfLegendTheme', { get: legendThemeGetter('shelfLegendName') })
+Object.defineProperty(RootContainer.prototype, 'portLegendTheme', { get: legendThemeGetter('portLegendName') })
+Object.defineProperty(RootContainer.prototype, 'carrierLegendTheme', { get: legendThemeGetter('carrierLegendName') })
+Object.defineProperty(RootContainer.prototype, 'carrierAnimationTheme', { get: legendThemeGetter('carrierAnimationName') })
+Object.defineProperty(RootContainer.prototype, 'stockerCapacityLegendTheme', { get: legendThemeGetter('stockerCapacityLegendName') })
+Object.defineProperty(RootContainer.prototype, 'zoneCapacityLegendTheme', { get: legendThemeGetter('zoneCapacityLegendName') })
+Object.defineProperty(RootContainer.prototype, 'batteryRateLegendTheme', { get: legendThemeGetter('batteryRateLegendName') })
 
 Object.defineProperty(RootContainer.prototype, 'vehicleAnimation', {
   get: function () {