@operato/scene-storage 10.0.0-beta.44 → 10.0.0-beta.47

package/dist/rack-grid.js

@@ -30,9 +30,9 @@ import { __decorate } from "tslib";
  *   - cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments) — *grid + shelf*
  *   - 자식 StorageRack 내부에서는 `0-0-${shelf-1}` (자체 cellId 형식). RackGrid 가 변환.
  */
-import { ContainerAbstract, Layout, Model, sceneComponent } from '@hatiolab/things-scene';
+import { Component, ContainerAbstract, Layout, Model, sceneComponent } from '@hatiolab/things-scene';
 import * as THREE from 'three';
-import { Placeable, SlotTarget } from '@operato/scene-base';
+import { CarrierHolder, Placeable, SlotTarget } from '@operato/scene-base';
 import { RackGrid3D } from './rack-grid-3d.js';
 // RackGridCell 의 refid 충돌 회피 — load 시 동적 생성되는 cell 의 refid 가 *부모
 // RackGrid + 모델 안 다른 컴포넌트* refid 와 겹치지 않도록 *높은 시작값 + monotonic
@@ -41,6 +41,12 @@ let _cellRefidCounter = 100_000_000;
 function _nextCellRefid() {
     return _cellRefidCounter++;
 }
+// Transient carrier (obtainCarrier 가 materialize 한 컴포넌트) 용 refid. 모델 안
+// 다른 컴포넌트와 겹치지 않도록 별도 대역.
+let _carrierRefidCounter = 200_000_000;
+function _nextCarrierRefid() {
+    return _carrierRefidCounter++;
+}
 function buildNewCell(app) {
     const refid = _nextCellRefid();
     const m = Model.compile({
@@ -60,6 +66,43 @@ function buildNewCell(app) {
     return m;
 }
 const TABLE_LAYOUT = 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 = {
+    reflow(container) {
+        const all = container.components ?? [];
+        const cellsOnly = all.filter((c) => 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) { return TABLE_LAYOUT.capturables(container); },
+    drawables(container) { return TABLE_LAYOUT.drawables(container); },
+    isStuck(component) { return TABLE_LAYOUT.isStuck?.(component) ?? true; },
+    keyNavigate(container, component, e) {
+        return TABLE_LAYOUT.keyNavigate?.(container, component, e);
+    },
+    joinType: TABLE_LAYOUT.joinType
+};
 function arrayOf(value, size) {
     const arr = [];
     for (let i = 0; i < size; i++)
@@ -113,7 +156,23 @@ const rowControlHandler = {
 // handler 안 `this` 가 *해당 RackGrid 인스턴스* 를 가리키도록 (화살표 함수가
 // getter 의 `this` 를 capture). rack-table-cell 의 동일 패턴.
 // ─── RackGrid ─────────────────────────────────────────────────────────────────
-let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
+let RackGrid = class RackGrid extends CarrierHolder(Placeable(ContainerAbstract)) {
+    // Phase Auto-Nav (AN-PR-2) — Obstacle 자격. AMR / mover 의 자동 path planning
+    // 시 회피 대상. `state.isObstacle` 명시 false 시 override (예외 처리).
+    get isObstacle() {
+        return this.state?.isObstacle !== false;
+    }
+    obstacleBoundingBox() {
+        const s = this.state;
+        if (typeof s?.left !== 'number')
+            return null;
+        return {
+            left: s.left, top: s.top,
+            width: s.width, height: s.height,
+            y: typeof s.zPos === 'number' ? s.zPos : 0,
+            zHeight: typeof s.depth === 'number' ? s.depth : 0
+        };
+    }
     static placement = 'floor';
     static align = 'bottom';
     static defaultDepth = (h) => h.ceiling - h.floor;
@@ -545,12 +604,118 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
      * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
      */
     isBayEmpty(col, row = 0) {
+        // 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() {
+        const ids = [];
+        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) {
+        const set = new Set();
+        for (const r of this.records) {
+            const cid = r?.cellId;
+            if (typeof cid === 'string' && (!filter || filter(cid)))
+                set.add(cid);
+        }
+        for (const c of this.components ?? []) {
+            // *carriable 만* — RackGridCell (rack-grid-cell type) 의 bayKey 제외.
+            if (!c?.isCarriable)
+                continue;
+            const cid = c?.state?.cellId;
+            if (typeof cid === 'string' && (!filter || filter(cid)))
+                set.add(cid);
+        }
+        return Array.from(set);
+    }
+    /** 비어있는 slot 의 id 목록 — slotIds() - occupiedSlotIds(). isEmpty bay 자동 제외. */
+    emptySlotIds(filter) {
+        const occ = new Set(this.occupiedSlotIds());
+        const result = [];
+        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) {
+        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 = this._realObject;
+        if (!ro?.object3d)
+            return undefined;
+        const rs = this.state;
+        const width = rs?.width ?? 400;
+        const height = rs?.depth ?? 2000;
+        const depth = rs?.height ?? 200;
+        const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 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() {
         return new RackGrid3D(this);
     }
@@ -721,13 +886,16 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
     }
     // ── Grid layout ─────────────────────────────────────────
     get columns() {
-        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() {
-        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() {
-        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 변환 ────────────────────────────────
     /** posKey = `${col-1}-${row-1}` (0-based, 2 segments). 1-based input. */
@@ -735,10 +903,10 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
         return `${col - 1}-${row - 1}`;
     }
     /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
-    cellIdOf(col, row = 1, shelf = 1) {
+    slotIdOf(col, row = 1, shelf = 1) {
         return `${col - 1}-${row - 1}-${shelf - 1}`;
     }
-    parseCellId(cellId) {
+    parseSlotId(cellId) {
         const parts = cellId.split('-');
         if (parts.length !== 3)
             return null;
@@ -789,7 +957,7 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
      * section/unit 둘 다 있고 isEmpty=false 일 때만 부여. 미부여 시 null.
      */
     locationOf(cellId) {
-        const parsed = this.parseCellId(cellId);
+        const parsed = this.parseSlotId(cellId);
         if (!parsed)
             return null;
         const posKey = `${parsed.col}-${parsed.row}`;
@@ -913,99 +1081,312 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
      * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
      * 자식 추가 시 자동 할당 또는 사용자가 명시.
      */
-    _childRackAt(posKey) {
-        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 의 동일 패턴.
+     */
+    _carrierChildAt(cellId) {
         const children = this.components ?? [];
-        for (const c of children) {
-            const type = c.state?.type;
-            if (type !== 'storage-rack')
-                continue;
-            const childCol = (c.state?.column ?? 1) - 1;
-            const childRow = (c.state?.row ?? 1) - 1;
-            if (childCol === parsed.col && childRow === parsed.row) {
-                return c;
-            }
-        }
-        return null;
+        return children.find(c => {
+            const placement = c.constructor.placement;
+            return placement === 'operation' && c.state?.cellId === cellId;
+        });
     }
-    // ── SlottedHolder 컨트랙 — 자식 StorageRack 으로 위임 ────
-    hasCarrierAt(slotId) {
-        const parsed = this.parseCellId(slotId);
-        if (!parsed)
+    /**
+     * state.data 의 internal 갱신 — obtainCarrier / receiveAt 가 사용.
+     * setState 와 달리 'change' / onchangeData / mapping cascade 우회 — 사용자 script
+     * 의 자기-자신 호출 회귀 차단. 시각 갱신은 직접 RealObject.rebuildStockMesh 호출.
+     * storage-rack 의 동일 패턴.
+     */
+    _setDataSilently(newData) {
+        const self = this;
+        if (!self._state)
+            self._state = {};
+        self._state.data = newData;
+        self._cachedState = null;
+        this._realObject?.rebuildStockMesh?.();
+    }
+    // ── 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 로 적응.
+    /** state.data record 또는 이미 transient materialize 된 carrier child 가 있는가. */
+    hasCarrierAt(slotIdOrLocation) {
+        const cellId = this._resolveToCellId(slotIdOrLocation);
+        if (!cellId)
             return false;
-        const child = this._childRackAt(`${parsed.col}-${parsed.row}`);
-        return child?.hasCarrierAt(`0-0-${parsed.shelf}`) ?? 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) {
-        const slotId = this._resolveToCellId(slotIdOrLocation);
-        if (!slotId)
+        const cellId = this._resolveToCellId(slotIdOrLocation);
+        if (!cellId)
             return null;
-        const parsed = this.parseCellId(slotId);
+        const existing = this._carrierChildAt(cellId);
+        if (existing)
+            return existing;
+        const records = this.records;
+        const idx = records.findIndex(r => r?.cellId === cellId);
+        if (idx === -1)
+            return null;
+        const record = records[idx];
+        const carrierType = record.type || 'parcel';
+        const CarrierClass = Component.register(carrierType);
+        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 ?? 400;
+        const rackDepthY = this.state.height ?? 200; // 2D height = 3D Z = inner Y
+        const stateDepth = this.state.depth ?? 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.shelfBaseHeight || 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, fb) => 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?.width, stateH: this.state?.height,
+                    stateD: this.state?.depth
+                }
+            });
+            return null;
+        }
+        // record 에서 id / refid / transform 류는 *제외* — id 가 들어가면 scene 안 기존
+        // component 와 충돌해 parent 가 잘못 잡힘.
+        const { id: _id, refid: _refid, transform: _tf, ...recordCopy } = record;
+        const carrierState = {
+            ...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._app);
+        this.addComponent(carrier, { silent: true });
+        // 3D 강제 빌드 + holder attach + manual placement/anchor.
+        void carrier.realObject;
+        carrier.applyHolderAttachPoint?.();
+        carrier.realObject?.setTransientPlacement?.({ policy: 'carried' });
+        const anchor = this.getSlotAttachObject3d(cellId);
+        const carrierObj3d = carrier.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, carrier) {
-        const slotId = this._resolveToCellId(slotIdOrLocation);
-        if (!slotId)
+        const cellId = this._resolveToCellId(slotIdOrLocation);
+        if (!cellId)
             return false;
-        const parsed = this.parseCellId(slotId);
+        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;
+        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, carrier, options) {
-        const slotId = this._resolveToCellId(slotIdOrLocation);
-        if (!slotId)
+    /**
+     * Carrier 가 RackGrid 의 slot 으로 들어옴 — 즉시 dispose + state.data 에 record 로
+     * 환원. 결과: stock InstancedMesh 가 그 자리에 instance 표시, RackGrid 의 자식 트리는
+     * 깨끗 (rack-grid-cell 만 남음).
+     */
+    async receiveAt(slotIdOrLocation, carrier, _options) {
+        const cellId = this._resolveToCellId(slotIdOrLocation);
+        if (!cellId)
             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}`);
+        // disposed carrier 의 재처리 차단
+        if (carrier?._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.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 = carrier.parent;
+        if (carrierParent && typeof carrierParent.removeComponent === 'function') {
+            carrierParent.removeComponent(carrier);
         }
-        return child.receiveAt(`0-0-${parsed.shelf}`, carrier, options);
+        // 명시적 Three.js detach — RealObject.dispose() 의 clear() 는 object3d 자체를
+        // scene graph 의 parent 에서 떼지 않으므로 ghost 방지 위해 명시 제거.
+        const carrierObj3d = carrier._realObject?.object3d;
+        if (carrierObj3d?.parent && typeof carrierObj3d.parent.remove === 'function') {
+            carrierObj3d.parent.remove(carrierObj3d);
+        }
+        ;
+        carrier.dispose?.();
+        // state.data 에 push — silent (mapping cascade 회피). 동일 cellId 중복 방어.
+        const currentRecords = this.records.filter(r => r?.cellId !== cellId);
+        this._setDataSilently([...currentRecords, record]);
+        this.trigger?.('transfer-received', {
+            type: 'transfer-received',
+            component: carrier, container: this, slotId: cellId, record
+        });
     }
-    recordFromCarrier(carrier, slotId) {
-        const { id, refid, transform, ...rest } = (carrier.state || {});
-        return { ...rest, cellId: slotId };
+    /**
+     * Carrier 의 state 를 state.data record 로 추출. transform/position 관련은 record
+     * 와 무관해 skip. (storage-rack 의 동일 패턴.)
+     */
+    recordFromCarrier(carrier, cellId) {
+        const state = carrier.state ?? {};
+        const SKIP_KEYS = new Set([
+            'left', 'top', 'zPos',
+            'transform', 'rotation', 'scale',
+            '_transferSlotId',
+            'cellId',
+            'id',
+            'refid'
+        ]);
+        const record = { cellId, type: state.type };
+        for (const key of Object.keys(state)) {
+            if (SKIP_KEYS.has(key))
+                continue;
+            record[key] = state[key];
+        }
+        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) {
+        if (!component)
+            return false;
+        if (component?.state?.type === 'rack-grid-cell')
+            return true;
+        return component.isCarriable === true;
+    }
+    /**
+     * Attach frame for direct-child carrier — `applyHolderAttachPoint` 가 이 결과의
+     * `attach` 에 carrier obj3d 를 attach 하고 `localPosition` 을 set. cell anchor
+     * 반환 + carried placement 와 함께 동작 — carrier 가 cell 위치에 고정.
+     */
+    attachPointFor(carrier) {
+        const cellId = carrier?.state?.cellId;
+        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.
+     */
+    _attachAnchorBySlot = new Map();
+    /**
+     * Anchor position cache 의 signature — rack 의 차원 state 변경 시 무효화 trigger.
+     * 동일 signature 인 동안 *anchor.position.set 재계산 skip*. crane 의 첫
+     * findAdjacentSlots 가 *수많은 anchor 의 position.set 매 호출* — *동일 차원
+     * state 일 때* 의 *중복 계산 차단*.
      */
-    _attachAnchorByCell = new Map();
+    _attachAnchorSig;
     getSlotAttachObject3d(slotId) {
-        const parsed = this.parseCellId(slotId);
-        if (!parsed)
+        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)
+        }
+        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)
+        }
+        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)
+        }
+        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 = this._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 = this.state;
         const cols = this.columns;
         const rows = this.rackRows;
@@ -1014,25 +1395,42 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
         const height = rs?.depth ?? 2000;
         const depth = rs?.height ?? 200;
         const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 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 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);
+        const sig = `${cols}-${rows}-${shelves}-${width}-${height}-${depth}-${shelfBase}`;
+        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);
         return obj;
     }
     getSlotSize(slotId) {
-        const parsed = this.parseCellId(slotId);
+        const parsed = this.parseSlotId(slotId);
         if (!parsed)
             return undefined;
         const rs = this.state;
@@ -1049,7 +1447,7 @@ let RackGrid = class RackGrid extends Placeable(ContainerAbstract) {
         };
     }
     cellCenter2D(slotId) {
-        const parsed = this.parseCellId(slotId);
+        const parsed = this.parseSlotId(slotId);
         if (!parsed)
             return null;
         const rs = this.state;