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

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

@@ -12,7 +12,7 @@
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js'
-import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 
@@ -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 {
@@ -77,13 +77,10 @@ export class OHT3D extends RealObjectGroup {
     const armThickness = Math.min(w, h) * 0.12
     const bodyCornerR = Math.min(w, h, bodyH) * 0.1
 
-    const frameMat = new THREE.MeshStandardMaterial({
-      color: FRAME_COLOR,
-      roughness: 0.5,
-      metalness: 0.4,
-    })
+    // MaterialBank 공유 — dedup + faint 안전(코어 변형 스왑, disposeObject3D 가 __bankOwned 스킵).
+    const frameMat = MaterialBank.material('oht|frame', { roughness: 0.5, metalness: 0.4 }, FRAME_COLOR)
 
-    // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바) ──
+    // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바 — 이동 방향과 직교) ──
     const gripperBarW = w * 0.7
     const gripperBarD = h * 0.15
     const gripperGeo = new THREE.BoxGeometry(gripperBarW, gripperBarH, gripperBarD)
@@ -91,21 +88,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)
 
@@ -116,53 +113,48 @@ export class OHT3D extends RealObjectGroup {
     const bodyBaseY = armBaseY + armH
     const bodyColor = this.resolveColor()
     const bodyGeo = new RoundedBoxGeometry(w, bodyH, h, 4, bodyCornerR)
-    const bodyMat = new THREE.MeshStandardMaterial({
-      color: bodyColor,
-      roughness: 0.3,
-      metalness: 0.5,
-    })
+    const bodyMat = MaterialBank.material('oht|body', { roughness: 0.3, metalness: 0.5 }, bodyColor)
     const bodyMesh = new THREE.Mesh(bodyGeo, bodyMat)
     bodyMesh.position.y = bodyBaseY + bodyH / 2
     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,
-      roughness: 0.6,
-      metalness: 0.3,
-    })
+    const trolleyMat = MaterialBank.material('oht|trolley', { roughness: 0.6, metalness: 0.3 }, TROLLEY_COLOR)
     const trolleyMesh = new THREE.Mesh(trolleyGeo, trolleyMat)
     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)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
 
   update() {
     for (const m of this._ownMeshes) {
-      this.object3d.remove(m)
+      this.components3D.remove(m)
       disposeObject3D(m)
     }
     this._ownMeshes = []
@@ -172,16 +164,8 @@ export class OHT3D extends RealObjectGroup {
     this.updateHidden()
   }
 
-  updateAlpha() {
-    const { alpha = 1 } = this.component.state
-    for (const m of this._ownMeshes) {
-      const materials = Array.isArray(m.material) ? m.material : [m.material]
-      for (const mat of materials) {
-        ;(mat as THREE.MeshStandardMaterial).opacity = alpha
-        ;(mat as THREE.MeshStandardMaterial).transparent = alpha < 1
-      }
-    }
-  }
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // canonical(bank base opacity 1) × state.alpha × faint. view 모드 불변, 편집 모드 faint 추가.
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after ||

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

@@ -12,7 +12,7 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 
@@ -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
 
@@ -72,11 +68,9 @@ export class Shuttle3D extends RealObjectGroup {
     // ── 1. 하단 베이스 플레이트 (납작하고 넓은 주행부) ──
     const basePad = Math.min(w, h) * 0.05
     const baseGeo = new THREE.BoxGeometry(w + basePad * 2, baseH, h + basePad * 2)
-    const baseMat = new THREE.MeshStandardMaterial({
-      color: BASE_COLOR,
-      roughness: 0.7,
-      metalness: 0.3,
-    })
+    // MaterialBank 공유 — 정적/상태색 dedup + faint 안전(코어가 공유 base 변형 스왑). dispose 는
+    // disposeObject3D 가 __bankOwned 를 건너뛰어 안전.
+    const baseMat = MaterialBank.material('shuttle|base', { roughness: 0.7, metalness: 0.3 }, BASE_COLOR)
     const baseMesh = new THREE.Mesh(baseGeo, baseMat)
     baseMesh.position.y = baseH / 2
     baseMesh.castShadow = true
@@ -85,11 +79,7 @@ export class Shuttle3D extends RealObjectGroup {
     // ── 2. 좌우 마스트 기둥 (statusColor 적용) ──
     const mastBaseY = baseH
     const bodyColor = this.resolveColor()
-    const mastMat = new THREE.MeshStandardMaterial({
-      color: bodyColor,
-      roughness: 0.4,
-      metalness: 0.5,
-    })
+    const mastMat = MaterialBank.material('shuttle|mast', { roughness: 0.4, metalness: 0.5 }, bodyColor)
 
     const mastGeometries: THREE.BufferGeometry[] = []
 
@@ -112,11 +102,7 @@ export class Shuttle3D extends RealObjectGroup {
 
     // ── 3. 상단 포크 (2개의 평행 암 + 백 플레이트) ──
     const forkBaseY = mastBaseY + mastH
-    const forkMat = new THREE.MeshStandardMaterial({
-      color: FORK_COLOR,
-      roughness: 0.4,
-      metalness: 0.6,
-    })
+    const forkMat = MaterialBank.material('shuttle|fork', { roughness: 0.4, metalness: 0.6 }, FORK_COLOR)
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
@@ -142,14 +128,17 @@ 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)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
 
   update() {
     for (const m of this._ownMeshes) {
-      this.object3d.remove(m)
+      this.components3D.remove(m)
       disposeObject3D(m)
     }
     this._ownMeshes = []
@@ -159,16 +148,9 @@ export class Shuttle3D extends RealObjectGroup {
     this.updateHidden()
   }
 
-  updateAlpha() {
-    const { alpha = 1 } = this.component.state
-    for (const m of this._ownMeshes) {
-      const materials = Array.isArray(m.material) ? m.material : [m.material]
-      for (const mat of materials) {
-        ;(mat as THREE.MeshStandardMaterial).opacity = alpha
-        ;(mat as THREE.MeshStandardMaterial).transparent = alpha < 1
-      }
-    }
-  }
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // 코어가 canonical(=bank base, opacity 1) 위에 state.alpha × faint 를 일괄. view 모드는
+  // 1×state.alpha = 기존 in-place 결과와 동일 → 불변, 편집 모드만 faint 추가.
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after ||

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'