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

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.0.0-beta.41](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.40...v10.0.0-beta.41) (2026-05-17)
+
+
+### :rocket: New Features
+
+* **storage,mover:** Rack 자동 cell build + cellComponent helper + carrier 호환성 확장 + Mover null guard ([ed906fd](https://github.com/things-scene/operato-scene/commit/ed906fdbcc24715158aeb14cee133f6183a5dd56))
+* **storage:** Box, Pallet 에도 agv-deck pickupFrame 추가 ([fc74a1a](https://github.com/things-scene/operato-scene/commit/fc74a1a44fc9d10cff9b140180974fca93884b2a))
+* **storage:** Crane fork pnp 시각 정밀화 + 기하학 단순화 ([73cff2d](https://github.com/things-scene/operato-scene/commit/73cff2d4fbd02e310cdaa6144889a1ad8ebda2f4))
+* **storage:** Parcel.pickupFrames 에 agv-deck frame 추가 ([be20388](https://github.com/things-scene/operato-scene/commit/be203886231523653bee94a6f3ae6953a82dd794))
+
+
+### :bug: Bug Fix
+
+* **storage:** cell 2D 좌표 결함 + crane.simulate default + rack 시각 + parcel material hoist ([c6aa929](https://github.com/things-scene/operato-scene/commit/c6aa929255327e40859e638448ff6ae9719e8715))
+
+
+
 ## [10.0.0-beta.40](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.39...v10.0.0-beta.40) (2026-05-16)
 
 **Note:** Version bump only for package @operato/scene-storage

package/dist/box.js

@@ -88,6 +88,24 @@ let Box = class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {
                 tolerance: { positionMm: 5, angleDeg: 1 },
                 priority: 0,
                 id: 'top-gripper'
+            }),
+            topApproachFrame({
+                carrierWorld: me,
+                topY: boxDepth,
+                approachDistance: 40,
+                toolType: 'agv-deck',
+                tolerance: { positionMm: 15, angleDeg: 3 },
+                priority: 1,
+                id: 'top-deck'
+            }),
+            topApproachFrame({
+                carrierWorld: me,
+                topY: boxDepth,
+                approachDistance: 80, // crane fork hover
+                toolType: 'forklift-fork',
+                tolerance: { positionMm: 25, angleDeg: 4 },
+                priority: 2,
+                id: 'top-fork'
             })
         ];
     }

package/dist/box.js.map

@@ -1 +1 @@
-{"version":3,"file":"box.js","sourceRoot":"","sources":["../src/box.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n */\nimport {\n  ComponentNature,\n  RealObject,\n  RectPath,\n  Shape,\n  topApproachFrame,\n  getWorldPose,\n  sceneComponent\n} from '@hatiolab/things-scene'\nimport type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'\nimport {\n  Carriable,\n  Legendable,\n  Placeable,\n  type Alignment,\n  type LegendBinding,\n  type PlacementArchetype\n} from '@operato/scene-base'\n\nimport { Box3D } from './box-3d.js'\n\n/**\n * Box material — drives 3D structure and color.\n *\n * - `wood`     — wood crate: visible vertical slats, gaps between, open or\n *                semi-open top. Used for heavy / industrial parts.\n * - `plastic`  — plastic tote / bin: solid molded walls with stackable lip\n *                at top. Used for fulfillment, parts kitting.\n *\n * Cardboard parcels are a separate component (see `parcel.ts`) — they have\n * different proportions, taping, and labels that warrant a distinct class.\n */\nexport type BoxMaterial = 'wood' | 'plastic'\n\n/** Box 컴포넌트 state */\nexport interface BoxState extends State {\n  // ── 외관 ──\n  material?: BoxMaterial\n\n  // ── 3D 재질 ──\n  material3d?: Material3D\n}\n\nconst BODY_LEGEND = {\n  wood: '#a87644',\n  plastic: '#3a5078',\n  default: '#a87644'\n}\n\nconst NATURE: ComponentNature = {\n  mutable: false,\n  resizable: true,\n  rotatable: true,\n  properties: [\n    {\n      type: 'select',\n      label: 'material',\n      name: 'material',\n      property: {\n        options: [\n          { display: 'Wood', value: 'wood' },\n          { display: 'Plastic', value: 'plastic' }\n        ]\n      }\n    }\n  ],\n  help: 'scene/component/box'\n}\n\n// Carriable: a box can be a child of any CarrierHolder (Pallet for stacking,\n// AGV deck, robot-arm gripper, Spot for staging).\n/**\n * Box — a generic stackable container for goods. Wood crate or plastic tote\n * variants distinguished by `material` prop.\n *\n * Shape-based (not Container) — boxes nesting other components is rare in\n * logistics visualization (a *case* of items inside a box is data, not\n * scene-tree). If a future use case needs nested boxes, extend Container.\n */\n@sceneComponent('box')\nexport default class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {\n  declare state: BoxState\n\n  static legends: Record<string, LegendBinding> = {\n    bodyColor: { from: 'material', legend: BODY_LEGEND }\n  }\n\n  static placement: PlacementArchetype = 'operation'\n  static align: Alignment = 'bottom'\n  static defaultDepth = 300\n\n  get nature() {\n    return NATURE\n  }\n\n  get anchors() {\n    return []\n  }\n\n  /** 2D — top-down rectangle. */\n  render(ctx: CanvasRenderingContext2D) {\n    const { width, height, left, top } = this.state\n    ctx.beginPath()\n    ctx.rect(left, top, width, height)\n  }\n\n  get fillStyle() {\n    return (this.state.bodyColor as string) || '#a87644'\n  }\n\n  buildRealObject(): RealObject | undefined {\n    return new Box3D(this)\n  }\n\n  /**\n   * Phase H — pickup contract. Box 는 위에서 gripper / vacuum cup 으로 집기 —\n   * 단일 entry (top center). Box 의 dimensions 가 작아서 forklift fork 보다는\n   * gripper 가 일반적. forklift 로 들어올릴 box 는 통상 pallet 위에 stacking\n   * 후 pallet 째로 운반.\n   *\n   * tolerance 가 pallet 보다 빡빡 (gripper 정밀도 vs forklift pocket 폭).\n   */\n  pickupFrames(): PickupFrame[] {\n    const wp = getWorldPose(this)\n    const me: PoseSerialized = {\n      position: { x: wp.position.x, y: wp.position.y, z: wp.position.z },\n      rotation: { x: wp.rotation.x, y: wp.rotation.y, z: wp.rotation.z, w: wp.rotation.w }\n    }\n    const boxDepth = (this.constructor as any).defaultDepth ?? 300\n\n    return [\n      topApproachFrame({\n        carrierWorld: me,\n        topY: boxDepth,                  // Box top in carrier-local Y (depth = full height; top at depth)\n        approachDistance: 50,            // gripper 가 hover 하는 거리\n        toolType: 'gripper',\n        tolerance: { positionMm: 5, angleDeg: 1 },\n        priority: 0,\n        id: 'top-gripper'\n      })\n    ]\n  }\n}\n"]}
+{"version":3,"file":"box.js","sourceRoot":"","sources":["../src/box.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright © HatioLab Inc. All rights reserved.\n */\nimport {\n  ComponentNature,\n  RealObject,\n  RectPath,\n  Shape,\n  topApproachFrame,\n  getWorldPose,\n  sceneComponent\n} from '@hatiolab/things-scene'\nimport type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'\nimport {\n  Carriable,\n  Legendable,\n  Placeable,\n  type Alignment,\n  type LegendBinding,\n  type PlacementArchetype\n} from '@operato/scene-base'\n\nimport { Box3D } from './box-3d.js'\n\n/**\n * Box material — drives 3D structure and color.\n *\n * - `wood`     — wood crate: visible vertical slats, gaps between, open or\n *                semi-open top. Used for heavy / industrial parts.\n * - `plastic`  — plastic tote / bin: solid molded walls with stackable lip\n *                at top. Used for fulfillment, parts kitting.\n *\n * Cardboard parcels are a separate component (see `parcel.ts`) — they have\n * different proportions, taping, and labels that warrant a distinct class.\n */\nexport type BoxMaterial = 'wood' | 'plastic'\n\n/** Box 컴포넌트 state */\nexport interface BoxState extends State {\n  // ── 외관 ──\n  material?: BoxMaterial\n\n  // ── 3D 재질 ──\n  material3d?: Material3D\n}\n\nconst BODY_LEGEND = {\n  wood: '#a87644',\n  plastic: '#3a5078',\n  default: '#a87644'\n}\n\nconst NATURE: ComponentNature = {\n  mutable: false,\n  resizable: true,\n  rotatable: true,\n  properties: [\n    {\n      type: 'select',\n      label: 'material',\n      name: 'material',\n      property: {\n        options: [\n          { display: 'Wood', value: 'wood' },\n          { display: 'Plastic', value: 'plastic' }\n        ]\n      }\n    }\n  ],\n  help: 'scene/component/box'\n}\n\n// Carriable: a box can be a child of any CarrierHolder (Pallet for stacking,\n// AGV deck, robot-arm gripper, Spot for staging).\n/**\n * Box — a generic stackable container for goods. Wood crate or plastic tote\n * variants distinguished by `material` prop.\n *\n * Shape-based (not Container) — boxes nesting other components is rare in\n * logistics visualization (a *case* of items inside a box is data, not\n * scene-tree). If a future use case needs nested boxes, extend Container.\n */\n@sceneComponent('box')\nexport default class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {\n  declare state: BoxState\n\n  static legends: Record<string, LegendBinding> = {\n    bodyColor: { from: 'material', legend: BODY_LEGEND }\n  }\n\n  static placement: PlacementArchetype = 'operation'\n  static align: Alignment = 'bottom'\n  static defaultDepth = 300\n\n  get nature() {\n    return NATURE\n  }\n\n  get anchors() {\n    return []\n  }\n\n  /** 2D — top-down rectangle. */\n  render(ctx: CanvasRenderingContext2D) {\n    const { width, height, left, top } = this.state\n    ctx.beginPath()\n    ctx.rect(left, top, width, height)\n  }\n\n  get fillStyle() {\n    return (this.state.bodyColor as string) || '#a87644'\n  }\n\n  buildRealObject(): RealObject | undefined {\n    return new Box3D(this)\n  }\n\n  /**\n   * Phase H — pickup contract. Box 는 위에서 gripper / vacuum cup 으로 집기 —\n   * 단일 entry (top center). Box 의 dimensions 가 작아서 forklift fork 보다는\n   * gripper 가 일반적. forklift 로 들어올릴 box 는 통상 pallet 위에 stacking\n   * 후 pallet 째로 운반.\n   *\n   * tolerance 가 pallet 보다 빡빡 (gripper 정밀도 vs forklift pocket 폭).\n   */\n  pickupFrames(): PickupFrame[] {\n    const wp = getWorldPose(this)\n    const me: PoseSerialized = {\n      position: { x: wp.position.x, y: wp.position.y, z: wp.position.z },\n      rotation: { x: wp.rotation.x, y: wp.rotation.y, z: wp.rotation.z, w: wp.rotation.w }\n    }\n    const boxDepth = (this.constructor as any).defaultDepth ?? 300\n\n    return [\n      topApproachFrame({\n        carrierWorld: me,\n        topY: boxDepth,                  // Box top in carrier-local Y (depth = full height; top at depth)\n        approachDistance: 50,            // gripper 가 hover 하는 거리\n        toolType: 'gripper',\n        tolerance: { positionMm: 5, angleDeg: 1 },\n        priority: 0,\n        id: 'top-gripper'\n      }),\n      topApproachFrame({\n        carrierWorld: me,\n        topY: boxDepth,\n        approachDistance: 40,\n        toolType: 'agv-deck',\n        tolerance: { positionMm: 15, angleDeg: 3 },\n        priority: 1,\n        id: 'top-deck'\n      }),\n      topApproachFrame({\n        carrierWorld: me,\n        topY: boxDepth,\n        approachDistance: 80,            // crane fork hover\n        toolType: 'forklift-fork',\n        tolerance: { positionMm: 25, angleDeg: 4 },\n        priority: 2,\n        id: 'top-fork'\n      })\n    ]\n  }\n}\n"]}

package/dist/crane-3d.d.ts

@@ -2,13 +2,58 @@ import * as THREE from 'three';
 import { RealObjectGroup } from '@hatiolab/things-scene';
 export declare class Crane3D extends RealObjectGroup {
     private _forkGroup?;
-    private _forkTopY;
+    private _carrierBaseY;
     private _bladeMidZ;
+    /** floor rail 만 제외한 나머지 (trolley + masts + carriage + fork) 의 movable parent. */
+    private _trolleyGroup?;
+    /** carriage + fork 의 lift parent (carriageHeight + forkLiftRT 변경 시 Y 만 update). */
+    private _carriageLiftGroup?;
+    /** Fork active extension mesh — scale.z 와 position.z 로 lerp (rebuild 없이). */
+    private _extLeftMesh?;
+    private _extRightMesh?;
+    private _extBaseParams?;
+    /** Fork mesh 의 group-local Y center (carriage 위 + bladeH/2). _applyForkExtensionMeshes 가 ext mesh Y 결정. */
+    private _forkOffsetY;
+    /** liftGroup.position.y 재계산용 base parameters. */
+    private _liftBaseParams?;
     build(): void;
     getCarriageFrame(): THREE.Object3D | undefined;
-    get platformTopY(): number;
+    /**
+     * 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;
     get bladeMidZ(): number;
     updateDimension(): void;
     onchange(after: Record<string, unknown>, before: Record<string, unknown>): void;
+    /** carriageHeight + forkLiftRT 를 liftGroup.position.y 로 변환. */
+    private _computeLiftGroupY;
+    /**
+     * 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): number;
+    /**
+     * 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;
+    /** Fork active extension mesh 의 scale.z + position.z + visibility update. */
+    private _applyForkExtensionMeshes;
     updateAlpha(): void;
 }

package/dist/crane-3d.js

@@ -30,7 +30,7 @@
  *   carriageHeight, forkExtension (±), forkLift
  */
 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
 const CARRIAGE_COLOR = 0xffcc00; // carriage (shuttle) — yellow
@@ -40,25 +40,45 @@ const RAIL_COLOR = 0x1a1f24; // rail — dark steel
 const LAMP_OFF = 0x222222;
 export class Crane3D extends RealObjectGroup {
     _forkGroup;
-    _forkTopY = 0;
+    _carrierBaseY = 0;
     _bladeMidZ = 0;
+    /** floor rail 만 제외한 나머지 (trolley + masts + carriage + fork) 의 movable parent. */
+    _trolleyGroup;
+    /** carriage + fork 의 lift parent (carriageHeight + forkLiftRT 변경 시 Y 만 update). */
+    _carriageLiftGroup;
+    /** Fork active extension mesh — scale.z 와 position.z 로 lerp (rebuild 없이). */
+    _extLeftMesh;
+    _extRightMesh;
+    _extBaseParams;
+    /** Fork mesh 의 group-local Y center (carriage 위 + bladeH/2). _applyForkExtensionMeshes 가 ext mesh Y 결정. */
+    _forkOffsetY = 0;
+    /** liftGroup.position.y 재계산용 base parameters. */
+    _liftBaseParams;
     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 || '#222222';
         const status = this.component.state.status;
         const lampOn = status && status !== 'idle';
         // Actuators
         const D = numOr(depth, Math.max(width, height) * 4);
-        const carriageRaw = numOr(this.component.state.carriageHeight, D * 0.4);
+        const carriageRaw = numOr(this.component.state.carriageHeight, this.component._canonicalDefault?.('carriageHeight') ?? D * 0.4);
         const carriageHeight = Math.max(0, Math.min(carriageRaw, D * 0.85));
         const forkLength = numOr(this.component.state.forkLength, height * 0.6);
         const forkExtensionRaw = numOr(this.component.state.forkExtension, 0);
         const forkExtension = Math.max(-forkLength, Math.min(forkLength, forkExtensionRaw));
-        const forkLift = numOr(this.component.state.forkLift, 0);
+        // forkLiftRT — 시뮬 runtime current 들림. state.forkLift 는 *configured 진폭*
+        // (사용자 설정) 라 안 건드림. 3D carriage Y 는 runtime 값 사용.
+        const forkLift = numOr(this.component.state.forkLiftRT, 0);
         // ── Axis convention (FIXED): ─────────────────────────────────────
         //   Rail = X (state.left = 2D X = 3D X). Crane 좌우 이동.
         //   Fork = Z (2D Y = 3D Z). Fork 앞뒤 신축.
@@ -71,18 +91,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)
+        // Carriage assembly 크기 — state.carriageWidth 기반 (rail 길이 = crane.width
+        // 와 독립). 미명시 시 rail 의 10%.
+        const carriageAssemblyW = numOr(this.component.state.carriageWidth, width * 0.1);
+        const mastW = carriageAssemblyW * 0.15; // mast X 단면 (along rail)
         const mastD = height * 0.25; // mast Z 단면 (cross-rail)
-        const mastSpacing = width * 0.7; // 두 mast X 간격
+        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);
         // ── Materials ─────────────────────────────────────────────────────
@@ -92,31 +118,46 @@ export class Crane3D extends RealObjectGroup {
         const cabinetMat = new THREE.MeshStandardMaterial({ color: CONTROLLER_COLOR, metalness: 0.2, roughness: 0.6 });
         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.carriagePosition, this.component._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, baseTrolleyY + baseH / 2 + cabH / 2, -height * 0.25 + cabD / 2);
+            cab.position.set(-(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 ───────────────────────────────────────────────────
         {
@@ -131,8 +172,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 ────────────────────────────────────────────────────
         const mastY = baseTrolleyY + baseH / 2 + mastH / 2;
@@ -142,128 +183,244 @@ 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.loaded || !!this.component.state.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);
-        }
-        // ── 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);
+            trolleyGroup.add(mesh);
         }
+        // Ceiling rail 생략 — 상단은 top guide trolley 만으로 충분. 사용자 의도.
     }
     getCarriageFrame() {
-        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() {
-        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() {
+        return this._carrierBaseY;
     }
     get bladeMidZ() {
         return this._bladeMidZ;
     }
     updateDimension() { }
     onchange(after, before) {
-        if ('width' in after ||
+        // 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;
+                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;
+                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 로 변환. */
+    _computeLiftGroupY(carriageHeight, forkLift) {
+        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, forkLift = 0) {
+        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) {
+        const sign = localZ >= 0 ? 1 : -1;
+        const state = this.component.state;
+        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. */
+    _applyForkExtensionMeshes(absExt, sign) {
+        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.userData?.context;
+                if (ctx && ctx !== this && ctx instanceof RealObject) {
+                    child.position.z = this._bladeMidZ;
+                }
+            }
+        }
+    }
     updateAlpha() { }
 }
 function numOr(v, dflt) {