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

package/src/stocker-abnormal-bar.ts

@@ -72,6 +72,11 @@ export default class StockerAbnormalBar extends ParentObjectMixin(RectPath(Shape
     return NATURE
   }
 
+  /** StockerAbnormalBar 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   get controls() {
     var { left, top, width, round, height } = this.state
     round = round == undefined ? 0 : safeRound(round, width, height)
@@ -232,7 +237,7 @@ export default class StockerAbnormalBar extends ParentObjectMixin(RectPath(Shape
     const {
       CARRIER_NORMAL = 0,
       CARRIER_ABNORMAL = 0
-    } = typeof this.data == 'object' ? this.data : {}
+    } = this.data && typeof this.data == 'object' ? this.data : {}
 
     this.setState({
       carrierNormal: Number(CARRIER_NORMAL) || 0,

package/src/stocker-capacity-bar.ts

@@ -9,10 +9,30 @@ import {
 } from '@hatiolab/things-scene'
 import { themesColorRange } from '@fmsim/api'
 import { MCSStatusMixin } from './features/mcs-status-mixin'
-import { LEGEND_CAPACITY, Legend } from './features/mcs-status-default'
+import { LEGEND_CAPACITY, Legend, resolveCarrierLegend } from './features/mcs-status-default'
 import { safeRound } from './utils/safe-round'
-import { getVaueOnRanges } from './utils/get-value-on-ranges'
+import { getValueOnRanges } from './utils/get-value-on-ranges'
 import { ParentObjectMixin, ParentObjectMixinProperties } from './features/parent-object-mixin'
+import { carrierSegments, abnormalSegments, carrierColorsFromLegend, GaugeSegment } from './utils/stocker-gauge'
+
+/**
+ * 스토커 게이지 (통합).
+ *
+ * 하나의 컴포넌트가 mode 에 따라 3가지 게이지를 표현한다:
+ *  - 'capacity'  : 용량 사용률(usage%) 채움 게이지 + high/low watermark (기본)
+ *  - 'carrier'   : 캐리어 상태비율 세그먼트 (Full / Empty / EmptyEmpty)
+ *  - 'abnormal'  : 캐리어 정상/비정상 비율 세그먼트 (Normal / Abnormal)
+ *
+ * mode 소스: root.stockerGaugeMode (기본 'capacity').
+ * RootContainer 의 **런타임 전용 transient 속성** — 모델에 저장하지 않고 항상 'capacity'
+ * 로 시작하며 실행 중 동적으로만 변경된다(root-container-override.ts 정의). 3D 표현
+ * (machine-3d.ts buildGauge)과 동일 소스라 2D/3D 게이지가 항상 일치한다.
+ *
+ * 데이터 필드(2D 기준, canonical):
+ *  - capacity : CURRENTCAPACITY / MAXCAPACITY / HIGHWATERMARK / LOWWATERMARK / FULLUP
+ *  - carrier  : CARRIER_FULL / CARRIER_EMPTY / CARRIER_EMPTY_EMPTY
+ *  - abnormal : CARRIER_NORMAL / CARRIER_ABNORMAL
+ */
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -53,6 +73,31 @@ const NATURE: ComponentNature = {
       name: 'fullup',
       label: 'fullup'
     },
+    {
+      type: 'number',
+      name: 'carrierFull',
+      label: 'carrier-full'
+    },
+    {
+      type: 'number',
+      name: 'carrierEmpty',
+      label: 'carrier-empty'
+    },
+    {
+      type: 'number',
+      name: 'carrierEmptyEmpty',
+      label: 'carrier-empty-empty'
+    },
+    {
+      type: 'number',
+      name: 'carrierNormal',
+      label: 'carrier-normal'
+    },
+    {
+      type: 'number',
+      name: 'carrierAbnormal',
+      label: 'carrier-abnormal'
+    },
     {
       type: 'number',
       label: 'round',
@@ -92,6 +137,16 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
     return NATURE
   }
 
+  /** StockerCapacityBar / MCSGaugeCapacityBar 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
+  /** 게이지 모드: RootContainer 런타임 transient 속성. 3D(machine-3d) 와 동일 소스. */
+  get gaugeMode(): string {
+    return (this.root as any)?.stockerGaugeMode || 'capacity'
+  }
+
   get controls() {
     var { left, top, width, round, height } = this.state
     round = round == undefined ? 0 : safeRound(round, width, height)
@@ -127,16 +182,28 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
 
   get statusColor() {
     const { fullup } = this.state
-    return fullup ? 'red' : getVaueOnRanges(this.usage, this.legend)
+    return fullup ? 'red' : getValueOnRanges(this.usage, this.legend)
   }
 
   get text() {
+    // usage% 값은 capacity 모드에서만 표시. carrier/abnormal 은 세그먼트별 자체 라벨을 그리므로
+    // base 의 value 텍스트(value-property=usage)를 억제한다.
+    if (this.gaugeMode !== 'capacity') {
+      return ''
+    }
     return this.usage + '%'
   }
 
   render(context: CanvasRenderingContext2D) {
-    const { left, top, width, height } = this.bounds
+    const mode = this.gaugeMode
 
+    if (mode === 'carrier' || mode === 'abnormal') {
+      this.renderSegmentGauge(context, this.segments(mode))
+      return
+    }
+
+    // capacity (기본)
+    const { width, height } = this.bounds
     if (width >= height) {
       this.renderLandscape(context)
     } else {
@@ -144,6 +211,125 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
     }
   }
 
+  /**
+   * Shape.postrender 의 drawFill/drawStroke 를 건너뛴다.
+   * 각 모드 render 가 자체 배경(fillStyle)·외곽선(strokeStyle)을 이미 그리므로, base 가
+   * fillStyle 로 게이지 전체를 다시 덮어(각 모드 표현이 사라지는) 것을 방지한다.
+   * 값 텍스트(drawText)는 Component.postrender 와 동일하게 유지한다.
+   */
+  postrender(context: CanvasRenderingContext2D) {
+    this.drawText(context)
+  }
+
+  /**
+   * carrier/abnormal mode 의 세그먼트 목록 (공유 유틸 = 3D 와 동일 계산).
+   * 배열 순서 = portrait 아래→위 / landscape 왼→오.
+   */
+  segments(mode: string): GaugeSegment[] {
+    if (mode === 'abnormal') {
+      const { carrierNormal = 0, carrierAbnormal = 0 } = this.state
+      return abnormalSegments(carrierNormal, carrierAbnormal)
+    }
+    const { carrierFull = 0, carrierEmpty = 0, carrierEmptyEmpty = 0 } = this.state
+    // 색상은 carrier 컴포넌트와 동일한 legend(테마)에서 취득 (carrierColorsFromLegend).
+    const colors = carrierColorsFromLegend(resolveCarrierLegend(this))
+    return carrierSegments(carrierFull, carrierEmpty, carrierEmptyEmpty, colors)
+  }
+
+  /** 세그먼트 게이지 렌더 (carrier/abnormal 공통). bounds 방향으로 landscape/portrait 자동. */
+  renderSegmentGauge(context: CanvasRenderingContext2D, segments: GaugeSegment[]) {
+    const { left, top, width, height } = this.bounds
+    const { lineWidth, strokeStyle, round, fillStyle = 'white' } = this.state
+    const landscape = width >= height
+
+    context.save()
+    context.translate(left, top)
+
+    // background
+    context.beginPath()
+    context.fillStyle = fillStyle
+    context.roundRect(0, 0, width, height, round)
+    context.fill()
+    context.clip()
+
+    if (landscape) {
+      // 왼→오
+      let x = 0
+      for (const seg of segments) {
+        const segWidth = width * seg.ratio
+        if (segWidth <= 0) continue
+
+        context.beginPath()
+        context.fillStyle = seg.color
+        context.rect(x, 0, segWidth, height)
+        context.fill()
+
+        this._drawSegmentLabel(context, seg, x, 0, segWidth, height)
+        x += segWidth
+      }
+    } else {
+      // 아래→위 (배열 첫 세그먼트가 바닥)
+      let y = height
+      for (const seg of segments) {
+        const segHeight = height * seg.ratio
+        if (segHeight <= 0) continue
+
+        y -= segHeight
+
+        context.beginPath()
+        context.fillStyle = seg.color
+        context.rect(0, y, width, segHeight)
+        context.fill()
+
+        this._drawSegmentLabel(context, seg, 0, y, width, segHeight)
+      }
+    }
+
+    // outline
+    context.beginPath()
+    context.setLineDash([])
+    context.strokeStyle = strokeStyle
+    context.lineWidth = lineWidth
+    context.roundRect(0, 0, width, height, round)
+    context.stroke()
+
+    context.translate(-left, -top)
+    context.restore()
+  }
+
+  private _drawSegmentLabel(
+    context: CanvasRenderingContext2D,
+    seg: GaugeSegment,
+    x: number,
+    y: number,
+    w: number,
+    h: number
+  ) {
+    // 이름 라벨(Full/Empty/Abnormal…)은 그리지 않는다. 각 세그먼트 영역 중심에 숫자(%)만 표시.
+    // 컴포넌트의 폰트 설정(fontFamily/fontSize/bold/italic)을 그대로 적용 — this.font.
+    const fontSize = this.state.fontSize || 15
+    context.font = this.font
+
+    // 공간에 따라 단계적 축소: 넉넉하면 '값%', 좁으면 '%' 떼고 값만, 더 좁으면 생략.
+    const value = `${Math.round(seg.ratio * 100)}`
+    const fits = (t: string) => fontSize <= h && context.measureText(t).width <= w
+
+    let text: string | null = null
+    if (fits(`${value}%`)) {
+      text = `${value}%`
+    } else if (fits(value)) {
+      text = value
+    }
+    if (text === null) {
+      return
+    }
+
+    context.fillStyle = '#333'
+    context.textAlign = 'center'
+    context.textBaseline = 'middle'
+    context.fillText(text, x + w / 2, y + h / 2)
+  }
+
   renderLandscape(context: CanvasRenderingContext2D) {
     const { left, top, width, height } = this.bounds
     const { highWatermark, lowWatermark, lineWidth, strokeStyle, round, fillStyle = 'white' } = this.state
@@ -298,13 +484,19 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
   }
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    const data = this.data && typeof this.data == 'object' ? this.data : {}
     const {
       CURRENTCAPACITY = 0,
       MAXCAPACITY = 100,
       HIGHWATERMARK = 100,
       LOWWATERMARK = 0,
-      FULLUP = 'F'
-    } = typeof this.data == 'object' ? this.data : {}
+      FULLUP = 'F',
+      CARRIER_FULL = 0,
+      CARRIER_EMPTY = 0,
+      CARRIER_EMPTY_EMPTY = 0,
+      CARRIER_NORMAL = 0,
+      CARRIER_ABNORMAL = 0
+    } = data
 
     const currentUsage = Number(CURRENTCAPACITY) || 0
     const maxCapacity = Number(MAXCAPACITY) || 100
@@ -317,7 +509,106 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
       highWatermark,
       lowWatermark,
       fullup: FULLUP == 'T',
-      usage: Math.round((currentUsage / maxCapacity) * 100)
+      usage: Math.round((currentUsage / maxCapacity) * 100),
+      carrierFull: Number(CARRIER_FULL) || 0,
+      carrierEmpty: Number(CARRIER_EMPTY) || 0,
+      carrierEmptyEmpty: Number(CARRIER_EMPTY_EMPTY) || 0,
+      carrierNormal: Number(CARRIER_NORMAL) || 0,
+      carrierAbnormal: Number(CARRIER_ABNORMAL) || 0
     })
   }
+
+  // ── hover 툴팁 (carrier/abnormal 모드 세그먼트별 수치) ───────────────────────────
+  // 색상만으로 타입 구분이 어려울 때, 마우스 hover 로 정확한 수치 확인. 뷰어 모드 전용
+  // (model-layer 가 편집 모드에선 hover dispatch 안 함).
+
+  async ready(): Promise<void> {
+    await super.ready()
+    // hover 이벤트 수신 opt-in: model-layer _onmouseenter_all guard(hasLegacyHover) 통과.
+    const ev = this.model.event
+    if (!ev || !ev.hover) {
+      this.model.event = { ...(ev || {}), hover: true }
+    }
+  }
+
+  onMouseEnter(): void {
+    // capacity 는 값이 한 개(usage%)라 툴팁 불필요. carrier/abnormal 만.
+    if (this.gaugeMode === 'capacity') return
+    this._showGaugeTooltip()
+  }
+
+  onMouseLeave(): void {
+    this._hideGaugeTooltip()
+  }
+
+  dispose(): void {
+    this._hideGaugeTooltip()
+    super.dispose()
+  }
+
+  private _tooltipEl?: HTMLDivElement
+  private _tooltipMove?: (e: MouseEvent) => void
+
+  private _showGaugeTooltip(): void {
+    if (typeof document === 'undefined') return
+    const segments = this.segments(this.gaugeMode).filter(s => s.count > 0)
+    if (!segments.length) return
+
+    this._hideGaugeTooltip()
+
+    const el = document.createElement('div')
+    el.style.cssText = [
+      'position:fixed',
+      'left:-9999px',
+      'top:0',
+      'z-index:2147483647',
+      'pointer-events:none',
+      'background:rgba(30,30,30,0.92)',
+      'color:#fff',
+      'padding:6px 9px',
+      'border-radius:6px',
+      'font:12px/1.5 sans-serif',
+      'box-shadow:0 2px 10px rgba(0,0,0,0.35)',
+      'white-space:nowrap'
+    ].join(';')
+
+    for (const seg of segments) {
+      const row = document.createElement('div')
+      row.style.cssText = 'display:flex;align-items:center;gap:6px'
+
+      const swatch = document.createElement('span')
+      swatch.style.cssText = `display:inline-block;width:10px;height:10px;border-radius:2px;background:${seg.color}`
+
+      const label = document.createElement('span')
+      label.textContent = seg.label.replace(/\n/g, ' ')
+      label.style.cssText = 'flex:1'
+
+      const value = document.createElement('span')
+      value.textContent = String(seg.count)
+      value.style.cssText = 'font-weight:700;margin-left:12px'
+
+      row.append(swatch, label, value)
+      el.appendChild(row)
+    }
+
+    document.body.appendChild(el)
+    this._tooltipEl = el
+
+    this._tooltipMove = (e: MouseEvent) => {
+      el.style.left = `${e.clientX + 14}px`
+      el.style.top = `${e.clientY + 14}px`
+    }
+    document.addEventListener('mousemove', this._tooltipMove, true)
+  }
+
+  private _hideGaugeTooltip(): void {
+    if (this._tooltipMove) {
+      document.removeEventListener('mousemove', this._tooltipMove, true)
+      this._tooltipMove = undefined
+    }
+    if (this._tooltipEl) {
+      this._tooltipEl.remove()
+      this._tooltipEl = undefined
+    }
+  }
 }

package/src/stocker-carrier-bar.ts

@@ -81,6 +81,11 @@ export default class StockerCarrierBar extends ParentObjectMixin(RectPath(Shape)
     return NATURE
   }
 
+  /** StockerCarrierBar 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   get controls() {
     var { left, top, width, round, height } = this.state
     round = round == undefined ? 0 : safeRound(round, width, height)
@@ -246,7 +251,7 @@ export default class StockerCarrierBar extends ParentObjectMixin(RectPath(Shape)
       CARRIER_FULL = 0,
       CARRIER_EMPTY = 0,
       CARRIER_EMPTY_EMPTY = 0
-    } = typeof this.data == 'object' ? this.data : {}
+    } = this.data && typeof this.data == 'object' ? this.data : {}
 
     this.setState({
       carrierFull: Number(CARRIER_FULL) || 0,

package/src/stocker.ts

@@ -47,6 +47,13 @@ export default class Stocker extends MCSTransport {
   }
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    /* MCSStatusMixin.onchangeData 의 statusColor → state.fillStyle 동기화 로직을
+     * 호출. 3D 경로에서는 mesh material 의 color 가 build 시점 한 번 결정되므로
+     * 데이터 변경 시 fillStyle 이 갱신되어야 MCSRealObject3D.onchange 의
+     * 'fillStyle in after' 분기를 타고 mesh rebuild 가 발생한다.
+     * (2D 는 render() 가 매 프레임 statusColor getter 를 직접 사용하므로 영향 없음.) */
+    super.onchangeData(after, before)
+
     /* non-identifiable component 즉, StockerCapacityBar 에게 데이터를 전달함 */
     this.components.filter(component => !component.isIdentifiable()).forEach(component => (component.data = this.data))
   }

package/src/templates/backdrop.ts

@@ -0,0 +1,30 @@
+const icon = new URL('../../icons/backdrop.png', import.meta.url).href
+
+export default {
+  type: 'backdrop',
+  description: '3D scene backdrop — 6-sided envelope (4 walls + floor + ceiling)',
+  group: ['etc'],
+  icon,
+  model: {
+    type: 'backdrop',
+    top: 0,
+    left: 0,
+    width: 3000,
+    height: 2400,
+    // depth seeded on creation as min(width, height) by Backdrop's
+    // `_syncFromRoot(seedDepth=true)`. Editable via property panel
+    // afterward — board-resize syncs won't override it.
+    fitToBoard: true,
+    alpha: 1,
+    // 6면 합성 상태. 비어있으면 backdrop 컴포넌트의 default 가 적용됨
+    // (벽 4면 = #dde2e8/0.35, 바닥 = #9c9c9c/1.0, 천장 = #e8e8ec/1.0).
+    faces: {
+      east: { fillStyle: '#dde2e8', visible: true, alpha: 0.35 },
+      west: { fillStyle: '#dde2e8', visible: true, alpha: 0.35 },
+      north: { fillStyle: '#dde2e8', visible: true, alpha: 0.35 },
+      south: { fillStyle: '#dde2e8', visible: true, alpha: 0.35 },
+      floor: { fillStyle: '#9c9c9c', visible: true, alpha: 1.0 },
+      ceiling: { fillStyle: '#e8e8ec', visible: true, alpha: 1.0 }
+    }
+  }
+}

package/src/templates/decal.ts

@@ -0,0 +1,21 @@
+const icon = new URL('../../icons/decal.png', import.meta.url).href
+
+export default {
+  type: 'decal',
+  description: 'flat surface decal (3D-only) — floor zone paint, path lanes, signage',
+  group: ['etc'],
+  icon,
+  model: {
+    type: 'decal',
+    top: 100,
+    left: 100,
+    width: 200,
+    height: 200,
+    zPos: 0,
+    depth: 0,
+    fillStyle: '#cccccc',
+    strokeStyle: '#999999',
+    lineWidth: 1,
+    alpha: 1
+  }
+}

package/src/templates/index.ts

@@ -17,9 +17,12 @@ import agvLine from './agv-line'
 import ohtLine from './oht-line'
 import conveyor from './conveyor'
 
+import Scanner from './scanner'
 import Node from './node'
 import DataSubscription from './data-subscription'
 import FloatingContainer from './floating-container'
+import Decal from './decal'
+import Backdrop from './backdrop'
 
 export default [
   StockerCapacityBar,
@@ -41,7 +44,10 @@ export default [
   Shelf,
   Port,
 
+  Scanner,
   Node,
   FloatingContainer,
-  DataSubscription
+  DataSubscription,
+  Decal,
+  Backdrop
 ]

package/src/templates/scanner.ts

@@ -0,0 +1,20 @@
+const icon = new URL('../../icons/equipment.png', import.meta.url).href
+
+export default {
+  type: 'Scanner',
+  description: 'Fixed mount barcode/QR scanner',
+  group: ['etc'],
+  icon,
+  model: {
+    type: 'Scanner',
+    x1: 100,
+    y1: 100,
+    x2: 130,
+    y2: 110,
+    x3: 100,
+    y3: 120,
+    strokeStyle: '#333',
+    fillStyle: 'red',
+    lineWidth: 1
+  }
+}

package/src/utils/crane-position.ts

@@ -0,0 +1,105 @@
+/*
+ * Crane 위치 데이터 (data.cranePosition) 변환 유틸.
+ *
+ * 명세:
+ *   {
+ *     cranePosition: {
+ *       current: { x, y, z },               // 실 좌표값
+ *       limit: { x:{min,max}, y:{min,max}, z:{min,max} }  // 각 축 한계
+ *     }
+ *   }
+ *
+ * current 를 limit 범위 안의 0~1 비율로 환산한 뒤 host(부모) footprint 에 매핑한다.
+ * x → host 긴쪽, y → 짧은쪽, z → 포크 높이(forkZ 0~100).
+ */
+
+import { parseIfJsonString } from './data-value'
+
+/** 축별 한계 (cranePosition.limit.{x|y|z}). */
+export interface AxisLimit {
+  min?: number
+  max?: number
+}
+
+/** 새 데이터 명세 — data.cranePosition. */
+export interface CranePositionData {
+  current?: { x?: number; y?: number; z?: number }
+  limit?: { x?: AxisLimit; y?: AxisLimit; z?: AxisLimit }
+}
+
+/**
+ * current 값을 limit 범위 안에서 0~1 비율로 환산.
+ * limit 누락 / 0 span / 비정상 입력 시 0 반환 (안전 fallback).
+ */
+export function axisRatio(value: unknown, lim?: AxisLimit): number {
+  const v = Number(value)
+  const min = Number(lim?.min) || 0
+  const max = Number(lim?.max)
+  if (!Number.isFinite(v) || !Number.isFinite(max) || max === min) return 0
+  return Math.max(0, Math.min(1, (v - min) / (max - min)))
+}
+
+/**
+ * host(부모) footprint 안에서 0~1 비율 (rx,ry) → 크레인 top-left 로컬 좌표.
+ *
+ * **스토커 안쪽 오프셋**: 크레인의 폭/두께를 감안해, 크레인 *전체* 가 host 안에
+ * 머무르도록 top-left 좌표를 [0, hostLen - craneLen] 범위로 매핑한다 (= 양끝에서
+ * craneLen/2 만큼 inset 된 중심선 위를 움직임). 크레인이 host 보다 크면 span 0
+ * 으로 떨어져 host 모서리에 정렬.
+ *
+ * x(rx) 는 host 의 긴쪽, y(ry) 는 짧은쪽에 매핑 (가상 rail 은 host 긴쪽 방향).
+ */
+export function mapCraneLocalPosition(
+  hostW: number,
+  hostH: number,
+  craneW: number,
+  craneH: number,
+  rx: number,
+  ry: number
+): { left: number; top: number } {
+  const longIsWidth = hostW >= hostH
+  const longLen = longIsWidth ? hostW : hostH
+  const shortLen = longIsWidth ? hostH : hostW
+  const craneLongSize = longIsWidth ? craneW : craneH
+  const craneShortSize = longIsWidth ? craneH : craneW
+
+  // 크레인 크기를 뺀 inset 가용 span. top-left = ratio * span 이므로 크레인
+  // 전체가 host [0, hostLen] 안에 들어온다.
+  const longSpan = Math.max(0, longLen - craneLongSize)
+  const shortSpan = Math.max(0, shortLen - craneShortSize)
+  const longPos = rx * longSpan
+  const shortPos = ry * shortSpan
+
+  return {
+    left: longIsWidth ? longPos : shortPos,
+    top: longIsWidth ? shortPos : longPos
+  }
+}
+
+/**
+ * 객체 키를 재귀적으로 소문자화한 사본 반환 (배열/원시값은 그대로, 값은 변형 안 함).
+ * 데이터 키는 모두 대문자 전제 — CRANEPOSITION 의 중첩 키(CURRENT/LIMIT/X/Y/Z/MIN/MAX)를
+ * 내부 표준형(소문자 current/limit/x/y/z/min/max)으로 변환하기 위한 정규화.
+ */
+export function lowerKeysDeep<T = any>(value: any): T {
+  if (Array.isArray(value)) return value.map(v => lowerKeysDeep(v)) as any
+  if (value && typeof value === 'object') {
+    const out: Record<string, any> = {}
+    for (const k of Object.keys(value)) {
+      out[k.toLowerCase()] = lowerKeysDeep(value[k])
+    }
+    return out as T
+  }
+  return value as T
+}
+
+/**
+ * raw CRANEPOSITION → 내부 표준형(소문자 키) 구조(CranePositionData).
+ * 값이 JSON 문자열로 올 수 있어 먼저 파싱하고, 중첩 키(CURRENT/LIMIT/X/Y/Z/MIN/MAX)를
+ * 소문자(current.x / limit.x.min)로 변환. 파싱 실패/비객체면 undefined.
+ */
+export function normalizeCranePosition(raw: any): CranePositionData | undefined {
+  const obj = parseIfJsonString(raw)
+  if (!obj || typeof obj !== 'object') return undefined
+  return lowerKeysDeep<CranePositionData>(obj)
+}

package/src/utils/data-value.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * 데이터 필드값이 JSON 문자열로 전달될 수 있어(예: CRANEPOSITION, MULTICARRIERS)
+ * 객체/배열로 변환하기 위한 헬퍼.
+ */
+
+/**
+ * 값이 JSON 문자열이면 파싱해서 반환. 객체/배열 등 비문자열은 그대로 반환.
+ * 파싱 실패 시 undefined.
+ */
+export function parseIfJsonString(value: any): any {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}

package/src/utils/fit-gauge-scale.ts

@@ -0,0 +1,35 @@
+/**
+ * 스토커 지붕 위 용량 게이지 바의 비례 축소 계수를 계산한다.
+ *
+ * 정책:
+ *   - 게이지 바의 *최대* 크기는 maxW × maxH. 스토커가 충분히 크면 이 크기 그대로 (계수 1).
+ *   - 스토커가 그보다 작으면 지붕 footprint 안에 들어오도록 *비례* 축소 (uniform).
+ *   - *확대는 하지 않는다* (계수 상한 1) — 현재 크기가 상한이라는 요구사항.
+ *
+ * 방향 매핑: 바의 가로축(maxW)은 스토커의 *장축*에 정렬된다 (buildGauge 의
+ * `isWidthLonger ? geo.rotateY` 처리와 일치). 따라서 가용 치수도 그 기준으로 매칭한다.
+ *
+ * @param w 스토커 footprint 가로 (월드 단위)
+ * @param h 스토커 footprint 세로 (월드 단위)
+ * @param maxW 게이지 바 최대 가로
+ * @param maxH 게이지 바 최대 세로
+ * @param margin 지붕 가장자리 여백 비율 (0~1, 기본 0.85)
+ * @returns 0 < scale <= 1
+ */
+export function fitGaugeScale(
+  w: number,
+  h: number,
+  maxW: number,
+  maxH: number,
+  margin: number = 0.85
+): number {
+  const isWidthLonger = w >= h
+  // 바 가로축(maxW)이 정렬되는 스토커 치수 = 장축, 세로축(maxH) = 단축
+  const availAlongW = isWidthLonger ? w : h
+  const availAlongH = isWidthLonger ? h : w
+
+  const scale = Math.min(1, (availAlongW * margin) / maxW, (availAlongH * margin) / maxH)
+
+  // 음수/NaN 방어 — 0 이하로 떨어지면 안 됨
+  return scale > 0 && Number.isFinite(scale) ? scale : 1
+}