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

package/dist/storage-rack.js

@@ -3,7 +3,8 @@ import { __decorate } from "tslib";
  * Copyright © HatioLab Inc. All rights reserved.
  */
 import { Component, ContainerAbstract, sceneComponent } from '@hatiolab/things-scene';
-import { CellContainer, CellMap, CarrierHolder, Placeable } from '@operato/scene-base';
+import * as THREE from 'three';
+import { CellContainer, CellMap, CarrierHolder, Placeable, SlotTarget } from '@operato/scene-base';
 import { StorageRack3D } from './storage-rack-3d.js';
 const NATURE = {
     mutable: false,
@@ -21,6 +22,31 @@ const NATURE = {
             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 공간.'
+        },
+        {
+            type: 'id-input',
+            label: 'legend-target',
+            name: 'legendTarget',
+            property: { component: 'legend' },
+            placeholder: '미명시 시 scene 의 legend 자동 발견'
+        },
+        {
+            type: 'id-input',
+            label: 'popup-ref',
+            name: 'popupRef',
+            property: { component: 'popup' },
+            placeholder: 'click 시 invoke 할 Popup 컴포넌트 id (anchor 는 클릭된 cell 로 override)'
+        },
+        {
+            type: 'checkbox',
+            label: 'hide-horizontal-frame',
+            name: 'hideHorizontalFrame'
         }
     ],
     help: 'scene/component/rack'
@@ -34,22 +60,27 @@ const NATURE = {
 //   CarrierHolder: 3D attach-point protocol (attachPointFor, containable gates)
 //   Placeable:     floor-archetype positioning
 //   ContainerAbstract: child component management
+// Transient carrier refid generator — load 시 root._addTraverse 가 자식 부터 처리
+// 하면서 cell.model.refid 가 비어있으면 root.getNewRefid() = 1,2,3... 작은 값 부여
+// → *부모 Rack + 모델 안 다른 컴포넌트* refid 와 충돌 ("Refid Index replaced" 경고).
+// transient materialize 시 *큰 시작값 + monotonic counter* 로 자체 부여 → 충돌 0.
+// hierarchy override / state.data 만 저장 → 모델 파일엔 refid 안 새겨짐.
+let _carrierRefidCounter = 200_000_000;
+function _nextCarrierRefid() {
+    return _carrierRefidCounter++;
+}
 /**
  * Rack — a multi-level storage shelf system. A *Storage* whose role is to hold
  * carriers in a (bay × level) grid of cells.
  *
  * `levels` × `bays` cells form a vertical grid. Each cell holds one logistics
  * package (Pallet / Box / Parcel). A picker (Crane / Forklift / robot arm)
- * accesses individual cells via Phase G/H Pickable contract — the picker is
- * Rack-agnostic, knowing only how to interact with a cell.
+ * accesses individual cells via the Plan A slot API — the picker interacts
+ * with `SlotTarget` (no explicit cell-component required).
  *
- * **Monitoring mode** (default): carriers are direct children of the rack,
- * placed by external data binding. No RackCell children are created.
- *
- * **Simulation mode**: call `rack._buildCells()` after placing the rack on the
- * scene. This creates RackCell children at the correct 3D positions. A picker
- * (Crane / Forklift / ...) then navigates to individual RackCells for
- * pick-and-place.
+ * **Plan A**: carriers are direct children of the rack, addressed by
+ * `state.cellId`. Stock visualization uses InstancedMesh (batched). Slot
+ * lookup / pick / place via `obtainCarrier` / `receiveAt` / `slotTargetAt`.
  *
  * **Placement**: `floor` archetype, full ceiling depth by default.
  *
@@ -67,6 +98,25 @@ let Rack = class Rack extends CellContainer(CarrierHolder(Placeable(ContainerAbs
     get anchors() {
         return [];
     }
+    /**
+     * Runtime — bays / levels 변경 시 anchor 캐시 무효화. cell 위치가 바뀌므로 다음
+     * `_ensureCellAttachObject3d` 호출이 새 좌표로 갱신.
+     */
+    onchange(after, _before) {
+        super.onchange?.(after, _before);
+        if ('bays' in after ||
+            'levels' in after ||
+            'shelfBaseHeight' in after ||
+            'width' in after ||
+            'height' in after ||
+            'depth' in after) {
+            this._attachAnchorByCell.clear();
+        }
+        if ('hideHorizontalFrame' in after) {
+            ;
+            this._realObject?.applyFrameVisibility?.();
+        }
+    }
     // ── CellContainer ─────────────────────────────────────────────────────────
     /**
      * Derive the cell topology from the rack's current dimensions and bay/level
@@ -84,62 +134,28 @@ let Rack = class Rack extends CellContainer(CarrierHolder(Placeable(ContainerAbs
         const width = this.state.width || 1000;
         const rackDepth = this.state.depth || 3000; // Y: floor→ceiling
         const rackHeight = this.state.height || 600; // Z: front→back
+        const shelfBase = Math.max(0, Math.min(this.state.shelfBaseHeight || 0, rackDepth * 0.9 // clamp ≤ 90% — 최소 shelf zone
+        ));
+        const shelfZone = rackDepth - shelfBase; // 실제 shelf 가 차지하는 Y 영역
         return CellMap.grid({
             bays,
             rows: 1,
             levels,
             bayWidth: width / bays,
             rowDepth: rackHeight,
-            levelHeight: rackDepth / levels
+            levelHeight: shelfZone / levels,
+            origin: { x: 0, y: shelfBase, z: 0 } // 첫 cell 의 Y = shelfBase
         });
     }
-    /**
-     * Create RackCell child components for each cell in the CellMap.
-     *
-     * Called explicitly to enter simulation mode — monitoring-mode racks
-     * never call this (carriers are direct children, no explicit cells).
-     *
-     * Idempotent: removes existing rack-cell children first.
-     */
-    _buildCells() {
-        // Remove existing rack-cell children
-        const existing = this.components ?? [];
-        for (const child of [...existing]) {
-            if (child.state?.type === 'storage-cell') {
-                this.removeComponent(child);
-            }
-        }
-        // Create a RackCell for each cell in the map
-        const RackCellClass = Component.register('storage-cell');
-        if (!RackCellClass) {
-            console.warn('Rack._buildCells: rack-cell type not registered. Import rack-cell.ts first.');
-            return;
-        }
-        const context = this._app;
-        for (const cell of this.cellMap.cells) {
-            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
-            };
-            const rackCell = new RackCellClass(model, context);
-            this.addComponent(rackCell);
-        }
-    }
     // ── Container gates ───────────────────────────────────────────────────────
     /**
      * Allow:
-     *   - Carriable components (pallets, boxes, parcels) — direct children in monitoring mode.
-     *   - RackCell — created by _buildCells() in simulation mode.
+     *   - Carriable components (pallets, boxes, parcels) — direct children, operation archetype.
      *
      * Block:
      *   - Everything else (sensors, labels, etc. can be siblings of the rack, not children).
      */
     containable(component) {
-        if (component.state?.type === 'storage-cell')
-            return true;
         const archetype = component.constructor.placement;
         if (archetype === 'operation')
             return true;
@@ -147,42 +163,686 @@ let Rack = class Rack extends CellContainer(CarrierHolder(Placeable(ContainerAbs
     }
     // ── CarrierHolder — attach frame for direct carrier children ─────────────
     /**
-     * Attach frame for carriers that are DIRECT children of the rack
-     * (monitoring mode, where carriers go directly into the rack without
-     * explicit RackCell components).
-     *
-     * In simulation mode, carriers become children of their RackCell,
-     * and each RackCell provides its own attachPointFor(). So this method
-     * is only invoked on direct-child carriers in monitoring mode — it
-     * returns the rack's own object3d as the attach frame (default behavior).
+     * Attach frame for direct-child carriers — Plan A 의 모든 carrier 가 rack 의
+     * 직접 자식이므로 매번 호출됨. carrier 의 state.cellId 에 해당하는 *cell-local
+     * anchor object3d* 를 반환 → carrier 의 object3d 가 자동으로 셀 위치에 정렬됨.
      */
-    attachPointFor(_carrier) {
+    attachPointFor(carrier) {
+        // Plan A: rack 의 직접 자식 carrier 는 *state.cellId* 로 슬롯 위치를 표시 (매트릭스
+        // 내 주소). attachPointFor 는 그 cellId 의 *셀-로컬 anchor object3d* 를 반환 →
+        // carrier 의 object3d 가 자동으로 셀 위치에 정렬됨.
+        //
+        // localPosition: {0,0,0} 명시 — Carriable.applyHolderAttachPoint 가 Three.js
+        // attach() 후 *world pose 보존* 만 하고 local 을 reset 하지 않는 결함 우회.
+        // 명시 시 (Carriable + CarrierHolder.reparent 모두) 그대로 anchor origin 에 snap.
+        const cellId = carrier?.state?.cellId;
+        if (cellId) {
+            const obj = this._ensureCellAttachObject3d(cellId);
+            if (obj)
+                return { attach: obj, localPosition: { x: 0, y: 0, z: 0 } };
+        }
+        // Fallback — cellId 없는 (legacy) 호출 시 rack root.
         const root = this._realObject?.object3d;
         if (!root)
             return null;
-        return { attach: root };
+        return { attach: root, localPosition: { x: 0, y: 0, z: 0 } };
+    }
+    // ── Plan A — Slot API (LoopSorter-style; "rack 안 = 데이터, 밖 = 컴포넌트") ───
+    //
+    // Conceptual model:
+    //   - rack 안의 carrier 는 *state.data 의 한 record* (데이터)
+    //   - rack 밖의 carrier 는 *Component* (실재)
+    //   - 경계 통과 시 transient materialize / atomic absorb
+    //
+    // 불변식: 동일 cellId 가 state.data 의 record 와 rack-child carrier 양쪽에 동시
+    //   존재하지 않음. obtainCarrier 와 receiveAt 가 atomic 하게 전환.
+    //
+    // 호출 흐름:
+    //   - Pick:  const c = rack.obtainCarrier('A-0-0')  → c 는 rack child, record 빠짐
+    //            await crane.pick(c) → c.parent = crane (rack child 에서도 빠짐)
+    //   - Place: await crane.place(c, destRack.slotTargetAt('B-0-0'))
+    //            SlotTarget.receive → destRack.receiveAt → c dispose + record push
+    /** state.data 의 record 목록 (읽기 전용 뷰). */
+    get records() {
+        return this.state.data ?? [];
+    }
+    /**
+     * 1-based (bay, row, level) → 0-based cellId 문자열.
+     *
+     *   rack.cellIdOf(1, 1, 6)  →  '0-0-5'
+     *   rack.cellIdOf(3, 1, 4)  →  '2-0-3'
+     */
+    cellIdOf(bay, row = 1, level = 1) {
+        return `${bay - 1}-${row - 1}-${level - 1}`;
+    }
+    /** cellId 에 carrier 가 있는가 — child carrier 또는 state.data record 어느 쪽이든. */
+    hasCarrierAt(cellId) {
+        if (this._carrierChildAt(cellId))
+            return true;
+        return this.records.some(r => r.cellId === cellId);
+    }
+    /** cellId 매칭되는 rack 의 직접 자식 carrier (operation archetype). */
+    _carrierChildAt(cellId) {
+        const children = this.components ?? [];
+        return children.find(c => {
+            const placement = c.constructor.placement;
+            return placement === 'operation' && c.state?.cellId === cellId;
+        });
+    }
+    /**
+     * carrier 를 obtain — 이미 child 면 그대로, 아니면 state.data record 로 transient
+     * materialize 후 rack 의 직접 자식으로 add 하고 state.data 에서 그 record 제거.
+     * record 도 child 도 없으면 null.
+     *
+     * Signature overloads:
+     *   obtainCarrier('0-0-5')                — string cellId 직접
+     *   obtainCarrier(1, 1, 6)                — 1-based (bay, row, level)
+     *   obtainCarrier(1) ≡ obtainCarrier(1,1,1)
+     */
+    obtainCarrier(idOrBay, row, level) {
+        const cellId = typeof idOrBay === 'string'
+            ? idOrBay
+            : this.cellIdOf(idOrBay, row ?? 1, level ?? 1);
+        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(`[storage-rack] obtainCarrier("${cellId}"): carrier type "${carrierType}" 미등록`);
+            return null;
+        }
+        // 크기 기본값 — rack 기하에서 derive (record 가 명시 안 한 경우)
+        const rs = this.state;
+        const rackWidth = rs?.width || 1000;
+        const rackDepth = rs?.depth || 3000;
+        const rackHeight = rs?.height || 600;
+        const bays = Math.max(1, Math.floor(rs?.bays || 5));
+        const levels = Math.max(1, Math.floor(rs?.levels || 4));
+        const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 0, rackDepth * 0.9));
+        const shelfZone = rackDepth - shelfBase;
+        const bayWidth = rackWidth / bays;
+        const levelHeight = shelfZone / levels;
+        // record 에서 id / refid / transform 류는 *제외* — id 가 들어가면 scene 안 기존
+        // component 와 충돌해 parent 가 잘못 잡힘 (model-layer 의 원본을 재사용 등).
+        const { id: _id, refid: _refid, transform: _tf, ...recordCopy } = record;
+        const carrierW = record.width ?? bayWidth * 0.85;
+        const carrierH = record.height ?? rackHeight * 0.85;
+        // cell 의 *rack-inner 좌표* (= carrier 의 parent=rack 의 inner 좌표계 의 점).
+        // carrier.center = carrier.state.left + carrierW/2 가 *rack-inner 좌표 의 cell center*
+        // 이어야 Crane.moveTo (target.center → target.toScene) 가 정확한 layer 좌표로 변환.
+        // 이전엔 left=0, top=0 → center=(carrierW/2, carrierH/2) = bay 0 의 좌상단 근처 → fork 어긋남.
+        const cellInfo = this.cellMap?.findById(cellId);
+        const bayIdx = (cellInfo?.bay ?? 1) - 1;
+        const cellCenterInnerX = bayIdx * bayWidth + bayWidth / 2;
+        const cellCenterInnerY = rackHeight / 2;
+        const carrierState = {
+            ...recordCopy,
+            type: carrierType,
+            cellId, // 슬롯 주소
+            refid: _nextCarrierRefid(), // refid 충돌 회피
+            width: carrierW,
+            height: carrierH,
+            depth: record.depth ?? levelHeight * 0.7,
+            left: cellCenterInnerX - carrierW / 2,
+            top: cellCenterInnerY - carrierH / 2
+        };
+        const carrier = new CarrierClass(carrierState, this._app);
+        this.addComponent(carrier, { silent: true });
+        // 3D 강제 빌드 + attach (pipeline tick 없이도 즉시 표시 — Mover 가 곧 pick).
+        void carrier.realObject;
+        carrier.applyHolderAttachPoint?.();
+        // record 제거 — atomic: child 추가 직후. 동일 cellId 의 *모든* record 정리.
+        // *silent* 갱신 — mapping cascade (onchangeData → executeMappings → script fire)
+        // 회피. external (WMS push) 호출은 setState 거치므로 그쪽 mapping 은 정상 발사.
+        this._setDataSilently(records.filter(r => r?.cellId !== cellId));
+        return carrier;
+    }
+    /**
+     * State.data 의 *internal* 갱신 — Plan A 의 obtainCarrier / receiveAt 가 사용.
+     * `setState` 와 달리 *'change' 이벤트 / onchangeData / mapping cascade 를 우회*.
+     *
+     * 이유: mapping 시스템이 state.data 변경 시 *자동으로 script fire*. Plan A 의
+     * setState 가 그 cascade 를 트리거하면 사용자 script 가 *재귀적으로 자기 자신을 호출*
+     * 하는 회귀 (board 의 의도된 binding 일 수도, 우연일 수도) 발생.
+     *
+     * 대신 *직접 _state 갱신 + rebuildStockMesh 직접 호출* — 시각화는 갱신되지만 외부
+     * mapping 은 fire 안 됨. External (WMS / application setState) 호출은 그대로 setState
+     * 거치므로 그쪽 mapping 은 정상 동작.
+     */
+    _setDataSilently(newData) {
+        const self = this;
+        if (!self._state)
+            self._state = {};
+        self._state.data = newData;
+        self._cachedState = null // state getter 가 다음 read 때 fresh build
+        ;
+        this._realObject?.rebuildStockMesh?.();
+    }
+    /**
+     * cell 이 carrier 를 받을 수 있는가.
+     *
+     * 규칙:
+     *  - state.data 에 record 가 있으면 점유 → false
+     *  - carrier-child 가 있고 *그 child 가 들여오려는 carrier 자기 자신이 아니면* → false
+     *  - 들여오려는 carrier 가 *바로 그 cell 의 child 자기 자신* 이면 → true (idempotent —
+     *    obtain('A') 직후 receive('A', sameCarrier) 가 *자기 자리 복귀* 로 동작)
+     */
+    canReceiveAt(cellId, carrier) {
+        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;
+    }
+    /**
+     * Carrier 가 rack 의 slot 으로 들어옴 — "매트릭스 진입": 즉시 dispose + state.data 에
+     * record 로 환원. 결과: InstancedMesh 가 다시 그 자리에 instance 표시, rack 의 자식
+     * 컴포넌트 트리는 깨끗.
+     */
+    async receiveAt(cellId, carrier, _options) {
+        // R18 guard — disposed carrier 의 재처리 차단.
+        if (carrier?._disposed) {
+            throw new Error(`Rack.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) 이거나 rack 자신.
+        const carrierParent = carrier.parent;
+        if (carrierParent && typeof carrierParent.removeComponent === 'function') {
+            carrierParent.removeComponent(carrier);
+        }
+        // 명시적 Three.js detach — RealObject.dispose() 의 clear() 는 *object3d 의 children*
+        // 만 정리하고 *object3d 자체* 는 scene graph 의 parent 에서 *떼지 않음*. 결과:
+        // crane fork 또는 slot anchor 에 attach 됐던 object3d 가 빈 상태로 남아 ghost.
+        // dispose 호출 *전* 에 명시적으로 parent.remove. (geometry/material dispose 는
+        // RealObject.dispose() 의 clear() 에 위임 — 공유 material 정책 framework 책임.)
+        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 회피, 위 _setDataSilently 주석 참조).
+        // 중복 방어: 동일 cellId 의 기존 record 가 있으면 제거 후 새 record 단일 추가.
+        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
+        });
+    }
+    /**
+     * Carrier 의 state 를 state.data record 로 추출. application 이 carrier subclass 별
+     * 추가 필드 인코딩 원하면 override. transform/position 관련은 record 와 무관해 skip.
+     */
+    recordFromCarrier(carrier, cellId) {
+        const state = carrier.state ?? {};
+        const SKIP_KEYS = new Set([
+            'left', 'top', 'zPos',
+            'transform', 'rotation', 'scale',
+            '_transferSlotId',
+            'cellId', // 새로 override
+            'id', // 다음 materialize 시 충돌 방지 (id 는 component-instance 의 것, record 의 것 아님)
+            '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;
+    }
+    /**
+     * SlottedHolder 컨트랙 — slot 의 attach object3d 반환. SlotTarget 이 자기
+     * `_realObject.object3d` proxy 로 사용하고, Carriable.applyHolderAttachPoint 도
+     * 이걸 attach frame 으로 사용 (transit 중 carrier 가 slot 위치에 정렬).
+     */
+    getSlotAttachObject3d(cellId) {
+        return this._ensureCellAttachObject3d(cellId);
+    }
+    /**
+     * SlottedHolder 컨트랙 — slot 의 *expected carrier* 의 3D 크기 (slot 자체의 기하 크기가
+     * 아님). Crane 의 `resolveCarrierBottomY = centerY - depth/2` 에서 *carrier 가 놓일 때
+     * 예상되는 carrier depth* 를 써야 fork 가 *carrier 바닥 = shelf* 에 정확히 진입.
+     *
+     * 즉:
+     *   depth  = stockD (= levelHeight * 0.7) — *carrier 의 vertical extent*. 전체 셀 높이
+     *            (levelHeight) 가 아닌 *실제 stock 박스 깊이*. anchor 가 stock 시각 중심 (
+     *            shelf + stockD/2) 에 위치하므로 depth = stockD 여야 bottom 계산이 shelf.
+     *   width  = bayWidth — 그대로
+     *   height = rowDepth — 그대로 (2D 의 Z 축 폭)
+     */
+    getSlotSize(cellId) {
+        const cell = this.cellMap?.findById(cellId);
+        if (!cell)
+            return undefined;
+        const stockD = cell.size.height * 0.7; // matches _ensureCellAttachObject3d + storage-rack-3d.rebuildStockMesh
+        return {
+            width: cell.size.width,
+            height: cell.size.depth, // 2D height = Z extent (front-back)
+            depth: stockD // 3D depth = carrier Y extent (NOT full level)
+        };
+    }
+    /**
+     * SlottedHolder 컨트랙 — cellId 에 대한 SlotTarget. Mover.pickAndPlace 의 dest 로 넘김.
+     *
+     * Signature overloads:
+     *   slotTargetAt('0-0-5')                  — string cellId 직접
+     *   slotTargetAt(1, 1, 6)                  — 1-based (bay, row, level)
+     */
+    slotTargetAt(idOrBay, row, level) {
+        const cellId = typeof idOrBay === 'string'
+            ? idOrBay
+            : this.cellIdOf(idOrBay, row ?? 1, level ?? 1);
+        return new SlotTarget(this, cellId);
+    }
+    /**
+     * SlotTarget 의 2D center 위임 — Mover.moveTo 의 2D path 계산에 사용.
+     *
+     * 반환값은 *rack 자체의 local frame* (rack 의 left/top 미포함) — 즉 cell 의 위치를
+     * rack 의 *내부 좌표계로* 표현. SlotTarget.toScene 이 rack.toScene 을 위임해 *rack 의
+     * rotation / 부모 chain 변환 포함* 한 절대 좌표로 변환.
+     *
+     * 이전 결함: rack.left/top 을 포함해 model-layer 프레임 좌표 반환 + toScene 미구현 →
+     * rack 이 rotated 또는 nested 일 때 X 가 어긋났음.
+     */
+    cellCenter2D(cellId) {
+        const cell = this.cellMap?.findById(cellId);
+        if (!cell)
+            return null;
+        const rs = this.state;
+        const rackWidth = rs?.width || 1000;
+        const rackHeight = rs?.height || 100;
+        const bays = Math.max(1, Math.floor(rs?.bays || 5));
+        const bayWidth = rackWidth / bays;
+        const bayIdx = cell.bay - 1;
+        // things-scene 컨벤션: 컴포넌트의 `center` 는 *parent 좌표계 의 center*
+        // (= bounds.left + width/2). 즉 *layer 좌표* — rack 의 left/top 포함, *rack 의
+        // rotation 미적용*. toScene 가 rotation 처리. parcel.center 등 모든 실제
+        // 컴포넌트가 이 컨벤션이므로 SlotTarget.center 도 동일해야 *pick 과 place 의
+        // 좌표 변환 체인 일관성* 유지.
+        return {
+            x: (rs?.left ?? 0) + bayIdx * bayWidth + bayWidth / 2,
+            y: (rs?.top ?? 0) + rackHeight / 2
+        };
+    }
+    /**
+     * SlotTarget 의 toScene 위임 — *rack-local* 좌표를 *scene-absolute* 로 변환.
+     * rack.toScene 이 rack 의 rotation / translation / parent chain 모두 처리.
+     */
+    cellToScene(localX, localY) {
+        const f = this.toScene;
+        if (typeof f === 'function')
+            return f.call(this, localX, localY);
+        return { x: localX, y: localY };
+    }
+    /** cellId 별 attach anchor object3d cache (rack.object3d 의 자식). */
+    _attachAnchorByCell = new Map();
+    /**
+     * cellId 위치에 lightweight anchor object3d 를 *singleton 으로* 보장 + 갱신.
+     * 이 anchor 가:
+     *   - Carriable.applyHolderAttachPoint 가 attach 하는 frame
+     *   - SlotTarget._realObject.object3d 의 proxy
+     *   - 두 용도가 *같은 object3d* 를 공유해 carrier 가 transient 동안 SlotTarget 의
+     *     pose 와 정확히 동기화.
+     */
+    _ensureCellAttachObject3d(cellId) {
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return undefined;
+        let obj = this._attachAnchorByCell.get(cellId);
+        if (!obj) {
+            obj = new THREE.Object3D();
+            obj.name = `rack-slot-anchor:${cellId}`;
+            ro.object3d.add(obj);
+            this._attachAnchorByCell.set(cellId, obj);
+        }
+        const cell = this.cellMap?.findById(cellId);
+        if (!cell)
+            return undefined;
+        const rs = this.state;
+        const rackWidth = rs?.width || 1000;
+        const rackDepth = rs?.depth || 3000;
+        const rackHeight = rs?.height || 600;
+        const bays = Math.max(1, Math.floor(rs?.bays || 5));
+        const levels = Math.max(1, Math.floor(rs?.levels || 4));
+        const shelfBase = Math.max(0, Math.min(rs?.shelfBaseHeight || 0, rackDepth * 0.9));
+        const shelfZone = rackDepth - shelfBase;
+        const bayWidth = rackWidth / bays;
+        const levelHeight = shelfZone / levels;
+        const stockD = levelHeight * 0.7; // ← storage-rack-3d.rebuildStockMesh 의 stockD 와 동일
+        const rowDepth = rackHeight;
+        // Anchor Y = *stock 시각 중심* (shelf + stockD/2). InstancedMesh 의 stock 박스 중심과
+        // 일치 → carrier (depth = stockD) 가 attach 시 정확히 stock 위치에 올라 앉음. Crane
+        // 의 resolveCarrierBottomY = centerY - depth/2 = shelf 라 fork 가 정확히 shelf 진입.
+        const x = cell.localPosition.x + bayWidth / 2 - rackWidth / 2;
+        const y = cell.localPosition.y - rackDepth / 2 + stockD / 2;
+        const z = cell.localPosition.z + rowDepth / 2 - rackHeight / 2;
+        obj.position.set(x, y, z);
+        obj.updateMatrixWorld(true);
+        return obj;
     }
     // ── 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) {
-        const { width, height, left, top } = this.state;
+        const left = this.state.left ?? 0;
+        const top = this.state.top ?? 0;
+        const width = this.state.width ?? 400;
+        const height = this.state.height ?? 100;
         const bays = Math.max(1, Math.floor(this.state.bays || 5));
+        const fill = this.state.fillStyle || '#a0a0a8';
+        const stroke = this.state.strokeStyle || '#555';
+        const lineWidth = this.state.lineWidth || 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() {
         return '#a0a0a8';
     }
+    // ── Data binding — state.data 변경 시 InstancedMesh 재구성 ───────────────
+    onchangeData() {
+        ;
+        this._realObject?.rebuildStockMesh?.();
+    }
+    // ── Legend — record 의 field 값 → 색상 매핑 ────────────────────────────────
+    _legendTarget;
+    /**
+     * Legend 컴포넌트 lookup. 우선순위:
+     *  1) state.legendTarget id 명시
+     *  2) scene 전체에서 `type='legend'` 첫 번째 컴포넌트 (자동 발견)
+     */
+    get legendTarget() {
+        if (this._legendTarget)
+            return this._legendTarget;
+        const id = this.state.legendTarget;
+        if (id) {
+            const found = this.root?.findById?.(id);
+            if (found) {
+                this._legendTarget = found;
+                found.on?.('change', this._onLegendChanged, this);
+                return found;
+            }
+        }
+        // scene-wide auto-discovery
+        const visit = (node) => {
+            if (!node)
+                return undefined;
+            if (node.state?.type === 'legend')
+                return node;
+            const children = node.components;
+            if (children) {
+                for (const c of children) {
+                    const r = visit(c);
+                    if (r)
+                        return r;
+                }
+            }
+            return undefined;
+        };
+        const found = visit(this.root);
+        if (found) {
+            this._legendTarget = found;
+            found.on?.('change', this._onLegendChanged, this);
+        }
+        return found;
+    }
+    _onLegendChanged = () => {
+        ;
+        this._realObject?.rebuildStockMesh?.();
+    };
+    /**
+     * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+     *   - `range.value === recordValue` (카테고리 일치)
+     *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+     *   - 매칭 없으면 `defaultColor` 또는 undefined
+     */
+    resolveLegendColor(record) {
+        const legend = this.legendTarget;
+        if (!legend)
+            return undefined;
+        const status = legend.getState?.('status') ?? legend.state?.status;
+        if (!status)
+            return undefined;
+        const field = status.field;
+        const ranges = status.ranges;
+        if (!field || !Array.isArray(ranges))
+            return undefined;
+        const value = record?.[field];
+        if (value === undefined || value === null)
+            return status.defaultColor;
+        for (const range of ranges) {
+            if (!range)
+                continue;
+            if (range.value !== undefined) {
+                if (range.value === value)
+                    return range.color;
+                continue;
+            }
+            const num = Number(value);
+            if (!Number.isFinite(num))
+                continue;
+            const min = range.min !== undefined && range.min !== '' ? Number(range.min) : undefined;
+            const max = range.max !== undefined && range.max !== '' ? Number(range.max) : undefined;
+            const minOk = min === undefined || num >= min;
+            const maxOk = max === undefined || num < max;
+            if (minOk && maxOk)
+                return range.color;
+        }
+        return status.defaultColor;
+    }
+    // ── Click event — rack-cell-click 발사 ────────────────────────────────────
+    //
+    // 사용자가 *어떤 셀*을 클릭하든 (stock 가시화된 셀이든, 빈 셀이든) rack 이 다음
+    // payload 로 `rack-cell-click` 을 emit:
+    //   { cellId, record?, hitPoint, instanceId?, isStock }
+    //
+    // 외부 consumer 등록:
+    //   rack.on('rack-cell-click', ({ cellId, record, isStock }) => { ... })
+    //
+    // 분기:
+    //   - InstancedMesh (stock) hit  → cellId/record 는 records[instanceId] 에서 직접 추출, isStock=true
+    //   - 그 외 rack mesh (shelf/frame) hit → hit.point 를 rack-local 좌표로 변환 후
+    //                                          (bay, level) 역산, record 는 state.data 검색, isStock=false
+    // edit mode 클릭은 framework 의 선택 로직 우선이라 emit 하지 않음.
+    /**
+     * things-scene EventManager3D 가 raycast → object3d.userData.context.component 의
+     * `trigger("click", mouseEvent)` 을 호출 → eventMap 으로 receive.
+     * `(self).(self).click` 으로 등록해 *우리 rack 의 어떤 mesh 든 클릭됐을 때* 발사.
+     */
+    get eventMap() {
+        return {
+            '(self)': {
+                '(self)': {
+                    click: this._onRackClick
+                }
+            }
+        };
+    }
+    _onRackClick = (mouseEvent) => {
+        // view mode 에서만 동작 (modeling 중 클릭은 framework 의 선택 로직 우선).
+        if (!this.app?.isViewMode)
+            return;
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return;
+        const hit = this._raycastRackHit(mouseEvent);
+        if (!hit)
+            return;
+        const stockMesh = ro.stockMesh;
+        let cellId;
+        let record;
+        let isStock = false;
+        let instanceId;
+        if (hit.object === stockMesh) {
+            // (A) Stock instance 직접 hit — records 에서 정확한 record 추출.
+            const records = stockMesh.userData?._records;
+            record = records?.[hit.instanceId ?? -1];
+            cellId = record?.cellId;
+            isStock = true;
+            instanceId = hit.instanceId;
+        }
+        else {
+            // (B) 빈 cell / shelf / frame hit — world point → cellId 역산.
+            const cid = this._cellIdFromWorldPoint(hit.point);
+            if (!cid || cid.startsWith('out-of-bounds'))
+                return;
+            cellId = cid;
+            const data = this.state.data;
+            record = Array.isArray(data) ? data.find(r => r?.cellId === cid) : undefined;
+        }
+        const payload = { cellId, record, hitPoint: hit.point, instanceId, isStock };
+        this.trigger('rack-cell-click', payload);
+        // Popup 호출 — 일반 mechanism (Popup 컴포넌트) 활용, anchor 만 클릭된 cell 로 override.
+        this._invokePopup(cellId, record);
+    };
+    /**
+     * state.popupRef 가 가리키는 Popup 컴포넌트를 invoke. anchor 를 SlotTarget 으로
+     * 지정 — SlotTarget._realObject.object3d 가 cellId 위치의 anchor object3d 를
+     * 가리켜 tether / projectToScreen 정확.
+     *
+     * - popupRef 미설정 → no-op (event 만 발사된 상태로 남음)
+     * - 다른 cell 클릭 시 popup 이 새 anchor 로 "이동" (Popup 의 board 등 설정 유지)
+     * - frame/empty 영역 클릭 시 호출 안 됨 → popup 그대로 유지
+     * - 명시적 close 버튼은 popup 자체의 closable 옵션이 처리
+     */
+    _invokePopup(cellId, record) {
+        const popupRefId = this.state.popupRef;
+        if (!popupRefId || !cellId)
+            return;
+        const popupComp = this.root?.findById?.(popupRefId);
+        if (!popupComp || typeof popupComp.openPopup !== 'function') {
+            console.warn(`[storage-rack] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`);
+            return;
+        }
+        const anchor = this.slotTargetAt(cellId);
+        popupComp.openPopup(record ?? { cellId }, { anchor });
+    }
+    /**
+     * 클릭 시 framework 의 mouse NDC (이미 InteractionManager 가 set 한 상태) 를 재사용해
+     * raycast → *우리 rack* 의 어떤 mesh 가 closest hit 인지 반환. 다른 object 가 더 가까우면
+     * undefined (다른 rack 또는 무관 mesh 의 hit).
+     *
+     * 접근 경로:
+     *  1. ThreeCapability — ModelLayer 는 `_threeCapability`, ThreeContainer 는 `_capability`.
+     *     capability 의 `getObjectsByRaycast()` 가 *동일한* mouse NDC 로 framework 가 click
+     *     처리 직전에 쓴 그 raycaster 를 재사용 (가장 정확).
+     *  2. capability 가 없는 컨테이너 — public scene3d / renderer3d / camera + mouseEvent
+     *     좌표로 자체 ndc 변환 후 fresh raycaster.
+     */
+    _raycastRackHit(mouseEvent) {
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return undefined;
+        const tc = ro.threeContainer;
+        if (!tc)
+            return undefined;
+        const cap = tc._threeCapability ?? tc._capability;
+        let intersects;
+        if (cap?.getObjectsByRaycast) {
+            intersects = cap.getObjectsByRaycast();
+        }
+        if (!intersects || intersects.length === 0) {
+            const scene = tc.scene3d;
+            const renderer = tc.renderer3d;
+            const camera = tc.activeCamera3d ??
+                cap?.activeCamera ??
+                cap?.camera;
+            const canvas = renderer?.domElement;
+            if (!scene || !canvas || !camera)
+                return undefined;
+            const rect = canvas.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0)
+                return undefined;
+            const ndc = new THREE.Vector2(((mouseEvent.clientX - rect.left) / rect.width) * 2 - 1, -((mouseEvent.clientY - rect.top) / rect.height) * 2 + 1);
+            const raycaster = new THREE.Raycaster();
+            raycaster.setFromCamera(ndc, camera);
+            intersects = raycaster.intersectObjects(scene.children, true);
+        }
+        if (!intersects || intersects.length === 0)
+            return undefined;
+        // Three.js intersectObjects 는 distance 오름차순 정렬. 첫 hit 이 *우리 rack* 의 descendant
+        // 인지 확인 (userData.context walk-up 으로). 다른 object 가 더 가까우면 (다른 rack 또는
+        // 무관 mesh 가 사이에 있음) — 무시.
+        const closest = intersects[0];
+        let obj = closest.object;
+        while (obj) {
+            if (obj.userData?.context === ro)
+                return closest;
+            obj = obj.parent;
+        }
+        return undefined;
+    }
+    /**
+     * world point → cellId 역산.
+     *
+     *   1. rack 의 `matrixWorld.invert()` 로 world → rack-local 변환 (rack 의 회전·이동
+     *      반영)
+     *   2. rack-local point 의 `(x, y)` 를 (bay, level) 격자에 매핑
+     *
+     * 범위 밖이면 `"out-of-bounds(...)"` 문자열 반환 (caller 가 무시).
+     */
+    _cellIdFromWorldPoint(worldPoint) {
+        const ro = this._realObject;
+        if (!ro?.object3d)
+            return null;
+        const local = new THREE.Vector3().copy(worldPoint);
+        const mInv = new THREE.Matrix4().copy(ro.object3d.matrixWorld).invert();
+        local.applyMatrix4(mInv);
+        const bays = Math.max(1, Math.floor(this.state.bays || 5));
+        const levels = Math.max(1, Math.floor(this.state.levels || 4));
+        const width = this.state.width || 1000;
+        const depth = this.state.depth || 3000;
+        const shelfBase = this.state.shelfBaseHeight || 0;
+        const shelfZone = depth - shelfBase;
+        const bayWidth = width / bays;
+        const levelHeight = shelfZone / levels;
+        // rack 의 3D origin = rack center. X: [-width/2,+width/2], Y: [-depth/2,+depth/2]
+        const bayIdx = Math.floor((local.x + width / 2) / bayWidth);
+        const yFromBottom = local.y + depth / 2 - shelfBase;
+        const levelIdx = Math.floor(yFromBottom / levelHeight);
+        const rowIdx = 0; // storage-rack 은 rows=1
+        if (bayIdx < 0 || bayIdx >= bays || levelIdx < 0 || levelIdx >= levels) {
+            return `out-of-bounds(bay=${bayIdx}, level=${levelIdx})`;
+        }
+        return `${bayIdx}-${rowIdx}-${levelIdx}`;
+    }
     // ── 3D ───────────────────────────────────────────────────────────────────
     buildRealObject() {
         return new StorageRack3D(this);