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

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

@@ -30,9 +30,9 @@ export class OHT3D extends RealObjectGroup {
     return depth || TRANSPORT_SURFACE_HEIGHT
   }
 
-  /** 천장 레일 높이에 배치 */
+  /** 천장 레일 높이에 배치 (center origin 기준: 레일 높이 + 볼륨 중심 반깊이) */
   protected get syncZPosOffset(): number {
-    return OHT_RAIL_HEIGHT
+    return OHT_RAIL_HEIGHT + this.effectiveDepth / 2
   }
 
   private resolveColor(): number {
@@ -83,7 +83,7 @@ export class OHT3D extends RealObjectGroup {
       metalness: 0.4,
     })
 
-    // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바) ──
+    // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바 — 이동 방향과 직교) ──
     const gripperBarW = w * 0.7
     const gripperBarD = h * 0.15
     const gripperGeo = new THREE.BoxGeometry(gripperBarW, gripperBarH, gripperBarD)
@@ -91,21 +91,21 @@ export class OHT3D extends RealObjectGroup {
     gripperMesh.position.y = gripperBarH / 2
     gripperMesh.castShadow = true
 
-    // ── 2. 호이스트 암 (좌우 수직 기둥 + 하단 가로연결) ──
+    // ── 2. 호이스트 암 (전후 수직 기둥 + 하단 연결 바) ──
     const armBaseY = gripperBarH
     const armGeometries: THREE.BufferGeometry[] = []
 
-    // 좌우 수직 기둥
-    for (const xSign of [-1, 1]) {
+    // 전후 수직 기둥 (레일 방향 = Z축)
+    for (const zSign of [-1, 1]) {
       const pillar = new THREE.BoxGeometry(armThickness, armH, armThickness)
-      pillar.translate(xSign * (w * 0.3), armBaseY + armH / 2, 0)
+      pillar.translate(0, armBaseY + armH / 2, zSign * (h * 0.3))
       armGeometries.push(pillar)
     }
 
-    // 하단 가로 연결 바 (그리퍼와 암을 잇는 수평 바)
-    const crossBarW = w * 0.6 + armThickness
+    // 하단 연결 바 (레일 방향으로 연결)
+    const crossBarD = h * 0.6 + armThickness
     const crossBarH = armThickness * 0.6
-    const crossBar = new THREE.BoxGeometry(crossBarW, crossBarH, armThickness)
+    const crossBar = new THREE.BoxGeometry(armThickness, crossBarH, crossBarD)
     crossBar.translate(0, armBaseY + crossBarH / 2, 0)
     armGeometries.push(crossBar)
 
@@ -126,10 +126,10 @@ export class OHT3D extends RealObjectGroup {
     bodyMesh.castShadow = true
     bodyMesh.receiveShadow = true
 
-    // ── 4. 상단 트롤리 플레이트 (납작하고 넓은 레일 클램프) ──
+    // ── 4. 상단 트롤리 플레이트 (레일 방향으로 길게 — Z축) ──
     const trolleyBaseY = bodyBaseY + bodyH + gap
-    const trolleyW = w * 1.15
-    const trolleyD = h * 0.6
+    const trolleyW = w * 0.6
+    const trolleyD = h * 1.15
     const trolleyGeo = new THREE.BoxGeometry(trolleyW, trolleyH, trolleyD)
     const trolleyMat = new THREE.MeshStandardMaterial({
       color: TROLLEY_COLOR,
@@ -140,29 +140,29 @@ export class OHT3D extends RealObjectGroup {
     trolleyMesh.position.y = trolleyBaseY + trolleyH / 2
     trolleyMesh.castShadow = true
 
-    // ── 5. 좌우 바퀴 (트롤리 위, 레일을 타는 원통형 바퀴) ──
+    // ── 5. 전후 바퀴 (트롤리 위, 레일 방향 = Z축) ──
     const wheelBaseY = trolleyBaseY + trolleyH
     const wheelRadius = wheelH / 2
-    const wheelDepth = h * 0.2
+    const wheelDepth = w * 0.2
     const wheelMeshes: THREE.Mesh[] = []
-    for (const xSign of [-1, 1]) {
+    for (const zSign of [-1, 1]) {
       const wheelGeo = new THREE.CylinderGeometry(wheelRadius, wheelRadius, wheelDepth, 12)
-      wheelGeo.rotateX(Math.PI / 2)
+      wheelGeo.rotateZ(Math.PI / 2)
       const wheelMesh = new THREE.Mesh(wheelGeo, trolleyMat)
-      wheelMesh.position.set(xSign * (trolleyW * 0.35), wheelBaseY + wheelRadius, 0)
+      wheelMesh.position.set(0, wheelBaseY + wheelRadius, zSign * (trolleyD * 0.35))
       wheelMesh.castShadow = true
       wheelMeshes.push(wheelMesh)
     }
 
     this._ownMeshes = [gripperMesh, armMesh, bodyMesh, trolleyMesh, ...wheelMeshes]
-    for (const m of this._ownMeshes) this.object3d.add(m)
+    for (const m of this._ownMeshes) this.components3D.add(m)
   }
 
   updateDimension() {}
 
   update() {
     for (const m of this._ownMeshes) {
-      this.object3d.remove(m)
+      this.components3D.remove(m)
       disposeObject3D(m)
     }
     this._ownMeshes = []

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

@@ -27,10 +27,6 @@ export class Shuttle3D extends RealObjectGroup {
     return depth || TRANSPORT_SURFACE_HEIGHT
   }
 
-  protected get syncZPosOffset(): number {
-    return 0
-  }
-
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -142,14 +138,14 @@ export class Shuttle3D extends RealObjectGroup {
     forkMesh.castShadow = true
 
     this._ownMeshes = [baseMesh, mastMesh, forkMesh]
-    for (const m of this._ownMeshes) this.object3d.add(m)
+    for (const m of this._ownMeshes) this.components3D.add(m)
   }
 
   updateDimension() {}
 
   update() {
     for (const m of this._ownMeshes) {
-      this.object3d.remove(m)
+      this.components3D.remove(m)
       disposeObject3D(m)
     }
     this._ownMeshes = []

package/src/factories/z-priority-defaults.ts

@@ -0,0 +1,38 @@
+/*
+ * 기본 factory (RealObjectDomTexture) 를 쓰는 컴포넌트들에 대한 zPriority override.
+ *
+ * `factories/machine-3d.ts`, `conveyor-3d.ts`, `crane-rail-3d.ts` 등에 등록된
+ * 커스텀 RealObject 들은 자기 클래스에서 `get zPriority()` override. 그 외 컴포넌트는
+ * 기본 RealObjectDomTexture 를 쓰는데, 이 파일이 그것들도 priority 갖도록 등록.
+ *
+ * 패턴: registerRealObjectFactory(type, (component) => withZ(new RealObjectDomTexture(...), N))
+ */
+import { registerRealObjectFactory, RealObjectDomTexture } from '@hatiolab/things-scene'
+import type { Component } from '@hatiolab/things-scene'
+import { Z_FMSIM } from './z-priority'
+
+/** 주어진 RealObject 의 zPriority getter 를 override (instance level). */
+function withZ<T extends RealObjectDomTexture>(ro: T, zPriority: number): T {
+  Object.defineProperty(ro, 'zPriority', {
+    get: () => zPriority,
+    configurable: true
+  })
+  return ro
+}
+
+/** RealObjectDomTexture 기반 컴포넌트에 priority 일괄 등록 helper. */
+function registerWithPriority(type: string, zPriority: number) {
+  registerRealObjectFactory(type, (component: Component) =>
+    withZ(new RealObjectDomTexture(component), zPriority)
+  )
+}
+
+// ── 미등록 컴포넌트들 ──────────────────────────────────────
+registerWithPriority('ConveyorJoin', Z_FMSIM.CONVEYOR_JOIN)
+registerWithPriority('NodePath', Z_FMSIM.NODE_PATH)
+registerWithPriority('container', Z_FMSIM.STATIC_CONTAINER)
+registerWithPriority('FloatingContainer', Z_FMSIM.FLOATING_CONTAINER)
+registerWithPriority('popup', Z_FMSIM.POPUP)
+registerWithPriority('confidential-overlay', Z_FMSIM.CONFIDENTIAL_OVERLAY)
+registerWithPriority('StockerAbnormalBar', Z_FMSIM.STOCKER_ABNORMAL_BAR)
+registerWithPriority('StockerCarrierBar', Z_FMSIM.STOCKER_CARRIER_BAR)

package/src/factories/z-priority.ts

@@ -0,0 +1,60 @@
+/*
+ * fmsim 컴포넌트별 z-priority 상수.
+ *
+ * 같은 평면에 겹친 *다른 type 의* mesh 들이 GPU depth test 에서 결정적으로 정렬되도록
+ * 각 컴포넌트 type 마다 unique polygonOffset 값을 부여. 각 RealObject 가 자기 클래스에서
+ * `get zPriority(): number` override 로 이 상수 중 하나를 반환.
+ *
+ * 위치 (geometry vertex, object3d.position) 는 변경하지 않음 — depth buffer 의 fragment
+ * depth 값에만 미세 bias.
+ *
+ * 컨벤션 (높은 값 = 뒤로, 낮은 값 = 앞으로):
+ *
+ *   [14~17] 바닥 paths/lines (가장 뒤)
+ *   [11~13] 큰 영역 시각화 (container, 흐름 영역)
+ *   [10]    zone capacity bar (영역 표시)
+ *   [1~9]   바닥 설비 (facility)
+ *   [0]     이동 entity (AGV/OHT/Crane/Shuttle/Carrier) — default OBJECTS
+ *   [-1~-4] 설비 위 indicator bar (decal)
+ *   [-9~-10] overlay / popup (가장 앞)
+ */
+
+export const Z_FMSIM = {
+  // ── Floor paths (가장 뒤 — 바닥에 그려지는 선) ──────────────
+  AGV_LINE: 17,
+  OHT_LINE: 16,
+  CRANE_RAIL: 15,
+  NODE_PATH: 14,
+  PORT_FLOW: 13,
+
+  // ── Container 영역 ────────────────────────────────────────
+  STATIC_CONTAINER: 12,
+  FLOATING_CONTAINER: 11,
+
+  // ── Zone 표시 ─────────────────────────────────────────────
+  ZONE_CAPACITY_BAR: 10,
+
+  // ── 바닥 설비 (facility) ──────────────────────────────────
+  NODE: 9,
+  SCANNER: 8,
+  PORT: 7,
+  SHELF: 6,
+  STOCKER: 5,
+  CONVEYOR: 4,
+  CONVEYOR_JOIN: 3,
+  BUFFER: 2,
+  EQUIPMENT: 1,
+
+  // ── 이동 entity — priority 0 (default OBJECTS), polygonOffset 미적용 ──
+  // AGV, OHT, Crane, Shuttle, Carrier — override 안 함
+
+  // ── 설비 위 status indicator bar (decal) ─────────────────
+  MCS_GAUGE_CAPACITY_BAR: -1,
+  STOCKER_CAPACITY_BAR: -2,
+  STOCKER_CARRIER_BAR: -3,
+  STOCKER_ABNORMAL_BAR: -4,
+
+  // ── Overlay / popup (가장 앞) ──────────────────────────────
+  POPUP: -9,
+  CONFIDENTIAL_OVERLAY: -10
+} as const

package/src/features/conveyor-mixin.ts

@@ -50,7 +50,7 @@ function pattern(component: any) {
   return component._pattern
 }
 
-export function ConveyorMixin<TBase extends Constructor<Component>>(Base: TBase) {
+export function ConveyorMixin<TBase extends new (...args: any[]) => any>(Base: TBase): any {
   const A = class extends Base {
     _pattern
 

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

@@ -61,10 +61,24 @@ export const LEGEND_CARRIER: Legend = {
   default: '#F0F0F0'
 }
 
+/**
+ * carrier legend(테마) 해석 — carrier 컴포넌트(carrier.ts get legend)와 동일 로직 단일 소스.
+ * parent 에 carrierLegendName 이 지정되면 그 style 을, 아니면 board 전역 carrierLegendTheme,
+ * 둘 다 없으면 LEGEND_CARRIER 기본값. carrier 컴포넌트·스토커 게이지(2D/3D)가 공유한다.
+ */
+export function resolveCarrierLegend(component: any): Legend {
+  const carrierLegendName = component?.parent?.state?.carrierLegendName
+  if (carrierLegendName) {
+    return (component.root as any)?.style?.[carrierLegendName] || LEGEND_CARRIER
+  }
+  return (component.root as any)?.carrierLegendTheme || LEGEND_CARRIER
+}
+
 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/features/mcs-status-mixin.ts

@@ -1,12 +1,13 @@
+import { Component } from '@hatiolab/things-scene'
+import { themesColorMap } from '@fmsim/api'
+import { LEGEND_NULL } from './mcs-status-default'
+
 type Constructor<T = {}> = new (...args: any[]) => T
 
 interface Legend {
   [key: string]: string
 }
 
-import { themesColorMap } from '@fmsim/api'
-import { LEGEND_NULL } from './mcs-status-default'
-
 export const MCSStatusMixinProperties = [
   {
     type: 'select',
@@ -18,7 +19,7 @@ export const MCSStatusMixinProperties = [
   }
 ]
 
-export function MCSStatusMixin<TBase extends Constructor>(Base: TBase) {
+export function MCSStatusMixin<TBase extends Constructor<Component>>(Base: TBase): any {
   return class extends Base {
     isLVComponent() {
       return true
@@ -53,5 +54,26 @@ export function MCSStatusMixin<TBase extends Constructor>(Base: TBase) {
 
       return (status && legend && (legend[status] || legend[status!] || legend.default)) || legend?.default
     }
+
+    /**
+     * 데이터 변경 시 status 기반 색상을 state.fillStyle 로 반영.
+     * things-scene 표준 경로(updateFillStyle)가 2D/3D 모두 자동 갱신하도록 유도.
+     *
+     * 주의: state.fillStyle 이 runtime 색상으로 덮어써짐. 모델 저장 시 status 색상이
+     * 남을 수 있는 트레이드오프가 있음 (data-driven 컴포넌트의 fillStyle 은 의미상
+     * 초기값일 뿐 항상 status 가 덮어쓰는 것이 자연스러움).
+     */
+    onchangeData(after: any, before: any) {
+      // Base (mixin 인자) 의 onchangeData 를 렉시컬하게 호출.
+      // Object.getPrototypeOf(this) 는 leaf 를 가리켜 무한재귀되므로 Base.prototype 직접 사용.
+      const baseOnchange = (Base.prototype as any).onchangeData
+      if (typeof baseOnchange === 'function') {
+        baseOnchange.call(this, after, before)
+      }
+      const color = this.statusColor
+      if (color && color !== (this as any).state?.fillStyle) {
+        ;(this as any).setState('fillStyle', color)
+      }
+    }
   }
 }

package/src/features/mcs-zone-mixin.ts

@@ -10,7 +10,7 @@ export const MCSZoneMixinProperties = [
   }
 ]
 
-export function MCSZoneMixin<TBase extends Constructor<MCSUnit>>(Base: TBase) {
+export function MCSZoneMixin<TBase extends Constructor<MCSUnit>>(Base: TBase): any {
   return class extends Base {
     get zone(): string | undefined {
       return

package/src/features/parent-object-mixin.ts

@@ -4,15 +4,14 @@ import { Component } from '@hatiolab/things-scene'
 import MCSMachine from '../mcs-machine'
 import MCSUnit from '../mcs-unit'
 
-export const ParentObjectMixinProperties = [
-  {
-    type: 'string',
-    label: 'parent-object-id',
-    name: 'parentObjectId'
-  }
-]
+/**
+ * parentObjectId 는 generic property builder 가 아니라 property-sidebar 의 모델 참조
+ * 룩업(ox-input-entity-id, parentObjectTypes 기준 씬 머신/유닛 선택)으로 렌더한다.
+ * 따라서 NATURE 속성 목록에서는 제외 — 빈 배열.
+ */
+export const ParentObjectMixinProperties: any[] = []
 
-export function ParentObjectMixin<TBase extends Constructor<Component>>(Base: TBase) {
+export function ParentObjectMixin<TBase extends Constructor<Component>>(Base: TBase): any {
   return class extends Base {
     get parentObject(): MCSMachine | MCSUnit | undefined {
       const { id, parentObjectId } = this.state
@@ -32,5 +31,15 @@ export function ParentObjectMixin<TBase extends Constructor<Component>>(Base: TB
         return parent
       }
     }
+
+    /**
+     * parentObjectId 가 참조하는 모델 컴포넌트 타입들 — parentObject 후보를 모델(씬)에서
+     * 수집할 때 이 타입들로 거른다 (머신/유닛 무관, 복수 허용).
+     * 빈 배열(기본) 이면 모델의 모든 머신 (폴백). 참조 타입이 정해진 컴포넌트는 override:
+     *   AGV→['AGVLine'], OHT→['OHTLine'], Crane/Shelf→['STOCKER'], PortFlow→['Port'].
+     */
+    get parentObjectTypes(): string[] {
+      return []
+    }
   }
 }

package/src/floating-container.ts

@@ -42,6 +42,11 @@ const NATURE = {
 }
 @sceneComponent('FloatingContainer')
 export default class FloatingContainer extends Container {
+  // things-scene 의 `declare const Container_base` 패턴이 base 인스턴스 타입의 accessor
+  // 정보를 object-type property 로 평탄화하여 TS2611 발생. 동일 위치를 override 하는
+  // 케이스가 operato-scene 엔 없어 fmsim 만 영향. things-scene 측 mixin 타입 패턴이
+  // 개선되면 제거.
+  // @ts-expect-error TS2611
   get position() {
     return this.app?.isViewMode ? 'absolute' : 'static'
   }

package/src/index.ts

@@ -1,55 +1,74 @@
 // ── side-effect: scene override ──
-import './scene/root-container-override.js'
+import './scene/root-container-override'
 
 // ── side-effect: 3D factories ──
-import './factories/machine-3d.js'
-import './factories/conveyor-3d.js'
-import './factories/agv-3d.js'
-import './factories/oht-3d.js'
-import './factories/shuttle-3d.js'
-import './factories/crane-3d.js'
-import './factories/crane-rail-3d.js'
+import './factories/machine-3d'
+import './factories/conveyor-3d'
+import './factories/agv-3d'
+import './factories/oht-3d'
+import './factories/shuttle-3d'
+import './factories/crane-3d'
+import './factories/crane-rail-3d'
+// 기본 factory (RealObjectDomTexture) 쓰는 컴포넌트들의 z-priority override
+import './factories/z-priority-defaults'
 
 // ── side-effect: @sceneComponent 등록 (tree-shaking 방지) ──
-import './zone-capacity-bar.js'
-import './stocker-capacity-bar.js'
-import './stocker-carrier-bar.js'
-import './stocker-abnormal-bar.js'
-import './port-flow.js'
-import './agv-line.js'
-import './buffer.js'
-import './conveyor.js'
-import './conveyor-join.js'
-import './equipment.js'
-import './oht-line.js'
-import './stocker.js'
-import './crane-rail.js'
-import './agv.js'
-import './oht.js'
-import './shuttle.js'
-import './port.js'
-import './crane.js'
-import './shelf.js'
-import './carrier.js'
-import './node.js'
-import './node-path.js'
-import './floating-container.js'
-import './static-container.js'
-import './clickable-popup.js'
+// bars & overlays
+import './zone-capacity-bar'
+import './stocker-capacity-bar'
+import './stocker-carrier-bar'
+import './stocker-abnormal-bar'
+import './port-flow'
 
+// facilities
+import './agv-line'
+import './buffer'
+import './conveyor'
+import './conveyor-join'
+import './equipment'
+import './oht-line'
+import './stocker'
+import './crane-rail'
+import './scanner'
+
+// vehicles
+import './agv'
+import './oht'
+import './shuttle'
+
+// units
+import './port'
+import './crane'
+import './shelf'
+import './carrier'
+
+// topology
+import './node'
+import './node-path'
+
+// containers
+import './floating-container'
+import './static-container'
+import './clickable-popup'
+
+// ── groups ──
 export { default as MachineGroups } from './groups'
 
+// ── base classes ──
 export { default as MCSMachine } from './mcs-machine'
 export { default as MCSUnit } from './mcs-unit'
 export { default as MCSCarrierHolder } from './mcs-carrier-holder'
 export { default as MCSVehicle } from './mcs-vehicle'
 export { default as MCSTransport } from './mcs-transport'
+
+// ── bars & overlays ──
 export { default as ZoneCapacityBar } from './zone-capacity-bar'
 export { default as StockerCapacityBar } from './stocker-capacity-bar'
 export { default as StockerCarrierBar } from './stocker-carrier-bar'
 export { default as StockerAbnormalBar } from './stocker-abnormal-bar'
 export { default as PortFlow } from './port-flow'
 
+// ── facilities ──
 export { default as AGVLine } from './agv-line'
 export { default as Buffer } from './buffer'
 export { default as Conveyor } from './conveyor'
@@ -58,19 +77,24 @@ export { default as Equipment } from './equipment'
 export { default as OHTLine } from './oht-line'
 export { default as Stocker } from './stocker'
 export { default as CraneRail } from './crane-rail'
+export { default as Scanner } from './scanner'
 
+// ── vehicles ──
 export { default as AGV } from './agv'
 export { default as OHT } from './oht'
 export { default as Shuttle } from './shuttle'
 
+// ── units ──
 export { default as Port } from './port'
 export { default as Crane } from './crane'
 export { default as Shelf } from './shelf'
 export { default as Carrier } from './carrier'
 
+// ── topology ──
 export { default as Node } from './node'
 export { default as NodePath } from './node-path'
 
+// ── containers ──
 export { default as FloatingContainer } from './floating-container'
-export { default as StaticContainer } from './static-container.js'
+export { default as StaticContainer } from './static-container'
 export { default as ClickablePopup } from './clickable-popup'

package/src/mcs-carrier-holder.ts

@@ -1,7 +1,22 @@
-import { Model, Properties } from '@hatiolab/things-scene'
 import { themesColorMap, themesAnimationMap } from '@fmsim/api'
 import MCSUnit from './mcs-unit.js'
-import Carrier from './carrier.js'
+import { parseIfJsonString } from './utils/data-value'
+
+/**
+ * Holder.data 변경 감지 시 carrierManager 에 전달할 4 키 묶음 + multiCarriers 배열.
+ * 비교 결과 단 하나라도 다르면 carrierManager.update 호출.
+ * (데이터 키는 모두 대문자 전제 — 케이스 정규화 없이 직접 읽는다)
+ */
+const CARRIER_DATA_KEYS = ['CARRIERNAME', 'CARRIERTYPE', 'EMPTYTYPE', 'CARRIERSTATUS'] as const
+
+function multiCarriersChanged(a: any, b: any): boolean {
+  // MULTICARRIERS 값이 JSON 문자열로 올 수 있어 파싱 후 비교. shallow JSON 비교로 충분 —
+  // 각 항목이 4 키 primitive 만 가짐. 빈/누락은 같은 '[]' 직렬화로 동치 취급.
+  return (
+    JSON.stringify(parseIfJsonString(a?.MULTICARRIERS) ?? []) !==
+    JSON.stringify(parseIfJsonString(b?.MULTICARRIERS) ?? [])
+  )
+}
 
 export default class MCSCarrierHolder extends MCSUnit {
   static get properties(): any {
@@ -28,55 +43,63 @@ export default class MCSCarrierHolder extends MCSUnit {
         label: 'show-carrier-text',
         name: 'showCarrierText'
       }
+      // 적층 두께는 carrier 측 (Carrier.added) 에서 자기 default depth 를 결정.
+      // holder 측에는 별도 carrierDepth 속성을 두지 않는다.
     ]
   }
 
-  carrier?: Carrier | null
-
-  async ready() {
-    super.ready()
+  get showOverflow() {
+    return true
+  }
 
-    for (let component of this.components) {
-      this.removeComponent(component)
+  get hierarchy() {
+    return {
+      ...super.hierarchy,
+      components: []
     }
-
-    const { width, height } = this.state
-
-    this.carrier = Model.compile(
-      {
-        type: 'Carrier',
-        left: 0,
-        top: 0,
-        width,
-        height,
-        showText: this.getState('showCarrierText') || false
-      },
-      this.root.app
-    ) as any
-
-    this.addComponent(this.carrier!)
-
-    this.carrier!.data = this.data
   }
 
   dispose(): void {
-    this.carrier = null
-
+    ;(this.root as any)?.carrierManager?.update(this, {}, this.data)
     super.dispose()
   }
 
-  get hierarchy() {
-    return {
-      ...super.hierarchy,
-      components: []
+  async ready() {
+    super.ready()
+
+    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 {
-    if (this.carrier) {
-      this.carrier.data = this.data
+    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 = multiCarriersChanged(afterData, beforeData)
+    }
+
+    if (changed) {
+      ;(this.root as any).carrierManager.update(this, afterData, beforeData)
     }
 
     super.onchangeData(after, before)
   }
+
+  /** data 안에 carrier 정보 (대표 또는 multiCarriers) 가 하나라도 있는지. */
+  private _hasCarrierData(data: any): boolean {
+    if (!data) return false
+    if (data.CARRIERNAME) return true
+    const list = parseIfJsonString(data.MULTICARRIERS)
+    if (Array.isArray(list) && list.some((a: any) => a?.CARRIERNAME)) return true
+    return false
+  }
 }