@fmsim/machine 2.0.1 → 3.0.0-beta.1

package/src/carrier.ts

@@ -1,11 +1,12 @@
 import JSON5 from 'json5'
 import { getPopupData } from '@fmsim/api'
 
-import { BOUNDS, Component, ComponentNature, Properties, Shape, sceneComponent } from '@hatiolab/things-scene'
-import { ANIMATION_DEFAULT, AnimationPreset, AnimationConfig } from './features/animation-default.js'
+import { BOUNDS, ComponentNature, Item, TRANSFER_SLOT_KEY, figureLegendSourcesChanged, registerFigureCapability, sceneComponent } from '@hatiolab/things-scene'
+import { ANIMATION_DEFAULT, CARRIER_FIGURE, type AnimationConfig, type AnimationPreset } from '@fmsim/figure-capabilities'
 import { ParentObjectMixin } from './features/parent-object-mixin.js'
 import { Legend, resolveCarrierLegend } from './features/mcs-status-default.js'
 import { MCSStatusMixin } from './features/mcs-status-mixin.js'
+import { normalizeTypeCode } from './utils/carrier-type-code'
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -28,12 +29,26 @@ const NATURE: ComponentNature = {
  */
 const STATUS_TEXT_COUNTER_ROTATE = true
 
+/**
+ * 캐리어는 아이템이다 (공통 아이템 계약, ADR-0167 6). 컴포넌트 타입은 Carrier 그대로이고, 아이템 타입은 CARRIERTYPE 이다.
+ * 3D 는 그 타입이 이름한 피규어(carrier-types)가 그리고, 그리는 피규어가 없으면 fmsim 의 캐리어 상자다. 2D 는 그대로.
+ */
 @sceneComponent('Carrier')
-export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
+export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Item)) {
   static get nature() {
     return NATURE
   }
 
+  /** 아이템 타입 코드: CARRIERTYPE 을 라이브 데이터 비교 규칙대로 (fmsim 문서 01, 6.8 — trim·대문자) */
+  get itemTypeCode(): string {
+    return normalizeTypeCode(this.data?.CARRIERTYPE ?? this.state.CARRIERTYPE)
+  }
+
+  /** 3D 가 아이템의 것(피규어)인지: 타입의 피규어가 있을 때만. 없으면 'Carrier' 로 등록된 fmsim 상자가 지어진다 */
+  get drawnAsItem(): boolean {
+    return !!this.look
+  }
+
   get decorators() {
     return ['decotag']
   }
@@ -59,34 +74,26 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
   /** 마지막으로 적용한 (애니메이션 테마 | CARRIERSTATUS) 조합. 같은 조합 재적용을 막는다. */
   private _appliedAnimationKey?: string
 
-  added(parent: any) {
-    super.added(parent)
-
-    // 새 부모에 맞춰 크기 및 상태 갱신 — width/height 만. depth 는 *절대로
-    // 건드리지 않는다*. machine-3d.ts 의 CARRIER_CONFIG + MCSRealObject3D.
-    // effectiveDepth 가 depthRatio(0.5) × min(w,h) 로 자동 결정한다.
-    // 여기서 state.depth 를 명시 set 하면 그 resolution chain 의 step 1 에
-    // 걸려 본래 두께가 덮어써진다 (= 사용자 호소 "두께가 줄어들었다" 의 원인).
-    if (parent) {
-      const { width, height } = parent.state || {}
-      if (width && height) {
-        this.set({ width, height })
-      }
-    }
+  /**
+   * 홀더가 받았다 (공통 아이템 계약 3.5 의 handover 끝). 2D 는 홀더 평면을 덮으므로 width/height 를 새 홀더에 맞춘다.
+   * depth 는 건드리지 않는다 — 3D 크기는 홀더가 보이는 치수(itemSeatOf().dims)로 정한다.
+   */
+  held(holder: any) {
+    const { width, height } = holder?.state || {}
+    if (width && height) this.set({ width, height })
 
     this.syncStateFromData()
 
     /* 부모가 정해진 지금 다시 해석한다 — 생성 시(data 선할당) 판정에는 parent 가 없어
-     * 홀더의 carrierAnimationName 이 반영되지 않았다. reparent 로 홀더가 바뀐 경우도 여기서
+     * 홀더의 carrierAnimationName 이 반영되지 않았다. 홀더가 바뀐 경우도 여기서
      * 새 홀더 테마로 갱신된다. (같은 조합이면 내부 가드로 no-op) */
     this._applyStatusAnimation()
 
-    // 3D 오브젝트 최초 생성 (동기적 — reparent()에서 _realObject 필요)
-    if ((this.root as any)?.threed && !this._realObject) {
-      ;(this.root as any).model_layer?._threeCapability?.addObject(this)
-    }
+    /* 범례는 홀더가 물려준다: 새 홀더의 범례로 이 Carrier 의 피규어가 범례를 다시 고른다 (ADR-0166 결정 12) */
+    figureLegendSourcesChanged(this)
 
-    // reparent 애니메이션은 things-scene의 reparent()가 처리
+    // 새 홀더가 보이는 치수로 3D 를 다시 만든다 (자리는 홀더가 앉힌다)
+    ;(this._realObject as any)?.update?.()
   }
 
   /**
@@ -103,6 +110,7 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
     const { CARRIERNAME, CARRIERTYPE = '', EMPTYTYPE, CARRIERSTATUS } = this.data || {}
+    const typeChanged = (after.data?.CARRIERTYPE ?? '') !== (before.data?.CARRIERTYPE ?? '')
 
     this.setState('id', CARRIERNAME)
     this.setState('EMPTYTYPE', EMPTYTYPE)
@@ -113,6 +121,13 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
      * (테마|상태) 키 비교로 하므로 여기서 status 변경 여부를 따지지 않는다 —
      * 상태는 그대로여도 홀더가 바뀌어(=테마가 바뀌어) 재적용이 필요할 수 있다. */
     this._applyStatusAnimation()
+
+    /* 같은 Carrier 의 타입이 바뀌었다 (계약 Q10): 그 타입의 피규어가 모양이 되고, 보이는 치수로 3D 를 다시 만들고, 그 자리를 다시 앉힌다 */
+    if (typeChanged) this.refreshLook()
+    if (typeChanged && this.parent) {
+      ;(this._realObject as any)?.update?.()
+      ;(this.parent as any)._reseatSlot?.((this as any)[TRANSFER_SLOT_KEY])
+    }
   }
 
   /**
@@ -123,8 +138,8 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
    *
    * 호출 시점이 둘인 이유:
    *   1) onchangeData  — 상태(또는 테마) 변화 반영
-   *   2) added()       — **부모가 생긴 직후**. CarrierManager 는 `carrier.data = item` 을
-   *      addComponent 보다 먼저 하므로, 생성 시 첫 판정에는 parent 가 없어 홀더의
+   *   2) held()        — **홀더가 받은 직후**. 홀더는 data 를 넣어 Carrier 를 만든 뒤
+   *      받으므로, 생성 시 첫 판정에는 parent 가 없어 홀더의
    *      carrierAnimationName 이 무시된다(루트 폴백만 보임). 부모가 붙은 뒤 한 번 더
    *      해석해야 홀더 테마가 반영된다.
    */
@@ -184,7 +199,7 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
    * 적용할 애니메이션 테마 이름 — 소유 홀더(부모) 설정이 우선, 없으면 보드(rootModel) 폴백.
    *
    * 부모가 아직 없는 시점(생성 직후 data 선할당)에는 홀더 설정을 알 수 없어 루트 폴백만
-   * 보인다. 그래서 added() 에서 한 번 더 해석한다 — _applyStatusAnimation 참조.
+   * 보인다. 그래서 held() 에서 한 번 더 해석한다 — _applyStatusAnimation 참조.
    */
   get resolvedCarrierAnimationName(): string {
     return (
@@ -296,16 +311,12 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
       return
     }
 
-    // 2D 에서는 stack 의 *맨 위 (= parent.components 의 마지막)* 1개만 그린다.
-    // ADDITIONS 의 carrier 들도 인스턴스로는 살아있어 조회/reparent 가 가능하지만
-    // 2D 시각에는 노출하지 않는다 — 정책: "2D 는 현행처럼" (대표 1개만).
-    // 판단 기준은 *위치* — carrier 간 그룹/종속 정보는 두지 않는다.
-    const parent = this.parent
-    if (parent && parent.components && parent.components.length > 1) {
-      const siblings = parent.components
-      if (siblings[siblings.length - 1] !== this) {
-        return
-      }
+    // 2D 에서는 홀더 데이터 stack 의 *맨 위 (MULTICARRIERS 다음 CARRIERNAME 순서의 마지막)* 1개만 그린다.
+    // 다른 carrier 들도 인스턴스로는 살아있어 조회·이동이 가능하지만
+    // 2D 시각에는 노출하지 않는다 — 정책: "2D 는 현행처럼" (1개만). 판단 기준은 위치 — carrier 간 그룹/종속 정보는 두지 않는다.
+    const top = (this.parent as any)?.topCarrier
+    if (top && top !== this) {
+      return
     }
 
     const { width, height } = this.bounds
@@ -362,11 +373,6 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
     }
   }
 
-  dispose(): void {
-    ;(this.root as any)?.carrierManager?.onCarrierDisposed(this.state.id)
-
-    super.dispose()
-  }
 
   async detailInfo() {
     const { type, id } = this.state
@@ -378,3 +384,6 @@ export default class Carrier extends MCSStatusMixin(ParentObjectMixin(Shape)) {
     return await getPopupData(type, id)
   }
 }
+
+/* fmsim.Carrier (ADR-0167 12): what it gives a figure is its tables, handed by its descriptor -- no mixin of its own */
+registerFigureCapability(CARRIER_FIGURE, base => class extends base {})

package/src/crane.ts

@@ -1,6 +1,9 @@
 import { Component, ComponentNature, sceneComponent, frameClock } from '@hatiolab/things-scene'
 import MCSVehicle from './mcs-vehicle'
 import { LEGEND_CRANE } from './features/mcs-status-default'
+import { LoadLayoutHolder } from './features/load-layout-holder'
+import { HOLDER_ANCHOR, forkAnchorId } from '@hatiolab/figure-model'
+import { craneForkCount } from './utils/crane-forks'
 import {
   axisRatio,
   mapCraneLocalPosition,
@@ -12,9 +15,18 @@ const NATURE: ComponentNature = {
   mutable: false,
   resizable: true,
   rotatable: true,
-  properties: [...MCSVehicle.properties]
+  properties: [
+    ...MCSVehicle.properties,
+    {
+      type: 'select',
+      label: 'fork-count',
+      name: 'forkCount',
+      property: { options: ['1', '2'] }
+    }
+  ]
 }
 
+
 const GAP = 2
 
 /** 좌표 보간 기본 duration (ms). data.DURATION_MS 가 없으면 이 값 사용. */
@@ -41,11 +53,36 @@ interface CranePositionAnimator {
 }
 
 @sceneComponent('Crane')
-export default class Crane extends MCSVehicle {
+export default class Crane extends LoadLayoutHolder(MCSVehicle) {
   static get nature() {
     return NATURE
   }
 
+  /**
+   * 크레인이 주는 Anchor (설계 02번 3.7.2절): 홀더 원점과 포크마다 하나(fork_1, fork_2). 포크가 하나뿐인 장비에
+   * fork_2 에 선 Tier 가 있으면 레이아웃 전체가 잘못된 값이다: Carrier 를 자리 없이 한 무더기로 쌓고 패널에 오류를 보인다
+   * (ADR-0051 4.1절 결정 8).
+   */
+  slotAnchors(): string[] {
+    const forks = craneForkCount((this.state as any).forkCount)
+    return [HOLDER_ANCHOR, ...Array.from({ length: forks }, (_, i) => forkAnchorId(i + 1))]
+  }
+
+  /** 포크 Anchor 는 크레인 3D 의 그 포크 판 윗면 노드다. 포크가 오르내리고 뻗으면 그 위의 Carrier 가 함께 간다 */
+  anchorObject3D(anchorId: string): any {
+    return (this as any)._realObject?.forkAnchor?.(anchorId) ?? super.anchorObject3D(anchorId)
+  }
+
+  /** 포크 수가 바뀌면 주는 Anchor 가 바뀌므로, 데이터가 다시 오지 않아도 지금 데이터로 자리를 다시 배정한다 */
+  onchange(after: Record<string, any>, before: Record<string, any>): void {
+    super.onchange(after, before)
+    if ('forkCount' in after && craneForkCount(after.forkCount) !== craneForkCount(before?.forkCount)) {
+      ;(this as any)._carrierRecordsTaken = undefined
+      ;(this as any).syncCarriers(this.data || {})
+      ;(this as any)._carriersSeatedAgain()
+    }
+  }
+
   get auxColor() {
     return 'black'
   }

package/src/editors/index.ts

@@ -1,5 +1,7 @@
 import './ox-input-nodes'
 import './ox-property-editor-nodes'
+// 속성 패널의 "Carrier 적재 자리" 구역 (board specifics 가 적재 레이아웃 홀더를 선택했을 때 쓴다)
+import './ox-load-layout-panel'
 
 export default [
   {

package/src/editors/load-layout-host.ts

@@ -0,0 +1,121 @@
+/*
+ * fmsim 이 공통 편집기(@operato/slot-layout-editor)에 주는 것 (설계 02번 3.7.1절)
+ * Tier·Slot 편집, 검증, 미리보기, 적용 전 주소 영향은 공통 편집기가 한다. 기종 프리셋·실효 레이아웃·검증은 figure-model 의
+ * 것이다(ADR-0051 4.1절 결정 8). 이 패널은 도면 노드의 배치 덮어쓰기 화면이고, fmsim 은 자기 몫만 넘긴다:
+ * 프리셋 이름, 홀더가 주는 Anchor, 값의 출처·도면 단위 안내, 실시간 주소 읽기 설정과 그 검증, fmsim 고유 오류 문구.
+ * 화면 요소를 만들지 않는 순수 모듈이다 — 문구 함수(t)와 공통 문구 함수는 부르는 쪽이 준다.
+ */
+
+import type { SlotLayoutEditorOptions, SlotLayoutPreset } from '@operato/slot-layout-editor'
+import {
+  figureSlotLayoutIssues,
+  slotLayoutPreset,
+  SLOT_LAYOUT_PRESET_KEYS,
+  SLOT_LAYOUT_PRESET_PARAMS,
+  type LayoutIssue as SlotLayoutIssue,
+  type SlotLayoutPresetKey,
+  type SlotMount
+} from '@hatiolab/figure-model'
+import { LoadAddressing, LoadLayout, validateAddressing } from '../utils/load-address'
+import { LayoutIssue, LayoutIssueCode } from '../utils/layout-issue'
+import { ISSUE_TEXT } from '../utils/layout-issue-text'
+
+export type Translate = (key: string, fallback: string, options?: Record<string, unknown>) => string
+
+/** 문제 하나: 코드·값의 위치·매개변수 */
+export type IssueLike = { code: string; path: string; params?: Record<string, string | number> }
+
+/** 공통 편집기의 문제 문구 (층·자리 검증 코드) */
+export type CommonIssueText = (issue: IssueLike) => string
+
+// ── 기종 프리셋 (3.7절, figure-model) ─────────────────────────────────────────
+
+const PRESET_LABELS: Record<SlotLayoutPresetKey, string> = {
+  single: 'Single slot',
+  agvTandem: 'AGV tandem (front/rear)',
+  agvParallel: 'AGV parallel (left/right)',
+  agv2x2: 'AGV 2×2',
+  bufferPort2x2: 'Buffer port 2×2',
+  multiBufferPort: 'Multi-buffer port (4)',
+  dualTierConveyor: 'Dual-tier conveyor',
+  craneTwinFork: 'Crane twin fork',
+  floorBlock: 'Floor block'
+}
+
+const PARAM_LABELS: Record<string, string> = {
+  upperElevation: 'Upper tier elevation (mm)',
+  rows: 'Rows',
+  cols: 'Columns',
+  stackLimit: 'Stack limit'
+}
+
+/** 공통 편집기의 프리셋 목록. 홀더 원점·포크 Anchor 위에 펼치고, 단일 자리는 홀더의 적재 방식으로 만든다 */
+export function fmsimPresets(mount: SlotMount, t: Translate): SlotLayoutPreset<LoadLayout>[] {
+  return SLOT_LAYOUT_PRESET_KEYS.map(key => ({
+    key,
+    label: t(`preset-${key}`, PRESET_LABELS[key]),
+    params: SLOT_LAYOUT_PRESET_PARAMS[key].map(p => ({ key: p.key, label: t(`param-${p.key}`, PARAM_LABELS[p.key]), integer: p.integer })),
+    build: (size, params) => slotLayoutPreset(key, size, params, { mount })
+  }))
+}
+
+// ── 실시간 주소 읽기 (3.6절) ────────────────────────────────────────────────
+
+export function setAddressing(layout: LoadLayout, addressing: LoadAddressing | undefined): LoadLayout {
+  const next = structuredClone(layout)
+  if (addressing) next.addressing = structuredClone(addressing)
+  else delete next.addressing
+  return next
+}
+
+// ── 편집기 옵션 ─────────────────────────────────────────────────────────────
+
+/** fmsim 고유 오류(주소 읽기 등)의 문구. fmsim 코드가 아니면 undefined — 공통 편집기 문구를 쓴다 */
+export function fmsimIssueText(issue: IssueLike, t: Translate): string | undefined {
+  const fallback = ISSUE_TEXT[issue.code as LayoutIssueCode]
+  if (!fallback) return undefined
+  const text = t(`issue.${issue.code}`, fallback, { ...issue.params, interpolation: { escapeValue: false } })
+  return issue.path ? `${issue.path}: ${text}` : text
+}
+
+/**
+ * 공통 편집기가 보는 것 밖의 검증: 실효 레이아웃이 덮어쓰기에 거는 figure 규칙(받는 타입은 생략하면 모든 아이템, 적으면
+ * 비지 않은 목록, ADR-0051 4.1절 결정 5·7)과 주소 읽기 설정. 공통 검증 결과는 편집기가 이미 보이므로 figure 고유 코드만 더한다.
+ */
+export function holderLayoutIssues(layout: LoadLayout, anchors: readonly string[]): (SlotLayoutIssue | LayoutIssue)[] {
+  return [...figureSlotLayoutIssues(layout, anchors).filter(i => i.code === 'ACCEPTS_EMPTY'), ...validateAddressing(layout.addressing)]
+}
+
+/** 선택한 홀더(LoadLayoutHolder)에서 공통 편집기 옵션을 만든다. value 는 도면 노드의 개별 설정 */
+export function holderEditorOptions(holder: any, value: LoadLayout | undefined, t: Translate, commonText: CommonIssueText): SlotLayoutEditorOptions<LoadLayout> {
+  const sel = holder.effectiveLayout
+  const mm = holder.mmPerUnit
+  const state = holder.state || {}
+  const anchors: string[] = holder.slotAnchors?.() ?? []
+  const source: Record<string, string> = {
+    override: t('source-node', 'Set on this holder'),
+    figure: t('source-builtin', 'Built-in default'),
+    none: t('source-none', 'Not defined (one slot, stacked)')
+  }
+  const notes: SlotLayoutEditorOptions['notes'] = [{ text: `${t('source', 'Source')}: ${source[sel.source]}` }]
+  if (sel.status === 'invalid') {
+    notes.push({ level: 'error', text: t('invalid', 'The saved setting is invalid. Shown as one slot until fixed.') })
+    for (const e of sel.issues as SlotLayoutIssue[]) notes.push({ level: 'error', text: commonText(e) })
+  }
+  notes.push(
+    mm?.known
+      ? { text: t('unit-ok', 'Drawing unit 1 = {mm} mm', { mm: mm.mmPerUnit }) }
+      : { level: 'error', text: t('unit-missing', 'Drawing unit is not set (mmPerUnit). Physical placement and fit checks are unavailable.') }
+  )
+  return {
+    // 개별 설정이 없으면 실효 레이아웃(기본값)에서 편집을 시작한다
+    effective: value === undefined && sel.status === 'valid' ? sel.layout : undefined,
+    canUseDefault: value !== undefined,
+    presets: fmsimPresets(holder.loadMount ?? 'ON', t),
+    presetSize: mm?.known ? { width: Math.abs(state.width || 0) * mm.mmPerUnit, depth: Math.abs(state.height || 0) * mm.mmPerUnit } : {},
+    notes,
+    anchors: anchors.map(id => ({ id })),
+    validate: (layout: LoadLayout) => holderLayoutIssues(layout, anchors),
+    issueText: issue => fmsimIssueText(issue, t)
+  }
+}

package/src/editors/ox-load-layout-panel.ts

@@ -0,0 +1,129 @@
+/**
+ * @license Copyright © HatioLab Inc. All rights reserved.
+ *
+ * "Carrier 적재 자리" 구역 (설계 02번 3.7.1절)
+ * 공통 편집기(@operato/slot-layout-editor 의 ox-slot-layout-editor)를 띄우고 fmsim 의 몫만 넘긴다:
+ * 프리셋 이름, 홀더가 주는 Anchor, 값의 출처·도면 단위, 실시간 주소 읽기 설정, fmsim 고유 오류 문구 (load-layout-host).
+ * 이 화면은 도면 노드의 배치 덮어쓰기다. 프리셋·실효 레이아웃·검증은 figure-model 의 것이다 (ADR-0051 4.1절 결정 8).
+ * [적용]이면 고친 값을, [기본값 사용]이면 개별 설정을 지운 값(undefined)을 도면 노드에 넘긴다. 실행 중 점유는 저장하지 않는다.
+ *
+ * 속성 패널(board specifics)에서 custom-editor · value-key="slotLayout" 로 쓴다. value 를 바꾸고 change 를 보낸다.
+ */
+
+import { css, html, nothing, LitElement } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { i18next, localize } from '@operato/i18n'
+// 패키지 루트가 ox-slot-layout-editor 를 정의한다 (fmsim 의 moduleResolution 은 하위 경로 exports 를 풀지 않는다)
+import { issueText as commonIssueText } from '@operato/slot-layout-editor'
+
+import { LoadAddressing, LoadLayout } from '../utils/load-address'
+import { holderEditorOptions, setAddressing } from './load-layout-host'
+
+const t = (key: string, fallback: string, opts: Record<string, unknown> = {}) =>
+  i18next.t(`label.load-layout.${key}`, { defaultValue: fallback, ...opts })
+
+@customElement('ox-load-layout-panel')
+export class OxLoadLayoutPanel extends localize(i18next)(LitElement) {
+  static styles = css`
+    :host {
+      display: block;
+      font-size: 12px;
+    }
+    h4 {
+      margin: 6px 0 2px;
+      font-size: 12px;
+    }
+    .row {
+      display: grid;
+      grid-template-columns: 40% 1fr;
+      align-items: center;
+      gap: 4px;
+    }
+    input,
+    select {
+      font-size: 12px;
+      min-width: 0;
+    }
+  `
+
+  /** 선택한 홀더 (LoadLayoutHolder) */
+  @property({ attribute: false }) holder: any
+  /** 도면 노드의 개별 설정 (state.slotLayout) */
+  @property({ attribute: false }) value: LoadLayout | undefined
+
+  render() {
+    if (!this.holder?.effectiveLayout) return nothing
+    const options = {
+      ...holderEditorOptions(this.holder, this.value, t, commonIssueText),
+      renderExtra: (draft: LoadLayout, edit: (next: LoadLayout) => void) => this._renderAddressing(draft, edit)
+    }
+    return html`<ox-slot-layout-editor
+      .value=${this.value}
+      .options=${options}
+      @change=${this._apply}
+      @slot-layout-use-default=${this._useDefault}
+    ></ox-slot-layout-editor>`
+  }
+
+  /** 공통 편집기의 change 는 여기서 받고, 속성 패널에는 이 요소의 change 로 다시 알린다 (value-key 가 이 요소에 있다) */
+  private _apply(e: Event) {
+    e.stopPropagation()
+    this.value = structuredClone((e.target as any).value)
+    this.dispatchEvent(new Event('change', { bubbles: true, composed: true }))
+  }
+
+  /** 기본값 사용: 개별 설정을 지운다. 값을 비우는 편집과 다르다 */
+  private _useDefault(e: Event) {
+    e.stopPropagation()
+    this.value = undefined
+    this.dispatchEvent(new Event('change', { bubbles: true, composed: true }))
+  }
+
+  /** 실시간 데이터에서 주소를 읽는 규칙 (3.6절). 공통 편집기의 renderExtra 자리에 그린다 */
+  private _renderAddressing(draft: LoadLayout, edit: (next: LoadLayout) => void) {
+    const a = draft.addressing
+    const set = (next: LoadAddressing | undefined) => edit(setAddressing(draft, next))
+    const text = (field: string, label: string, value: string | undefined, onChange: (v: string) => void, placeholder = '') => html`
+      <div class="row">
+        <label>${label}</label>
+        <input
+          data-field=${field}
+          .value=${value ?? ''}
+          placeholder=${placeholder}
+          @change=${(e: Event) => onChange((e.target as HTMLInputElement).value.trim())}
+        />
+      </div>
+    `
+    return html`
+      <h4>${t('addressing', 'Address in live data')}</h4>
+      <div class="row">
+        <label>${t('addressing-by', 'Read by')}</label>
+        <select
+          data-field="addressing-by"
+          @change=${(e: Event) => {
+            const by = (e.target as HTMLSelectElement).value
+            set(
+              by === 'FIELDS'
+                ? { by, tierField: 'TIER', slotField: 'SLOT' }
+                : by === 'PATTERN'
+                ? { by, field: 'CARRIERLOC', pattern: '{slot}' }
+                : undefined
+            )
+          }}
+        >
+          <option value="" ?selected=${!a}>${t('addressing-none', 'Not read (all shown as address unknown)')}</option>
+          <option value="FIELDS" ?selected=${a?.by === 'FIELDS'}>${t('addressing-fields', 'Fields')}</option>
+          <option value="PATTERN" ?selected=${a?.by === 'PATTERN'}>${t('addressing-pattern', 'Location pattern')}</option>
+        </select>
+      </div>
+      ${a?.by === 'FIELDS'
+        ? html`${text('tier-field', t('tier-field', 'Tier field'), a.tierField, v => set({ ...a, tierField: v || undefined }), t('tier-field-empty', 'Empty = tier 1'))}
+          ${text('slot-field', t('slot-field', 'Slot field'), a.slotField, v => set({ ...a, slotField: v }))}`
+        : nothing}
+      ${a?.by === 'PATTERN'
+        ? html`${text('field', t('field', 'Field'), a.field, v => set({ ...a, field: v }))}
+          ${text('pattern', t('pattern-text', 'Pattern'), a.pattern, v => set({ ...a, pattern: v }), '{rack}-{slot:02}-{tier:02}')}`
+        : nothing}
+    `
+  }
+}

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

@@ -16,6 +16,8 @@ import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUti
 import { RealObjectGroup, registerRealObjectFactory, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+import { craneForkCount } from '../utils/crane-forks'
+import { forkAnchorId } from '@hatiolab/figure-model'
 
 const CLAMP_COLOR = 0x444444
 const FORK_COLOR = 0x999999
@@ -28,6 +30,12 @@ export class Crane3D extends RealObjectGroup {
   private forkGroup?: THREE.Group
   private forkMastBaseY = 0
   private forkMastH = 0
+  /** 포크별 Anchor 노드 (fork_1, fork_2). 캐리지(forkGroup) 아래에서 각자 뻗는다 */
+  private forkNodes = new Map<string, THREE.Group>()
+  /** 포크 판 윗면 높이 (포크 노드 로컬). Carrier 는 이 면에 놓인다 */
+  private forkSurfaceY = 0
+  /** 포크가 끝까지(100) 뻗었을 때의 거리 (+Z, 도면 y 방향) */
+  private forkReach = 0
 
   get effectiveDepth(): number {
     const { depth } = this.component.state
@@ -45,6 +53,35 @@ export class Crane3D extends RealObjectGroup {
     this.forkGroup.position.y = this.forkMastBaseY + (clamped / 100) * this.forkMastH
   }
 
+  /** 포크 n 을 0~100 만큼 뻗는다 (다른 포크는 그대로) */
+  applyForkExtend(fork: number, extend: number): void {
+    const node = this.forkNodes.get(forkAnchorId(fork))
+    if (!node) return
+    const clamped = Math.max(0, Math.min(100, Number(extend) || 0))
+    node.position.z = (clamped / 100) * this.forkReach
+  }
+
+  /** 포크 Anchor 노드: 포크 판 윗면의 중심. 포크 노드 아래에 있어 포크가 오르내리고 뻗으면 함께 간다 */
+  private forkAnchors = new Map<string, THREE.Group>()
+
+  /**
+   * A fork's anchor (common item contract 3.4): a node at the centre of its plate's top, under the fork, so what it
+   * holds goes up, down and out with it. Null when the crane has no such fork.
+   */
+  forkAnchor(anchorId: string): THREE.Object3D | null {
+    const fork = this.forkNodes.get(anchorId)
+    if (!fork) return null
+    let node = this.forkAnchors.get(anchorId)
+    if (!node || node.parent !== fork) {
+      node = new THREE.Group()
+      node.name = `${anchorId}-anchor`
+      fork.add(node)
+      this.forkAnchors.set(anchorId, node)
+    }
+    node.position.set(0, this.forkSurfaceY, 0)
+    return node
+  }
+
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -131,45 +168,60 @@ export class Crane3D extends RealObjectGroup {
     // 일 때 mast 바닥 자리에. forkZ 0~100 에 따라 group.position.y 만 변경하면
     // mast 따라 위/아래 이동. mesh 재구축 불필요.
     const forkMat = MaterialBank.material('crane|fork', { roughness: 0.4, metalness: 0.5 }, FORK_COLOR)
+    const forkCount = craneForkCount((this.component.state as any).forkCount)
 
-    const forkGeometries: THREE.BufferGeometry[] = []
-
-    const plateW = w * 0.9
     const plateH = d * 0.08
     const plateD = pillarThick * 0.8
-    const centerPlate = new THREE.BoxGeometry(plateW, plateH, plateD)
-    centerPlate.translate(0, plateH / 2, 0) // local 0 = mast 바닥
-    forkGeometries.push(centerPlate)
-
     const armW = pillarThick * 0.6
     const armH = plateH * 0.4
     const armD = h * 0.6
-    const armSpacing = w * 0.5
 
-    for (const zSign of [-1, 1]) {
-      for (const xSign of [-1, 1]) {
-        const arm = new THREE.BoxGeometry(armW, armH, armD)
-        arm.translate(xSign * (armSpacing / 2), armH / 2, zSign * (plateD / 2 + armD / 2))
-        forkGeometries.push(arm)
+    /* 포크 하나: 가로 판 + 판 앞뒤로 뻗은 팔 두 쌍. 로컬 0 = 판 바닥, 중심 x = 0 */
+    const buildFork = (plateW: number) => {
+      const parts: THREE.BufferGeometry[] = []
+      const plate = new THREE.BoxGeometry(plateW, plateH, plateD)
+      plate.translate(0, plateH / 2, 0)
+      parts.push(plate)
+      const armSpacing = plateW * 0.55
+      for (const zSign of [-1, 1]) {
+        for (const xSign of [-1, 1]) {
+          const arm = new THREE.BoxGeometry(armW, armH, armD)
+          arm.translate(xSign * (armSpacing / 2), armH / 2, zSign * (plateD / 2 + armD / 2))
+          parts.push(arm)
+        }
       }
+      const mesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(parts), forkMat)
+      mesh.castShadow = true
+      return mesh
     }
 
-    const forkMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(forkGeometries), forkMat)
-    forkMesh.castShadow = true
-
+    // 캐리지: forkZ 로 오르내린다. 포크는 캐리지 안에서 각자 Z 로 뻗는다 (트윈 포크의 독립 이동)
     const forkGroup = new THREE.Group()
-    forkGroup.add(forkMesh)
     inner.add(forkGroup)
+    this.forkNodes.clear()
+    const forkW = forkCount === 2 ? w * 0.42 : w * 0.9
+    for (let i = 1; i <= forkCount; i++) {
+      const node = new THREE.Group()
+      node.name = forkAnchorId(i)
+      node.position.x = forkCount === 2 ? (i === 1 ? -1 : 1) * w * 0.24 : 0
+      node.add(buildFork(forkW))
+      forkGroup.add(node)
+      this.forkNodes.set(node.name, node)
+    }
     this.forkGroup = forkGroup
     this.forkMastBaseY = mastBaseY
+    this.forkSurfaceY = plateH
+    this.forkReach = h * 0.8
     // forkZ=100 시점에 mast 의 *_위쪽 한계*. 포크 자체 두께 (plateH) 만큼은 마스트
     // 안에 머무르도록 limit 보정 — 그렇지 않으면 forkZ=100 일 때 포크가 상단
     // 클램프와 충돌. mastH * 0.92 로 약간 보수적 (= 마스트 본체 92% 까지만 이동).
     this.forkMastH = mastH * 0.92
 
-    // 초기 forkZ 반영 — state.forkZ 가 이미 set 되어 있으면 그 위치에 배치
-    const initialForkZ = Number((this.component.state as any).forkZ)
+    // 초기 forkZ·포크 뻗음 반영 — state 에 이미 있으면 그 위치에 배치
+    const state = this.component.state as any
+    const initialForkZ = Number(state.forkZ)
     this.applyForkZ(Number.isFinite(initialForkZ) ? initialForkZ : 0)
+    for (let i = 1; i <= forkCount; i++) this.applyForkExtend(i, Number(state[`forkExtend${i}`]) || 0)
 
     // ── 4. 상단 클램프 (천장 레일에 물리는 가이드부) ──
     const topClampGeo = new THREE.BoxGeometry(clampW, clampH, clampD)
@@ -188,14 +240,16 @@ export class Crane3D extends RealObjectGroup {
   /** build() 직전 호출. forkGroup 참조를 깨끗이 비워둔다 — 새 build 가 다시 set. */
   clear() {
     this.forkGroup = undefined
+    this.forkNodes.clear()
     super.clear()
   }
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
-    if ('width' in after || 'height' in after || 'depth' in after || 'fillStyle' in after || 'strokeStyle' in after) {
+    if ('width' in after || 'height' in after || 'depth' in after || 'fillStyle' in after || 'strokeStyle' in after || 'forkCount' in after) {
       this.update()
       return
     }
+    for (const fork of [1, 2]) if (`forkExtend${fork}` in after) this.applyForkExtend(fork, Number(after[`forkExtend${fork}`]) || 0)
     // forkZ 는 mesh 재구축 없이 group.position.y 만 갱신. 같은 onchange 에서
     // left/top 도 함께 변경될 수 있으므로 super 도 반드시 호출해 본체 transform
     // 갱신 path (state.left/top → obj3d.position.x/z) 가 동작하게 함.