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

package/src/pallet.ts

@@ -8,6 +8,7 @@ import {
   RealObject,
   Pose6DOF,
   rectangularFootprintFrames,
+  topApproachFrame,
   getWorldPose,
   sceneComponent
 } from '@hatiolab/things-scene'
@@ -41,6 +42,15 @@ export interface PalletState extends State {
   // ── 외관 ──
   material?: PalletMaterial
 
+  /**
+   * Fork pocket 의 깊이 (mm) — pallet 외부 bottom (skid bottom) 부터 deck bottom
+   * 까지의 수직 거리. fork blade 가 이 *pocket 안* 으로 수평 진입. 표준 EUR
+   * pallet (144mm depth) 의 pocket ≈ 50~60mm.
+   *
+   * 미명시 시 default = depth 의 40% (= ~60mm for 150mm pallet).
+   */
+  pocketDepth?: number
+
   // ── 3D 재질 ──
   material3d?: Material3D
 }
@@ -66,6 +76,12 @@ const NATURE: ComponentNature = {
           { display: 'Plastic', value: 'plastic' }
         ]
       }
+    },
+    {
+      type: 'number',
+      label: 'pocket-depth',
+      name: 'pocketDepth',
+      placeholder: 'mm — fork 진입 pocket 깊이 (skid bottom → deck bottom). default depth × 40%.'
     }
   ],
   help: 'scene/component/pallet'
@@ -121,6 +137,24 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
     return NATURE
   }
 
+  /**
+   * Fork pocket 의 깊이 — fork blade 가 진입하는 *pallet 외부 bottom 부터 deck
+   * bottom* 까지의 수직 거리. crane.attachPointFor 가 이 값을 차감해서
+   * carrier 외부 bottom (skid) 이 fork blade bottom *아래로 pocketDepth 만큼*
+   * 깊이 정렬 (= fork 가 pallet 의 *deck 와 skid 사이* 안 으로 들어간 자세).
+   */
+  get pocketDepth(): number {
+    const explicit = (this.state as any).pocketDepth
+    if (typeof explicit === 'number' && Number.isFinite(explicit) && explicit >= 0) {
+      return explicit
+    }
+    const d = this.state.depth
+    const depth = typeof d === 'number' && Number.isFinite(d) && d > 0
+      ? d
+      : ((this.constructor as any).defaultDepth ?? 150)
+    return depth * 0.4
+  }
+
   get anchors() {
     return []
   }
@@ -240,7 +274,7 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
 
     const longerAxis = Math.max(width, height)
 
-    return rectangularFootprintFrames({
+    const forkFrames = rectangularFootprintFrames({
       carrierWorld: me,
       width,
       depth: height,
@@ -251,5 +285,20 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
       tolerance: { positionMm: 50, angleDeg: 5 },
       priority: 0
     })
+
+    // 큰 AGV (deck size 충분) 가 pallet 을 위에 적재하는 패턴. priority 낮음
+    // — forklift fork 가 더 자연스러운 default. AGV deck size 가 pallet 보다
+    // 작으면 application 측이 carrier 의 dimensions check 필요.
+    const deckFrame = topApproachFrame({
+      carrierWorld: me,
+      topY: palletDepth,
+      approachDistance: longerAxis * 0.5 + 100,
+      toolType: 'agv-deck',
+      tolerance: { positionMm: 30, angleDeg: 4 },
+      priority: 1,
+      id: 'top-deck'
+    })
+
+    return [...forkFrames, deckFrame]
   }
 }

package/src/parcel-3d.ts

@@ -21,6 +21,26 @@ const CARDBOARD_COLOR = 0xc8a878
 const TAPE_COLOR = 0xddc899
 const LABEL_COLOR = 0xeeeeee
 
+// ── Module-level shared materials ───────────────────────────────────────────
+// Parcel 인스턴스가 수백~수천 가능. instance 별 new MeshStandardMaterial 시
+// material 개수 폭증 → GPU memory + draw call 비효율. static color 라 단일
+// instance 공유. 색 변경 시 모든 Parcel 에 자동 반영 (의도).
+const PARCEL_BODY_MATERIAL = new THREE.MeshStandardMaterial({
+  color: CARDBOARD_COLOR,
+  metalness: 0,
+  roughness: 0.9
+})
+const PARCEL_TAPE_MATERIAL = new THREE.MeshStandardMaterial({
+  color: TAPE_COLOR,
+  metalness: 0.05,
+  roughness: 0.5
+})
+const PARCEL_LABEL_MATERIAL = new THREE.MeshStandardMaterial({
+  color: LABEL_COLOR,
+  metalness: 0,
+  roughness: 0.4
+})
+
 export class Parcel3D extends RealObjectGroup {
   build() {
     super.build()
@@ -30,12 +50,7 @@ export class Parcel3D extends RealObjectGroup {
 
     // ── Main body ────────────────────────────────────────────────────
     const bodyGeo = new THREE.BoxGeometry(width, depth, height)
-    const bodyMaterial = new THREE.MeshStandardMaterial({
-      color: CARDBOARD_COLOR,
-      metalness: 0,
-      roughness: 0.9
-    })
-    const bodyMesh = new THREE.Mesh(bodyGeo, bodyMaterial)
+    const bodyMesh = new THREE.Mesh(bodyGeo, PARCEL_BODY_MATERIAL)
     bodyMesh.position.set(0, 0, 0)
     bodyMesh.castShadow = true
     bodyMesh.receiveShadow = true
@@ -48,12 +63,7 @@ export class Parcel3D extends RealObjectGroup {
     const tapeGeo = tapeAlongLong
       ? new THREE.BoxGeometry(width * 1.005, tapeT, tapeW)
       : new THREE.BoxGeometry(tapeW, tapeT, height * 1.005)
-    const tapeMaterial = new THREE.MeshStandardMaterial({
-      color: TAPE_COLOR,
-      metalness: 0.05,
-      roughness: 0.5
-    })
-    const tapeMesh = new THREE.Mesh(tapeGeo, tapeMaterial)
+    const tapeMesh = new THREE.Mesh(tapeGeo, PARCEL_TAPE_MATERIAL)
     tapeMesh.position.set(0, baseY + depth + tapeT / 2 - 0.01, 0)
     this.object3d.add(tapeMesh)
 
@@ -61,12 +71,7 @@ export class Parcel3D extends RealObjectGroup {
     const labelW = Math.min(width, height) * 0.35
     const labelH = labelW * 0.6
     const labelGeo = new THREE.BoxGeometry(labelW, depth * 0.005, labelH)
-    const labelMaterial = new THREE.MeshStandardMaterial({
-      color: LABEL_COLOR,
-      metalness: 0,
-      roughness: 0.4
-    })
-    const labelMesh = new THREE.Mesh(labelGeo, labelMaterial)
+    const labelMesh = new THREE.Mesh(labelGeo, PARCEL_LABEL_MATERIAL)
     // Position on top, off-center by ~25% of long axis
     if (tapeAlongLong) {
       labelMesh.position.set(width * 0.2, baseY + depth + depth * 0.0025, -height * 0.15)

package/src/parcel.ts

@@ -93,9 +93,10 @@ export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
   }
 
   /**
-   * Phase H — pickup contract. Parcel 은 위에서 vacuum gripper / suction cup 으로
-   * 집기 — Box 와 동일한 패턴이지만 cardboard 표면이라 더 큰 흡착 면 필요.
-   * tolerance 도 약간 완화 (cardboard 변형 가능성).
+   * Phase H — pickup contract. Parcel 의 pickup 방식:
+   *   - gripper (vacuum / suction): 위에서 흡착 — RobotArm
+   *   - agv-deck: AGV/Forklift 의 deck 위에 위에서 얹기 — 같은 top approach 지만
+   *     deck 자체가 운반체라 tolerance 더 완화
    */
   pickupFrames(): PickupFrame[] {
     const wp = getWorldPose(this)
@@ -109,11 +110,29 @@ export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
       topApproachFrame({
         carrierWorld: me,
         topY: parcelDepth,
-        approachDistance: 80,            // gripper hover 거리 (Box 보다 더 — vacuum 펼침)
+        approachDistance: 80,
         toolType: 'gripper',
-        tolerance: { positionMm: 10, angleDeg: 2 },  // cardboard 변형 감안
+        tolerance: { positionMm: 10, angleDeg: 2 },
         priority: 0,
         id: 'top-suction'
+      }),
+      topApproachFrame({
+        carrierWorld: me,
+        topY: parcelDepth,
+        approachDistance: 60,
+        toolType: 'agv-deck',
+        tolerance: { positionMm: 20, angleDeg: 5 },
+        priority: 1,
+        id: 'top-deck'
+      }),
+      topApproachFrame({
+        carrierWorld: me,
+        topY: parcelDepth,
+        approachDistance: 100,           // crane fork 가 cell 진입 hover
+        toolType: 'forklift-fork',
+        tolerance: { positionMm: 30, angleDeg: 5 },  // fork 적재 tolerance
+        priority: 2,                     // gripper/deck 다음
+        id: 'top-fork'
       })
     ]
   }

package/src/storage-cell.ts

@@ -157,6 +157,22 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
     }
     carrier[TRANSFER_SLOT_KEY] = this.cellId
     this.reparent(carrier, options)
+
+    // carrier.state.left/top/zPos 을 *cell-local center* 로 명시. 이전 holder
+    // 의 state (예: crane-local center) 가 그대로 남으면 *다음 pick 시
+    // moveTo(carrier) 의 target.center 계산이 *잘못된 좌표* 로 → 엉뚱한 위치
+    // 이동 결함. transient placement 'carried' 라 3D obj3d.position 영향 X,
+    // 2D render 와 moveTo 의 center 계산에만 영향.
+    const cw = numOr((this as any).state?.width, 0)
+    const ch = numOr((this as any).state?.height, 0)
+    const carrierW = numOr(carrier?.state?.width, 0)
+    const carrierH = numOr(carrier?.state?.height, 0)
+    carrier.setState?.({
+      left: (cw - carrierW) / 2,
+      top: (ch - carrierH) / 2,
+      zPos: 0
+    })
+
     this.trigger('transfer-received', {
       type: 'transfer-received',
       component: carrier,
@@ -209,16 +225,20 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
 
   /**
    * Return the 3D attach frame for carriers placed in this cell.
-   * Carriers are lifted by their own halfDepth so the bottom face
-   * rests at the cell's Y-center (which is levelHeight/2 above the beam).
+   *
+   * Center-origin convention: cell 의 *local origin* 은 cell 의 center
+   * (= levelHeight/2 above the shelf beam). carrier 의 *bottom face* 가 cell
+   * 의 *bottom* (= local Y -cellDepth/2) 에 닿도록 carrier center =
+   * -cellDepth/2 + carrierDepth/2.
    */
   attachPointFor(carrier: Component): AttachFrame | null {
     const root = this._realObject?.object3d
     if (!root) return null
     const carrierDepth = resolveCarrierDepth(carrier)
+    const cellDepth = numOr((this as any).state?.depth, 0)
     return {
       attach: root,
-      localPosition: { x: 0, y: carrierDepth / 2, z: 0 }
+      localPosition: { x: 0, y: -cellDepth / 2 + carrierDepth / 2, z: 0 }
     }
   }
 

package/src/storage-rack-3d.ts

@@ -34,10 +34,17 @@ export class StorageRack3D extends RealObjectGroup {
     const { width, height, depth = 3000 } = this.component.state
     const levels = Math.max(1, Math.floor((this.component.state.levels as number) || 4))
     const bays = Math.max(1, Math.floor((this.component.state.bays as number) || 5))
-
-    const baseY = -depth / 2
+    const shelfBase = Math.max(0, Math.min(
+      (this.component.state.shelfBaseHeight as number) || 0,
+      depth * 0.9
+    ))
+    const shelfZone = depth - shelfBase    // 실제 shelf 가 차지하는 Y
+
+    const baseY = -depth / 2               // rack 바닥 (3D Y 의 최저)
+    const shelfBaseY = baseY + shelfBase   // 첫 shelf 의 시작 (= level 1 의 바닥)
     const postW = Math.min(width / bays, height) * 0.06
-    const beamH = depth * 0.025
+    // beam 두께 = post 와 비슷 (산업 beam 이 post 보다 약간 두꺼움 — 1.2배)
+    const beamH = postW * 1.2
     const braceT = postW * 0.6
 
     const postMaterial = new THREE.MeshStandardMaterial({
@@ -75,11 +82,11 @@ export class StorageRack3D extends RealObjectGroup {
     this.object3d.add(postMesh)
 
     // ── Horizontal beams (front + back faces at each level) ──────────
-    // levels + 1 vertical positions (level 0 = ground, level N = top).
+    // shelf zone 안 levels+1 위치 (level 0 = shelfBase, level N = 천장).
     const beamGeos: THREE.BufferGeometry[] = []
     for (let lv = 0; lv <= levels; lv++) {
       const yFrac = lv / levels
-      const y = baseY + yFrac * depth - beamH / 2 + (lv === 0 ? beamH : 0)
+      const y = shelfBaseY + yFrac * shelfZone - beamH / 2 + (lv === 0 ? beamH : 0)
 
       for (const zSign of [-1, 1]) {
         const beam = new THREE.BoxGeometry(width, beamH, beamH)
@@ -97,7 +104,7 @@ export class StorageRack3D extends RealObjectGroup {
     // bay-tall cell. Visual signature of a load-bearing rack.
     const braceGeos: THREE.BufferGeometry[] = []
     const cellW = width / bays
-    const cellH = depth / levels
+    const cellH = shelfZone / levels                          // cell 높이 (shelf zone 안)
     const braceLen = Math.sqrt(cellW * cellW + cellH * cellH)
     const braceAngle = Math.atan2(cellH, cellW)
     const backZ = height / 2 - postW * 0.6
@@ -109,7 +116,7 @@ export class StorageRack3D extends RealObjectGroup {
       const cellCenterX = (bay - bays / 2 + 0.5) * cellW
 
       for (let lv = 0; lv < levels; lv++) {
-        const cellCenterY = baseY + (lv + 0.5) * cellH
+        const cellCenterY = shelfBaseY + (lv + 0.5) * cellH
 
         for (const sign of [-1, 1]) {
           const brace = new THREE.BoxGeometry(braceLen, braceT, braceT)
@@ -124,6 +131,37 @@ export class StorageRack3D extends RealObjectGroup {
       braceMesh.castShadow = true
       this.object3d.add(braceMesh)
     }
+
+    // ── Shelf planes (level 별 반투명 무볼륨 판) ────────────────────────────
+    // 각 level 의 *바닥 면* 에 plane — cell 위치 시각 인식. carrier 가 그 위
+    // 에 놓이는 *지지면*. 반투명.
+    //
+    // X-Z 넓이를 *frame 안쪽* 으로 줄여 mesh 겹침 자체 제거 (Z-fight 회피).
+    //   X: 양 옆 corner post 안쪽 (-postW 양쪽)
+    //   Z: 앞/뒤 beam 안쪽 (-beamH 양쪽)
+    const shelfW = Math.max(0, width - 2 * postW)
+    const shelfD = Math.max(0, height - 2 * beamH)
+    const shelfGeo = new THREE.PlaneGeometry(shelfW, shelfD)
+    shelfGeo.rotateX(-Math.PI / 2)  // X-Y plane → X-Z plane (= horizontal)
+    const shelfMaterial = new THREE.MeshStandardMaterial({
+      color: BEAM_COLOR,
+      metalness: 0.3,
+      roughness: 0.6,
+      transparent: true,
+      opacity: 0.25,
+      side: THREE.DoubleSide
+    })
+    for (let lv = 0; lv < levels; lv++) {
+      // shelf plane Y = 해당 level 의 *load beam top* 정확 일치 (cell 바닥 면).
+      //   beam center Y = shelfBaseY + yFrac*shelfZone - beamH/2 + (lv===0 ? beamH : 0)
+      //   beam top    Y = beam center + beamH/2 = shelfBaseY + yFrac*shelfZone + (lv===0 ? beamH : 0)
+      const yFrac = lv / levels
+      const y = shelfBaseY + yFrac * shelfZone + (lv === 0 ? beamH : 0)
+      const shelf = new THREE.Mesh(shelfGeo, shelfMaterial)
+      shelf.position.set(0, y, 0)
+      shelf.receiveShadow = true
+      this.object3d.add(shelf)
+    }
   }
 
   updateDimension() {}
@@ -134,7 +172,8 @@ export class StorageRack3D extends RealObjectGroup {
       'bays' in after ||
       'width' in after ||
       'height' in after ||
-      'depth' in after
+      'depth' in after ||
+      'shelfBaseHeight' in after
     ) {
       this.update()
       return

package/src/storage-rack.ts

@@ -22,6 +22,13 @@ export interface StorageRackState extends State {
   bays?: number
   levels?: number
 
+  /**
+   * Level 1 (첫 shelf) 의 *시작 높이* (mm, rack 의 3D Y 축, 바닥부터). 미명시 0
+   * (바닥 = 첫 shelf). 양수 시 그만큼 위로 올라가 stocker port / conveyor 같은
+   * 컴포넌트가 들어갈 *빈 공간* 확보. Frame uprights 는 바닥 ~ 천장 그대로.
+   */
+  shelfBaseHeight?: number
+
   // ── 디버그 ──
   debugCells?: boolean
 
@@ -45,6 +52,12 @@ const NATURE: ComponentNature = {
       label: 'bays',
       name: 'bays',
       placeholder: '# of horizontal bays (default 5)'
+    },
+    {
+      type: 'number',
+      label: 'shelf-base-height',
+      name: 'shelfBaseHeight',
+      placeholder: 'mm — level 1 시작 높이 (바닥부터). stocker port / conveyor 공간.'
     }
   ],
   help: 'scene/component/rack'
@@ -98,6 +111,50 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
     return []
   }
 
+  /**
+   * Model serialization — storage-cell 자식 자동 제외. cells 는 _buildCells() 가
+   * runtime 재생성 (added() 호출 시점). 저장하면 *redundant 모델 크기 폭증* +
+   * load 시 _buildCells 와 중복. rack 의 bays/levels/shelfBaseHeight 만 저장,
+   * cells 는 derive.
+   */
+  get hierarchy(): Record<string, any> {
+    const base = super.hierarchy as Record<string, any>
+    if (base?.components && Array.isArray(base.components)) {
+      base.components = base.components.filter(
+        (c: any) => c?.type !== 'storage-cell'
+      )
+      if (base.components.length === 0) delete base.components
+    }
+    return base
+  }
+
+  /**
+   * Lifecycle — RackCell child 자동 build. Rack 은 항상 cells 가짐.
+   */
+  added(parent: any): void {
+    super.added?.(parent)
+    this._buildCells()
+  }
+
+  /**
+   * Runtime — bays / levels 변경 시 RackCell child 재구성. _buildCells() 는
+   * 기존 cell 제거 후 재생성 (idempotent), 단 carrier 보유 시 결함 위험 —
+   * application 책임.
+   */
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>): void {
+    super.onchange?.(after, before)
+    if (
+      'bays' in after ||
+      'levels' in after ||
+      'shelfBaseHeight' in after ||
+      'width' in after ||
+      'height' in after ||
+      'depth' in after
+    ) {
+      this._buildCells()
+    }
+  }
+
   // ── CellContainer ─────────────────────────────────────────────────────────
 
   /**
@@ -116,6 +173,11 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
     const width = (this.state.width as number) || 1000
     const rackDepth = (this.state.depth as number) || 3000   // Y: floor→ceiling
     const rackHeight = (this.state.height as number) || 600  // Z: front→back
+    const shelfBase = Math.max(0, Math.min(
+      (this.state.shelfBaseHeight as number) || 0,
+      rackDepth * 0.9                                        // clamp ≤ 90% — 최소 shelf zone
+    ))
+    const shelfZone = rackDepth - shelfBase                  // 실제 shelf 가 차지하는 Y 영역
 
     return CellMap.grid({
       bays,
@@ -123,7 +185,8 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
       levels,
       bayWidth: width / bays,
       rowDepth: rackHeight,
-      levelHeight: rackDepth / levels
+      levelHeight: shelfZone / levels,
+      origin: { x: 0, y: shelfBase, z: 0 }                   // 첫 cell 의 Y = shelfBase
     })
   }
 
@@ -151,14 +214,35 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
       return
     }
 
+    // cell 의 state.left/top 는 *rack-local* (= parent-relative). things-scene
+    // 의 toScene() 이 parent chain 따라 board-absolute 변환 자동. 이전 board-
+    // absolute 설정은 *이중 변환* 결함 (rack.left 와 cell.left 둘 다 rack.transform
+    // 적용 받아 dx 폭증 → carriagePos clamp → carriage 안 움직임).
+    const rackWidth = (this.state.width as number) ?? 1000
+    const rackHeight = (this.state.height as number) ?? 100
+    const bays = Math.max(1, Math.floor((this.state.bays as number) || 5))
+    const bayWidth = rackWidth / bays
+
     const context = this._app
     for (const cell of this.cellMap.cells) {
+      // cell.bay / row 는 1-based. storage-rack 은 rows=1 라 모든 cell 이 같은 2D
+      // top. level (수직) 은 2D 표현 안 함 — Crane.engage 의 carriageHeight 가 처리.
+      const bayIdx = cell.bay - 1                // 0-based
+      const cellW = cell.size.width
+      const cellH = cell.size.depth              // 2D height = 3D Z (rack depth axis)
+      // rack-local 좌표 (rack 의 origin = rack.left/top, things-scene 의 자식 좌표)
+      const cellLeft = bayIdx * bayWidth + (bayWidth - cellW) / 2
+      const cellTop = (rackHeight - cellH) / 2
+
       const model = {
         type: 'storage-cell',
         cellId: cell.id,
-        width: cell.size.width,
-        height: cell.size.depth,  // 2D height = 3D Z depth
-        depth: cell.size.height   // 3D Y = level height
+        left: cellLeft,
+        top: cellTop,
+        width: cellW,
+        height: cellH,
+        depth: cell.size.height,                 // 3D Y = level height
+        zPos: cell.localPosition.y               // ← 3D Y 위치 (level 따라 다름)
       }
       const rackCell = new RackCellClass(model, context)
       this.addComponent(rackCell)
@@ -203,22 +287,38 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
   // ── 2D rendering ─────────────────────────────────────────────────────────
 
   /**
-   * 2D — top-down rectangle showing the rack footprint, with subdivisions
-   * suggesting the bay layout.
+   * 2D — top-down rectangle showing the rack footprint with bay subdivisions.
+   * 편집/배치 가 가능하도록 *명시 fill + stroke* — pipeline 분기 무관하게 항상
+   * 보임. fill 은 반투명 (carrier / cell 위 overlay).
    */
   render(ctx: CanvasRenderingContext2D) {
-    const { width, height, left, top } = this.state
+    const left = (this.state.left as number) ?? 0
+    const top = (this.state.top as number) ?? 0
+    const width = (this.state.width as number) ?? 400
+    const height = (this.state.height as number) ?? 100
     const bays = Math.max(1, Math.floor((this.state.bays as number) || 5))
+    const fill = (this.state.fillStyle as string) || '#a0a0a8'
+    const stroke = (this.state.strokeStyle as string) || '#555'
+    const lineWidth = (this.state.lineWidth as number) || 1
+
+    // Fill (반투명)
+    ctx.save()
+    ctx.fillStyle = fill
+    ctx.globalAlpha = 0.2
+    ctx.fillRect(left, top, width, height)
+    ctx.restore()
 
+    // Stroke — outer + bay subdivisions
+    ctx.strokeStyle = stroke
+    ctx.lineWidth = lineWidth
+    ctx.strokeRect(left, top, width, height)
     ctx.beginPath()
-    // Outer rectangle
-    ctx.rect(left, top, width, height)
-    // Bay subdivisions (vertical lines)
     for (let i = 1; i < bays; i++) {
       const x = left + (width * i) / bays
       ctx.moveTo(x, top)
       ctx.lineTo(x, top + height)
     }
+    ctx.stroke()
   }
 
   get fillStyle() {

package/test/test-cell-position.ts

@@ -0,0 +1,105 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * 정밀 진단 — Rack 의 _buildCells 가 cell 의 board-absolute state.left/top
+ * 정확히 설정하는지 + Crane.moveTo 의 railLocalX 계산 정확한지.
+ */
+
+import 'should'
+import { readFileSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function readSrc(rel: string): string {
+  return readFileSync(resolve(__dirname, rel), 'utf-8')
+}
+
+// ── Test 1: storage-rack._buildCells 의 cell 좌표 계산 검증 ─────────────────
+
+describe('storage-rack._buildCells: cell 의 rack-local state.left/top', () => {
+  it('coordinate formula — rack-local (toScene 이 parent transform 자동)', () => {
+    // rack-local: cell.state.left = bayIdx * bayWidth + (bayWidth - cellW)/2
+    // things-scene 의 toScene() 이 parent (rack) 의 transform 자동 적용 →
+    // board-absolute 변환. rackLeft 더하면 *이중 변환* 결함.
+    const src = readSrc('../src/storage-rack.ts')
+    src.should.match(/cellLeft = bayIdx \* bayWidth/)
+    src.should.not.match(/cellLeft = rackLeft/)   // rackLeft 더하면 안 됨
+    src.should.match(/left: cellLeft/)
+    src.should.match(/top: cellTop/)
+  })
+
+  it('cell.size.width 는 cellMap.grid 의 bayWidth (= rack.width / bays)', () => {
+    // 즉 (bayWidth - cellW) / 2 = 0 → bay 별 cellLeft = rackLeft + bayIdx * bayWidth
+    const src = readSrc('../src/storage-rack.ts')
+    src.should.match(/bayWidth = rackWidth \/ bays/)
+  })
+
+  it('storage-rack 은 rows=1 hardcoded', () => {
+    const src = readSrc('../src/storage-rack.ts')
+    src.should.match(/rows: 1/)
+  })
+})
+
+// ── Test 2: Crane.moveTo 의 railLocalX 계산 ─────────────────────────────
+
+describe('Crane.moveTo: target.center 의 carrier 위치 → carriagePosition', () => {
+  it('rotation=0 + crane.center.x = 200, target.center.x = 360 → railLocalX = 160', () => {
+    // crane.left=0, width=400 → crane.center.x = 200
+    // target (cell) 의 center.x = 360
+    // dx = 360 - 200 = 160, dy = 0
+    // rotation = 0 → cos=1, sin=0
+    // railLocalX = 160 * 1 + 0 * 0 = 160
+    // carriagePosition = clamp(160 + 400/2, [cw/2, width-cw/2]) = clamp(360, ...) → 360
+    const rotation = 0
+    const cos = Math.cos(rotation)
+    const sin = Math.sin(rotation)
+    const dx = 360 - 200
+    const dy = 0
+    const railLocalX = dx * cos + dy * sin
+    const W = 400
+    const cw = 40
+    const minPos = cw / 2
+    const maxPos = W - cw / 2
+    const carriagePos = Math.max(minPos, Math.min(maxPos, railLocalX + W / 2))
+    carriagePos.should.equal(360)
+  })
+
+  it('clamp 적용 — target 이 rail 범위 밖 (target.center.x = 1000, crane.center.x = 200)', () => {
+    const dx = 1000 - 200   // 800 — 매우 큼
+    const dy = 0
+    const railLocalX = dx * 1 + dy * 0  // 800
+    const W = 400
+    const cw = 40
+    const minPos = cw / 2     // 20
+    const maxPos = W - cw / 2 // 380
+    const carriagePos = Math.max(minPos, Math.min(maxPos, railLocalX + W / 2))
+    carriagePos.should.equal(380)   // clamp to maxPos
+  })
+
+  it('clamp 적용 — target 이 rail 왼쪽 밖 (target.center.x = -500, crane.center.x = 200)', () => {
+    const dx = -500 - 200   // -700
+    const dy = 0
+    const railLocalX = dx * 1 + dy * 0  // -700
+    const W = 400
+    const cw = 40
+    const carriagePos = Math.max(cw / 2, Math.min(W - cw / 2, railLocalX + W / 2))
+    carriagePos.should.equal(20)   // clamp to minPos
+  })
+
+  it('rotation=π/2 (90도) — Y projection 사용', () => {
+    // rack 이 사선 90도 — crane 의 rail 도 90도. target 의 Y 좌표만 사용.
+    const rotation = Math.PI / 2
+    const cos = Math.cos(rotation)  // ≈ 0
+    const sin = Math.sin(rotation)  // = 1
+    const dx = 0
+    const dy = 160
+    const railLocalX = dx * cos + dy * sin  // ≈ 160
+    const W = 400
+    const cw = 40
+    const carriagePos = Math.max(cw / 2, Math.min(W - cw / 2, railLocalX + W / 2))
+    carriagePos.should.be.approximately(360, 0.001)
+  })
+})