@fmsim/machine 2.0.1 → 3.0.0-beta.1

package/src/mcs-carrier-holder.ts

@@ -1,105 +1,346 @@
 import { themesColorMap, themesAnimationMap } from '@fmsim/api'
+import JSON5 from 'json5'
+import {
+  Capacity,
+  Holdable,
+  ItemsDataBinding,
+  Model,
+  TRANSFER_SLOT_KEY,
+  figureLegendSourcesChanged,
+  itemTypeEntryOf,
+  itemTypeTableOf,
+  registerFigureCapability,
+  registerFigureLegendResolver,
+  type ItemType
+} from '@hatiolab/things-scene'
+import { HOLDER_ANCHOR, type ItemDims, type ResolvedSlot } from '@hatiolab/figure-model'
+import { CARRIER_HOLDER, carrierHolderProperties } from '@fmsim/figure-capabilities'
 import MCSUnit from './mcs-unit.js'
-import { parseIfJsonString } from './utils/data-value'
+import { incomingFromV2 } from './utils/load-address'
 
 /**
- * Holder.data 변경 감지 시 carrierManager 에 전달할 4 키 묶음 + multiCarriers 배열.
- * 비교 결과 단 하나라도 다르면 carrierManager.update 호출.
- * (데이터 키는 모두 대문자 전제 — 케이스 정규화 없이 직접 읽는다)
+ * A holder's slots outside its layout (common item contract 3.4): every carrier of a holder without a layout stands in
+ * one pile, and a carrier whose address is unknown or wrong stands in the exception area beside the holder.
  */
-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 const PILE_SLOT = 'pile'
+export const EXCEPTION_SLOT = 'exception'
+
+/** Where the exception area starts, past the holder's +X edge: a gap of this much of the holder's width */
+const EXCEPTION_GAP_RATIO = 0.1
+
+/** A carrier shown in a pile is this much of its holder's plan, and half its smaller side high (fmsim v2) */
+const PILE_PLAN_RATIO = 0.8
+const PILE_HEIGHT_RATIO = 0.5
+
+/** The record of one carrier the holder's data names: its id, the slot it stands in, what it is told */
+export interface CarrierRecord {
+  slotId: string
+  itemId: string
+  itemState: { data: Record<string, any>; showText: boolean }
 }
 
-export default class MCSCarrierHolder extends MCSUnit {
-  static get properties(): any {
-    return [
-      ...MCSUnit.properties,
-      {
-        type: 'select',
-        label: 'carrier-legend-name',
-        name: 'carrierLegendName',
-        property: {
-          options: themesColorMap
-        }
-      },
-      {
-        type: 'select',
-        label: 'carrier-animation-name',
-        name: 'carrierAnimationName',
-        property: {
-          options: themesAnimationMap
-        }
-      },
-      {
-        type: 'boolean',
-        label: 'show-carrier-text',
-        name: 'showCarrierText'
+/** The properties a carrier holder adds, offering the legends this board has (ADR-0167 decision 11, 미결 1) */
+export const CARRIER_HOLDER_PROPERTIES = carrierHolderProperties({ legends: themesColorMap, animations: themesAnimationMap })
+
+/**
+ * A holder of MCS carriers, as a mixin over what holds things (`fmsim.CarrierHolder`). What it holds is the common item
+ * contract's: carriers are its items (`_items`), found by their CARRIERNAME in the root (itemById), made, moved between
+ * holders and let go by the one reconcile by id. MCS's part is here: reading the holder data into one record per
+ * carrier, looking its CARRIERTYPE up in the domain's carrier type table (ADR-0155, theme carrier-types), and how a
+ * carrier -- whose size MCS does not say -- is shown.
+ */
+export function CarrierHolder<T extends new (...args: any[]) => any>(Base: T) {
+  return class extends Base {
+    /** Whatever wears this is a carrier holder: the legend resolver finds it up a carrier's parents. */
+    get isCarrierHolder(): true {
+      return true
+    }
+
+    /** The records the reconcile took last, as JSON: the same again is not reconciled */
+    _carrierRecordsTaken?: string
+
+    get showOverflow() {
+      return true
+    }
+
+    get hierarchy() {
+      return {
+        ...super.hierarchy,
+        components: []
       }
-      // 적층 두께는 carrier 측 (Carrier.added) 에서 자기 default depth 를 결정.
-      // holder 측에는 별도 carrierDepth 속성을 두지 않는다.
-    ]
-  }
+    }
 
-  get showOverflow() {
-    return true
-  }
+    // ── items: the holder data is the holder's, the records are worked out from it ─────────────
 
-  get hierarchy() {
-    return {
-      ...super.hierarchy,
-      components: []
+    _itemsFromData(): boolean {
+      return false
     }
-  }
 
-  dispose(): void {
-    ;(this.root as any)?.carrierManager?.update(this, {}, this.data)
-    super.dispose()
-  }
+    _keyedById(): boolean {
+      return true
+    }
 
-  async ready() {
-    super.ready()
+    /** A carrier the data moves here from another holder travels for two seconds */
+    itemMoveAnimation() {
+      return { duration: 2000, ease: 'inout' }
+    }
 
-    if (this._hasCarrierData(this.data)) {
-      ;(this.root as any).carrierManager.update(this, this.data || {}, undefined)
+    _createItemFromRecord(record: CarrierRecord): any {
+      const { width, height } = (this as any).state
+      return Model.compile(
+        { id: record.itemId, type: 'Carrier', left: 0, top: 0, width, height, ...record.itemState },
+        (this as any).root?.app
+      )
     }
-  }
 
-  onchangeData(after: Record<string, any>, before: Record<string, any>): void {
-    const afterData = after.data || {}
-    const beforeData = before.data || {}
+    /**
+     * One record per carrier the data names, bottom first: MULTICARRIERS in order, then the representative. Without a
+     * layout they all stand in the pile. A carrier is told its own keys and whether to show its text.
+     */
+    carrierRecords(data: Record<string, any> | undefined): CarrierRecord[] {
+      return incomingFromV2(data).map(c => ({
+        slotId: PILE_SLOT,
+        itemId: c.name,
+        itemState: this.carrierStateOf(c.record, c.record === data)
+      }))
+    }
+
+    /** What a carrier is told: its own keys (the representative's are picked out of the holder data), and its text */
+    carrierStateOf(record: Record<string, any>, representative: boolean): CarrierRecord['itemState'] {
+      let data: Record<string, any> = { ...record }
+      if (representative) {
+        data = { CARRIERNAME: record.CARRIERNAME }
+        for (const k of ['CARRIERTYPE', 'EMPTYTYPE', 'CARRIERSTATUS']) if (k in record) data[k] = record[k]
+      }
+      return { data, showText: !!(this as any).getState('showCarrierText') }
+    }
+
+    /**
+     * The carrier 2D draws (fmsim v2, a rule of position): the top of the data's stack -- MULTICARRIERS bottom first, the
+     * holder's own CARRIERNAME last -- when the holder holds it, else the last it holds.
+     */
+    get topCarrier(): any {
+      const items: any[] = (this as any)._items
+      const names = incomingFromV2((this as any).data).map(c => c.name)
+      for (let i = names.length - 1; i >= 0; i--) {
+        const held = items.find(c => c.state.id === names[i])
+        if (held) return held
+      }
+      return items[items.length - 1]
+    }
+
+    /** The holder's carriers made to be what its data says now. Records the same as last time change nothing */
+    syncCarriers(data: Record<string, any> | undefined) {
+      const records = this.carrierRecords(data)
+      const taken = JSON.stringify(records)
+      if (taken === this._carrierRecordsTaken) return
+      this._carrierRecordsTaken = taken
+      ;(this as any)._reconcileItems(records)
+    }
+
+    async ready() {
+      await super.ready()
+      this.syncCarriers((this as any).data)
+    }
+
+    onchange(after: Record<string, any>, before: Record<string, any>): void {
+      super.onchange(after, before)
+      /* Its size moves its bottom and changes the size a pile shows carriers at: they take its plan, made and seated again. */
+      if ('width' in after || 'height' in after || 'depth' in after) {
+        const { width, height } = (this as any).state
+        for (const carrier of (this as any)._items) if (width && height) carrier.set({ width, height })
+        this._carriersSeatedAgain()
+      }
+      /* 이 홀더의 Carrier 들이 물려받는 범례가 바뀌었다: 그 피규어들이 범례를 다시 고른다 (ADR-0166 결정 12) */
+      if ('carrierLegendName' in after || 'carrierAnimationName' in after) figureLegendSourcesChanged(this)
+      if ('showCarrierText' in after || 'slotLayout' in after) {
+        this._carrierRecordsTaken = undefined
+        this.syncCarriers((this as any).data)
+        if ('slotLayout' in after) this._carriersSeatedAgain()
+      }
+    }
+
+    onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+      this.syncCarriers(after.data || {})
+      super.onchangeData(after, before)
+    }
+
+    // ── the domain's item types ────────────────────────────────────────────────
+
+    /**
+     * A carrier's type (ADR-0155): the code it says (its CARRIERTYPE, trimmed and upper-cased -- doc 01, 6.8), in the
+     * domain's carrier type table the scene was given when it opened. None when the table does not have it, or the scene
+     * was given none.
+     */
+    carrierItemType(carrier: any): ItemType | null {
+      const table = itemTypeTableOf(this)
+      return (table && itemTypeEntryOf(table, carrier)) || null
+    }
+
+    /** A carrier's item type: its code, when the domain's table has it; else null */
+    itemTypeOf(carrier: any): string | null {
+      return this.carrierItemType(carrier)?.code ?? null
+    }
+
+    /**
+     * A carrier's size in mm, as judged: none. MCS data does not say a carrier's size and a carrier type has none
+     * (ADR-0155 amendment 1 C); a carrier is shown at the size of the place it stands in (itemShownDimsOf).
+     */
+    itemDimsOf(_carrier: any): ItemDims | null {
+      return null
+    }
 
-    let changed = false
-    for (const k of CARRIER_DATA_KEYS) {
-      if (afterData[k] !== beforeData[k]) {
-        changed = true
-        break
+    /**
+     * The size a carrier of unknown size is shown at, in mm (for showing only, never judged). In the pile, most of the
+     * holder's plan and half its smaller side high; elsewhere the box filling its slot, its height shared by the stack.
+     */
+    itemShownDimsOf(_carrier: any, slot: ResolvedSlot, slotId: string): ItemDims | null {
+      /* Elsewhere outside the layout, a holder that keeps carriers there says (the exception area: LoadLayoutHolder). */
+      if (slotId === PILE_SLOT) {
+        const k = (this as any).mmPerSceneUnit
+        const { width = 0, height = 0 } = (this as any).state
+        const w = Math.abs(width) * PILE_PLAN_RATIO
+        const d = Math.abs(height) * PILE_PLAN_RATIO
+        return w > 0 && d > 0 ? { width: w * k, depth: d * k, height: Math.min(w, d) * PILE_HEIGHT_RATIO * k } : null
       }
+      const layers = Number.isFinite(slot.stackLimit) && slot.stackLimit > 0 ? slot.stackLimit : 1
+      return Number.isFinite(slot.allowed.width)
+        ? { width: slot.allowed.width, depth: slot.allowed.depth, height: slot.allowed.height / layers }
+        : null
     }
-    if (!changed) {
-      changed = multiCarriersChanged(afterData, beforeData)
+
+    /** A carrier's size as it is shown, in mm: its own, or the size its slot shows an unknown one at (its seat's) */
+    carrierShownDimsOf(carrier: any): ItemDims | null {
+      return (this as any).itemSeatOf(carrier)?.dims ?? null
+    }
+
+    /** Every carrier made again at the size it is shown at, and every slot seated again */
+    _carriersSeatedAgain() {
+      const items: any[] = (this as any)._items
+      for (const carrier of items) carrier._realObject?.update?.()
+      const slots = new Set(items.map(c => c[TRANSFER_SLOT_KEY]))
+      for (const slotId of slots) (this as any)._reseatSlot(slotId)
+    }
+
+    // ── where carriers stand ──────────────────────────────────────────────────
+
+    /**
+     * Where a holder's carriers rest, in coordinates above the holder's bottom, and whether they stand on it or hang from
+     * it: on the transport surface by default (fmsim v2). A Port, Shelf or Shuttle holds them at its bottom; an OHT hangs
+     * them below.
+     */
+    get carrierRest(): { height: number; mount: 'ON' | 'HANG' } {
+      return { height: 30, mount: 'ON' }
+    }
+
+    /** The pile, and the exception area beside the holder's +X edge. Frames in mm on the holder's own anchor (its bottom) */
+    outsideSlots() {
+      const k = (this as any).mmPerSceneUnit
+      const { width = 0 } = (this as any).state
+      const w = Math.abs(width)
+      const rest = this.carrierRest
+      return [
+        {
+          id: PILE_SLOT,
+          anchorId: HOLDER_ANCHOR,
+          frame: { position: { x: 0, y: rest.height * k, z: 0 }, rotation: 0 },
+          mount: rest.mount
+        },
+        {
+          id: EXCEPTION_SLOT,
+          anchorId: HOLDER_ANCHOR,
+          frame: {
+            position: { x: (w / 2 + w * EXCEPTION_GAP_RATIO) * k + this.exceptionHalfWidth, y: 0, z: 0 },
+            rotation: 0
+          }
+        }
+      ]
     }
 
-    if (changed) {
-      ;(this.root as any).carrierManager.update(this, afterData, beforeData)
+    /** Half the width of a carrier in the exception area, in mm: its edge stands past the gap */
+    get exceptionHalfWidth(): number {
+      return 0
     }
 
-    super.onchangeData(after, before)
+    /**
+     * The holder's own anchor is its bottom's centre: a node on the frame at its 3D's origin (the box centre), half its
+     * 3D's depth down, turned and moved with it. Others by the layer below.
+     */
+    anchorObject3D(anchorId: string): any {
+      const frame = super.anchorObject3D(anchorId)
+      if (anchorId !== HOLDER_ANCHOR || !frame) return frame
+      let node = frame.userData.carrierAnchor
+      if (!node || node.parent !== frame) {
+        node = new frame.constructor()
+        node.name = 'carrier-anchor'
+        frame.add(node)
+        frame.userData.carrierAnchor = node
+      }
+      node.position.set(0, -(Number((this as any)._realObject?.effectiveDepth) || 0) / 2, 0)
+      return node
+    }
   }
+}
+
+/* The mixins of things-scene are typed loosely: the holder is still an MCSUnit. */
+interface MCSCarrierHolder extends MCSUnit {}
+
+/** fmsim's own carrier holder: an MCS unit that holds things, wearing `fmsim.CarrierHolder`. */
+class MCSCarrierHolder extends CarrierHolder(ItemsDataBinding(Holdable(Capacity(MCSUnit as any)))) {
+  static get properties(): any {
+    return [...MCSUnit.properties, ...CARRIER_HOLDER_PROPERTIES]
+  }
+}
+
+export default MCSCarrierHolder
 
-  /** 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
+/*
+  The legend a carrier figure shows its tables by (ADR-0166 7, 12; ADR-0167 11): the nearest carrier holder up its
+  parents that chose one for the role -- carrier-legend its carrier legend, carrier-animation its carrier animation --
+  then the board root's same choice; none chosen, no answer (the figure's own table, fmsim's default). Colour and effect
+  only: a carrier figure's thickness is its own fixed table (ADR-0167 12).
+*/
+const ROLE_PROPERTY: Record<string, string> = {
+  'carrier-legend': 'carrierLegendName',
+  'carrier-animation': 'carrierAnimationName'
+}
+
+export function carrierHolderLegend({ component, role }: { component: any; role: string }): unknown {
+  const property = ROLE_PROPERTY[role]
+  if (!property) return undefined
+  let name: unknown
+  for (let at = component?.parent; at && !name; at = at.parent) if (at.isCarrierHolder) name = at.state?.[property]
+  name ||= component?.root?.rootModel?.state?.[property]
+  if (typeof name !== 'string' || !name) return undefined
+  let legend = component?.root?.style?.[name]
+  if (typeof legend === 'string') {
+    try {
+      legend = JSON5.parse(legend)
+    } catch {
+      return undefined
+    }
   }
+  return legend && typeof legend === 'object' ? colourAndEffect(legend) : undefined
 }
+
+/** A legend as a figure takes it from fmsim: each entry's colour and effect; a colour alone stays the colour; an entry's JSON5 text read. */
+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, entry]
+      const { color, effect } = entry as { color?: unknown; effect?: unknown }
+      return [code, { ...(color !== undefined ? { color } : {}), ...(effect !== undefined ? { effect } : {}) }]
+    })
+  )
+}
+
+registerFigureLegendResolver(carrierHolderLegend)
+registerFigureCapability({ ...CARRIER_HOLDER, properties: CARRIER_HOLDER_PROPERTIES as never }, base => CarrierHolder(base) as never)

package/src/oht.ts

@@ -16,6 +16,11 @@ export default class OHT extends MCSVehicle {
     return NATURE
   }
 
+  /** Carriers hang below the OHT's bottom, the gripper's (fmsim v2) */
+  get carrierRest(): { height: number; mount: 'ON' | 'HANG' } {
+    return { height: 0, mount: 'HANG' }
+  }
+
   get auxColor() {
     return 'black'
   }

package/src/port.ts

@@ -1,6 +1,7 @@
 import { Component, ComponentNature, sceneComponent } from '@hatiolab/things-scene'
 import { MCSZoneMixin, MCSZoneMixinProperties } from './features/mcs-zone-mixin'
 import MCSCarrierHolder from './mcs-carrier-holder'
+import { LoadLayoutHolder } from './features/load-layout-holder'
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -10,11 +11,16 @@ const NATURE: ComponentNature = {
 }
 
 @sceneComponent('Port')
-export default class Port extends MCSZoneMixin(MCSCarrierHolder) {
+export default class Port extends LoadLayoutHolder(MCSZoneMixin(MCSCarrierHolder)) {
   static get nature() {
     return NATURE
   }
 
+  /** Carriers stand at the Port's bottom (fmsim v2) */
+  get carrierRest(): { height: number; mount: 'ON' | 'HANG' } {
+    return { height: 0, mount: 'ON' }
+  }
+
   get auxColor() {
     return 'black'
   }

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

@@ -1,7 +1,6 @@
-import { Component, RootContainer } from '@hatiolab/things-scene'
+import { Component, RootContainer, figureLegendSourcesChanged } from '@hatiolab/things-scene'
 import { themesColorMap, themesColorRange, themesAnimationMap } from '@fmsim/api'
 import { Legend } from '../features/mcs-status-default'
-import CarrierManager from '../carrier-manager'
 
 // RootContainer 클래스 타입 확장
 declare module '@hatiolab/things-scene' {
@@ -31,8 +30,6 @@ declare module '@hatiolab/things-scene' {
     _refreshStockerGauges(): void
     // 캐시 관련 속성 추가
     _animationConfigCache?: Map<string, any>
-    _carrierManager?: CarrierManager
-    carrierManager: CarrierManager
   }
 }
 
@@ -263,6 +260,8 @@ ModelLayer.prototype.onchange = function (after: any) {
       })
     }
   }
+  /* 보드의 Carrier 범례가 바뀌었다: Carrier 피규어들이 범례를 다시 고른다 (ADR-0166 결정 12) */
+  if (after && ['carrierLegendName', 'carrierAnimationName'].some(k => Object.prototype.hasOwnProperty.call(after, k))) figureLegendSourcesChanged()
   return _origModelLayerOnchange.call(this, after)
 }
 
@@ -272,7 +271,7 @@ ModelLayer.prototype.onchange = function (after: any) {
 // 형태에 따라 (a) 정상 object 또는 (b) JSON 문자열 둘 다로 나타난다 (2026-06-09
 // 진단 — consumer 인 carrier.ts:animationPreset 이 같은 이유로 typeof string
 // 분기 + JSON5.parse 처리하는 선례 존재). LegendTheme getter 들이 이 분기를
-// 두지 않아 string 통과 → getValueOnRanges 매칭 실패 → 3D gauge 의 색상이
+// 두지 않아 string 통과 → 구간 조회 매칭 실패 → 3D gauge 의 색상이
 // fallback 으로만 결정되던 증상.
 //
 // fix 는 getter 한 곳에서 lazy parse. WeakMap<state, Map<rawString, parsed>>
@@ -327,15 +326,6 @@ Object.defineProperty(RootContainer.prototype, 'vehicleAnimation', {
   }
 })
 
-Object.defineProperty(RootContainer.prototype, 'carrierManager', {
-  get: function () {
-    if (!this._carrierManager) {
-      this._carrierManager = new CarrierManager(this)
-    }
-    return this._carrierManager
-  }
-})
-
 // === 스토커 게이지 표시 모드 (런타임 전용 transient) ===
 //
 // 모델(state)에 저장하지 않는다 — nature 속성이 아니므로 보드 직렬화에 포함되지 않고,

package/src/shelf.ts

@@ -15,6 +15,11 @@ export default class Shelf extends MCSZoneMixin(MCSCarrierHolder) {
     return NATURE
   }
 
+  /** Carriers stand at the Shelf's bottom (fmsim v2) */
+  get carrierRest(): { height: number; mount: 'ON' | 'HANG' } {
+    return { height: 0, mount: 'ON' }
+  }
+
   get auxColor() {
     return 'black'
   }

package/src/shuttle.ts

@@ -15,6 +15,11 @@ export default class Shuttle extends MCSVehicle {
     return NATURE
   }
 
+  /** Carriers stand at the Shuttle's bottom (fmsim v2) */
+  get carrierRest(): { height: number; mount: 'ON' | 'HANG' } {
+    return { height: 0, mount: 'ON' }
+  }
+
   get auxColor() {
     return 'black'
   }

package/src/stocker-carrier-bar.ts

@@ -6,7 +6,7 @@ import {
   Shape,
   sceneComponent
 } from '@hatiolab/things-scene'
-import { LEGEND_CARRIER } from './features/mcs-status-default'
+import { LEGEND_CARRIER, legendColor } from './features/mcs-status-default'
 import { safeRound } from './utils/safe-round'
 import { ParentObjectMixin, ParentObjectMixinProperties } from './features/parent-object-mixin'
 
@@ -57,9 +57,9 @@ const NATURE: ComponentNature = {
 }
 
 const DEFAULT_COLORS = {
-  full: LEGEND_CARRIER['FULL'] || '#4AA7FE',
-  empty: LEGEND_CARRIER['EMPTY'] || '#8BDA5B',
-  emptyEmpty: LEGEND_CARRIER['EMPTYEMPTY'] || '#019D59'
+  full: legendColor(LEGEND_CARRIER['FULL']) || '#4AA7FE',
+  empty: legendColor(LEGEND_CARRIER['EMPTY']) || '#8BDA5B',
+  emptyEmpty: legendColor(LEGEND_CARRIER['EMPTYEMPTY']) || '#019D59'
 }
 
 var controlHandler = {

package/src/utils/carrier-type-code.ts

@@ -0,0 +1,9 @@
+/*
+ * How live data's CARRIERTYPE is compared (fmsim doc 01, 6.8): trimmed and upper-cased. The code it makes is looked up
+ * in the domain's item type table (ADR-0155), whose codes fmsim writes in that form.
+ */
+export function normalizeTypeCode(code: unknown): string {
+  return String(code ?? '')
+    .trim()
+    .toUpperCase()
+}

package/src/utils/crane-forks.ts

@@ -0,0 +1,4 @@
+/* 크레인 포크 수 (설계 02번 3.2.1절 트윈 포크). 1(단일) 또는 2(트윈). 그 밖의 값은 1 */
+export function craneForkCount(value: unknown): 1 | 2 {
+  return Number(value) === 2 ? 2 : 1
+}

package/src/utils/layout-issue-text.ts

@@ -0,0 +1,18 @@
+/*
+ * fmsim 고유 오류 코드의 기본 문구 (영어). 화면은 label.load-layout.issue.{코드} 번역을 먼저 쓰고, 없으면 이 문구를 쓴다.
+ * 층·자리 검증 코드의 문구는 공통 편집기(@operato/slot-layout-editor)의 것을 쓴다.
+ */
+
+import { LayoutIssueCode } from './layout-issue'
+
+/** 오류 코드의 기본 문구 (번역이 없을 때). 매개변수는 {name} 으로 넣는다. 자리표시자가 중괄호라서 문구에 중괄호 글자를 쓰지 않는다 */
+export const ISSUE_TEXT: Record<LayoutIssueCode, string> = {
+  ADDRESSING_BY_INVALID: 'Must be fields or a location pattern',
+  FIELD_REQUIRED: 'A field name is required',
+  ADDRESS_PATTERN_EMPTY: 'The pattern is empty',
+  ADDRESS_PATTERN_SYNTAX: 'Broken token near "{text}"',
+  ADDRESS_PATTERN_TOKEN_REPEATED: 'The {token} token may appear only once',
+  ADDRESS_PATTERN_WIDTH_NOT_ALLOWED: 'Digits are allowed only on the tier and slot tokens, not on {token}',
+  ADDRESS_PATTERN_SLOT_REQUIRED: 'The pattern needs a slot token',
+  DUPLICATE_CARRIER: 'The same carrier came twice: {name}'
+}

package/src/utils/layout-issue.ts

@@ -0,0 +1,41 @@
+/*
+ * fmsim 고유 검증 결과: 실시간 주소 읽기 규칙과 점유 데이터 (설계 02번 3.6절, 4.2절)
+ * 층·자리 레이아웃의 검증은 figure-model 이 한다. 검증 함수는 문장을 만들지 않고 코드·필드 경로·매개변수만 돌려준다.
+ */
+
+export type LayoutIssueCode =
+  /** FIELDS·PATTERN 중 하나 */
+  | 'ADDRESSING_BY_INVALID'
+  /** 필드 이름이 필요하다 */
+  | 'FIELD_REQUIRED'
+  /** 위치 문자열 패턴이 비었다 */
+  | 'ADDRESS_PATTERN_EMPTY'
+  /** 토큰 문법 오류 (params.text) */
+  | 'ADDRESS_PATTERN_SYNTAX'
+  /** {tier}·{slot} 은 한 번만 (params.token) */
+  | 'ADDRESS_PATTERN_TOKEN_REPEATED'
+  /** {tier}·{slot} 밖의 토큰에는 자릿수를 쓰지 않는다 (params.token) */
+  | 'ADDRESS_PATTERN_WIDTH_NOT_ALLOWED'
+  /** {slot} 이 없다 */
+  | 'ADDRESS_PATTERN_SLOT_REQUIRED'
+  /** 한 홀더에 같은 Carrier 가 두 번 왔다 (params.name) */
+  | 'DUPLICATE_CARRIER'
+
+export interface LayoutIssue {
+  code: LayoutIssueCode
+  /** 값의 위치. 예 'addressing.pattern'. 값 전체이면 빈 문자열 */
+  path: string
+  params?: Record<string, string | number>
+}
+
+export function issue(code: LayoutIssueCode, path: string, params?: Record<string, string | number>): LayoutIssue {
+  return params ? { code, path, params } : { code, path }
+}
+
+/** 위치 문자열 패턴 문법 오류. issues 에 모든 문제가 들어 있다 */
+export class AddressPatternError extends Error {
+  constructor(readonly issues: LayoutIssue[]) {
+    super(issues.map(i => i.code).join(', '))
+    this.name = 'AddressPatternError'
+  }
+}