@fmsim/machine 3.0.0-beta.4 → 3.0.0-beta.6

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fmsim/machine",
   "description": "Layout View를 구성하는 설비(machine)들과 유닛을 구현한 모듈입니다.",
   "author": "heartyoh",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.6",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "things-scene": true,
@@ -27,10 +27,11 @@
   },
   "dependencies": {
     "@fmsim/api": "^3.0.0-beta.2",
-    "@fmsim/figure-capabilities": "^3.0.0-beta.4",
+    "@fmsim/figure-capabilities": "^3.0.0-beta.5",
     "@hatiolab/figure-model": "^0.12.0",
     "@hatiolab/things-scene": "^10.1.90",
-    "@operato/slot-layout-editor": "^10.29.33"
+    "@operato/slot-layout-editor": "^10.29.33",
+    "tinycolor2": "^1.6.0"
   },
   "devDependencies": {
     "@hatiolab/prettier-config": "^1.0.0",
@@ -58,5 +59,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "95b704a73e326b7be3bbd1ef3db5ee31f7ef7184"
+  "gitHead": "d3de9f6ded33cac773a583a2308883a8bed2fabc"
 }

package/src/agv-line.ts

@@ -22,8 +22,8 @@ export default class AGVLine extends MCSTransport {
     return '#333'
   }
 
-  getLegendFallback() {
-    return (this.root as any).agvlineLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'agvline'
   }
 
   render(context: CanvasRenderingContext2D) {

package/src/agv.ts

@@ -37,8 +37,13 @@ export default class AGV extends MCSVehicle {
     return ['AGVLine']
   }
 
-  getLegendFallback() {
-    return (this.root as any).agvLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'agv'
+  }
+
+  /** Its STATUS row and its battery's (the battery is the AGV's own: only a board with AGVs shows the row) */
+  get legendRowsUsed(): string[] {
+    return [...super.legendRowsUsed, 'battery-rate']
   }
 
   getBatteryLegendFallback() {

package/src/buffer.ts

@@ -14,8 +14,8 @@ export default class Buffer extends MCSMachine {
     return NATURE
   }
 
-  getLegendFallback() {
-    return (this.root as any).bufferLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'buffer'
   }
 
   containable(component: Component) {

package/src/conveyor-join.ts

@@ -98,8 +98,8 @@ export default class ConveyorJoin extends ConveyorMixin(MCSTransport) {
     return NATURE
   }
 
-  getLegendFallback() {
-    return (this.root as any).conveyorLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'conveyor'
   }
 
   containable(component: Component) {

package/src/conveyor.ts

@@ -36,8 +36,8 @@ export default class Conveyor extends MCSTransport {
     return '#777'
   }
 
-  getLegendFallback() {
-    return (this.root as any).conveyorLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'conveyor'
   }
 
   containable(component: Component) {

package/src/crane.ts

@@ -92,8 +92,8 @@ export default class Crane extends LoadLayoutHolder(MCSVehicle) {
     return ['STOCKER']
   }
 
-  getLegendFallback() {
-    return (this.root as any).craneLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'crane'
   }
 
   private _posAnimator?: CranePositionAnimator

package/src/equipment.ts

@@ -14,8 +14,8 @@ export default class Equipment extends MCSMachine {
     return NATURE
   }
 
-  getLegendFallback() {
-    return (this.root as any).equipmentLegendTheme || super.getLegendFallback()
+  get statusLegendRow(): string {
+    return 'equipment'
   }
 
   containable(component: Component) {

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

@@ -15,7 +15,7 @@ import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 import { RealObjectGroup, registerRealObjectFactory, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
-import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+import { MACHINE_HEIGHTS } from '../features/lv-heights.js'
 import { Z_FMSIM } from './z-priority'
 
 const FRAME_COLOR = 0x888899
@@ -27,7 +27,7 @@ export class Conveyor3D extends RealObjectGroup {
 
   get effectiveDepth(): number {
     const { depth } = this.component.state
-    return depth || TRANSPORT_SURFACE_HEIGHT
+    return depth || MACHINE_HEIGHTS.conveyor
   }
 
   private resolveColor(): number {

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

@@ -14,6 +14,8 @@ import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBa
 import type { Component } from '@hatiolab/things-scene'
 import { LEGEND_CAPACITY, legendColor, legendRangeEntryOf, resolveCarrierLegend } from '../features/mcs-status-default'
 import { fitGaugeScale } from '../utils/fit-gauge-scale'
+import { railTopOf } from '../features/oht-rail'
+import { MACHINE_HEIGHTS, MACHINE_OPACITY, TRANSPORT_SURFACE_HEIGHT } from '../features/lv-heights'
 import {
   carrierSegmentsFromData,
   abnormalSegmentsFromData,
@@ -59,12 +61,8 @@ interface MCS3DConfig {
   zPriority?: number
 }
 
-/**
- * 포트 기본 높이 (절대값).
- * 모든 이송장치의 상단 높이 = 이 값.
- * 캐리어가 이송장치 간 높이 차 없이 이동할 수 있는 기준 높이.
- */
-export const TRANSPORT_SURFACE_HEIGHT = 30
+/* 포트 기본 높이와 설비 타입별 높이는 한 곳(features/lv-heights) — 피규어 fmsim.Machine 도 같은 표를 읽는다 */
+export { TRANSPORT_SURFACE_HEIGHT } from '../features/lv-heights'
 
 const DEFAULTS: MCS3DConfig = {
   depthRatio: 0.5,
@@ -502,8 +500,8 @@ function register(type: string, overrides: Partial<MCS3DConfig> = {}) {
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 register('Equipment', {
-  defaultDepth: 3 * TRANSPORT_SURFACE_HEIGHT,
-  opacity: 0.75,
+  defaultDepth: MACHINE_HEIGHTS.equipment,
+  opacity: MACHINE_OPACITY.equipment,
   metalness: 0.4,
   roughness: 0.6,
   defaultColor: 0x8899aa,
@@ -511,8 +509,8 @@ register('Equipment', {
 })
 
 register('Buffer', {
-  defaultDepth: TRANSPORT_SURFACE_HEIGHT,
-  opacity: 1.0,
+  defaultDepth: MACHINE_HEIGHTS.buffer,
+  opacity: MACHINE_OPACITY.buffer,
   metalness: 0.3,
   roughness: 0.7,
   defaultColor: 0x99aa88,
@@ -534,14 +532,14 @@ register('AGVLine', {
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 const OHT_LINE_RAIL_COLOR = 0xcccccc
-const OHT_LINE_HEIGHT = 7 * TRANSPORT_SURFACE_HEIGHT // OHT 상단과 일치
 
 class OHTLineRealObject3D extends RealObjectGroup {
   private _mesh?: THREE.Mesh
 
   get zPriority(): number { return Z_FMSIM.OHT_LINE }
   get effectiveDepth(): number { return 0 }
-  protected get syncZPosOffset(): number { return OHT_LINE_HEIGHT }
+  /** 레일 윗면 = 작업환경 천장 − 라인의 매달림 길이(railHang). OHT 상단이 여기에 매달린다 */
+  protected get syncZPosOffset(): number { return railTopOf(this.component) }
 
   build() {
     super.build()
@@ -616,6 +614,7 @@ class OHTLineRealObject3D extends RealObjectGroup {
       this.update()
       return
     }
+    if ('railHang' in after) this.updateTransform()
     super.onchange(after, before)
   }
 

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

@@ -15,14 +15,12 @@ import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeom
 import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+import { ohtRailTop } from '../features/oht-rail.js'
 
 const TROLLEY_COLOR = 0x222222
 const FRAME_COLOR = 0x444444
 const DEFAULT_BODY_COLOR = 0x6688cc
 
-/** OHT 레일 높이: 스토커(5x) 위 */
-const OHT_RAIL_HEIGHT = 6 * TRANSPORT_SURFACE_HEIGHT
-
 export class OHT3D extends RealObjectGroup {
   private _ownMeshes: THREE.Mesh[] = []
   get effectiveDepth(): number {
@@ -30,9 +28,9 @@ export class OHT3D extends RealObjectGroup {
     return depth || TRANSPORT_SURFACE_HEIGHT
   }
 
-  /** 천장 레일 높이에 배치 (center origin 기준: 레일 높이 + 볼륨 중심 반깊이) */
+  /** 자기 라인의 레일에 상단을 매단다 (center origin 기준: 레일 윗면 − 볼륨 중심 반깊이) */
   protected get syncZPosOffset(): number {
-    return OHT_RAIL_HEIGHT + this.effectiveDepth / 2
+    return ohtRailTop(this.component) - this.effectiveDepth / 2
   }
 
   private resolveColor(): number {

package/src/features/legend-panel.ts

@@ -0,0 +1,31 @@
+import { themesColorMap, themesColorRange, themesAnimationMap } from '@fmsim/api'
+import { legendRows, type LegendRow } from '@fmsim/figure-capabilities'
+import { legendRowsOnBoard } from './legend-rows'
+
+/** The options a row's legend select offers: the board's legends of its kind. */
+const LEGEND_OPTIONS: Record<LegendRow['kind'], unknown> = {
+  'color-map': themesColorMap,
+  'color-ranges': themesColorRange,
+  'animation-map': themesAnimationMap
+}
+
+const legendSelect = (row: LegendRow) => ({ type: 'select', label: row.label, name: row.property, property: { options: LEGEND_OPTIONS[row.kind] } })
+const legendHeader = (name: string, label: string) => ({ type: 'legend', label: '', name, property: { label } })
+
+/**
+ * The board's LEGENDS panel, drawn from the registered rows (ADR-0167 decision 20): the rows the board's components
+ * follow first, then the others; the stocker's rows apart, as they were.
+ */
+export function legendPanel(board: any): any[] {
+  const used = legendRowsOnBoard(board)
+  const rows = legendRows().filter(row => row.section !== 'stocker')
+  const here = rows.filter(row => used.has(row.name))
+  const others = rows.filter(row => !used.has(row.name))
+  const stocker = legendRows().filter(row => row.section === 'stocker')
+  return [
+    legendHeader('LEGENDS', 'LEGENDS'),
+    ...here.map(legendSelect),
+    ...(others.length ? [legendHeader('LEGENDS-OTHERS', 'LEGENDS · NOT ON THIS BOARD'), ...others.map(legendSelect)] : []),
+    ...(stocker.length ? [legendHeader('LEGENDS-STOCKER', 'LEGENDS · STOCKER'), ...stocker.map(legendSelect)] : [])
+  ]
+}

package/src/features/legend-rows.ts

@@ -0,0 +1,86 @@
+import JSON5 from 'json5'
+import tinycolor from 'tinycolor2'
+import { legendRowOf } from '@fmsim/figure-capabilities'
+import type { Legend } from './mcs-status-default'
+
+/*
+ * A board's legend rows (ADR-0167 decision 20): the legend a row chose is read here, by the row's board property, for
+ * fmsim's own components and its figures alike. Kept in the board properties they have always had.
+ */
+
+// rootModel.state.style[name] 에 저장된 legend/animation 값은 보드 직렬화 형태에 따라 (a) 정상 object 또는 (b) JSON 문자열
+// 둘 다로 나타난다 (2026-06-09 진단). 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>>()
+
+export 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
+}
+
+/** The legend a board property names, read from the board's style: none when the board chose none. */
+export function boardLegendOf(root: any, property: string): Legend | undefined {
+  const name = root?.rootModel?.state?.[property]
+  if (!name || !root?.state?.style) return undefined
+  return parseLegendIfString(root.state, root.state.style[name]) || undefined
+}
+
+/** The legend the board chose for a row, for a component on it: none when the row is not registered or not chosen. */
+export function boardLegendOfRow(component: any, row: unknown): Legend | undefined {
+  const registered = legendRowOf(row)
+  return registered ? boardLegendOf(component?.root, registered.property) : undefined
+}
+
+/**
+ * A legend colour as a figure takes it: `#RRGGBB`. fmsim's own components draw any CSS colour a legend gives (`navy`,
+ * `rgb(33, 148, 33)`, `#f00`); a figure's table takes `#RRGGBB` only (ADR-0166), so an opaque colour is written so. A
+ * colour that is not opaque (`transparent`) has no `#RRGGBB` and stays as it is -- the figure says it did not take it.
+ */
+export function figureColourOf(value: unknown): unknown {
+  if (typeof value !== 'string' || /^#[0-9a-f]{6}$/i.test(value)) return value
+  const colour = tinycolor(value.trim())
+  return colour.isValid() && colour.getAlpha() === 1 ? colour.toHexString() : value
+}
+
+/** A legend as a figure takes it from fmsim: each entry's colour, written `#RRGGBB`, and effect; an entry's JSON5 text read. */
+export function colourAndEffect(legend: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(legend).map(([code, raw]) => {
+      let entry = raw
+      if (typeof entry === 'string' && entry.trim().startsWith('{')) {
+        try {
+          entry = JSON5.parse(entry)
+        } catch {
+          return [code, raw]
+        }
+      }
+      if (!entry || typeof entry !== 'object') return [code, figureColourOf(entry)]
+      const { color, effect } = entry as { color?: unknown; effect?: unknown }
+      return [code, { ...(color !== undefined ? { color: figureColourOf(color) } : {}), ...(effect !== undefined ? { effect } : {}) }]
+    })
+  )
+}
+
+/** The rows the components of a board follow, each once: what its LEGENDS panel shows first. */
+export function legendRowsOnBoard(container: any): Set<string> {
+  const used = new Set<string>()
+  const walk = (c: any) => {
+    for (const row of c?.legendRowsUsed ?? []) if (row) used.add(row)
+    for (const child of c?.components ?? []) walk(child)
+  }
+  walk(container)
+  return used
+}

package/src/features/lv-figures.ts

@@ -0,0 +1,151 @@
+import { figureLegendSourcesChanged, registerFigureCapability, registerFigureLegendResolver } from '@hatiolab/things-scene'
+import { CARRIER_HOLDER, MACHINE, STATUS, STATUS_LEGEND_ROLE, UNIT, VEHICLE, carrierHolderProperties, statusProperties } from '@fmsim/figure-capabilities'
+import { themesAnimationMap, themesColorMap } from '@fmsim/api'
+import { boardLegendOfRow, colourAndEffect, parseLegendIfString } from './legend-rows'
+import { MACHINE_HEIGHTS, TRANSPORT_SURFACE_HEIGHT } from './lv-heights'
+import { VehicleTravel } from './vehicle-travel'
+import { CarrierHolder } from '../mcs-carrier-holder'
+
+/*
+ * fmsim's figure capabilities (ADR-0167 decision 22): what a figure is in LV -- fmsim.Machine, fmsim.Unit or
+ * fmsim.Vehicle, one at most -- and the features worn with any of them, fmsim.Status and fmsim.CarrierHolder. A kind
+ * says its type (`lvType`), the board row a status follows; the features are the mixins fmsim's own wear.
+ */
+
+/**
+ * STATUS as the figure takes it: a code, so a number (MCS sends 4001) is given as its text ('4001'). The status table reads
+ * STATUS as a text and a figure refuses data whose value is not of the declared kind; the component's own data is not changed.
+ */
+export function statusAsCode(data: any): any {
+  return data && typeof data === 'object' && typeof data.STATUS === 'number' ? { ...data, STATUS: String(data.STATUS) } : data
+}
+
+/**
+ * `fmsim.Status`: the figure follows the board row of its kind's type, a change of its legend has its tables chosen
+ * again, and its STATUS reaches the figure as a code. The colour is its capability's table, drawn by things-scene.
+ */
+export function StatusFigure<T extends new (...args: any[]) => any>(Base: T) {
+  return class extends Base {
+    _statusInputs?: unknown
+
+    /** The figure's inputs, given the data's STATUS as a code when they are made (a new release starts them again) */
+    get figureInputs(): any {
+      const inputs = super.figureInputs
+      if (inputs && inputs !== this._statusInputs) {
+        this._statusInputs = inputs
+        if (typeof (this as any).state?.data?.STATUS === 'number') inputs.setData(statusAsCode((this as any).state.data))
+      }
+      return inputs
+    }
+
+    /** The board row its status follows: its kind's type, none without a kind */
+    get statusLegendRow(): string | undefined {
+      return (this as any).lvType
+    }
+
+    get legendRowsUsed(): string[] {
+      const row = this.statusLegendRow
+      return [...((super.legendRowsUsed as string[] | undefined) ?? []), ...(row ? [row] : [])]
+    }
+
+    onchange(after: Record<string, any>, before: Record<string, any>) {
+      super.onchange?.(after && 'data' in after ? { ...after, data: statusAsCode(after.data) } : after, before)
+      if (after && 'legendName' in after) figureLegendSourcesChanged(this)
+    }
+  }
+}
+
+/** An LV kind: its type, chosen or its default, is `lvType`; another type has the figure's legends chosen again. */
+function Kind<T extends new (...args: any[]) => any>(Base: T, property: string, defaultOf: (figure: any) => string) {
+  return class extends Base {
+    get lvType(): string {
+      const chosen = (this as any).state?.[property]
+      return typeof chosen === 'string' && chosen ? chosen : defaultOf(this)
+    }
+
+    onchange(after: Record<string, any>, before: Record<string, any>) {
+      super.onchange?.(after, before)
+      if (after && property in after) figureLegendSourcesChanged(this)
+    }
+  }
+}
+
+/**
+ * `fmsim.Machine`: an LV machine of a type, equipment unless chosen -- it stands as tall as fmsim's own machine of that
+ * type when the board writes no height (things-scene asks the component, `effectiveDepth`).
+ */
+export function LVMachine<T extends new (...args: any[]) => any>(Base: T) {
+  return class extends Kind(Base, 'machineType', () => 'equipment') {
+    get effectiveDepth(): number | undefined {
+      return MACHINE_HEIGHTS[this.lvType]
+    }
+
+    onchange(after: Record<string, any>, before: Record<string, any>) {
+      super.onchange(after, before)
+      /* Another type stands at another height: the 3D object takes it */
+      if (after && 'machineType' in after) {
+        const real = (this as any)._realObject
+        real?.updateDimension?.()
+        real?.updateTransform?.()
+      }
+    }
+  }
+}
+
+/** `fmsim.Unit`: an LV unit of a type, a port unless chosen -- a tag LV handles it by */
+export function LVUnit<T extends new (...args: any[]) => any>(Base: T) {
+  return Kind(Base, 'unitType', () => 'port')
+}
+
+/** `fmsim.Vehicle`: an LV vehicle -- it travels between nodes; its type, unless chosen, an AGV on the floor and an OHT on the ceiling */
+export function LVVehicle<T extends new (...args: any[]) => any>(Base: T) {
+  return Kind(VehicleTravel(Base), 'vehicleType', figure => (figure?.constructor?.placement === 'ceiling' ? 'oht' : 'agv'))
+}
+
+/**
+ * `fmsim.CarrierHolder` on a figure: its carriers stand in its places -- a gripper, a lift plate, a fork's tiers -- and
+ * go with them; one without places keeps them in a pile on its top. Carriers change hands at the transport surface, so a
+ * holder that takes them on its
+ * top stands that tall when nothing else says -- as fmsim's own AGV and shuttle do. A machine's height wins (whichever is
+ * worn over the other); a holder that hangs them or hangs itself from the ceiling (an OHT) keeps its own.
+ */
+export function FigureCarrierHolder<T extends new (...args: any[]) => any>(Base: T) {
+  return class extends CarrierHolder(Base) {
+    /** Its carriers stand in its own places, which go with the parts that carry them (ADR-0167 decision 23) */
+    get fillsPlaces(): boolean {
+      return true
+    }
+
+    get effectiveDepth(): number | undefined {
+      const given = super.effectiveDepth
+      if (given !== undefined) return given
+      const hung = (this as any).state?.carrierMount === 'HANG' || (this as any).constructor?.placement === 'ceiling'
+      return hung ? undefined : TRANSPORT_SURFACE_HEIGHT
+    }
+  }
+}
+
+/**
+ * The legend a status figure shows its STATUS by: its own choice (`legendName`, as fmsim's own have), then the board row
+ * of its kind's type; none chosen, no answer (its capability's table, fmsim's default legends).
+ */
+export function statusLegend({ component, role }: { component: any; role: string }): unknown {
+  if (role !== STATUS_LEGEND_ROLE) return undefined
+  const own = component?.state?.legendName
+  const root = component?.root
+  const row = component?.statusLegendRow
+  const legend =
+    (typeof own === 'string' && own && root?.state?.style ? parseLegendIfString(root.state, root.state.style[own]) : undefined) ||
+    (row ? boardLegendOfRow(component, row) : undefined)
+  return legend && typeof legend === 'object' ? colourAndEffect(legend) : undefined
+}
+
+registerFigureLegendResolver(statusLegend)
+registerFigureCapability(MACHINE, base => LVMachine(base) as never)
+registerFigureCapability(UNIT, base => LVUnit(base) as never)
+registerFigureCapability(VEHICLE, base => LVVehicle(base) as never)
+registerFigureCapability({ ...STATUS, properties: statusProperties({ legends: themesColorMap }) as never }, base => StatusFigure(base) as never)
+registerFigureCapability(
+  { ...CARRIER_HOLDER, properties: carrierHolderProperties({ legends: themesColorMap, animations: themesAnimationMap, mount: true }) as never },
+  base => FigureCarrierHolder(base) as never
+)

package/src/features/lv-heights.ts

@@ -0,0 +1,22 @@
+/**
+ * LV's heights (ADR-0167 decision 21): fmsim gives no height on the board -- a machine stands as tall as its type, in
+ * transport surfaces, the height every port and transport stands at so carriers move between them level. fmsim's own
+ * machines and a figure wearing fmsim.Machine read the one table.
+ */
+
+/** 포트 기본 높이 (절대값). 모든 이송장치의 상단 높이 = 이 값 — 캐리어가 이송장치 간 높이 차 없이 이동하는 기준 */
+export const TRANSPORT_SURFACE_HEIGHT = 30
+
+/** The height a machine of each type stands at, by its legend row name */
+export const MACHINE_HEIGHTS: Record<string, number> = {
+  equipment: 3 * TRANSPORT_SURFACE_HEIGHT,
+  buffer: TRANSPORT_SURFACE_HEIGHT,
+  conveyor: TRANSPORT_SURFACE_HEIGHT
+}
+
+/** How opaque fmsim's own machine of each type is drawn: equipment is seen through, so the ports and carriers in it show */
+export const MACHINE_OPACITY: Record<string, number> = {
+  equipment: 0.75,
+  buffer: 1,
+  conveyor: 1
+}

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

@@ -1,8 +1,8 @@
 import { resolveLegend, resolveLegendEntries, type LegendEntry as RangeEntry } from '@hatiolab/things-scene'
-import { LEGEND_CARRIER, legendColor, type Legend, type LegendEntry } from '@fmsim/figure-capabilities'
+import { LEGEND_CARRIER, LEGEND_CRANE, LEGEND_MACHINE, LEGEND_UNIT, LEGEND_VEHICLE, legendColor, type Legend, type LegendEntry } from '@fmsim/figure-capabilities'
 
-/* 범례 항목 모양과 캐리어 기본 범례는 피규어 능력과 한 곳(@fmsim/figure-capabilities, ADR-0167) */
-export { LEGEND_CARRIER, legendColor, type Legend, type LegendEntry }
+/* 범례 항목 모양과 캐리어 · 상태 기본 범례는 피규어 능력과 한 곳(@fmsim/figure-capabilities, ADR-0167) */
+export { LEGEND_CARRIER, LEGEND_CRANE, LEGEND_MACHINE, LEGEND_UNIT, LEGEND_VEHICLE, legendColor, type Legend, type LegendEntry }
 
 /**
  * 코드의 범례 항목: 그 코드의 항목, 없으면 `default` (ADR-0166 판정 6). things-scene 의 한 조회(resolveLegend)로 읽는다 — 피규어의 표와
@@ -30,56 +30,6 @@ export function legendRangeEntryOf(value: unknown, legend: Legend | null | undef
 
 export const LEGEND_NULL: Legend = { default: '#F0F0F0' }
 
-export const LEGEND_MACHINE: Legend = {
-  '1000': '#707070', // DISCONNECTED
-  '1001': '#8BDA5B', // UP
-  '1002': '#EB3245', // OUTOFSERVICE
-  '1003': '#5630D0', // PM
-  '1004': '#FFFFFF', // NOTONLINE
-  '1005': '#404040', // DOWN
-  '1006': '#F4F226', // NOTAUTO
-  '1007': '#FD9B00', // ALARM
-  '1008': '#4AA7FE', // FULL
-  default: '#F0F0F0'
-}
-
-export const LEGEND_VEHICLE: Legend = {
-  '4000': '#EB3245', // OUTOFSERVICE
-  '4001': '#8BDA5B', // ASSIGNED
-  // '4002': '#cbf266', // ASSIGNED_ACQUIRING
-  // '4003': '#cbf266', // ASSIGNED_DEPOSITING
-  // '4004': '#cbf266', // ASSIGNED_ENROUTE
-  // '4005': '#cbf266', // ASSIGNED_PARKED
-  '4006': '#FD9B00', // NOTASSIGNED
-  '4007': '#32D1C4', // INSTALLED
-  '4008': '#9790EC', // CHARGING
-  '4009': '#4AA7FE', // CHARGED
-  '4010': '#404040', // REMOVED
-  default: '#F0F0F0'
-}
-
-export const LEGEND_UNIT: Legend = {
-  '2000': '#FD9B00', // BANNED
-  '2001': '#404040', // DOWN
-  '2002': '#8BDA5B', // EMPTY
-  '2003': '#FFFFFF', // EMPTY_RESERVED
-  '2004': '#32D1C4', // FULL_RESERVED
-  '2005': '#4AA7FE', // FULL
-  '2006': '#EB3245', // NOTINSERVICE
-  default: '#F0F0F0'
-}
-
-export const LEGEND_CRANE: Legend = {
-  '3000': '#EB3245', // OUTOFSERVICE
-  // '3001': '#404040', // DOWN
-  // '3002': '#8BDA5B', // EMPTY
-  '3003': '#FFFFFF', // IDLE
-  '3004': '#32D1C4', // ACTIVE
-  // '3005': '#4AA7FE', // FULL
-  // '3006': '#EB3245', // NOTINSERVICE
-  default: '#F0F0F0'
-}
-
 /**
  * carrier legend(테마) 해석 — carrier 컴포넌트(carrier.ts get legend)와 동일 로직 단일 소스.
  * parent 에 carrierLegendName 이 지정되면 그 style 을, 아니면 board 전역 carrierLegendTheme,

package/src/features/oht-rail.ts

@@ -0,0 +1,31 @@
+import { drawingScaleFor, sceneHeightsOf } from '@hatiolab/things-scene'
+
+/*
+ * Where an OHT runs: on its line's rail, hung from the work environment's ceiling. The rail's top is the ceiling less the
+ * line's hang (`railHang`, mm); an OHT -- fmsim's own or a figure wearing fmsim.Vehicle -- hangs its top from the rail of
+ * the line it runs on. Nothing here is a height of its own: each follows the ceiling of the room the board draws.
+ */
+
+/** The top of an OHT line's rail, in drawing units: the scene's ceiling less the line's hang. */
+export function railTopOf(line: any): number {
+  const ceiling = sceneHeightsOf(line).ceiling
+  const hang = Number(line?.state?.railHang) || 0
+  return ceiling - hang / drawingScaleFor(line).mmPerUnit
+}
+
+/** The OHT line a vehicle runs on: the one its data names (NODEMACHINE), its parent object, or the line holding it. */
+export function ohtLineOf(vehicle: any): any {
+  const isLine = (c: any) => c?.state?.type === 'OHTLine'
+  for (const id of [vehicle?.data?.NODEMACHINE, vehicle?.state?.parentObjectId]) {
+    if (!id) continue
+    const line = (vehicle.root?.findAllById?.(id) || []).find(isLine)
+    if (line) return line
+  }
+  return isLine(vehicle?.parent) ? vehicle.parent : undefined
+}
+
+/** The height an OHT hangs its top from, in drawing units: its line's rail, or the ceiling when it runs on none. */
+export function ohtRailTop(vehicle: any): number {
+  const line = ohtLineOf(vehicle)
+  return line ? railTopOf(line) : sceneHeightsOf(vehicle).ceiling
+}