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

package/src/crane-3d.ts

@@ -31,7 +31,7 @@
  */
 
 import * as THREE from 'three'
-import { RealObjectGroup } from '@hatiolab/things-scene'
+import { RealObject, RealObjectGroup } from '@hatiolab/things-scene'
 
 const MAST_COLOR = 0xff7a00          // mast — orange
 const TROLLEY_COLOR = 0x3a4048       // base / top — dark charcoal
@@ -43,15 +43,33 @@ const LAMP_OFF = 0x222222
 
 export class Crane3D extends RealObjectGroup {
   private _forkGroup?: THREE.Group
-  private _forkTopY: number = 0
+  private _carrierBaseY: number = 0
   private _bladeMidZ: number = 0
+  /** floor rail 만 제외한 나머지 (trolley + masts + carriage + fork) 의 movable parent. */
+  private _trolleyGroup?: THREE.Group
+  /** carriage + fork 의 lift parent (carriageHeight + forkLiftRT 변경 시 Y 만 update). */
+  private _carriageLiftGroup?: THREE.Group
+  /** Fork active extension mesh — scale.z 와 position.z 로 lerp (rebuild 없이). */
+  private _extLeftMesh?: THREE.Mesh
+  private _extRightMesh?: THREE.Mesh
+  private _extBaseParams?: { bladeSpacing: number; carriageZ: number; stubL: number }
+  /** Fork mesh 의 group-local Y center (carriage 위 + bladeH/2). _applyForkExtensionMeshes 가 ext mesh Y 결정. */
+  private _forkOffsetY: number = 0
+  /** liftGroup.position.y 재계산용 base parameters. */
+  private _liftBaseParams?: { baseTrolleyY: number; baseH: number; carriageH: number; bladeH: number }
 
   build() {
     super.build()
 
     this._forkGroup = undefined
-    this._forkTopY = 0
+    this._carrierBaseY = 0
     this._bladeMidZ = 0
+    this._trolleyGroup = undefined
+    this._carriageLiftGroup = undefined
+    this._extLeftMesh = undefined
+    this._extRightMesh = undefined
+    this._extBaseParams = undefined
+    this._liftBaseParams = undefined
 
     const { width, height, depth } = this.component.state
     const emissiveColor = (this.component.state.lampEmissive as string) || '#222222'
@@ -60,13 +78,15 @@ export class Crane3D extends RealObjectGroup {
 
     // Actuators
     const D = numOr(depth, Math.max(width, height) * 4)
-    const carriageRaw = numOr((this.component.state as any).carriageHeight, D * 0.4)
+    const carriageRaw = numOr((this.component.state as any).carriageHeight, (this.component as any)._canonicalDefault?.('carriageHeight') ?? D * 0.4)
     const carriageHeight = Math.max(0, Math.min(carriageRaw, D * 0.85))
 
     const forkLength = numOr((this.component.state as any).forkLength, height * 0.6)
     const forkExtensionRaw = numOr((this.component.state as any).forkExtension, 0)
     const forkExtension = Math.max(-forkLength, Math.min(forkLength, forkExtensionRaw))
-    const forkLift = numOr((this.component.state as any).forkLift, 0)
+    // forkLiftRT — 시뮬 runtime current 들림. state.forkLift 는 *configured 진폭*
+    // (사용자 설정) 라 안 건드림. 3D carriage Y 는 runtime 값 사용.
+    const forkLift = numOr((this.component.state as any).forkLiftRT, 0)
 
     // ── Axis convention (FIXED): ─────────────────────────────────────
     //   Rail = X (state.left = 2D X = 3D X). Crane 좌우 이동.
@@ -80,18 +100,24 @@ export class Crane3D extends RealObjectGroup {
     const topFrameH = S * 0.1
     const topGuideH = S * 0.1
     const carriageH = S * 0.12
-    const mastW = width * 0.1                       // mast X 단면 (along rail)
-    const mastD = height * 0.25                     // mast Z 단면 (cross-rail)
-    const mastSpacing = width * 0.7                 // 두 mast X 간격
+    // Carriage assembly 크기 — state.carriageWidth 기반 (rail 길이 = crane.width
+    // 와 독립). 미명시 시 rail 의 10%.
+    const carriageAssemblyW = numOr((this.component.state as any).carriageWidth, width * 0.1)
+    const mastW = carriageAssemblyW * 0.15           // mast X 단면 (along rail)
+    const mastD = height * 0.25                      // mast Z 단면 (cross-rail)
+    const mastSpacing = carriageAssemblyW * 0.85     // 두 mast X 간격
     const bladeW = S * 0.1
-    const bladeH = S * 0.05
+    // bladeH — fork 두께. carriage 보다 얇게 (실 fork prong 의 가는 모양).
+    // carriage 와 *같은 Y center (0)* 이고 두께만 carriageH * 0.35.
+    const bladeH = carriageH * 0.35
     const bladeL = forkLength
     const bladeSpacing = mastSpacing * 0.45
     const carriageW = mastSpacing - mastW * 0.2
     const carriageZ = height * 0.55
-    const cabW = S * 0.4
-    const cabH = S * 0.4
-    const cabD = S * 0.3
+    // Cabinet — 존재감만. 작게.
+    const cabW = S * 0.18
+    const cabH = S * 0.18
+    const cabD = S * 0.15
 
     const baseY = -D / 2
     const mastH = Math.max(D - railH * 2 - baseH - topFrameH - topGuideH, S * 0.5)
@@ -104,37 +130,52 @@ export class Crane3D extends RealObjectGroup {
     const forkMat = new THREE.MeshStandardMaterial({ color: FORK_COLOR, metalness: 0.85, roughness: 0.3 })
     const railMat = new THREE.MeshStandardMaterial({ color: RAIL_COLOR, metalness: 0.9, roughness: 0.3 })
 
-    // ── Floor rail ────────────────────────────────────────────────────
+    // ── Floor rail (고정 — crane 본체 안 움직임). 폭 = crane.width (overhang 제거).
     {
-      const geo = new THREE.BoxGeometry(width * 1.1, railH, height * 0.35)
+      const railThin = railH * 0.5
+      const geo = new THREE.BoxGeometry(width, railThin, height * 0.15)
       const mesh = new THREE.Mesh(geo, railMat)
-      mesh.position.set(0, baseY + railH / 2, 0)
+      mesh.position.set(0, baseY + railThin / 2, 0)
       mesh.receiveShadow = true
       this.object3d.add(mesh)
     }
 
+    // ── Trolley group — carriage assembly (rail 위 X 만 이동) ─────────
+    // 모든 movable 부품 (base trolley, masts, carriage, fork, cabinet, lamp)
+    // 의 parent. carriagePosition 변경 시 group 의 local X 만 변경.
+    const trolleyGroup = new THREE.Group()
+    this._trolleyGroup = trolleyGroup
+    this.object3d.add(trolleyGroup)
+    // 초기 carriagePosition 적용 — rail-local X (0 ~ width) → object3d-local X (-W/2 ~ +W/2)
+    const carriagePos = numOr((this.component.state as any).carriagePosition, (this.component as any)._canonicalDefault?.('carriagePosition') ?? width / 2)
+    trolleyGroup.position.x = carriagePos - width / 2
+
     // ── Base trolley ──────────────────────────────────────────────────
+    // Cabinet 이 mast 바깥쪽에 자연스럽게 놓이도록 *trolley 폭을 mast + cabinet
+    // padding 까지 확장*. carriage assembly width 보다 양 옆으로 (cabW + gap) × 2.
+    const trolleyPad = cabW + S * 0.04
+    const baseTrolleyW = carriageAssemblyW + trolleyPad * 2
     const baseTrolleyY = baseY + railH + baseH / 2
     {
-      const geo = new THREE.BoxGeometry(width * 0.95, baseH, height * 0.7)
+      const geo = new THREE.BoxGeometry(baseTrolleyW, baseH, height * 0.7)
       const mesh = new THREE.Mesh(geo, trolleyMat)
       mesh.position.set(0, baseTrolleyY, 0)
       mesh.castShadow = true
       mesh.receiveShadow = true
-      this.object3d.add(mesh)
+      trolleyGroup.add(mesh)
     }
 
-    // ── Control cabinet on one side of base ───────────────────────────
+    // ── Control cabinet — mast 바깥쪽 (trolley 의 *확장 padding 영역* 위) ─────
     {
       const geo = new THREE.BoxGeometry(cabW, cabH, cabD)
       const cab = new THREE.Mesh(geo, cabinetMat)
       cab.position.set(
-        -width * 0.4 + cabW / 2,
+        -(carriageAssemblyW / 2 + cabW / 2 + S * 0.02),   // mast 왼쪽 바깥
         baseTrolleyY + baseH / 2 + cabH / 2,
         -height * 0.25 + cabD / 2
       )
       cab.castShadow = true
-      this.object3d.add(cab)
+      trolleyGroup.add(cab)
     }
 
     // ── Status lamp ───────────────────────────────────────────────────
@@ -150,8 +191,8 @@ export class Crane3D extends RealObjectGroup {
       })
       const geo = new THREE.CylinderGeometry(lampR, lampR * 0.8, lampH, 12)
       const lamp = new THREE.Mesh(geo, lampMat)
-      lamp.position.set(width * 0.4, baseTrolleyY + baseH / 2 + lampH / 2, 0)
-      this.object3d.add(lamp)
+      lamp.position.set(carriageAssemblyW / 2 + lampR * 1.5 + S * 0.02, baseTrolleyY + baseH / 2 + lampH / 2, 0)
+      trolleyGroup.add(lamp)
     }
 
     // ── Twin masts ────────────────────────────────────────────────────
@@ -162,118 +203,131 @@ export class Crane3D extends RealObjectGroup {
       mesh.position.set(xOff, mastY, 0)
       mesh.castShadow = true
       mesh.receiveShadow = true
-      this.object3d.add(mesh)
+      trolleyGroup.add(mesh)
     }
 
-    // ── Carriage + Fork 어셈블리 (forkLift 시 함께 이동) ───────────────
-    // 시각 단절 방지를 위해 carriage 와 fork 를 *함께* forkLift 만큼 올림.
-    // 의미상으로는 carriageHeight 가 mast 위 carriage 위치, forkLift 가 *그 어셈블리의*
-    // 추가 미세 Y. 둘 다 적용된 위치를 carriage / fork 둘 다 공유.
-    const carriageY = baseTrolleyY + baseH / 2 + carriageHeight + forkLift + carriageH / 2
+    // ── Carriage + Fork lift group (carriageHeight + forkLiftRT 따라 Y 이동) ─
+    // _carriageLiftGroup 안에 carriage + forkGroup. forkLiftRT / carriageHeight
+    // 변경 시 *그룹 Y 만 update* (mesh rebuild X). _forkGroup 의 child carrier 가
+    // *dispose 없이 그대로* 함께 따라 움직임.
+    const stubL = Math.min(carriageZ * 0.2, Math.max(bladeL * 0.05, 6))
+    const liftGroup = new THREE.Group()
+    this._carriageLiftGroup = liftGroup
+    this._liftBaseParams = { baseTrolleyY, baseH, carriageH, bladeH }
+    liftGroup.position.set(0, this._computeLiftGroupY(carriageHeight, forkLift), 0)
+    trolleyGroup.add(liftGroup)
+
+    // Carriage — liftGroup local center
     {
       const geo = new THREE.BoxGeometry(carriageW, carriageH, carriageZ)
       const mesh = new THREE.Mesh(geo, carriageMat)
-      mesh.position.set(0, carriageY, 0)
+      mesh.position.set(0, 0, 0)
       mesh.castShadow = true
       mesh.receiveShadow = true
-      this.object3d.add(mesh)
+      liftGroup.add(mesh)
     }
 
-    // ── Two-prong forks (양옆 stub + active 신축, 2D 와 동일 모델) ─────
-    //   ext=0: 양 ±Z 면에 작은 stub. carriage 안에 들어있는 인상 (튀어나옴 없음)
-    //   ext=±forkLen: active 쪽 stub + |ext| 길이로 신장. 반대쪽 stub 유지.
-    //   회전 flip 없음 → ext 가 0 을 지날 때 시각 점프 없음.
-    const forkY = carriageY            // carriage 중심 Y (embed)
-    const stubL = Math.min(carriageZ * 0.2, Math.max(bladeL * 0.05, 6))
+    // ── Two-prong forks ───────────────────────────────────────────────
+    // stub (4 box, fixed) + active extension (2 box, scale.z 로 lerp).
+    // active mesh 는 *unit-length* 로 생성. _applyForkExtension 이 scale.z 와
+    // position.z 로 길이/방향 update — rebuild 없이 매 frame 부드러운 변형.
     const absExt = Math.abs(forkExtension)
     const sign = forkExtension >= 0 ? 1 : -1
     {
       const group = new THREE.Group()
-      group.position.set(0, forkY, 0)
+      // _forkGroup 은 liftGroup-local center (0,0,0) — frame 일치 단순화.
+      // attach localPosition (carrier 자식) 도 *group-local = liftGroup-local* 동일 frame.
+      // Fork mesh 자체가 group-local 안에서 carriage *위* 로 (mesh.position.y).
+      group.position.set(0, 0, 0)
+
+      // Fork mesh 가 carriage 와 *수평 (같은 Y 평면)* — carriage 안에 embed.
+      // fork mesh group-local Y center = 0 (carriage center 와 같음).
+      // fork blade *bottom* 면 group-local Y = -bladeH/2.
+      // fork blade *top*    면 group-local Y = +bladeH/2.
+      const forkOffsetY = 0
 
       // 양옆 stub — 두 prong × 두 측면 = 4 box
       const stubGeo = new THREE.BoxGeometry(bladeW, bladeH, stubL)
       for (const xOff of [-bladeSpacing / 2, +bladeSpacing / 2]) {
         for (const zSide of [-1, +1]) {
           const mesh = new THREE.Mesh(stubGeo, forkMat)
-          mesh.position.set(xOff, 0, zSide * (carriageZ / 2 + stubL / 2))
+          mesh.position.set(xOff, forkOffsetY, zSide * (carriageZ / 2 + stubL / 2))
           mesh.castShadow = true
           mesh.receiveShadow = true
           group.add(mesh)
         }
       }
 
-      // Active side 신장
-      if (absExt > 0.5) {
-        const extGeo = new THREE.BoxGeometry(bladeW, bladeH, absExt)
-        for (const xOff of [-bladeSpacing / 2, +bladeSpacing / 2]) {
-          const mesh = new THREE.Mesh(extGeo, forkMat)
-          mesh.position.set(xOff, 0, sign * (carriageZ / 2 + stubL + absExt / 2))
-          mesh.castShadow = true
-          mesh.receiveShadow = true
-          group.add(mesh)
-        }
-      }
-
-      // Pallet — 정지 시 carriage 중심 Z, 신축 시 fork 중간으로 이동.
-      const loaded = forkLift > 0 || !!(this.component.state as any).loaded || !!(this.component.state as any).carrying
-      if (loaded) {
-        const palletMat = new THREE.MeshStandardMaterial({
-          color: 0xa08864, metalness: 0.1, roughness: 0.85
-        })
-        const palletW = bladeSpacing * 1.2
-        const palletH = Math.max(bladeH * 2.5, carriageH * 0.5)
-        const palletL = Math.max(bladeL * 0.3, carriageZ * 0.6)
-        const geo = new THREE.BoxGeometry(palletW, palletH, palletL)
-        const pallet = new THREE.Mesh(geo, palletMat)
-        const palletZ = absExt < 0.5 ? 0 : sign * (carriageZ / 2 + absExt / 2)
-        pallet.position.set(0, carriageH / 2 + palletH / 2, palletZ)
-        pallet.castShadow = true
-        pallet.receiveShadow = true
-        group.add(pallet)
-      }
-
-      this.object3d.add(group)
+      // Active extension — unit length, scale.z + position.z 로 변형
+      const extGeo = new THREE.BoxGeometry(bladeW, bladeH, 1)
+      const extLeft = new THREE.Mesh(extGeo, forkMat)
+      const extRight = new THREE.Mesh(extGeo, forkMat)
+      this._forkOffsetY = forkOffsetY
+      extLeft.castShadow = true
+      extLeft.receiveShadow = true
+      extRight.castShadow = true
+      extRight.receiveShadow = true
+      group.add(extLeft)
+      group.add(extRight)
+      this._extLeftMesh = extLeft
+      this._extRightMesh = extRight
+      this._extBaseParams = { bladeSpacing, carriageZ, stubL }
+      this._applyForkExtensionMeshes(absExt, sign)
+
+      // carrier 의 초기 Z = sign * absExt (= _applyForkExtensionMeshes 의 공식 동일).
+      const carrierZ = sign * absExt
+
+      liftGroup.add(group)
       this._forkGroup = group
-      this._forkTopY = carriageH / 2
-      this._bladeMidZ = absExt < 0.5 ? 0 : sign * (carriageZ / 2 + absExt / 2)
+      // Carrier 외부 bottom 정렬점 (liftGroup-local Y) = fork blade *bottom* =
+      // -bladeH/2 (fork mesh group-local center = 0, 두께 bladeH).
+      // 사용자 모델: "fork 의 아랫면 ≈ carrier 의 아랫면" — fork blade 가 carrier
+      // 의 bottom 부분 안으로 *찔러 들어감* (겹친 자세).
+      this._carrierBaseY = -bladeH / 2
+      this._bladeMidZ = carrierZ
     }
 
-    // ── Top frame (connects mast tops) ────────────────────────────────
+    // ── Top frame (connects mast tops) — trolley 함께 이동 ─────────────
     const topFrameY = mastY + mastH / 2 + topFrameH / 2
     {
       const geo = new THREE.BoxGeometry(mastSpacing + mastW, topFrameH, height * 0.35)
       const mesh = new THREE.Mesh(geo, trolleyMat)
       mesh.position.set(0, topFrameY, 0)
       mesh.castShadow = true
-      this.object3d.add(mesh)
+      trolleyGroup.add(mesh)
     }
 
-    // ── Top guide trolley ─────────────────────────────────────────────
+    // ── Top guide trolley — trolley 함께 이동 (ceiling rail 위 미끄러짐) ─
     const topGuideY = topFrameY + topFrameH / 2 + topGuideH / 2
     {
       const geo = new THREE.BoxGeometry(mastSpacing + mastW * 2, topGuideH, height * 0.3)
       const mesh = new THREE.Mesh(geo, trolleyMat)
       mesh.position.set(0, topGuideY, 0)
       mesh.castShadow = true
-      this.object3d.add(mesh)
+      trolleyGroup.add(mesh)
     }
 
-    // ── Ceiling rail ──────────────────────────────────────────────────
-    {
-      const geo = new THREE.BoxGeometry(width * 1.1, railH, height * 0.3)
-      const mesh = new THREE.Mesh(geo, railMat)
-      mesh.position.set(0, topGuideY + topGuideH / 2 + railH / 2, 0)
-      this.object3d.add(mesh)
-    }
+    // Ceiling rail 생략 — 상단은 top guide trolley 만으로 충분. 사용자 의도.
+
   }
 
   getCarriageFrame(): THREE.Object3D | undefined {
-    return this._forkGroup ?? this.object3d
+    // Fallback chain — carrier 가 *carriage transform (X 이동, Y lift)* 따라오도록.
+    // _forkGroup 미존재 시 _carriageLiftGroup (X+Y 따라옴) → _trolleyGroup (X 만) →
+    // root (no follow). 절대 root 로 떨어지지 않도록 lift/trolley 우선.
+    return this._forkGroup ?? this._carriageLiftGroup ?? this._trolleyGroup ?? this.object3d
   }
 
-  get platformTopY(): number {
-    return this._forkTopY
+  /**
+   * Fork blade *bottom* 의 liftGroup-local Y. *carrier 외부 bottom 정렬점*.
+   *
+   * 모델: carrier 의 외부 bottom 과 fork blade 의 bottom 이 *거의 일치*. fork 가
+   * carrier 의 bottom 부분을 *찔러 들어가* carrier 와 *겹친 자세* (pallet pocket
+   * 안 fork 진입). attachPointFor 가 `carrierBaseY + carrier.depth/2` 로 carrier
+   * center 를 정렬 → carrier bottom = fork blade bottom.
+   */
+  get carrierBaseY(): number {
+    return this._carrierBaseY
   }
 
   get bladeMidZ(): number {
@@ -283,24 +337,135 @@ export class Crane3D extends RealObjectGroup {
   updateDimension() {}
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
-    if (
+    // carriagePosition — trolleyGroup.position.x (mesh-level update).
+    if ('carriagePosition' in after && this._trolleyGroup) {
+      const W = numOr(this.component.state.width, 100)
+      const pos = numOr(after.carriagePosition, W / 2)
+      this._trolleyGroup.position.x = pos - W / 2
+    }
+
+    // Mesh-level updates — fork extension / lift / carriage height. *rebuild 없이*
+    // mesh 의 scale / position 만 변경. _forkGroup 의 child carrier 가 dispose
+    // 없이 그대로 따라 움직임 (fork 작업 시 시각 자연스러움).
+    //
+    // status / bodyColor / lampEmissive 는 *cosmetic* — full rebuild 회피. 별도
+    // 처리 없음 시 status 변경 시 carrier dispose → 사라짐 결함의 원인. 향후
+    // material color 만 update 하는 path 추가 가능.
+    const needsFullRebuild =
       'width' in after ||
       'height' in after ||
       'depth' in after ||
-      'carriageHeight' in after ||
       'forkLength' in after ||
-      'forkExtension' in after ||
-      'forkLift' in after ||
-      'status' in after ||
-      'bodyColor' in after ||
-      'lampEmissive' in after
-    ) {
+      'carriageWidth' in after
+
+    if (!needsFullRebuild) {
+      let meshUpdated = false
+      if (('carriageHeight' in after || 'forkLiftRT' in after) && this._carriageLiftGroup) {
+        const state = this.component.state as any
+        const D = numOr(state.depth, Math.max(numOr(state.width, 100), numOr(state.height, 100)) * 4)
+        const carriageRaw = numOr(state.carriageHeight, D * 0.4)
+        const carriageHeight = Math.max(0, Math.min(carriageRaw, D * 0.85))
+        const forkLift = numOr(state.forkLiftRT, 0)
+        this._carriageLiftGroup.position.y = this._computeLiftGroupY(carriageHeight, forkLift)
+        meshUpdated = true
+      }
+      if ('forkExtension' in after && this._extLeftMesh && this._extRightMesh) {
+        const state = this.component.state as any
+        const forkLength = numOr(state.forkLength, numOr(state.height, 100) * 0.6)
+        const forkExtensionRaw = numOr(state.forkExtension, 0)
+        const forkExtension = Math.max(-forkLength, Math.min(forkLength, forkExtensionRaw))
+        const absExt = Math.abs(forkExtension)
+        const sign = forkExtension >= 0 ? 1 : -1
+        this._applyForkExtensionMeshes(absExt, sign)
+        meshUpdated = true
+      }
+      if (meshUpdated) return
+    }
+
+    if (needsFullRebuild) {
       this.update()
       return
     }
     super.onchange(after, before)
   }
 
+  /** carriageHeight + forkLiftRT 를 liftGroup.position.y 로 변환. */
+  private _computeLiftGroupY(carriageHeight: number, forkLift: number): number {
+    const p = this._liftBaseParams
+    if (!p) return 0
+    return p.baseTrolleyY + p.baseH / 2 + carriageHeight + forkLift + p.carriageH / 2
+  }
+
+  /**
+   * Carrier 외부 bottom 의 world Y → carriageHeight state 값 inverse-solve.
+   *
+   * Forward 공식 (build):
+   *   liftGroup.y crane-local = baseTrolleyY + baseH/2 + carriageHeight + forkLift + carriageH/2
+   *   carrier 외부 bottom crane-local = liftGroup.y + carrierBaseY (= -bladeH/2)
+   *                                   = baseTrolleyY + baseH/2 + carriageH/2 - bladeH/2 + carriageHeight + forkLift
+   *
+   * Inverse:
+   *   carriageHeight = worldY − craneCenterY − (baseTrolleyY + baseH/2 + carriageH/2 − bladeH/2) − forkLift
+   */
+  solveCarriageHeightForCarrierBaseWorldY(worldY: number, forkLift: number = 0): number {
+    const p = this._liftBaseParams
+    if (!p) return 0
+    this.object3d.updateWorldMatrix(true, false)
+    const v = new THREE.Vector3()
+    this.object3d.matrixWorld.decompose(v, new THREE.Quaternion(), new THREE.Vector3())
+    const craneCenterWorldY = v.y
+    return worldY - craneCenterWorldY - (p.baseTrolleyY + p.baseH / 2 + p.carriageH / 2 - p.bladeH / 2) - forkLift
+  }
+
+  /**
+   * target 의 *crane-local Z* → fork extension 값 inverse-solve.
+   *
+   * Forward (_applyForkExtensionMeshes): `_bladeMidZ = sign * absExt`
+   * (carrier 가 ext 만큼 fork 따라 진출). Inverse: `ext = |localZ|, sign = sign(localZ)`.
+   *
+   * forkLength 로 clamp — localZ 가 forkLength 보다 멀면 carrier 가 fork tip 까지만.
+   */
+  solveForkExtensionForLocalZ(localZ: number): number {
+    const sign = localZ >= 0 ? 1 : -1
+    const state = this.component.state as any
+    const forkLen = numOr(state.forkLength, numOr(state.height, 100) * 0.6)
+    const clamped = Math.max(0, Math.min(forkLen, Math.abs(localZ)))
+    return sign * clamped
+  }
+
+  /** Fork active extension mesh 의 scale.z + position.z + visibility update. */
+  private _applyForkExtensionMeshes(absExt: number, sign: number) {
+    if (!this._extLeftMesh || !this._extRightMesh || !this._extBaseParams) return
+    const { bladeSpacing, carriageZ, stubL } = this._extBaseParams
+    const visible = absExt > 0.5
+    const len = Math.max(0.001, absExt)
+    const posZ = sign * (carriageZ / 2 + stubL + absExt / 2)
+    this._extLeftMesh.scale.z = len
+    this._extRightMesh.scale.z = len
+    this._extLeftMesh.position.set(-bladeSpacing / 2, this._forkOffsetY, posZ)
+    this._extRightMesh.position.set(+bladeSpacing / 2, this._forkOffsetY, posZ)
+    this._extLeftMesh.visible = visible
+    this._extRightMesh.visible = visible
+
+    // _bladeMidZ = carrier 의 Z 위치 = sign * absExt (= fork extension 만큼 직접).
+    //   ext=0   → 0    (carriage 정중앙 — retract 끝 자세)
+    //   ext=L   → ±L   (fork 가 L 만큼 진출한 위치 = carrier 도 그 위치)
+    // 단순 linear — solveForkExtensionForLocalZ 의 inverse 도 단순 (ext = |localZ|).
+    this._bladeMidZ = sign * absExt
+
+    // _forkGroup 의 child carrier 의 Z 도 동기 — fork tip 위치 따라 carrier 가
+    // 함께 끌려와야 retract 시각 자연.
+    if (this._forkGroup) {
+      for (const child of this._forkGroup.children) {
+        const ctx = (child as any).userData?.context
+        if (ctx && ctx !== this && ctx instanceof RealObject) {
+          child.position.z = this._bladeMidZ
+        }
+      }
+    }
+
+  }
+
   updateAlpha() {}
 }