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

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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.42](https://github.com/things-scene/operato-scene/compare/v10.0.0-beta.41...v10.0.0-beta.42) (2026-05-21)
+
+
+### :rocket: New Features
+
+* **storage,scene-base:** Plan A slot API + pickAndPlace 좌표 컨벤션 수정 ([fab1970](https://github.com/things-scene/operato-scene/commit/fab1970f54863ddb7c0b17646a313aad648fd031))
+* **storage:** batched 시각화 + cell-anchored popup + 클릭 라우팅 ([3acde61](https://github.com/things-scene/operato-scene/commit/3acde61be2647b41a3e550e3ee115736af0922d6))
+* **storage:** RackGrid 3D frame 정밀화 + shared materials + hideHorizontalFrame ([8e65763](https://github.com/things-scene/operato-scene/commit/8e65763fedffea3b7350855ebb9b09be8289f597))
+* **storage:** RackGrid 완성 — bay 그리드 + light cell-component + Plan A stock ([79ee9a6](https://github.com/things-scene/operato-scene/commit/79ee9a6da852af4834fe0ac58bcba2030aeb2462)), closes [#888](https://github.com/things-scene/operato-scene/issues/888)
+
+
+
+## [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/MIGRATION-plan-a-slot-api.md

@@ -0,0 +1,266 @@
+# StorageRack Plan A — Slot API 마이그레이션 가이드
+
+## TL;DR
+
+Application 코드의 `rack.cellComponent(...).carrier` 류 패턴을 **`rack.obtainCarrier(cellId)` + `rack.slotTargetAt(cellId)`** 로 바꾸면 다음이 해결됨:
+
+- 클릭/pickAndPlace 시 InstancedMesh stock 위에 carrier 가 겹쳐 그려지는 Z-fighting
+- 같은 cell 에 반복 작업 시 carrier 가 누적되어 박스가 늘어나는 회귀
+- pickAndPlace 후 state.data 와 시각화 사이의 부정합
+- batched rack 의 메모리 낭비 (10000-cell rack 의 ~98% 절감)
+
+기존 API (`cellComponent`, `_buildCells`) 는 유지 — 점진 마이그레이션 가능.
+
+---
+
+## 모델 변화: "Matrix 안 = 데이터, 밖 = Component"
+
+```
+이전 모델:
+  Rack
+   └─ RackCell (10000 개 영구 Component)
+        └─ Carrier (재고가 있을 때마다 영구 Component)
+
+새 모델 (Plan A):
+  Rack
+   └─ state.data: [{cellId, sku, qty, ...}, ...]   ← "매트릭스 안"
+   └─ (transit 중 일시적으로 carrier child)         ← "밖"
+
+  경계 통과 시:
+    obtainCarrier(cellId)  → 데이터 → 컴포넌트 (transient materialize)
+    receiveAt(cellId, c)   → 컴포넌트 → 데이터 (atomic absorb + dispose)
+```
+
+**불변식**: 동일 cellId 가 state.data 의 record 와 rack-child carrier 양쪽에 동시 존재하지 않음.
+
+---
+
+## API 매핑
+
+### Pick (carrier 를 cell 에서 빼냄)
+
+```ts
+// ── Before ─────────────────────────────────────────────
+const cell = rack.cellComponent('A-0-0')
+const carrier = cell.carrier   // ← side-effect: state.data 의 record 로부터 자동 materialize
+                               //   (그러나 record 는 안 빠짐 → Z-fight, 누적)
+await crane.pick(carrier)
+
+// ── After ──────────────────────────────────────────────
+const carrier = rack.obtainCarrier('A-0-0')
+if (!carrier) {
+  // cell 에 record 도 child 도 없음 — 빈 cell.
+  return
+}
+await crane.pick(carrier)
+// state.data 에서 그 record 가 atomic 하게 빠지고, InstancedMesh 가 그 자리 더 이상
+// 안 그림. carrier 는 transient → 곧 crane child 가 됨.
+```
+
+### Place (carrier 를 cell 에 넣음)
+
+```ts
+// ── Before ─────────────────────────────────────────────
+const destCell = rack.cellComponent('B-0-0')
+await crane.place(carrier, destCell)
+// carrier 는 destCell 의 child 로 영구 존재 → 다음 pickAndPlace 때 또 materialize
+// 시도되어 누적 회귀.
+
+// ── After ──────────────────────────────────────────────
+await crane.place(carrier, rack.slotTargetAt('B-0-0'))
+// SlotTarget.receive → rack.receiveAt → carrier dispose + state.data 에 record push.
+// 결과: rack 의 자식 트리는 깨끗, state.data 에 record 만 추가. InstancedMesh 가
+// 자동으로 그 자리에 instance 그림. 누적 없음.
+```
+
+### pickAndPlace (한 줄)
+
+```ts
+// ── Before ─────────────────────────────────────────────
+await crane.pickAndPlace(
+  rack.cellComponent('A-0-0').carrier,
+  rack.cellComponent('B-0-0')
+)
+
+// ── After ──────────────────────────────────────────────
+const carrier = rack.obtainCarrier('A-0-0')
+if (!carrier) return
+await crane.pickAndPlace(carrier, rack.slotTargetAt('B-0-0'))
+```
+
+### 다른 rack 사이 이동
+
+```ts
+// ── After ──────────────────────────────────────────────
+const carrier = sourceRack.obtainCarrier('A-0-0')
+if (!carrier) return
+await crane.pickAndPlace(carrier, destRack.slotTargetAt('B-0-0'))
+```
+
+### Rack → 자유공간 (model-layer 의 carrier holder)
+
+```ts
+// ── After ──────────────────────────────────────────────
+const carrier = rack.obtainCarrier('A-0-0')
+if (!carrier) return
+await crane.pickAndPlace(carrier, freeSpaceHolder)
+// freeSpaceHolder 는 SlottedHolder 아님 → 흡수 안 일어남.
+// carrier 가 freeSpaceHolder 의 child Component 로 영구 존재. ("매트릭스 밖")
+```
+
+### 자유공간 → Rack
+
+```ts
+// ── After ──────────────────────────────────────────────
+const carrier = root.findById('parcel-123')   // model-layer 의 free carrier
+await crane.pickAndPlace(carrier, rack.slotTargetAt('A-0-0'))
+// rack.receiveAt → carrier dispose + record push. "매트릭스 진입".
+```
+
+---
+
+## 조회 / 검사
+
+### 점유 여부
+
+```ts
+// ── Before ─────────────────────────────────────────────
+const cell = rack.cellComponent('A-0-0')
+const isOccupied = !!cell?.carrier   // side-effect 동반 — 빈 cell 에 carrier 만들 가능성
+
+// ── After ──────────────────────────────────────────────
+const isOccupied = rack.hasCarrierAt('A-0-0')   // 순수 검사, side-effect 없음
+const canPlace   = rack.canReceiveAt('A-0-0')
+```
+
+### 모든 점유 cell 의 record
+
+```ts
+// ── Before ─────────────────────────────────────────────
+// rack 의 모든 cell 컴포넌트 순회 + 각 cell.carrier 검사 (느림)
+const occupied = rack.components
+  .filter(c => c.state?.type === 'storage-cell')
+  .map(c => c.carrier?.state)
+  .filter(Boolean)
+
+// ── After ──────────────────────────────────────────────
+const occupied = rack.records   // state.data 의 readonly view
+```
+
+### 특정 record 의 데이터
+
+```ts
+// ── Before ─────────────────────────────────────────────
+const data = rack.cellComponent('A-0-0')?.carrier?.state   // side-effect 위험
+
+// ── After ──────────────────────────────────────────────
+const record = rack.records.find(r => r.cellId === 'A-0-0')
+```
+
+---
+
+## Type guard
+
+```ts
+import { isSlottedHolder } from '@operato/scene-base'
+
+// 일반화된 target 처리 (rack, table, future slot holders)
+function moveTo(target: any, carrier: Component, cellId?: string) {
+  if (cellId && isSlottedHolder(target)) {
+    return crane.place(carrier, target.slotTargetAt(cellId))
+  }
+  return crane.place(carrier, target)
+}
+```
+
+---
+
+## 메모리 최적화 — eagerCells
+
+대용량 batched rack (예: 10000 cells) 에서는 RackCell Component 의 eager build 가 메모리 부담:
+
+```ts
+// state.data 가 있으면 자동으로 eagerCells = false (메모리 절약)
+const rack = new Rack({ type: 'storage-rack', bays: 100, levels: 100, data: [...] })
+
+// 명시 옵션:
+rack.setState('eagerCells', false)   // 강제 skip (Plan A 만 사용)
+rack.setState('eagerCells', true)    // 강제 eager (legacy 호환)
+```
+
+기본 정책:
+- `state.data` 있음 → `eagerCells = false` (auto, batched)
+- `state.data` 없음 → `eagerCells = true` (auto, legacy non-batched)
+- `state.eagerCells` 명시 시 그대로 따름
+
+---
+
+## 마이그레이션 단계별 권장
+
+### Phase 1 — 신규 코드는 Plan A
+- 새로 작성하는 application 로직은 `obtainCarrier` / `slotTargetAt` 사용
+- `cellComponent` 호출 새로 추가하지 않음
+
+### Phase 2 — 기존 호출처 점검
+```bash
+# application 코드에서 cellComponent 사용처 찾기
+grep -rn "cellComponent\b\|\.carrier\b" src/ apps/
+```
+각 호출처:
+- 단순 lookup (점유 검사 등) → `hasCarrierAt` / `canReceiveAt` 로 교체
+- carrier 추출 → `obtainCarrier` 로 교체
+- destination 으로 사용 → `slotTargetAt` 로 교체
+
+### Phase 3 — 회귀 검증
+- batched rack 의 *반복 pickAndPlace* 시 Z-fight / 누적 없음 확인
+- 동일 cell 클릭으로 popup 띄우기 반복 → 박스 시각화 정상 유지 확인
+- pickAndPlace 후 state.data 가 source 에서 빠지고 dest 로 갱신 확인
+
+### Phase 4 — 메모리 검증 (대용량 rack)
+- 1만+ cell rack 에서 eagerCells 미설정 시 자동 batched 모드 진입 확인
+- JS heap 점유량이 기대치 (instance + record 만) 안 인지 측정
+
+### Phase 5 — Legacy API 제거 (선택)
+- application 전체가 Plan A 로 마이그레이션 완료되면, 향후 storage-rack 의
+  `cellComponent` / `_addCarrierToCell` / `_materializeCell` 메소드 제거 가능
+- breaking change 라 별도 major 버전에서
+
+---
+
+## 자주 묻는 질문
+
+### Q: 기존 cellComponent 호출이 그대로 동작하나?
+A: 네. 후방 호환 유지. 단 *batched 모드 (state.data 있음) 에서* `cellComponent('A').carrier` 가 record 로부터 carrier 를 materialize 하는 부수효과는 *제거되지 않았음* — Z-fight 회귀의 원인. Plan A 로 마이그레이션 필요.
+
+### Q: 시뮬레이션 (Crane 이 박스를 옮기는 데모) 도 batched 로 가능?
+A: 거의 모두 가능. Plan A 의 obtainCarrier → transient materialize → crane 동행 → receiveAt → absorb 흐름이 *눈에 안 보이게* 처리. 박스 식별성 (어느 박스가 어디로 갔는지) 은 state.data record 의 데이터 자체가 보존.
+
+### Q: 박스가 자체 행위 (애니메이션, 이벤트 핸들러, child component) 를 가지면?
+A: 그땐 batched 모드 부적합. record 로 표현 불가능한 정보가 있는 경우 — `state.data` 안 쓰고 carrier 를 *명시적으로 추가* 해 영구 child 로 둠 (= 매트릭스 밖). 이 carrier 는 transient 가 아닌 영구.
+
+### Q: 두 모드 혼합 가능?
+A: 가능. 같은 rack 안에 state.data 의 record 9000개 + 영구 carrier child 10개 공존 OK. 불변식 ("같은 cellId 가 양쪽에 동시 존재 X") 만 application 이 지키면 됨.
+
+### Q: SlotTarget 의 lifecycle 은? 매 클릭마다 새로 만들면 메모리 누수?
+A: SlotTarget 자체는 가벼운 wrapper — 자체 Object3D 없음. `_realObject.object3d` 는 holder 의 *singleton anchor object3d* (lazy 생성, cellId 별 캐시) 를 참조. 즉 SlotTarget 객체는 GC 자유, 실제 3D 자원은 holder 가 관리.
+
+### Q: record 에 어떤 필드를 포함시킬 수 있나?
+A: `cellId` (필수) + 자유 application 필드 (sku, qty, status, color, ...). carrier 가 materialize 될 때 record 의 모든 필드가 carrier.state 로 spread. carrier 가 absorb 될 때 `recordFromCarrier(carrier, cellId)` 가 *transform 관련 필드 제외* 한 모든 state 를 record 로 환원 — application 이 override 로 추가 인코딩 가능.
+
+### Q: 양방향 sync — 외부 (WMS) 에서 state.data 를 갱신하면?
+A: `setState('data', newData)` → `onchangeData` → `rebuildStockMesh` 자동. InstancedMesh 가 새 데이터 반영. 즉 외부 데이터 → 시각화 push 그대로 작동.
+
+---
+
+## 회귀 케이스 체크리스트
+
+마이그레이션 완료 후 다음을 확인:
+
+- [ ] Stock instance 클릭 → popup 정확한 cell anchor 위치
+- [ ] 다른 cell 클릭 시 popup *이동* (이전 cell 의 stock 표면 정상 유지, Z-fight 없음)
+- [ ] pickAndPlace cell → cell 후 source cell 에 박스 없음 + dest cell 에 instance 표시
+- [ ] 같은 cell 에 반복 pickAndPlace 실행 → 박스 누적 없음
+- [ ] pickAndPlace 도중 텔레포트 회귀 없음 (carrier 가 moveTo 단계 동안 source 에 머묾)
+- [ ] WMS state.data push → InstancedMesh 즉시 반영
+- [ ] 다른 rack 사이 이동 — source state.data 빠짐, dest state.data 추가
+- [ ] 자유공간 ↔ rack 양방향 이동 정상

package/PLAN-A-rack-as-slot-holder.md

@@ -0,0 +1,164 @@
+# Plan A — Rack as Slot Holder (LoopSorter-style)
+
+## 동기
+
+현재 StorageRack 은 *각 cell 을 RackCell Component 로 eager build* (10000 cell rack 이면 10000 Component + 10000 object3d). 이 비대한 구조가:
+
+- batched 시각화 (InstancedMesh) 의 메모리 이점 무력화
+- pickAndPlace 시 `cellComponent.carrier` 의 lazy materialize 가 *진짜 carrier Component* 를 만들어 InstancedMesh stock 과 Z-fight
+- materialize 후 carrier 가 영구 존재하면서 (1) 누적 (2) state.data 와 불일치
+
+LoopSorter 는 이미 *slot-as-index* 패턴으로 같은 종류 문제를 해결했음 — sorter 가 holder, slot 은 index, carrier 는 sorter 의 직접 자식 (proxy group attach). **Rack 도 그 패턴 채용**.
+
+## 변경 후 모델
+
+```
+Rack (CarrierHolder)
+├── carrier (state.cellId = 'A-0-0')   ← real Component, 직접 child
+├── carrier (state.cellId = 'B-0-0')   ← real Component, 직접 child
+├── state.data: [{cellId: 'C-0-0', ...}, ...]   ← 나머지는 record only (InstancedMesh)
+└── 3D: InstancedMesh (state.data) + 각 carrier 의 mesh (직접 child)
+```
+
+- *RackCell Component 제거* (또는 debug-only)
+- Carrier 는 Rack 의 직접 자식. `state.cellId` 이 slot 위치.
+- state.data 와 carrier-children 은 *상호 배타* — 같은 cellId 가 양쪽에 있을 수 없음.
+- InstancedMesh 는 state.data 의 record 만 렌더 — 자동으로 carrier 있는 cell 은 제외 (record 가 거기 없음).
+
+## API
+
+### Rack 의 새 메소드 (LoopSorter 의 reserveAtJoinPoint 와 대응)
+
+```ts
+class Rack {
+  // ── Slot-aware Pickable source ────────────────────────────────────────
+  
+  /** state.data 에 record 가 있는 점유된 slot 인지 또는 child carrier 가 있는지 */
+  hasCarrierAt(cellId: string): boolean
+
+  /** record/carrier 를 carrier Component 로 보장. 이미 child 면 그대로 반환. */
+  obtainCarrier(cellId: string): Component | null
+  // 동작:
+  //   1. carrier-children 에서 state.cellId === cellId 찾기 → 있으면 return
+  //   2. state.data 에서 record 찾기 → 있으면 transient carrier materialize
+  //      (Rack 의 직접 자식으로 addComponent, state.data 에서 record 제거)
+  //   3. 둘 다 없으면 null
+
+  // ── Slot-aware CarrierHolder destination ──────────────────────────────
+  
+  /** 특정 cell 로의 placement 가 가능한가 (slot 비어있나) */
+  canReceiveAt(cellId: string, carrier?: Component): boolean
+
+  /** Mover.place 가 호출. carrier 를 slot 에 흡수 */
+  async receiveAt(cellId: string, carrier: Component, options?): Promise<void>
+  // 동작:
+  //   1. carrier 를 rack 의 자식으로 reparent (carrier.state.cellId = cellId 로 set)
+  //   2. 이후 absorb 정책 적용:
+  //        - 'auto' (default, batched-rack): carrier 를 dispose + state.data 에 record push
+  //          → 다시 record-only 상태로 환원 (InstancedMesh 가 렌더)
+  //        - 'keep': carrier 를 그대로 child 로 유지 (non-batched 모드)
+  //      정책 결정: state.absorbPolicy 또는 carrier 의 transient flag
+
+  // ── 3D 위치 정보 (Mover/Crane 의 target 위치 계산용) ───────────────────
+  
+  /** cell 의 world-space pose — Mover.moveTo / Crane.engage 가 사용 */
+  getCellPose(cellId: string): { position: Vector3, rotation: Quaternion }
+}
+```
+
+### 호출 패턴
+
+**Pick from rack slot**:
+```ts
+const carrier = rack.obtainCarrier('A-0-0')   // batched 면 materialize, 아니면 기존 child
+if (!carrier) throw new Error('no stock at A-0-0')
+
+await crane.pickAndPlace(carrier, rack.slotTargetAt('B-0-0'))
+```
+
+**`rack.slotTargetAt(cellId)`** — 가벼운 SlotTarget wrapper:
+```ts
+class SlotTarget {
+  constructor(public rack: Rack, public cellId: string) {}
+
+  // Mover/Crane 가 다음 인터페이스 사용:
+  get center(): {x, y}               // → rack.getCellPose(cellId) 의 2D 투영
+  get state(): { cellId, ... }       // Crane.engage 의 target pose 추출용
+  get _realObject() { ... }          // proxy object3d 반환 (transient)
+  get parent() { return this.rack.parent }
+
+  // CarrierHolder 컨트랙
+  canReceive(carrier) { return this.rack.canReceiveAt(this.cellId, carrier) }
+  async receive(carrier, options) { return this.rack.receiveAt(this.cellId, carrier, options) }
+}
+```
+
+SlotTarget 은 *호출 시점에만 생성되는 가벼운 wrapper* — 영구 Component 아님. 의미: "rack 위에 위치한 slot 의 carriable contract 진입점". RackCell 의 역할을 transient 로 대체.
+
+### Mover/Crane 의 변경
+
+이상적으로 *최소 변경*. SlotTarget 이 기존 Mover/Crane 가 부르는 인터페이스 (center / state / _realObject / canReceive / receive) 를 만족하면 Mover/Crane 코드 자체는 안 건드려도 됨.
+
+확인 필요:
+- `Crane.engage(target, kind)` 의 `getWorldPose(target)` — target 의 `_realObject.object3d` 의 matrixWorld 사용. SlotTarget 의 proxy object3d 가 올바른 위치/회전을 가지면 OK.
+- `Mover.computeTarget(carrier, 'pick')` / `computeTarget(holder, 'place', carrier)` — target 의 center/bounds 사용.
+
+→ SlotTarget 의 proxy object3d 를 *rack.object3d 의 자식* 으로 두고 cellId 위치에 배치. matrixWorld 자동 계산.
+
+## state.data 와 carrier child 의 관계
+
+| 상황                       | state.data    | carrier child | InstancedMesh |
+|---------------------------|---------------|---------------|--------------|
+| 빈 cell                    | record 없음    | child 없음    | 없음          |
+| 점유 (batched 표시중)       | record 있음   | child 없음    | instance 표시 |
+| Pick 진행 중               | record 없음   | crane child   | 없음          |
+| Place 직후 (absorb 전)     | record 없음   | rack child    | 없음          |
+| Absorb 완료                | record 있음   | child 없음    | instance 표시 |
+
+핵심: *동일 cellId 가 record + child 양쪽에 동시 존재하지 않음*. 변환 (materialize / absorb) 시 atomic 하게 한쪽만.
+
+## 단계별 작업
+
+### Step 1: Rack 에 새 슬롯 API 추가 (RackCell 제거 *없이*)
+- `obtainCarrier`, `canReceiveAt`, `receiveAt`, `getCellPose` 추가
+- `slotTargetAt(cellId)` 추가
+- 기존 `cellComponent` / `_buildCells` 는 그대로 (호환)
+- 변경 영향: 새 API 만 사용하는 application 코드는 새 idiom 으로 작동
+
+### Step 2: Materialize/Absorb 흐름 검증
+- 단위 테스트:
+  - `obtainCarrier('A')` → state.data 에서 record 빠짐 + carrier 가 rack 의 자식
+  - `receiveAt('B', carrier)` → carrier dispose + state.data 에 record push
+  - InstancedMesh rebuild 가 정확히 반영
+- pickAndPlace 통합 테스트:
+  - `crane.pickAndPlace(rack.obtainCarrier('A'), rack.slotTargetAt('B'))` → state.data 의 A 빠지고 B 추가, Z-fight 없음, 누적 없음
+
+### Step 3: SlotTarget 의 Mover/Crane 호환성 검증
+- Crane.engage 가 SlotTarget.targetPose 로 fork extension 정확히 계산
+- Mover.moveTo 가 SlotTarget.center 로 정확히 이동
+- 양 끝점 모두 SlotTarget 인 경우 (rack→rack) 양방향 정상
+
+### Step 4: RackCell 제거 (또는 debug-only flag 화)
+- `_buildCells()` 호출 제거 (added() 에서)
+- `cellComponent()` 도 새 obtainCarrier 로 위임 (호환 wrapper)
+- 10000-cell rack 메모리 검증
+
+### Step 5: 응용 코드 마이그레이션
+- things-factory / operato-mms 의 기존 호출 코드 (`rack.cellComponent('A').carrier` 등) 새 API 로 갱신
+- 마이그레이션 가이드 작성
+
+## 위험 / 미해결 질문
+
+1. **SlotTarget 의 `_realObject` 가 충분한가** — Crane.engage 의 getWorldPose / solveForkExtensionForLocalZ 가 SlotTarget 의 proxy object3d 로 정상 동작하는지 실측 필요. RackCell 의 StorageCell3D 가 추가로 제공하던 게 있나 검증.
+2. **non-batched (real-time WMS 모니터링) 모드 호환성** — `state.absorbPolicy = 'keep'` 으로 처리 가능하나 application 측 결정 필요.
+3. **Mover.computeTarget 인터페이스** — SlotTarget 의 `state`/`center`/`bounds` 가 기존과 호환되는지.
+4. **테스트 회귀** — 현재 114 통과 테스트 중 RackCell 의존 테스트 다수. 단계별 마이그레이션 필요.
+
+## 일정 추정
+
+- Step 1-2: 0.5 day (작성 + 단위 테스트)
+- Step 3: 0.5 day (Crane 호환 검증, 필요 시 SlotTarget proxy object3d 정렬 보완)
+- Step 4: 0.5 day (eager build 제거, 회귀 fix)
+- Step 5: 별도 (application 코드 위치에 따라 0.5-1 day)
+
+총 ~2 day 추정. Step 1-3 마무리되면 batched pickAndPlace UX 정상화 완료. Step 4-5 는 효율/일관성 마무리.

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;
 }