@operato/scene-storage 10.0.0-beta.43 → 10.0.0-beta.46

package/src/rack-grid.ts

@@ -36,8 +36,10 @@ import {
 import type { State } from '@hatiolab/things-scene'
 import * as THREE from 'three'
 import {
+  CarrierHolder,
   Placeable,
   SlotTarget,
+  type AttachFrame,
   type Alignment,
   type Heights,
   type PlacementArchetype,
@@ -57,6 +59,13 @@ function _nextCellRefid(): number {
   return _cellRefidCounter++
 }
 
+// Transient carrier (obtainCarrier 가 materialize 한 컴포넌트) 용 refid. 모델 안
+// 다른 컴포넌트와 겹치지 않도록 별도 대역.
+let _carrierRefidCounter = 200_000_000
+function _nextCarrierRefid(): number {
+  return _carrierRefidCounter++
+}
+
 function buildNewCell(app: ApplicationContext) {
   const refid = _nextCellRefid()
   const m: any = Model.compile(
@@ -78,7 +87,42 @@ function buildNewCell(app: ApplicationContext) {
   return m
 }
 
-const TABLE_LAYOUT = Layout.get('table')
+const TABLE_LAYOUT: any = Layout.get('table')
+
+/**
+ * RackGrid 의 *layout-aware children* — `rack-grid-cell` (= 데이타-proxy 시각
+ * 자식) 만 Table 분배 대상. obtainCarrier 가 만든 *실물 carrier* (Carriable —
+ * Parcel/Pallet 등) 는 *transient* 라 layout 분배 외. Table.reflow 가 *carrier
+ * 도 cells 다음 인덱스로 분배* 하면 `heights[rackRows] = undefined` → carrier.
+ * state.height = NaN → BoxGeometry NaN → invisible. 그 회귀 방지.
+ */
+const RACK_GRID_LAYOUT: any = {
+  reflow(container: any) {
+    const all = container.components ?? []
+    const cellsOnly = all.filter((c: any) => c?.state?.type === 'rack-grid-cell')
+    if (cellsOnly.length === all.length) {
+      return TABLE_LAYOUT.reflow.call(TABLE_LAYOUT, container)
+    }
+    // Carrier 자식이 있는 경우 — container.components 를 *cells only* 로
+    // 임시 교체 후 base reflow. base 가 idx 기반 분배 시 carrier 가 *out of
+    // range* 인덱스에 안 오게.
+    const desc = Object.getOwnPropertyDescriptor(container, 'components')
+    Object.defineProperty(container, 'components', { value: cellsOnly, configurable: true, writable: true })
+    try {
+      TABLE_LAYOUT.reflow.call(TABLE_LAYOUT, container)
+    } finally {
+      if (desc) Object.defineProperty(container, 'components', desc)
+      else delete container.components
+    }
+  },
+  capturables(container: any) { return TABLE_LAYOUT.capturables(container) },
+  drawables(container: any) { return TABLE_LAYOUT.drawables(container) },
+  isStuck(component: any) { return TABLE_LAYOUT.isStuck?.(component) ?? true },
+  keyNavigate(container: any, component: any, e: any) {
+    return TABLE_LAYOUT.keyNavigate?.(container, component, e)
+  },
+  joinType: TABLE_LAYOUT.joinType
+}
 
 function arrayOf(value: number, size: number): number[] {
   const arr: number[] = []
@@ -223,7 +267,7 @@ export interface RackGridState extends State {
 
 @sceneComponent('rack-grid')
 export default class RackGrid
-  extends Placeable(ContainerAbstract)
+  extends CarrierHolder(Placeable(ContainerAbstract))
   implements SlottedHolder
 {
   declare state: RackGridState
@@ -665,12 +709,114 @@ export default class RackGrid
    * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
    */
   isBayEmpty(col: number, row: number = 0): boolean {
+    // cell.state.isEmpty 가 *명시 true* 일 때만 우선. false / undefined 면 fallback
+    // 으로 cellOverrides 확인. _buildCells 가 모든 bay 에 cell 자동 생성 + default
+    // isEmpty=false 라서, "cell 객체 존재 만으로 cellOverrides 차단" 시 사용자가
+    // cellOverrides 만 설정한 모델에서 isEmpty 효과 0 회귀.
     const cell = this.cellAt(col, row)
-    if (cell) return !!cell.state.isEmpty
+    if (cell?.state?.isEmpty === true) return true
     const posKey = `${col}-${row}`
     return !!this.cellOverrides[posKey]?.isEmpty
   }
 
+  /**
+   * 모든 slot id 의 목록. columns × rackRows × shelves 조합. *isEmpty bay 는 제외*
+   * (물리적으로 없는 위치). SlottedHolder.slotIds — capability 기반 enumeration
+   * entry point.
+   */
+  slotIds(): ReadonlyArray<string> {
+    const ids: string[] = []
+    const cols = this.columns
+    const rows = this.rackRows
+    const shelves = this.shelves
+    for (let col = 0; col < cols; col++) {
+      for (let row = 0; row < rows; row++) {
+        if (this.isBayEmpty(col, row)) continue   // 물리적 없음 — 제외
+        for (let shelf = 0; shelf < shelves; shelf++) {
+          ids.push(`${col}-${row}-${shelf}`)
+        }
+      }
+    }
+    return ids
+  }
+
+  /**
+   * 점유된 slot 의 id 목록 — state.data record + child *carrier* 둘 다.
+   *
+   * 중요: RackGridCell (시각 proxy) 의 *state.cellId 는 bayKey ("col-row")
+   * 형식* (`_syncChildCellIds` 가 set). slot 의 *full id ("col-row-shelf")* 와
+   * 다르다 — RackGridCell 은 *carrier 아닌 시각 proxy* 라 *occupied 카운트
+   * 대상 아님*. carriable child (= 실 carrier) 만 sweep.
+   *
+   * @param filter  predicate — 통과하는 slotId 만. sweep 중 즉시 reject.
+   */
+  occupiedSlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string> {
+    const set = new Set<string>()
+    for (const r of this.records as any[]) {
+      const cid = r?.cellId
+      if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+    }
+    for (const c of (this as any).components ?? []) {
+      // *carriable 만* — RackGridCell (rack-grid-cell type) 의 bayKey 제외.
+      if (!(c as any)?.isCarriable) continue
+      const cid = (c as any)?.state?.cellId
+      if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+    }
+    return Array.from(set)
+  }
+
+  /** 비어있는 slot 의 id 목록 — slotIds() - occupiedSlotIds(). isEmpty bay 자동 제외. */
+  emptySlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string> {
+    const occ = new Set(this.occupiedSlotIds())
+    const result: string[] = []
+    for (const id of this.slotIds()) {
+      if (occ.has(id)) continue
+      if (filter && !filter(id)) continue
+      result.push(id)
+    }
+    return result
+  }
+
+  /**
+   * slot 의 *world position* — anchor object3d *생성 없이* 직접 계산. crane 의
+   * reach 검사 같은 *match 전 단계* 에서 *anchor 생성 0* 으로 사용 가능.
+   * match 후 *실제 attach* 가 필요할 때 `getSlotAttachObject3d` 가 lazy 생성.
+   */
+  slotWorldPosition(slotId: string): { x: number; y: number; z: number } | undefined {
+    const parsed = this.parseSlotId(slotId)
+    if (!parsed) return undefined
+    if (parsed.col < 0 || parsed.col >= this.columns) return undefined
+    if (parsed.row < 0 || parsed.row >= this.rackRows) return undefined
+    if (parsed.shelf < 0 || parsed.shelf >= this.shelves) return undefined
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return undefined
+
+    const rs: any = this.state
+    const width = (rs?.width as number) ?? 400
+    const height = (rs?.depth as number) ?? 2000
+    const depth = (rs?.height as number) ?? 200
+    const shelfBase = Math.max(0, Math.min((rs?.shelfBaseHeight as number) || 0, height * 0.9))
+    const cols = this.columns
+    const rows = this.rackRows
+    const shelves = this.shelves
+    const shelfZone = height - shelfBase
+    const bayW = width / cols
+    const bayD = depth / rows
+    const cellY = shelfZone / shelves
+    const baseY = -height / 2
+    const shelfBaseY = baseY + shelfBase
+    const stockD = cellY * 0.7
+
+    const cx = (parsed.col - cols / 2 + 0.5) * bayW
+    const cellBottomY = shelfBaseY + parsed.shelf * cellY
+    const cy = cellBottomY + stockD / 2
+    const cz = (parsed.row - rows / 2 + 0.5) * bayD
+
+    const v = new THREE.Vector3(cx, cy, cz)
+    ro.object3d.localToWorld(v)
+    return { x: v.x, y: v.y, z: v.z }
+  }
+
   buildRealObject(): RealObject | undefined {
     return new RackGrid3D(this)
   }
@@ -842,15 +988,18 @@ export default class RackGrid
   // ── Grid layout ─────────────────────────────────────────
 
   get columns(): number {
-    return Math.max(1, Math.floor(this.state.columns ?? 5))
+    const v = this.state.columns
+    return Math.max(1, Math.floor(typeof v === 'number' && Number.isFinite(v) ? v : 5))
   }
 
   get rackRows(): number {
-    return Math.max(1, Math.floor(this.state.rows ?? 1))
+    const v = this.state.rows
+    return Math.max(1, Math.floor(typeof v === 'number' && Number.isFinite(v) ? v : 1))
   }
 
   get shelves(): number {
-    return Math.max(1, Math.floor(this.state.shelves ?? 4))
+    const v = this.state.shelves
+    return Math.max(1, Math.floor(typeof v === 'number' && Number.isFinite(v) ? v : 4))
   }
 
   // ── cellId / posKey 변환 ────────────────────────────────
@@ -861,11 +1010,11 @@ export default class RackGrid
   }
 
   /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
-  cellIdOf(col: number, row: number = 1, shelf: number = 1): string {
+  slotIdOf(col: number, row: number = 1, shelf: number = 1): string {
     return `${col - 1}-${row - 1}-${shelf - 1}`
   }
 
-  parseCellId(cellId: string): { col: number; row: number; shelf: number } | null {
+  parseSlotId(cellId: string): { col: number; row: number; shelf: number } | null {
     const parts = cellId.split('-')
     if (parts.length !== 3) return null
     const [c, r, s] = parts.map(Number)
@@ -920,7 +1069,7 @@ export default class RackGrid
    * section/unit 둘 다 있고 isEmpty=false 일 때만 부여. 미부여 시 null.
    */
   locationOf(cellId: string): string | null {
-    const parsed = this.parseCellId(cellId)
+    const parsed = this.parseSlotId(cellId)
     if (!parsed) return null
     const posKey = `${parsed.col}-${parsed.row}`
 
@@ -1051,95 +1200,332 @@ export default class RackGrid
    * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
    * 자식 추가 시 자동 할당 또는 사용자가 명시.
    */
-  private _childRackAt(posKey: string): StorageRack | null {
-    const parsed = this.parsePosKey(posKey)
-    if (!parsed) return null
+  /**
+   * cellId 매칭되는 RackGrid 의 직접 자식 carrier (operation archetype).
+   * RackGrid 의 자식 중 rack-grid-cell (시각 proxy) 외에 obtainCarrier 가 add 한
+   * transient carrier 들이 섞임 — 그 중 cellId / placement='operation' 매칭.
+   * storage-rack 의 동일 패턴.
+   */
+  private _carrierChildAt(cellId: string): Component | undefined {
     const children = (this.components as Component[] | undefined) ?? []
-    for (const c of children) {
-      const type = (c.state as any)?.type
-      if (type !== 'storage-rack') continue
-      const childCol = ((c.state as any)?.column ?? 1) - 1
-      const childRow = ((c.state as any)?.row ?? 1) - 1
-      if (childCol === parsed.col && childRow === parsed.row) {
-        return c as unknown as StorageRack
-      }
-    }
-    return null
+    return children.find(c => {
+      const placement = (c.constructor as any).placement
+      return placement === 'operation' && (c.state as any)?.cellId === cellId
+    })
+  }
+
+  /**
+   * state.data 의 internal 갱신 — obtainCarrier / receiveAt 가 사용.
+   * setState 와 달리 'change' / onchangeData / mapping cascade 우회 — 사용자 script
+   * 의 자기-자신 호출 회귀 차단. 시각 갱신은 직접 RealObject.rebuildStockMesh 호출.
+   * storage-rack 의 동일 패턴.
+   */
+  private _setDataSilently(newData: any[]): void {
+    const self = this as any
+    if (!self._state) self._state = {}
+    self._state.data = newData
+    self._cachedState = null
+    ;(this._realObject as any)?.rebuildStockMesh?.()
   }
 
-  // ── SlottedHolder 컨트랙 — 자식 StorageRack 으로 위임 ────
+  // ── SlottedHolder 컨트랙 — RackGrid 자체의 records 에서 직접 처리 ────
+  //
+  // Plan A 정신: stock 데이터는 RackGrid 의 state.data 에 sparse 로 통합 저장.
+  // 자식 컴포넌트는 시각용 rack-grid-cell (light proxy) 뿐 carrier 보유 X.
+  // storage-rack 의 본체 로직 (transient materialize / silent setData) 을 차용,
+  // 좌표 / 사이즈만 RackGrid 의 cellAt(col,row).bounds + getSlotSize 로 적응.
 
-  hasCarrierAt(slotId: string): boolean {
-    const parsed = this.parseCellId(slotId)
-    if (!parsed) return false
-    const child = this._childRackAt(`${parsed.col}-${parsed.row}`)
-    return child?.hasCarrierAt(`0-0-${parsed.shelf}`) ?? false
+  /** state.data record 또는 이미 transient materialize 된 carrier child 가 있는가. */
+  hasCarrierAt(slotIdOrLocation: string): boolean {
+    const cellId = this._resolveToCellId(slotIdOrLocation)
+    if (!cellId) return false
+    if (this._carrierChildAt(cellId)) return true
+    return this.records.some(r => r.cellId === cellId)
   }
 
+  /**
+   * carrier 를 obtain — 이미 child 면 그대로, 아니면 state.data record 로 transient
+   * materialize 후 RackGrid 의 직접 자식으로 add 하고 state.data 에서 그 record 제거.
+   * record 도 child 도 없으면 null.
+   */
   obtainCarrier(slotIdOrLocation: string): Component | null {
-    const slotId = this._resolveToCellId(slotIdOrLocation)
-    if (!slotId) return null
-    const parsed = this.parseCellId(slotId)
+    const cellId = this._resolveToCellId(slotIdOrLocation)
+    if (!cellId) return null
+
+    const existing = this._carrierChildAt(cellId)
+    if (existing) return existing
+
+    const records = this.records as Array<any>
+    const idx = records.findIndex(r => r?.cellId === cellId)
+    if (idx === -1) return null
+    const record = records[idx]
+
+    const carrierType = (record.type as string) || 'parcel'
+    const CarrierClass = (Component as any).register(carrierType) as
+      | (new (...args: any[]) => Component) | undefined
+    if (!CarrierClass) {
+      console.warn(`[rack-grid] obtainCarrier("${cellId}"): carrier type "${carrierType}" 미등록`)
+      return null
+    }
+
+    // RackGrid-inner 좌표 — anchor (getSlotAttachObject3d) / stock InstancedMesh 와
+    // *동일 식* 사용: 균등 분할 + center origin → top-left origin 변환.
+    // 이전엔 widths/heights *비례 분할* 을 썼는데 anchor/stock 은 *균등 분할* 이라
+    // 어긋났음. update loop 이 carrier.state.left/top 기반으로 위치 재계산해도
+    // anchor 와 일치하도록 *처음부터 같은 식* 으로 박는다.
+    const parsed = this.parseSlotId(cellId)
     if (!parsed) return null
-    const child = this._childRackAt(`${parsed.col}-${parsed.row}`)
-    return child?.obtainCarrier(`0-0-${parsed.shelf}`) ?? null
+    const rackWidth = (this.state.width as number) ?? 400
+    const rackDepthY = (this.state.height as number) ?? 200   // 2D height = 3D Z = inner Y
+    const stateDepth = (this.state.depth as number) ?? 2000   // 3D Y (vertical)
+    const bayW = rackWidth / this.columns
+    const bayD = rackDepthY / this.rackRows
+    // anchor X(center) = (col - cols/2 + 0.5) * bayW → 2D top-left center = anchor.X + rackWidth/2
+    const cellCenterInnerX = (parsed.col + 0.5) * bayW
+    const cellCenterInnerY = (parsed.row + 0.5) * bayD
+    // shelf level Y — anchor (getSlotAttachObject3d) 와 동일 식.
+    const shelfBase = Math.max(0, Math.min(((this.state as any).shelfBaseHeight as number) || 0, stateDepth * 0.9))
+    const shelfZone = stateDepth - shelfBase
+    const cellYHeight = shelfZone / this.shelves
+    const shelfBaseY = -stateDepth / 2 + shelfBase
+    const cellBottomY = shelfBaseY + parsed.shelf * cellYHeight
+
+    const slotSize = this.getSlotSize(cellId) ?? { width: 50, height: 50, depth: 50 }
+    // record 의 사이즈가 *0* 또는 *non-finite (NaN/Infinity)* 이면 slotSize fallback —
+    // nullish 만으로는 NaN/0 통과해 BoxGeometry NaN bug 유발.
+    const pickSize = (v: any, fb: number) =>
+      typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fb
+    const carrierW = pickSize(record.width, slotSize.width)
+    const carrierH = pickSize(record.height, slotSize.height)
+    const carrierD = pickSize(record.depth, slotSize.depth)
+
+    // 차원 / 좌표 finite 검증 — 어느 단계에서 NaN 이 들어왔는지 명시 진단.
+    if (
+      !Number.isFinite(carrierW) || !Number.isFinite(carrierH) || !Number.isFinite(carrierD) ||
+      !Number.isFinite(cellCenterInnerX) || !Number.isFinite(cellCenterInnerY)
+    ) {
+      console.error('[rack-grid] obtainCarrier: non-finite dim/pos — carrier 생성 차단', {
+        cellId,
+        carrierW, carrierH, carrierD,
+        cellCenterInnerX, cellCenterInnerY,
+        slotSize,
+        recordSize: { w: record.width, h: record.height, d: record.depth },
+        gridDims: {
+          columns: this.columns, rackRows: this.rackRows, shelves: this.shelves,
+          stateW: (this.state as any)?.width, stateH: (this.state as any)?.height,
+          stateD: (this.state as any)?.depth
+        }
+      })
+      return null
+    }
+
+    // record 에서 id / refid / transform 류는 *제외* — id 가 들어가면 scene 안 기존
+    // component 와 충돌해 parent 가 잘못 잡힘.
+    const { id: _id, refid: _refid, transform: _tf, ...recordCopy } = record as any
+    const carrierState: any = {
+      ...recordCopy,
+      type: carrierType,
+      cellId,                                          // 슬롯 주소
+      refid: _nextCarrierRefid(),                      // refid 충돌 회피
+      width: carrierW,
+      height: carrierH,
+      depth: carrierD,
+      left: cellCenterInnerX - carrierW / 2,
+      top: cellCenterInnerY - carrierH / 2,
+      // zPos = carrier 의 *parent-local 3D Y bottom*. things-scene 의 RealObject 가
+      // 3D Y center = zPos + depth/2 로 계산. 미명시 시 NaN — carrier.matrixWorld NaN
+      // → fork 가 NaN target 따라가서 빈 포크질. anchor 식 (cellBottomY + stockD/2)
+      // 와 일치하도록 zPos = cellBottomY 명시.
+      zPos: cellBottomY
+    }
+
+    const carrier = new CarrierClass(carrierState, (this as any)._app)
+    // silent: true — Plan A transient materialize 는 내부 use, mapping cascade 차단.
+    ;(this as any).addComponent(carrier, { silent: true })
+
+    // 3D 강제 빌드 + holder attach + manual placement/anchor.
+    void (carrier as any).realObject
+    ;(carrier as any).applyHolderAttachPoint?.()
+    ;(carrier as any).realObject?.setTransientPlacement?.({ policy: 'carried' })
+    const anchor = this.getSlotAttachObject3d(cellId)
+    const carrierObj3d = (carrier as any).realObject?.object3d
+    if (anchor && carrierObj3d) {
+      anchor.add(carrierObj3d)
+      carrierObj3d.position.set(0, 0, 0)
+      carrierObj3d.updateMatrixWorld(true)
+    }
+
+    // record 제거 — silent (mapping cascade 회피). 동일 cellId 의 *모든* record 정리.
+    this._setDataSilently(records.filter(r => r?.cellId !== cellId))
+
+    return carrier
   }
 
+  /**
+   * cell 이 carrier 를 받을 수 있는가.
+   *  - isEmpty 위치 는 거부 (modeling 차원 location-less)
+   *  - state.data 에 record 있으면 점유 → false
+   *  - 자기 자신 carrier 가 child 면 idempotent true (자기 자리 복귀)
+   */
   canReceiveAt(slotIdOrLocation: string, carrier?: Component): boolean {
-    const slotId = this._resolveToCellId(slotIdOrLocation)
-    if (!slotId) return false
-    const parsed = this.parseCellId(slotId)
+    const cellId = this._resolveToCellId(slotIdOrLocation)
+    if (!cellId) return false
+    const parsed = this.parseSlotId(cellId)
     if (!parsed) return false
-    // isEmpty 위치 는 carrier 못 받음 (location-less, modeling 차원)
     const override = this.cellOverrides[`${parsed.col}-${parsed.row}`]
     if (override?.isEmpty) return false
-    const child = this._childRackAt(`${parsed.col}-${parsed.row}`)
-    return child?.canReceiveAt(`0-0-${parsed.shelf}`, carrier) ?? false
+
+    const records = this.records as Array<any>
+    if (records.some(r => r?.cellId === cellId)) return false
+    const existingChild = this._carrierChildAt(cellId)
+    if (existingChild && existingChild !== carrier) return false
+    return true
   }
 
-  async receiveAt(slotIdOrLocation: string, carrier: Component, options?: any): Promise<void> {
-    const slotId = this._resolveToCellId(slotIdOrLocation)
-    if (!slotId) throw new Error(`RackGrid.receiveAt: cannot resolve "${slotIdOrLocation}"`)
-    const parsed = this.parseCellId(slotId)
-    if (!parsed) throw new Error(`RackGrid.receiveAt: invalid cellId "${slotId}"`)
-    const child = this._childRackAt(`${parsed.col}-${parsed.row}`)
-    if (!child) {
-      throw new Error(`RackGrid.receiveAt: no StorageRack at posKey=${parsed.col}-${parsed.row}`)
+  /**
+   * Carrier 가 RackGrid 의 slot 으로 들어옴 — 즉시 dispose + state.data 에 record 로
+   * 환원. 결과: stock InstancedMesh 가 그 자리에 instance 표시, RackGrid 의 자식 트리는
+   * 깨끗 (rack-grid-cell 만 남음).
+   */
+  async receiveAt(slotIdOrLocation: string, carrier: Component, _options?: any): Promise<void> {
+    const cellId = this._resolveToCellId(slotIdOrLocation)
+    if (!cellId) throw new Error(`RackGrid.receiveAt: cannot resolve "${slotIdOrLocation}"`)
+
+    // disposed carrier 의 재처리 차단
+    if ((carrier as any)?._disposed) {
+      throw new Error(
+        `RackGrid.receiveAt("${cellId}"): carrier is already disposed. ` +
+        'After a successful pickAndPlace the carrier becomes a state.data record — ' +
+        'use rack.obtainCarrier(cellId) to get a fresh transient carrier instead.'
+      )
+    }
+    if (!this.canReceiveAt(cellId, carrier)) {
+      ;(this as any).trigger?.('transfer-rejected', {
+        type: 'transfer-rejected',
+        component: carrier, container: this, reason: 'slot-occupied', cellId
+      })
+      return
+    }
+
+    const record = this.recordFromCarrier(carrier, cellId)
+
+    // Carrier 의 parent 에서 떼고 dispose. parent 는 보통 mover (crane) 이거나 RackGrid 자신.
+    const carrierParent: any = (carrier as any).parent
+    if (carrierParent && typeof carrierParent.removeComponent === 'function') {
+      carrierParent.removeComponent(carrier)
+    }
+
+    // 명시적 Three.js detach — RealObject.dispose() 의 clear() 는 object3d 자체를
+    // scene graph 의 parent 에서 떼지 않으므로 ghost 방지 위해 명시 제거.
+    const carrierObj3d: any = (carrier as any)._realObject?.object3d
+    if (carrierObj3d?.parent && typeof carrierObj3d.parent.remove === 'function') {
+      carrierObj3d.parent.remove(carrierObj3d)
+    }
+
+    ;(carrier as any).dispose?.()
+
+    // state.data 에 push — silent (mapping cascade 회피). 동일 cellId 중복 방어.
+    const currentRecords = (this.records as any[]).filter(r => r?.cellId !== cellId)
+    this._setDataSilently([...currentRecords, record])
+
+    ;(this as any).trigger?.('transfer-received', {
+      type: 'transfer-received',
+      component: carrier, container: this, slotId: cellId, record
+    })
+  }
+
+  /**
+   * Carrier 의 state 를 state.data record 로 추출. transform/position 관련은 record
+   * 와 무관해 skip. (storage-rack 의 동일 패턴.)
+   */
+  recordFromCarrier(carrier: Component, cellId: string): SlotRecord {
+    const state: any = (carrier as any).state ?? {}
+    const SKIP_KEYS = new Set([
+      'left', 'top', 'zPos',
+      'transform', 'rotation', 'scale',
+      '_transferSlotId',
+      'cellId',
+      'id',
+      'refid'
+    ])
+    const record: any = { cellId, type: state.type }
+    for (const key of Object.keys(state)) {
+      if (SKIP_KEYS.has(key)) continue
+      record[key] = state[key]
     }
-    return child.receiveAt(`0-0-${parsed.shelf}`, carrier, options)
+    return record
+  }
+
+  // ── CarrierHolder — attach frame for direct carrier children ─────────────
+
+  /**
+   * children gate — CarrierHolder.containable 의 *carriable-only* 제한을 완화.
+   * RackGrid 의 자식은 두 종류:
+   *  - RackGridCell : modeling-time visual proxy (carriable 아님)
+   *  - carrier      : Plan A 의 obtainCarrier 가 materialize (carriable)
+   * 둘 다 허용해야 정상 동작.
+   */
+  containable(component: Component): boolean {
+    if (!component) return false
+    if ((component as any)?.state?.type === 'rack-grid-cell') return true
+    return (component as any).isCarriable === true
   }
 
-  recordFromCarrier(carrier: Component, slotId: string): SlotRecord {
-    const { id, refid, transform, ...rest } = ((carrier.state as any) || {}) as any
-    return { ...rest, cellId: slotId }
+  /**
+   * Attach frame for direct-child carrier — `applyHolderAttachPoint` 가 이 결과의
+   * `attach` 에 carrier obj3d 를 attach 하고 `localPosition` 을 set. cell anchor
+   * 반환 + carried placement 와 함께 동작 — carrier 가 cell 위치에 고정.
+   */
+  attachPointFor(carrier: Component): AttachFrame | null {
+    const cellId = (carrier as any)?.state?.cellId as string | undefined
+    if (cellId) {
+      const obj = this.getSlotAttachObject3d(cellId)
+      if (obj) return { attach: obj, localPosition: { x: 0, y: 0, z: 0 } }
+    }
+    const root = this._realObject?.object3d
+    if (!root) return null
+    return { attach: root, localPosition: { x: 0, y: 0, z: 0 } }
   }
 
   /**
    * Slot 의 attach object3d — Stock InstancedMesh 의 instance 와 *같은 world 위치* 에
-   * 위치한 invisible Object3D. popup tether / Carriable.applyHolderAttachPoint 가 이
-   * object3d 의 matrixWorld 를 사용. lazy 생성 + cache.
+   * 위치한 invisible Object3D. popup tether 등이 이 object3d 의 matrixWorld 를
+   * 사용. lazy 생성 + cache.
    */
-  private _attachAnchorByCell: Map<string, THREE.Object3D> = new Map()
+  private _attachAnchorBySlot: Map<string, THREE.Object3D> = new Map()
+
+  /**
+   * Anchor position cache 의 signature — rack 의 차원 state 변경 시 무효화 trigger.
+   * 동일 signature 인 동안 *anchor.position.set 재계산 skip*. crane 의 첫
+   * findAdjacentSlots 가 *수많은 anchor 의 position.set 매 호출* — *동일 차원
+   * state 일 때* 의 *중복 계산 차단*.
+   */
+  private _attachAnchorSig?: string
 
   getSlotAttachObject3d(slotId: string): THREE.Object3D | undefined {
-    const parsed = this.parseCellId(slotId)
-    if (!parsed) return undefined
-    if (parsed.col < 0 || parsed.col >= this.columns) return undefined
-    if (parsed.row < 0 || parsed.row >= this.rackRows) return undefined
-    if (parsed.shelf < 0 || parsed.shelf >= this.shelves) return undefined
+    const parsed = this.parseSlotId(slotId)
+    if (!parsed) {
+      console.warn(`[rack-grid] getSlotAttachObject3d: invalid cellId format "${slotId}"`)
+      return undefined
+    }
+    if (parsed.col < 0 || parsed.col >= this.columns) {
+      console.warn(`[rack-grid] getSlotAttachObject3d: col=${parsed.col} out of range [0, ${this.columns})`)
+      return undefined
+    }
+    if (parsed.row < 0 || parsed.row >= this.rackRows) {
+      console.warn(`[rack-grid] getSlotAttachObject3d: row=${parsed.row} out of range [0, ${this.rackRows})`)
+      return undefined
+    }
+    if (parsed.shelf < 0 || parsed.shelf >= this.shelves) {
+      console.warn(`[rack-grid] getSlotAttachObject3d: shelf=${parsed.shelf} out of range [0, ${this.shelves}) — cellId "${slotId}" — fork 가 fallback 위치 (한 층 아래 등) 로 갈 수 있음`)
+      return undefined
+    }
 
     const ro: any = (this as any)._realObject
     if (!ro?.object3d) return undefined
 
-    let obj = this._attachAnchorByCell.get(slotId)
-    if (!obj) {
-      obj = new THREE.Object3D()
-      obj.name = `rack-grid-anchor:${slotId}`
-      ro.object3d.add(obj)
-      this._attachAnchorByCell.set(slotId, obj)
-    }
-
-    // 위치 갱신 — Stock InstancedMesh 의 instance 위치 와 동일 공식
+    // signature 검사 — 차원 state 변경 시 *모든 anchor invalidate* 후 새로 생성.
+    // 동일 sig 일 때 *기존 anchor 그대로 사용 (position.set skip)*.
     const rs: any = this.state
     const cols = this.columns
     const rows = this.rackRows
@@ -1148,19 +1534,39 @@ export default class RackGrid
     const height = (rs?.depth as number) ?? 2000
     const depth = (rs?.height as number) ?? 200
     const shelfBase = Math.max(0, Math.min((rs?.shelfBaseHeight as number) || 0, height * 0.9))
-    const shelfZone = height - shelfBase
-    const bayW = width / cols
-    const bayD = depth / rows
-    const cellY = shelfZone / shelves
-    const baseY = -height / 2
-    const shelfBaseY = baseY + shelfBase
-    const stockD = cellY * 0.7
+    const sig = `${cols}-${rows}-${shelves}-${width}-${height}-${depth}-${shelfBase}`
 
-    const cx = (parsed.col - cols / 2 + 0.5) * bayW
-    const cellBottomY = shelfBaseY + parsed.shelf * cellY
-    const cy = cellBottomY + stockD / 2
-    const cz = (parsed.row - rows / 2 + 0.5) * bayD
-    obj.position.set(cx, cy, cz)
+    if (this._attachAnchorSig !== sig) {
+      // 차원 변경 — 모든 기존 anchor 폐기 후 sig 갱신.
+      for (const oldObj of this._attachAnchorBySlot.values()) {
+        ro.object3d.remove(oldObj)
+      }
+      this._attachAnchorBySlot.clear()
+      this._attachAnchorSig = sig
+    }
+
+    let obj = this._attachAnchorBySlot.get(slotId)
+    if (!obj) {
+      obj = new THREE.Object3D()
+      obj.name = `rack-grid-anchor:${slotId}`
+      ro.object3d.add(obj)
+      this._attachAnchorBySlot.set(slotId, obj)
+
+      // 신규 anchor — position 계산 + set (1 회 만, 이후 호출은 cache hit).
+      const shelfZone = height - shelfBase
+      const bayW = width / cols
+      const bayD = depth / rows
+      const cellY = shelfZone / shelves
+      const baseY = -height / 2
+      const shelfBaseY = baseY + shelfBase
+      const stockD = cellY * 0.7
+
+      const cx = (parsed.col - cols / 2 + 0.5) * bayW
+      const cellBottomY = shelfBaseY + parsed.shelf * cellY
+      const cy = cellBottomY + stockD / 2
+      const cz = (parsed.row - rows / 2 + 0.5) * bayD
+      obj.position.set(cx, cy, cz)
+    }
     // *parent 의 matrixWorld 가 dirty 면 자식 matrixWorld 도 dirty* — 강제 갱신.
     ro.object3d.updateMatrixWorld(true)
     obj.updateMatrixWorld(true)
@@ -1168,7 +1574,7 @@ export default class RackGrid
   }
 
   getSlotSize(slotId: string): { width: number; height: number; depth: number } | undefined {
-    const parsed = this.parseCellId(slotId)
+    const parsed = this.parseSlotId(slotId)
     if (!parsed) return undefined
     const rs: any = this.state
     const width = (rs?.width as number) ?? 400
@@ -1185,7 +1591,7 @@ export default class RackGrid
   }
 
   cellCenter2D(slotId: string): { x: number; y: number } | null {
-    const parsed = this.parseCellId(slotId)
+    const parsed = this.parseSlotId(slotId)
     if (!parsed) return null
     const rs: any = this.state
     const left = (rs?.left as number) ?? 0