@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.41

package/src/crane.ts

@@ -1,8 +1,8 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { Component, ComponentNature, ContainerAbstract, ContainerCapacity, RealObject, sceneComponent } from '@hatiolab/things-scene'
-import type { SlotDef, State, Material3D } from '@hatiolab/things-scene'
+import { Component, ComponentNature, ContainerAbstract, ContainerCapacity, RealObject, Transfer, getWorldPose, sceneComponent } from '@hatiolab/things-scene'
+import type { SlotDef, State, Material3D, Transferable } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Legendable,
@@ -35,14 +35,6 @@ export interface CraneState extends State {
   // ── 운영 상태 ──
   status?: CraneStatus
 
-  /**
-   * Crane 이 서비스 할 타깃 컴포넌트의 refid (또는 id).
-   * 명시되면 그 컴포넌트 (또는 그 children) 의 위치를 stop point 로 사용 — heuristic
-   * 으로 sibling 추정 안 함. 미명시면 sibling 안에서 추측.
-   * 예: RackGrid 의 refid 를 지정하면 그 안의 cell 들 사이에서만 이동.
-   */
-  target?: string
-
   // ── 액추에이터 ──
   /** 마스트 따라 carriage 의 수직 위치 (mm). */
   carriageHeight?: number
@@ -62,11 +54,42 @@ export interface CraneState extends State {
    */
   forkExtension?: number
   /**
-   * Fork 의 *carrier 들어올림 높이* (mm). 0 = neutral (cell shelf 와 같은 면),
-   * +값 = carrier 를 *위로* 들어올림 (fork pocket 안으로 진입 후 위로 lifting).
+   * Fork 가 carrier 를 *cell shelf 에서 분리하기 위해 들어올리는 높이* (mm).
+   * 사용자가 board 에서 설정하는 *configured 진폭*. engage 의 lift 단계 target.
+   * 미명시 시 default 30mm.
+   *
+   * Note: 시뮬 *진행 중 current 들림 값* 은 별도 internal transient — `forkLiftRT`
+   * state. 3D / 2D render 가 carriage Y 결정 시 그 값을 사용.
    */
   forkLift?: number
 
+  /**
+   * Fork lift *runtime current value* (mm). engage 가 시뮬 진행 중 매 frame
+   * setState 로 lerp. *사용자가 설정하는 값 아님* — internal transient.
+   */
+  forkLiftRT?: number
+
+  /**
+   * 자동 random simulate (visual smoke test) 시작 여부.
+   * - `undefined` 또는 `false` (default): 자동 시작 안 함. application 이 crane.
+   *   pickAndPlace 등 직접 제어 시 사용.
+   * - `true`: added() 시 자동 시작.
+   */
+  simulate?: boolean
+
+  /**
+   * Carriage 의 rail-local X 위치 (0 ~ crane.width). Crane.moveTo / simulate 가
+   * lerp. crane 본체 (rail) 는 안 움직임 — carriage assembly (masts + carriage +
+   * forks) 만 rail 안 X 만 슬라이드.
+   */
+  carriagePosition?: number
+
+  /**
+   * Carriage 의 폭 (rail-local X 방향). 미명시 시 rail (crane.width) 의 ~10%.
+   * Target rack 의 cell 폭과 매칭 권유.
+   */
+  carriageWidth?: number
+
   // ── 3D 재질 ──
   material3d?: Material3D
 }
@@ -109,10 +132,21 @@ const NATURE: ComponentNature = {
       }
     },
     {
-      type: 'string',
-      label: 'target',
-      name: 'target',
-      placeholder: 'refid of target (e.g., a RackGrid) — crane serves only its cells'
+      type: 'checkbox',
+      label: 'simulate',
+      name: 'simulate'
+    },
+    {
+      type: 'number',
+      label: 'carriage-position',
+      name: 'carriagePosition',
+      placeholder: 'rail-local X (0 ~ rail width). Crane.moveTo 가 lerp.'
+    },
+    {
+      type: 'number',
+      label: 'carriage-width',
+      name: 'carriageWidth',
+      placeholder: 'rail-local 폭 (mm). 미명시 rail width × 10%.'
     },
     {
       type: 'number',
@@ -214,9 +248,59 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
 
   // ── ContainerCapacity ─────────────────────────────────────────────────────
 
-  /** Stacker crane carries at most one load at a time on its forks. */
+  /**
+   * Stacker crane carries at most one load at a time on its forks.
+   *
+   * localPosition.z = 0 명시 — ContainerCapacity.receive 의 atomic setState 가
+   * `carrier.state.zPos = slot.localPosition.z + parentGeoOffset = 0` 강제.
+   * 미명시 시 zPos update skip → carrier 의 *이전 holder 또는 board model 의
+   * 임의 zPos (음수 가능)* 그대로 → _realObject 미빌드 시점 (transient placement
+   * 미설정 = state-driven) 에 carrier 가 *지하* 로 가는 결함.
+   */
   get slots(): SlotDef[] {
-    return [{ id: 'forks', maxCount: 1 }]
+    return [{ id: 'forks', maxCount: 1, localPosition: { x: 0, y: 0, z: 0 } }]
+  }
+
+  /**
+   * Acceptance rotation — carrier 가 crane.fork 에 attach 시 *crane 의 local
+   * axis (전방)* 으로 정렬. identity quaternion 반환 → atomic setState 가
+   * carrier.state.rotation/X/Y = 0 강제. _realObject 미빌드 시점 (transient
+   * placement 미설정 = state-driven) fallback 에서도 자세 정렬.
+   *
+   * follow-holder carryPolicy 와 짝 — 두 path 모두 동일 결과 (local identity).
+   */
+  acceptanceRotation(_carrier: Component, _slot?: SlotDef): { x: number; y: number; z: number; w: number } {
+    return { x: 0, y: 0, z: 0, w: 1 }
+  }
+
+  /**
+   * Arrangement — carrier.state.left/top 의 *기준* 이 *crane 전체 footprint* 가
+   * 아닌 *carriage X (carriagePosition) + fork Z (bladeMidZ)*. carriage / fork
+   * 의 위치가 carrier 의 위치.
+   *
+   *   left = carriagePosition − carrier.w/2     (carriage X 중심)
+   *   top  = crane.h/2 + bladeMidZ − carrier.h/2   (fork Z 중심)
+   */
+  get arrangementStrategy() {
+    const crane = this as any
+    return {
+      positionAt(_idx: number, _slot: any, _occ: number, component?: any) {
+        const cw = numOr(crane.state?.width, 100)
+        const ch = numOr(crane.state?.height, 100)
+        const carrierW = numOr(component?.state?.width, 0)
+        const carrierH = numOr(component?.state?.height, 0)
+        const carriagePos = numOr(crane.state?.carriagePosition, cw / 2)
+        const bladeMidZ = numOr(crane._realObject?.bladeMidZ, 0)
+        return {
+          x: carriagePos - carrierW / 2,
+          y: ch / 2 + bladeMidZ - carrierH / 2,
+          z: 0
+        }
+      },
+      capacity(slot: any) {
+        return slot.maxCount ?? Infinity
+      }
+    }
   }
 
   // ── CarrierHolder — attach frame (carriage fork position) ─────────────────
@@ -233,20 +317,17 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
   attachPointFor(carrier: Component): AttachFrame | null {
     const ro = this._realObject
     const frame = ro?.getCarriageFrame?.()
-    if (frame) {
-      const carrierDepth = resolveCarrierDepth(carrier)
-      // fork blade 위 (top surface) 에 pallet pocket 끼우듯 얹힘. y = blade top + carrier/2.
-      // z = blade 중심 (forkLength 의 반쪽 위치 — pallet center 가 blade 중간에 위치).
-      const platformTopY = ro?.platformTopY ?? 0
-      const bladeMidZ = ro?.bladeMidZ ?? 0
-      return {
-        attach: frame,
-        localPosition: { x: 0, y: platformTopY + carrierDepth / 2, z: bladeMidZ }
-      }
+    if (!frame) return null
+    const carrierDepth = resolveCarrierDepth(carrier)
+    const carrierBaseY = ro?.carrierBaseY ?? 0
+    const bladeMidZ = ro?.bladeMidZ ?? 0
+    // carrier 외부 bottom = fork blade bottom. carryPolicy: 'follow-holder' —
+    // carrier 가 crane 의 *local axis (전방)* 정렬.
+    return {
+      attach: frame,
+      localPosition: { x: 0, y: carrierBaseY + carrierDepth / 2, z: bladeMidZ },
+      carryPolicy: 'follow-holder'
     }
-    const root = this._realObject?.object3d
-    if (!root) return null
-    return { attach: root }
   }
 
   // ── Mover overrides ───────────────────────────────────────────────────────
@@ -269,21 +350,184 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
    * binding sets 'moving' in monitoring mode; override pick()/place() to
    * set it in full simulation environments.
    */
+  /**
+   * Crane.moveTo — **Crane 본체 (rail) 은 안 움직임**. *내부 carriage 의 rail-
+   * local X 위치 (carriagePosition) 만 lerp*. 실제 gantry / AS/RS crane 의
+   * 자연스러운 운동 패턴.
+   *
+   * target.center 의 world 좌표를 *crane 의 local frame (rail-aligned)* 로
+   * 변환 → rail-local X 추출 → carriagePosition setState.
+   *
+   * Crane.state.rotation = rail 방향. carriage 가 rail 위 X 만 이동.
+   */
+  async moveTo(target: Component, options: MoveOptions = {}): Promise<void> {
+    // target.center 는 *parent-local* 좌표 — child component (cell) 의 경우
+    // *rack-local*. board-absolute 변환 필요 (= toScene).
+    const tcLocal = target?.center
+    if (!tcLocal || typeof tcLocal.x !== 'number' || typeof tcLocal.y !== 'number') {
+      return
+    }
+    const tcAbs = typeof (target as any).toScene === 'function'
+      ? (target as any).toScene(tcLocal.x, tcLocal.y)
+      : tcLocal
+    const tcx = tcAbs.x
+    const tcy = tcAbs.y
+
+    // Crane 도 자체 center 를 toScene 으로 (crane 이 다른 container 의 child 일 수도)
+    const W = (this.state.width as number) ?? 100
+    const craneCenterLocal = (this as any).center ?? { x: 0, y: 0 }
+    const craneCenterAbs = typeof (this as any).toScene === 'function'
+      ? (this as any).toScene(craneCenterLocal.x, craneCenterLocal.y)
+      : craneCenterLocal
+    const ccx = craneCenterAbs.x
+    const ccy = craneCenterAbs.y
+    const rotation = (this.state.rotation as number) ?? 0
+    const cos = Math.cos(rotation)
+    const sin = Math.sin(rotation)
+
+    const dx = tcx - ccx
+    const dy = tcy - ccy
+    const railLocalX = dx * cos + dy * sin
+
+    const cw = (this.state.carriageWidth as number) ?? W * 0.1
+    const minPos = cw / 2
+    const maxPos = W - cw / 2
+    const newCarriagePos = Math.max(minPos, Math.min(maxPos, railLocalX + W / 2))
+
+    // X + Y 동시 lerp — carriage 의 횡 (rail) + 종 (mast) 운동 동기.
+    //
+    // 진입 위치 (= fork blade bottom world Y):
+    //   pick (no holding):  cellBottom
+    //   place (holding):    cellBottom + liftH (들린 carrier 와 함께 진입)
+    const tween: Record<string, number> = { carriagePosition: newCarriagePos }
+    const targetBottomWorldY = resolveCarrierBottomY(target)
+    if (targetBottomWorldY !== null) {
+      const isHoldingCarrier = ((this as any).components as any[] | undefined)?.some?.(
+        (c: any) => c?._transferSlotId === 'forks'
+      ) ?? false
+      const liftH = numOr((this.state as any).forkLift, 30)
+      const approachWorldY = targetBottomWorldY + (isHoldingCarrier ? liftH : 0)
+
+      const ro = this._realObject
+      const currentForkLift = numOr((this.state as any).forkLiftRT, 0)
+      const solver = ro?.solveCarriageHeightForCarrierBaseWorldY
+      if (typeof solver === 'function') {
+        tween.carriageHeight = solver.call(ro, approachWorldY, currentForkLift)
+      } else {
+        tween.carriageHeight = approachWorldY
+      }
+    }
+
+    const duration = (options.duration as number) ?? 1500
+    this.setState({ status: 'moving' as CraneStatus })
+    await this._tween(tween, duration)
+    this.setState({ status: 'idle' as CraneStatus })
+  }
+
   async engage(
     target: Component,
     kind: 'pick' | 'place',
     _options: MoveOptions = {}
   ): Promise<void> {
+    // carriageHeight 는 moveTo 안 X+Y 동시 lerp 에서 처리.
+    // engage 가 책임: fork extension → lift / drop → retract.
+    const forkLen = numOr((this.state as any).forkLength, 600)
+    // liftH — 사용자 설정 `forkLift` (= configured 진폭). 미설정 시 default 30mm.
+    // 시뮬 lerp 는 *forkLiftRT* (runtime current) state 에 적용 — `forkLift` 자체
+    // 는 *진폭 의미 보존* 위해 안 건드림.
+    const liftH = numOr((this.state as any).forkLift, 30)
+
+    // Fork side 결정 — target 이 crane 의 어느 *local Z 방향* (cross-rail, fork
+    // axis) 인지. things-scene 의 `getWorldPose` 로 양쪽 world pose 산출 후
+    // delta 를 crane local frame 으로 inverse-rotate → local Z 부호 = side.
+    // pick/place 동일하게 동작 (이전 코드는 carrier=cell.child 케이스에서
+    // rack-local vs world 좌표계 혼선으로 pick 시 방향 반대였음).
+    let side: 1 | -1 = +1
+    try {
+      const cranePose = getWorldPose(this)
+      const targetPose = getWorldPose(target)
+      const dv = targetPose.position.clone().sub(cranePose.position)
+      dv.applyQuaternion(cranePose.rotation.clone().invert())
+      side = dv.z >= 0 ? +1 : -1
+    } catch {
+      // fallback — pose 계산 실패 시 +1 (rotation 무관, 의미적으로 안전한 default).
+    }
+
+    // Animation duration — fork extend/retract 1000ms, lift/lower 600ms.
+    // 이전 (500ms / 300ms) 보다 2배 — 시각 자연스러움 강화.
+    const D_EXT = 1000
+    const D_LIFT = 600
+
+    // fork extension target — target 의 local Z 와 _bladeMidZ 매칭. helper 가
+    // inverse-solve. mismatch 시 carrier 가 *fork tip 위치 (= local Z 미일치)*
+    // 로 jump → 텔레포트 결함. helper 가 정확 일치 보장.
+    let extTarget = side * forkLen
+    try {
+      const cranePose = getWorldPose(this)
+      const targetPose = getWorldPose(target)
+      const dv = targetPose.position.clone().sub(cranePose.position)
+      dv.applyQuaternion(cranePose.rotation.clone().invert())
+      const localZ = dv.z
+      const solver = (this._realObject as any)?.solveForkExtensionForLocalZ
+      if (typeof solver === 'function') {
+        const ext = solver.call(this._realObject, localZ)
+        if (Number.isFinite(ext)) extTarget = ext
+      }
+    } catch {
+      // fallback — 기존 side * forkLen.
+    }
+
     if (kind === 'pick') {
       this.setState({ status: 'loading' as CraneStatus })
-      const carrierY = resolveCarrierCenterY(target)
-      if (carrierY !== null) {
-        this.setState({ carriageHeight: carrierY })
+      await this._tween({ forkExtension: extTarget }, D_EXT)
+
+      // Mid-engage reparent — fork 가 cell 안 도달. carrier 를 fork 위로 *즉시
+      // snap* (animated:false). Transfer 객체 통과 → monitor panel 추적.
+      const source = (target as any).parent
+      if (source) {
+        try {
+          new Transfer({
+            source,
+            target: this as unknown as Transferable,
+            carrier: target,
+            options: { animated: false }
+          }).executeSync()
+        } catch (e) {
+          // Transfer 실패 — carrier 그대로. 후속 Mover.pick receive 가 처리.
+        }
       }
+
+      await this._tween({ forkLiftRT: liftH }, D_LIFT)
+      await this._tween({ forkExtension: 0 }, D_EXT)
     } else {
       this.setState({ status: 'unloading' as CraneStatus })
+      // 1. fork extend (cell 위에서 carrier 자리 위로 진입). extTarget = inverse-
+      //    solved target.local.z 매칭 위치.
+      await this._tween({ forkExtension: extTarget }, D_EXT)
+
+      // 2. carrier lower — forkLiftRT liftH → 0. carrier 가 cell 바닥 안착.
+      await this._tween({ forkLiftRT: 0 }, D_LIFT)
+
+      // 3. dispatch — carrier world 위치 = cell 내 attach 위치, jump 없음. Transfer 추적.
+      const comps = (this as any).components as any[] | undefined
+      const carrier = comps?.find?.((c: any) => c?._transferSlotId === 'forks')
+        ?? comps?.find?.((c: any) => c?.state?.type !== 'storage-cell')
+      if (carrier) {
+        try {
+          new Transfer({
+            source: this as unknown as Transferable,
+            target: target as unknown as Transferable,
+            carrier,
+            options: { animated: false }
+          }).executeSync()
+        } catch (e) {
+          // dispatch 실패 — Mover.place 가 후속 처리.
+        }
+      }
+
+      // 4. fork retract — 빈 fork.
+      await this._tween({ forkExtension: 0 }, D_EXT)
     }
-    // In a full simulation: await carriage-motion tween here.
   }
 
   // ── Domain aliases ────────────────────────────────────────────────────────
@@ -326,9 +570,14 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     const depth = num(state.depth, Math.max(width, height) * 4)
     const carriageHeight = clamp(num(state.carriageHeight, 0), 0, depth)
     const forkExtension = num(state.forkExtension, 0)   // ± (rail 양쪽 rack)
-    const forkLift = num(state.forkLift, 0)
-
-    const cx = left + width / 2
+    // forkLiftRT — *시뮬 runtime current 들림*. *configured 진폭* (state.forkLift)
+    // 와 분리. 시뮬 미진행 시 0 (carriage 가 mast 위 carriageHeight 만큼).
+    const forkLift = num(state.forkLiftRT, 0)
+
+    // carriagePosition: rail-local X (0 ~ width). default = rail center.
+    // 사용자 의도 — Crane 본체 (rail) 안 움직이고 carriage assembly 만 X 슬라이드.
+    const carriagePosition = clamp(num(state.carriagePosition, width / 2), 0, width)
+    const cx = left + carriagePosition   // masts/carriage/forks 의 중심 X
     const cy = top + height / 2
     // 적재 여부 — forkLift > 0 (시뮬 중 들어올린 상태) 또는 state.loaded 명시.
     // monitoring 모드는 외부 데이터로 state.loaded 바인딩.
@@ -348,16 +597,28 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
 
     ctx.save()
 
-    // 1. Rail — 위/아래 두 줄
-    const railW = Math.max(1.5, height * 0.03)
+    // 0. Rail footprint — 반투명 회색 fill + 외곽선. 사용자가 board 에서 crane 의
+    //    *rail 영역* 을 명확히 인식 + 편집 핸들 가능.
+    ctx.fillStyle = '#aab0b8'
+    ctx.globalAlpha = 0.15
+    ctx.fillRect(left, top, width, height)
+    ctx.globalAlpha = 1
+    ctx.strokeStyle = DARK
+    ctx.lineWidth = 1
+    ctx.strokeRect(left, top, width, height)
+
+    // 1. Rail — 하단 한 줄 (얇은 가이드). 톤 절제 — outer footprint 가 이미 영역 표시.
+    const railW = Math.max(1, height * 0.02)
     ctx.fillStyle = DARK
-    ctx.fillRect(left, top, width, railW)
+    ctx.globalAlpha = 0.6
     ctx.fillRect(left, top + height - railW, width, railW)
+    ctx.globalAlpha = 1
 
-    // 2. Twin masts — 두 orange 사각형. mast 길이가 *3D 의 mast height (depth)* 를
-    //    의미하므로, 그 위에 carriage 위치 indicator 를 매핑하면 1층/N층 인식 가능.
-    const mastW = Math.max(2.5, width * 0.07)
-    const mastSpacing = width * 0.75    // 넉넉히 — carrier 가 mast 잠식 안 하도록
+    // 2. Twin masts — *carriageWidth 기반* (crane.width 와 분리). rail (= crane.width)
+    //    이 넓어져도 carriage assembly 는 *carriageWidth 만큼* 만.
+    const carriageW = num(state.carriageWidth, width * 0.1)   // default rail 의 10%
+    const mastW = Math.max(2.5, carriageW * 0.15)
+    const mastSpacing = carriageW * 0.85
     const mastY = top + railW
     const mastH = height - railW * 2
     const mastX1 = cx - mastSpacing / 2 - mastW / 2
@@ -384,23 +645,22 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     ctx.fillRect(mastX1 - 2, indY, indWidth, indLen)
     ctx.fillRect(mastX2 - 2, indY, indWidth, indLen)
 
-    // 3. Carriage (= 적재 deck) — 팔레트 1200×800mm aspect 반영. *폭만* sizeMul 적용 (높이감),
-    //    길이 (Y) 고정. carrier / fork 모두 이 carriage 기준으로 derive.
-    const carriageW = (mastSpacing - mastW) * sizeMul
+    // 3. Carriage deck — 팔레트 1200×800mm aspect 반영. *폭만* sizeMul 적용 (높이감),
+    //    길이 (Y) 고정. carrier / fork 모두 이 deck 기준으로 derive.
+    const deckW = (mastSpacing - mastW) * sizeMul
     const carriageH = Math.min((mastSpacing - mastW) * 1.3, (height - railW * 2) * 0.55)
-    const carriageX = cx - carriageW / 2
+    const carriageX = cx - deckW / 2
     const carriageY = cy - carriageH / 2
     ctx.fillStyle = CARRIAGE_C
-    ctx.fillRect(carriageX, carriageY, carriageW, carriageH)
+    ctx.fillRect(carriageX, carriageY, deckW, carriageH)
 
     // 4. Fork — 좌우 균형:
     //    - 양쪽 모두 *작은 stub* 항상 표시 (crane 이 양쪽 rack 사이 있는 인상)
     //    - extension 부호 (+/-) 에 따라 active 쪽이 추가로 신축
     //    - 신축 길이 = |forkExtension| (실제 reach 만큼)
     const stubLen = Math.max(2, carriageH * 0.5)
-    // 포크 폭 — carriage 의 80% (carrier 90% 보다 약간 좁아 carrier 가 fork 양옆으로
-    // 살짝 overhang). carriage 가 sizeMul 적용된 폭이라 fork 도 자동 scale 반영.
-    const forkW = carriageW * 0.8
+    // 포크 폭 — deck 의 80%.
+    const forkW = deckW * 0.8
     const forkX = cx - forkW / 2
     const extLen = Math.abs(forkExtension)
     const sign = forkExtension >= 0 ? 1 : -1
@@ -424,26 +684,20 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     if (carrying) {
       // 팔레트 — 항상 carriage 의 90% (폭/길이 모두). carriage 가 sizeMul 적용된 폭이라
       // carrier 도 자동으로 sizeMul 반영. 길이는 carriage 길이 고정에 따라 고정.
-      const carrW = carriageW * 0.9
+      const carrW = deckW * 0.9
       const carrH = carriageH * 0.9
-      let carrCenterY: number
-      if (extLen > 0.5) {
-        // 포크의 *중간* 에 carrier 배치 — fork prong 이 pallet pocket 에 끼워진 자연스러운
-        // 위치 (현실 AS/RS 에서 pallet 이 fork 끝이 아닌 fork 길이 중간 부근에 안착).
-        const forkMid = (stubLen + extLen) / 2
-        carrCenterY = sign > 0
-          ? carriageY + carriageH + forkMid
-          : carriageY - forkMid
-      } else {
-        carrCenterY = cy  // transit
-      }
+      // Carrier 2D 위치 — 3D _bladeMidZ 와 동일 공식 (sign * extLen).
+      //   extLen=0 → carriage 정중앙. extLen 증가 → cell 방향 으로 진출.
+      const offset = extLen
+      const carrCenterY = sign > 0
+        ? carriageY + carriageH / 2 + offset
+        : carriageY + carriageH / 2 - offset
       const carrX = cx - carrW / 2
       const carrY = carrCenterY - carrH / 2
 
       // 들린 상태 — drop shadow 로 *떠 있는* 인상 (forkLift > 0). offset 비율 = lift 강도.
       if (forkLift > 0) {
-        const forkLengthRef = num(state.forkLength, height * 0.4)
-        const liftMax = Math.max(forkLengthRef * 0.05, 20)   // forkLift 정상 범위
+        const liftMax = Math.max(num(state.forkLift, 30), 20)  // configured 진폭
         const liftRatio = clamp(forkLift / liftMax, 0.3, 1)  // 최소 30% 표시 (있다는 것만 보이게)
         const shadowOff = Math.max(2, Math.min(carrW, carrH) * 0.14) * liftRatio
         ctx.fillStyle = 'rgba(0, 0, 0, 0.4)'
@@ -470,17 +724,90 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
 
   added(parent: any): void {
     super.added?.(parent)
+
+    // state ↔ visual single source of truth. state 미설정 시 _canonicalDefault
+    // 로 명시 초기화 — build / _tween / 외부 read 모두 동일 값.
+    const init: Record<string, number> = {}
+    for (const k of ['carriagePosition', 'carriageHeight', 'forkExtension', 'forkLiftRT']) {
+      if (typeof (this.state as any)[k] !== 'number') {
+        init[k] = this._canonicalDefault(k)
+      }
+    }
+    if (Object.keys(init).length > 0) this.setState(init)
+
+    // state.simulate === true 명시 시만 자동 시작. mode 연동은 board view layer
+    // 책임 — 컴포넌트 자체는 simulate state 만 본다 (sorter/conveyor 등 다른
+    // 시뮬 컴포넌트와 동일 패턴).
+    if ((this.state as CraneState).simulate !== true) return
+    this._startAutoSimulate()
+  }
+
+  /**
+   * Actuator state 의 *canonical default*. state 미설정 시 모든 read 경로
+   * (build / _tween / 외부) 가 *동일 값* 보도록.
+   *
+   * single source 패턴 — visual fallback 과 state fallback 이 *분리* 되어
+   * 첫 _tween 시 start 가 visual current 와 어긋나는 jump 결함을 근본 차단.
+   */
+  _canonicalDefault(key: string): number {
+    const state = this.state as any
+    const W = numOr(state.width, 100)
+    const H = numOr(state.height, 100)
+    const D = numOr(state.depth, Math.max(W, H) * 4)
+    switch (key) {
+      case 'carriagePosition': return W / 2
+      case 'carriageHeight': return D * 0.4
+      case 'forkExtension':
+      case 'forkLiftRT':
+      case 'forkLift':
+        return 0
+      default: return 0
+    }
+  }
+
+  private _startAutoSimulate(): void {
     if (this._simStarted) return
     this._simStarted = true
     // 초기 지연 800~2800ms 사이 random — 여러 crane 이 동기적으로 시작하지 않도록.
-    // added 에서 시작 → 2D/3D 모드 무관. buildRealObject 는 3D 진입 시만 호출돼 시점이
-    // 늦거나 누락될 수 있으므로 부적합.
     const initialDelay = 800 + Math.random() * 2000
     setTimeout(() => {
+      if (this._simAbort || (this.state as CraneState).simulate !== true) return
       this.simulate().catch(e => console.error('[Crane] simulate', e))
     }, initialDelay)
   }
 
+  /**
+   * state.simulate 변경 시 자동 simulate 시작/중단. application 이 런타임 toggle
+   * 가능 (예: editor 에서 simulate off, view 에서 on).
+   */
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>): void {
+    super.onchange(after as any, before as any)
+    // carriage 관련 state 변경 시 2D render 명시 invalidate. things-scene 의
+    // setState → trigger change 가 render queue 에 자동 등록 못 하는 케이스 방어.
+    if (
+      'carriagePosition' in after ||
+      'carriageWidth' in after ||
+      'carriageHeight' in after ||
+      'forkExtension' in after ||
+      'forkLift' in after ||
+      'forkLiftRT' in after
+    ) {
+      ;(this as any).invalidate?.()
+    }
+    if ('simulate' in after) {
+      if (after.simulate === true) {
+        // 명시 true → 자동 시작 (이미 시작 중이면 noop). mode gating 은
+        // frameClock (animate 의 simTime) 이 자동 처리 — modeler 면 simTime
+        // 안 흐름, _tween step 호출 안 됨.
+        this._simAbort = false
+        this._simStarted = false
+        this._startAutoSimulate()
+      } else {
+        this._simAbort = true
+      }
+    }
+  }
+
   // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {
@@ -524,17 +851,14 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
   private _initRailRange(): void {
     this._railMin = this._railMax = NaN
 
-    // 1순위: state.target refid 로 명시. 2순위: crane 의 parent 컴포넌트 (자연스러운
-    // "이 컨테이너 안에서만 움직여" 기본값).
-    const targetRefId = (this.state as any).target as string | undefined
+    // simulate cycle 의 random pickAndPlace range — crane 의 parent 컨테이너
+    // (= 보통 rack 또는 board) 의 bbox 를 기준으로. parent 가 top-level
+    // (root/model-layer) 이면 bbox 의미 없음 → skip.
     const root = (this as any).root
-    let target = targetRefId ? root?.findById?.(targetRefId) : null
-    if (!target) {
-      const parent = (this as any).parent
-      // parent 가 root/model-layer 같은 top-level 이면 bbox 가 의미없음 → skip
-      if (parent && parent !== root && (parent.state as any)?.width > 0) {
-        target = parent
-      }
+    const parent = (this as any).parent
+    let target: any = null
+    if (parent && parent !== root && (parent.state as any)?.width > 0) {
+      target = parent
     }
     if (!target) return
 
@@ -611,20 +935,16 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     const H = numOr((this.state as any).height, 100)
     const D = numOr((this.state as any).depth, W * 4)
     const forkLen = numOr((this.state as any).forkLength, H * 0.6)
+    const cw = numOr((this.state as any).carriageWidth, W * 0.1)
 
-    if (!Number.isFinite(this._railMin) || !Number.isFinite(this._railMax)) {
-      await new Promise(r => setTimeout(r, 800))
-      return
-    }
-
-    const pickRail = () => this._railMin + Math.random() * Math.max(0, this._railMax - this._railMin)
-    const toLeftTop = (rail: number) => ({
-      left: this._railOriginX + rail * this._railCos - W / 2,
-      top: this._railOriginY + rail * this._railSin - H / 2
-    })
+    // carriagePosition 의 valid range — rail 안 [cw/2, W - cw/2].
+    // crane 본체 (rail) 는 안 움직임 — *carriage assembly 만* X 슬라이드.
+    const minPos = cw / 2
+    const maxPos = Math.max(minPos, W - cw / 2)
+    const pickPos = () => minPos + Math.random() * (maxPos - minPos)
 
-    const source = toLeftTop(pickRail())
-    const dest = toLeftTop(pickRail())
+    const sourcePos = pickPos()
+    const destPos = pickPos()
 
     const sourceCH = Math.random() * D * 0.75
     const destCH = Math.random() * D * 0.75
@@ -636,14 +956,14 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
     // Tween duration 은 base 의 70~130% 사이 random — 여러 crane 이 같은 타이밍으로 안 보이도록.
     const jitter = (base: number): number => base * (0.7 + Math.random() * 0.6)
 
-    // 이동: crane local X 방향 → canvas (left, top) 둘 다 동시 변경 (rotation 적용 시 diagonal)
-    await this._tween({ status: 'moving', left: source.left, top: source.top, carriageHeight: sourceCH }, jitter(1500))
+    // 이동: carriagePosition 만 변경 (crane.left/top 안 건드림).
+    await this._tween({ status: 'moving', carriagePosition: sourcePos, carriageHeight: sourceCH }, jitter(1500))
     await this._tween({ status: 'loading', forkExtension: sideA * forkLen }, jitter(700))
-    await this._tween({ forkLift: liftH }, jitter(400))
+    await this._tween({ forkLiftRT: liftH }, jitter(400))
     await this._tween({ forkExtension: 0 }, jitter(700))
-    await this._tween({ status: 'moving', left: dest.left, top: dest.top, carriageHeight: destCH }, jitter(1500))
+    await this._tween({ status: 'moving', carriagePosition: destPos, carriageHeight: destCH }, jitter(1500))
     await this._tween({ status: 'unloading', forkExtension: sideB * forkLen }, jitter(700))
-    await this._tween({ forkLift: 0 }, jitter(400))
+    await this._tween({ forkLiftRT: 0 }, jitter(400))
     await this._tween({ status: 'idle', forkExtension: 0 }, jitter(700))
 
     // 사이클 사이 짧은 idle (200~1000ms) — 자연스러운 phase 분산
@@ -651,15 +971,16 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
   }
 
   /**
-   * things-scene 의 `component.animate()` 로 한 구간 tween. step 콜백에서 setState 호출.
-   * frameClock.simTime 기반이라 scene pause / speed change / suppressAnimations 모두 자동 대응.
+   * frameClock 기반 tween — things-scene 의 표준 `Component.animate()` 사용.
+   * frameClock.simTime 진행 (view mode + scene 활성) 시에만 step 호출 → modeler
+   * 또는 paused 시 자동 정지. scene.simulationSpeed 도 자동 대응.
    */
   private _tween(targets: Record<string, any>, duration: number): Promise<void> {
     const start: Record<string, number> = {}
     for (const k of Object.keys(targets)) {
       if (k === 'status') continue
       const v = (this.state as any)[k]
-      start[k] = typeof v === 'number' && Number.isFinite(v) ? v : 0
+      start[k] = typeof v === 'number' && Number.isFinite(v) ? v : this._canonicalDefault(k)
     }
     if (typeof targets.status === 'string') {
       this.setState({ status: targets.status })
@@ -676,10 +997,6 @@ export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legenda
         ease: 'inout',
         delta: 'quad',
         step: (dx: number) => {
-          if (this._simAbort) {
-            controller.stop?.()
-            return finish()
-          }
           const update: Record<string, number> = {}
           for (const k of Object.keys(start)) {
             const tgt = targets[k]
@@ -701,13 +1018,31 @@ function resolveCarrierDepth(c: Component): number {
   return numOr((c as any)?.state?.depth, 0)
 }
 
-function resolveCarrierCenterY(c: Component): number | null {
-  const pos = (c as any).state
-  if (!pos) return null
-  // zPos is the 3D Y center of a Placeable component in things-scene
-  const zPos = numOr(pos.zPos, NaN)
-  if (!Number.isNaN(zPos)) return zPos
-  return null
+
+/**
+ * Target 의 *world bottom Y* — fork blade 가 위치해야 할 높이.
+ *
+ * `getWorldPose(c).position.y` 는 *center Y*. fork 는 carrier 의 *바닥* (pallet
+ * pocket 진입 면) 에 위치해야 함 → center 에서 depth/2 만큼 빼서 bottom.
+ *
+ * `effectiveDepth` 는 RealObject 가 자동 계산한 실제 3D Y 키. 미가용 시 state.
+ * depth fallback.
+ */
+function resolveCarrierBottomY(c: Component): number | null {
+  if (!c) return null
+  try {
+    const pose = getWorldPose(c)
+    const centerY = pose?.position?.y
+    if (typeof centerY !== 'number' || !Number.isFinite(centerY)) return null
+    const ro = (c as any)._realObject
+    const eff = ro?.effectiveDepth
+    const depth = typeof eff === 'number' && Number.isFinite(eff)
+      ? eff
+      : numOr((c as any)?.state?.depth, 0)
+    return centerY - depth / 2
+  } catch {
+    return null
+  }
 }
 
 function numOr(v: unknown, dflt: number): number {