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

package/src/storage-rack.ts

@@ -3,15 +3,19 @@
  */
 import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
 import type { State, Material3D } from '@hatiolab/things-scene'
+import * as THREE from 'three'
 import {
   CellContainer,
   CellMap,
   CarrierHolder,
   Placeable,
+  SlotTarget,
   type AttachFrame,
   type Alignment,
   type Heights,
-  type PlacementArchetype
+  type PlacementArchetype,
+  type SlotRecord,
+  type SlottedHolder
 } from '@operato/scene-base'
 
 import { StorageRack3D } from './storage-rack-3d.js'
@@ -22,6 +26,51 @@ export interface StorageRackState extends State {
   bays?: number
   levels?: number
 
+  /**
+   * Level 1 (첫 shelf) 의 *시작 높이* (mm, rack 의 3D Y 축, 바닥부터). 미명시 0
+   * (바닥 = 첫 shelf). 양수 시 그만큼 위로 올라가 stocker port / conveyor 같은
+   * 컴포넌트가 들어갈 *빈 공간* 확보. Frame uprights 는 바닥 ~ 천장 그대로.
+   */
+  shelfBaseHeight?: number
+
+  /**
+   * 적재 시각화 데이터. 배열의 각 record 는 최소 `cellId` 필드가 필요. cellMap 에
+   * 존재하는 cellId 만 InstancedMesh 의 instance 로 렌더링됨 (한 박스 = 한 cell).
+   * Plan A: 이 record 들이 *"매트릭스 안"* 의 carrier — obtainCarrier 가 materialize
+   * 시 record 빠짐, receiveAt 시 record push. pickAndPlace 와 양방향 atomic sync.
+   */
+  data?: Array<{ cellId: string; [key: string]: any }>
+
+  /**
+   * RackCell 컴포넌트의 eager 생성 여부.
+   *  - `undefined` (default): state.data 있으면 false (batched, 메모리 절약),
+   *    없으면 true (legacy non-batched, RackCell-based Mover 호환).
+   *  - `true`: 명시적 eager — 모든 cell 을 RackCell 로 생성.
+   *  - `false`: 명시적 skip — Plan A 의 slot API 만 사용 (obtainCarrier / slotTargetAt).
+   */
+  eagerCells?: boolean
+
+  /**
+   * Legend 컴포넌트의 id. legend 의 `state.status = {field, ranges:[{value|min,max, color}], defaultColor}`
+   * 를 사용해 각 record 의 `field` 값을 색상으로 매핑. 미명시 시 scene-wide auto-discovery
+   * (type='legend' 인 첫 번째 컴포넌트).
+   */
+  legendTarget?: string
+
+  /**
+   * Cell 클릭 시 invoke 할 things-scene `Popup` 컴포넌트의 id. Popup 컴포넌트는 scene
+   * 어딘가에 일반 컴포넌트로 배치되어 있고, 그 자체의 state (board / modal / closable /
+   * draggable / tether / billboard 등) 가 popup 동작을 정의. rack 은 *anchor 만 동적으로*
+   * override 해 호출 — 클릭된 cell 위에 popup 이 뜸.
+   *
+   * 미명시 시 popup 비활성 (rack-cell-click 이벤트는 여전히 발사 — 외부 consumer 가
+   * 직접 처리 가능).
+   */
+  popupRef?: string
+
+  /** 가로 frame (beam) 만 숨김 — uprights 는 유지. */
+  hideHorizontalFrame?: boolean
+
   // ── 디버그 ──
   debugCells?: boolean
 
@@ -45,6 +94,31 @@ const NATURE: ComponentNature = {
       label: 'bays',
       name: 'bays',
       placeholder: '# of horizontal bays (default 5)'
+    },
+    {
+      type: 'number',
+      label: 'shelf-base-height',
+      name: 'shelfBaseHeight',
+      placeholder: 'mm — level 1 시작 높이 (바닥부터). stocker port / conveyor 공간.'
+    },
+    {
+      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'
@@ -59,22 +133,28 @@ const NATURE: ComponentNature = {
 //   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(): number {
+  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.
  *
@@ -83,7 +163,10 @@ const NATURE: ComponentNature = {
  * the cell topology and pickable contract stay the same.
  */
 @sceneComponent('storage-rack')
-export default class Rack extends CellContainer(CarrierHolder(Placeable(ContainerAbstract))) {
+export default class Rack
+  extends CellContainer(CarrierHolder(Placeable(ContainerAbstract)))
+  implements SlottedHolder
+{
   declare state: StorageRackState
 
   static placement: PlacementArchetype = 'floor'
@@ -98,6 +181,27 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
     return []
   }
 
+  /**
+   * Runtime — bays / levels 변경 시 anchor 캐시 무효화. cell 위치가 바뀌므로 다음
+   * `_ensureCellAttachObject3d` 호출이 새 좌표로 갱신.
+   */
+  onchange(after: Record<string, unknown>, _before: Record<string, unknown>): void {
+    super.onchange?.(after, _before)
+    if (
+      'bays' in after ||
+      'levels' in after ||
+      'shelfBaseHeight' in after ||
+      'width' in after ||
+      'height' in after ||
+      'depth' in after
+    ) {
+      this._attachAnchorByCell.clear()
+    }
+    if ('hideHorizontalFrame' in after) {
+      ;(this._realObject as any)?.applyFrameVisibility?.()
+    }
+  }
+
   // ── CellContainer ─────────────────────────────────────────────────────────
 
   /**
@@ -116,6 +220,11 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
     const width = (this.state.width as number) || 1000
     const rackDepth = (this.state.depth as number) || 3000   // Y: floor→ceiling
     const rackHeight = (this.state.height as number) || 600  // Z: front→back
+    const shelfBase = Math.max(0, Math.min(
+      (this.state.shelfBaseHeight as number) || 0,
+      rackDepth * 0.9                                        // clamp ≤ 90% — 최소 shelf zone
+    ))
+    const shelfZone = rackDepth - shelfBase                  // 실제 shelf 가 차지하는 Y 영역
 
     return CellMap.grid({
       bays,
@@ -123,108 +232,751 @@ export default class Rack extends CellContainer(CarrierHolder(Placeable(Containe
       levels,
       bayWidth: width / bays,
       rowDepth: rackHeight,
-      levelHeight: rackDepth / levels
+      levelHeight: shelfZone / levels,
+      origin: { x: 0, y: shelfBase, z: 0 }                   // 첫 cell 의 Y = shelfBase
     })
   }
 
+  // ── Container gates ───────────────────────────────────────────────────────
+
   /**
-   * Create RackCell child components for each cell in the CellMap.
+   * Allow:
+   *   - Carriable components (pallets, boxes, parcels) — direct children, operation archetype.
    *
-   * Called explicitly to enter simulation mode — monitoring-mode racks
-   * never call this (carriers are direct children, no explicit cells).
+   * Block:
+   *   - Everything else (sensors, labels, etc. can be siblings of the rack, not children).
+   */
+  containable(component: Component): boolean {
+    const archetype = (component.constructor as any).placement
+    if (archetype === 'operation') return true
+    return component.isDescendible(this)
+  }
+
+  // ── CarrierHolder — attach frame for direct carrier children ─────────────
+
+  /**
+   * Attach frame for direct-child carriers — Plan A 의 모든 carrier 가 rack 의
+   * 직접 자식이므로 매번 호출됨. carrier 의 state.cellId 에 해당하는 *cell-local
+   * anchor object3d* 를 반환 → carrier 의 object3d 가 자동으로 셀 위치에 정렬됨.
+   */
+  attachPointFor(carrier: Component): AttachFrame | null {
+    // 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 as any)?.state?.cellId as string | undefined
+    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, 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(): ReadonlyArray<{ cellId: string; [key: string]: any }> {
+    return (this.state.data as any) ?? []
+  }
+
+  /**
+   * 1-based (bay, row, level) → 0-based cellId 문자열.
    *
-   * Idempotent: removes existing rack-cell children first.
+   *   rack.cellIdOf(1, 1, 6)  →  '0-0-5'
+   *   rack.cellIdOf(3, 1, 4)  →  '2-0-3'
    */
-  _buildCells(): void {
-    // Remove existing rack-cell children
-    const existing = (this.components as Component[] | undefined) ?? []
-    for (const child of [...existing]) {
-      if ((child as any).state?.type === 'storage-cell') {
-        this.removeComponent(child)
-      }
+  cellIdOf(bay: number, row: number = 1, level: number = 1): string {
+    return `${bay - 1}-${row - 1}-${level - 1}`
+  }
+
+  /** cellId 에 carrier 가 있는가 — child carrier 또는 state.data record 어느 쪽이든. */
+  hasCarrierAt(cellId: string): boolean {
+    if (this._carrierChildAt(cellId)) return true
+    return this.records.some(r => r.cellId === cellId)
+  }
+
+  /** cellId 매칭되는 rack 의 직접 자식 carrier (operation archetype). */
+  private _carrierChildAt(cellId: string): Component | undefined {
+    const children = (this.components as Component[] | undefined) ?? []
+    return children.find(c => {
+      const placement = (c.constructor as any).placement
+      return placement === 'operation' && (c.state as any)?.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: string | number, row?: number, level?: number): Component | null {
+    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 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(`[storage-rack] obtainCarrier("${cellId}"): carrier type "${carrierType}" 미등록`)
+      return null
     }
 
-    // Create a RackCell for each cell in the map
-    const RackCellClass = (Component as any).register('storage-cell') as (new (...args: any[]) => Component) | undefined
-    if (!RackCellClass) {
-      console.warn('Rack._buildCells: rack-cell type not registered. Import rack-cell.ts first.')
+    // 크기 기본값 — rack 기하에서 derive (record 가 명시 안 한 경우)
+    const rs: any = 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 as any
+    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: any = {
+      ...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 as any)._app)
+    // *silent: true* — Plan A 의 transient materialize 는 사용자가 직접 컴포넌트
+    // 만든 게 아니라 *내부적으로 잠시 빌리는 것*. 새 컴포넌트 추가 → root.onadded
+    // → refreshMappings (1s debounce) → 모든 컴포넌트 매핑 재실행 의 cascade 차단.
+    // (silent 모드: _silentAdd 플래그 set → refreshMappings skip)
+    ;(this as any).addComponent(carrier, { silent: true })
+
+    // 3D 강제 빌드 + attach (pipeline tick 없이도 즉시 표시 — Mover 가 곧 pick).
+    void (carrier as any).realObject
+    ;(carrier as any).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 은 정상 동작.
+   */
+  private _setDataSilently(newData: any[]): void {
+    const self = this as any
+    if (!self._state) self._state = {}
+    self._state.data = newData
+    self._cachedState = null   // state getter 가 다음 read 때 fresh build
+    ;(this._realObject as any)?.rebuildStockMesh?.()
+  }
+
+  /**
+   * cell 이 carrier 를 받을 수 있는가.
+   *
+   * 규칙:
+   *  - state.data 에 record 가 있으면 점유 → false
+   *  - carrier-child 가 있고 *그 child 가 들여오려는 carrier 자기 자신이 아니면* → false
+   *  - 들여오려는 carrier 가 *바로 그 cell 의 child 자기 자신* 이면 → true (idempotent —
+   *    obtain('A') 직후 receive('A', sameCarrier) 가 *자기 자리 복귀* 로 동작)
+   */
+  canReceiveAt(cellId: string, carrier?: Component): boolean {
+    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
+  }
+
+  /**
+   * Carrier 가 rack 의 slot 으로 들어옴 — "매트릭스 진입": 즉시 dispose + state.data 에
+   * record 로 환원. 결과: InstancedMesh 가 다시 그 자리에 instance 표시, rack 의 자식
+   * 컴포넌트 트리는 깨끗.
+   */
+  async receiveAt(cellId: string, carrier: Component, _options?: any): Promise<void> {
+    // R18 guard — disposed carrier 의 재처리 차단.
+    if ((carrier as any)?._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 as any).trigger?.('transfer-rejected', {
+        type: 'transfer-rejected',
+        component: carrier, container: this, reason: 'slot-occupied', cellId
+      })
       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)
+    const record = this.recordFromCarrier(carrier, cellId)
+
+    // Carrier 의 parent 에서 떼고 dispose. parent 는 보통 mover (crane) 이거나 rack 자신.
+    const carrierParent: any = (carrier as any).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: 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 회피, 위 _setDataSilently 주석 참조).
+    // 중복 방어: 동일 cellId 의 기존 record 가 있으면 제거 후 새 record 단일 추가.
+    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
+    })
   }
 
-  // ── Container gates ───────────────────────────────────────────────────────
+  /**
+   * Carrier 의 state 를 state.data record 로 추출. application 이 carrier subclass 별
+   * 추가 필드 인코딩 원하면 override. transform/position 관련은 record 와 무관해 skip.
+   */
+  recordFromCarrier(carrier: Component, cellId: string): { cellId: string; [key: string]: any } {
+    const state: any = (carrier as any).state ?? {}
+    const SKIP_KEYS = new Set([
+      'left', 'top', 'zPos',
+      'transform', 'rotation', 'scale',
+      '_transferSlotId',
+      'cellId',  // 새로 override
+      'id',      // 다음 materialize 시 충돌 방지 (id 는 component-instance 의 것, record 의 것 아님)
+      '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 record
+  }
 
   /**
-   * Allow:
-   *   - Carriable components (pallets, boxes, parcels) — direct children in monitoring mode.
-   *   - RackCell — created by _buildCells() in simulation mode.
+   * SlottedHolder 컨트랙 — slot 의 attach object3d 반환. SlotTarget 이 자기
+   * `_realObject.object3d` proxy 로 사용하고, Carriable.applyHolderAttachPoint 도
+   * 이걸 attach frame 으로 사용 (transit 중 carrier 가 slot 위치에 정렬).
+   */
+  getSlotAttachObject3d(cellId: string): THREE.Object3D | undefined {
+    return this._ensureCellAttachObject3d(cellId)
+  }
+
+  /**
+   * SlottedHolder 컨트랙 — slot 의 *expected carrier* 의 3D 크기 (slot 자체의 기하 크기가
+   * 아님). Crane 의 `resolveCarrierBottomY = centerY - depth/2` 에서 *carrier 가 놓일 때
+   * 예상되는 carrier depth* 를 써야 fork 가 *carrier 바닥 = shelf* 에 정확히 진입.
    *
-   * Block:
-   *   - Everything else (sensors, labels, etc. can be siblings of the rack, not children).
+   * 즉:
+   *   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 축 폭)
    */
-  containable(component: Component): boolean {
-    if ((component as any).state?.type === 'storage-cell') return true
-    const archetype = (component.constructor as any).placement
-    if (archetype === 'operation') return true
-    return component.isDescendible(this)
+  getSlotSize(cellId: string): { width: number; height: number; depth: number } | undefined {
+    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)
+    }
   }
 
-  // ── CarrierHolder — attach frame for direct carrier children ─────────────
+  /**
+   * 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: string | number, row?: number, level?: number): SlotTarget {
+    const cellId = typeof idOrBay === 'string'
+      ? idOrBay
+      : this.cellIdOf(idOrBay, row ?? 1, level ?? 1)
+    return new SlotTarget(this, cellId)
+  }
 
   /**
-   * Attach frame for carriers that are DIRECT children of the rack
-   * (monitoring mode, where carriers go directly into the rack without
-   * explicit RackCell components).
+   * SlotTarget 의 2D center 위임 — Mover.moveTo 의 2D path 계산에 사용.
    *
-   * 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).
+   * 반환값은 *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 가 어긋났음.
    */
-  attachPointFor(_carrier: Component): AttachFrame | null {
-    const root = this._realObject?.object3d
-    if (!root) return null
-    return { attach: root }
+  cellCenter2D(cellId: string): { x: number; y: number } | null {
+    const cell = this.cellMap?.findById(cellId)
+    if (!cell) return null
+    const rs: any = 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: number, localY: number): { x: number; y: number } {
+    const f = (this as any).toScene
+    if (typeof f === 'function') return f.call(this, localX, localY)
+    return { x: localX, y: localY }
+  }
+
+  /** cellId 별 attach anchor object3d cache (rack.object3d 의 자식). */
+  private _attachAnchorByCell: Map<string, THREE.Object3D> = new Map()
+
+  /**
+   * cellId 위치에 lightweight anchor object3d 를 *singleton 으로* 보장 + 갱신.
+   * 이 anchor 가:
+   *   - Carriable.applyHolderAttachPoint 가 attach 하는 frame
+   *   - SlotTarget._realObject.object3d 의 proxy
+   *   - 두 용도가 *같은 object3d* 를 공유해 carrier 가 transient 동안 SlotTarget 의
+   *     pose 와 정확히 동기화.
+   */
+  private _ensureCellAttachObject3d(cellId: string): THREE.Object3D | undefined {
+    const ro: any = (this as any)._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: any = 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: CanvasRenderingContext2D) {
-    const { width, height, left, top } = this.state
+    const left = (this.state.left as number) ?? 0
+    const top = (this.state.top as number) ?? 0
+    const width = (this.state.width as number) ?? 400
+    const height = (this.state.height as number) ?? 100
     const bays = Math.max(1, Math.floor((this.state.bays as number) || 5))
+    const fill = (this.state.fillStyle as string) || '#a0a0a8'
+    const stroke = (this.state.strokeStyle as string) || '#555'
+    const lineWidth = (this.state.lineWidth as number) || 1
 
+    // Fill (반투명)
+    ctx.save()
+    ctx.fillStyle = fill
+    ctx.globalAlpha = 0.2
+    ctx.fillRect(left, top, width, height)
+    ctx.restore()
+
+    // Stroke — outer + bay subdivisions
+    ctx.strokeStyle = stroke
+    ctx.lineWidth = lineWidth
+    ctx.strokeRect(left, top, width, height)
     ctx.beginPath()
-    // Outer rectangle
-    ctx.rect(left, top, width, height)
-    // Bay subdivisions (vertical lines)
     for (let i = 1; i < bays; i++) {
       const x = left + (width * i) / bays
       ctx.moveTo(x, top)
       ctx.lineTo(x, top + height)
     }
+    ctx.stroke()
   }
 
   get fillStyle() {
     return '#a0a0a8'
   }
 
+  // ── Data binding — state.data 변경 시 InstancedMesh 재구성 ───────────────
+
+  onchangeData(): void {
+    ;(this._realObject as any)?.rebuildStockMesh?.()
+  }
+
+  // ── Legend — record 의 field 값 → 색상 매핑 ────────────────────────────────
+
+  private _legendTarget?: Component
+
+  /**
+   * Legend 컴포넌트 lookup. 우선순위:
+   *  1) state.legendTarget id 명시
+   *  2) scene 전체에서 `type='legend'` 첫 번째 컴포넌트 (자동 발견)
+   */
+  get legendTarget(): Component | undefined {
+    if (this._legendTarget) return this._legendTarget
+
+    const id = this.state.legendTarget
+    if (id) {
+      const found = (this.root as any)?.findById?.(id) as Component | undefined
+      if (found) {
+        this._legendTarget = found
+        ;(found as any).on?.('change', this._onLegendChanged, this)
+        return found
+      }
+    }
+
+    // scene-wide auto-discovery
+    const visit = (node: any): Component | undefined => {
+      if (!node) return undefined
+      if (node.state?.type === 'legend') return node as Component
+      const children = node.components as Component[] | undefined
+      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 as any).on?.('change', this._onLegendChanged, this)
+    }
+    return found
+  }
+
+  private _onLegendChanged = (): void => {
+    ;(this._realObject as any)?.rebuildStockMesh?.()
+  }
+
+  /**
+   * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+   *   - `range.value === recordValue` (카테고리 일치)
+   *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+   *   - 매칭 없으면 `defaultColor` 또는 undefined
+   */
+  resolveLegendColor(record: any): string | undefined {
+    const legend = this.legendTarget
+    if (!legend) return undefined
+    const status: any = (legend as any).getState?.('status') ?? (legend.state as any)?.status
+    if (!status) return undefined
+
+    const field = status.field as string | undefined
+    const ranges = status.ranges as any[] | undefined
+    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 as string | undefined
+  }
+
+  // ── 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
+        }
+      }
+    }
+  }
+
+  private _onRackClick = (mouseEvent: MouseEvent) => {
+    // view mode 에서만 동작 (modeling 중 클릭은 framework 의 선택 로직 우선).
+    if (!(this as any).app?.isViewMode) return
+
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return
+
+    const hit = this._raycastRackHit(mouseEvent)
+    if (!hit) return
+
+    const stockMesh: THREE.InstancedMesh | undefined = ro.stockMesh
+    let cellId: string | undefined
+    let record: any
+    let isStock = false
+    let instanceId: number | undefined
+
+    if (hit.object === stockMesh) {
+      // (A) Stock instance 직접 hit — records 에서 정확한 record 추출.
+      const records: any[] | undefined = (stockMesh as any).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 as Array<any> | undefined
+      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 옵션이 처리
+   */
+  private _invokePopup(cellId: string | undefined, record: any): void {
+    const popupRefId = this.state.popupRef
+    if (!popupRefId || !cellId) return
+    const popupComp: any = (this.root as any)?.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.
+   */
+  private _raycastRackHit(mouseEvent: MouseEvent): THREE.Intersection | undefined {
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return undefined
+
+    const tc: any = ro.threeContainer
+    if (!tc) return undefined
+
+    const cap: any = tc._threeCapability ?? tc._capability
+    let intersects: THREE.Intersection[] | undefined
+    if (cap?.getObjectsByRaycast) {
+      intersects = cap.getObjectsByRaycast() as THREE.Intersection[] | undefined
+    }
+
+    if (!intersects || intersects.length === 0) {
+      const scene = tc.scene3d as THREE.Scene | undefined
+      const renderer = tc.renderer3d as THREE.WebGLRenderer | undefined
+      const camera =
+        (tc.activeCamera3d as THREE.Camera | undefined) ??
+        (cap?.activeCamera as THREE.Camera | undefined) ??
+        (cap?.camera as THREE.Camera | undefined)
+      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: THREE.Object3D | null = 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 가 무시).
+   */
+  private _cellIdFromWorldPoint(worldPoint: THREE.Vector3): string | null {
+    const ro: any = (this as any)._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 as number) || 5))
+    const levels = Math.max(1, Math.floor((this.state.levels as number) || 4))
+    const width = (this.state.width as number) || 1000
+    const depth = (this.state.depth as number) || 3000
+    const shelfBase = (this.state.shelfBaseHeight as number) || 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(): RealObject | undefined {