@operato/scene-storage 10.0.0-beta.50 → 10.0.0-beta.53

package/src/box.ts

@@ -13,6 +13,7 @@ import {
 import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
+  Identifiable,
   Legendable,
   Placeable,
   type Alignment,
@@ -81,7 +82,7 @@ const NATURE: ComponentNature = {
  * scene-tree). If a future use case needs nested boxes, extend Container.
  */
 @sceneComponent('box')
-export default class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {
+export default class Box extends Identifiable(Carriable(Legendable(Placeable(RectPath(Shape))))) {
   declare state: BoxState
 
   static legends: Record<string, LegendBinding> = {

package/src/pallet.ts

@@ -15,6 +15,7 @@ import {
 import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
+  Identifiable,
   Legendable,
   Placeable,
   type Alignment,
@@ -122,7 +123,7 @@ const NATURE: ComponentNature = {
  * detection.
  */
 @sceneComponent('pallet')
-export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbstract))) {
+export default class Pallet extends Identifiable(Carriable(Legendable(Placeable(ContainerAbstract)))) {
   declare state: PalletState
 
   static legends: Record<string, LegendBinding> = {

package/src/parcel.ts

@@ -13,6 +13,7 @@ import {
 import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
+  Identifiable,
   Placeable,
   type Alignment,
   type PlacementArchetype
@@ -62,7 +63,7 @@ const NATURE: ComponentNature = {
  * inspected indicators would add a status legend then.
  */
 @sceneComponent('parcel')
-export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
+export default class Parcel extends Identifiable(Carriable(Placeable(RectPath(Shape)))) {
   declare state: ParcelState
 
   static placement: PlacementArchetype = 'operation'

package/src/picking-station.ts

@@ -14,11 +14,12 @@ import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
-  SlotTarget,
+  SingleSlotHolder,
   type AttachFrame,
   type Alignment,
   type Heights,
-  type PlacementArchetype
+  type PlacementArchetype,
+  type ProcessStep
 } from '@operato/scene-base'
 
 import { PickingStation3D } from './picking-station-3d.js'
@@ -52,7 +53,10 @@ const NATURE: ComponentNature = {
 }
 
 @sceneComponent('picking-station')
-export default class PickingStation extends CarrierHolder(Placeable(ContainerAbstract)) {
+export default class PickingStation
+  extends SingleSlotHolder()(CarrierHolder(Placeable(ContainerAbstract)))
+  implements ProcessStep
+{
   declare state: PickingStationState
   declare _realObject?: PickingStation3D
 
@@ -63,57 +67,30 @@ export default class PickingStation extends CarrierHolder(Placeable(ContainerAbs
   get nature(): ComponentNature { return NATURE }
   get anchors() { return [] }
 
-  // ── SlottedHolder duck-type (단일 slot 'station') ─────────────
-  slotIds(): ReadonlyArray<string> { return [SLOT_ID] }
-
-  hasCarrierAt(slotId: string): boolean {
-    return slotId === SLOT_ID &&
-      ((this as any).components ?? []).some((c: any) => c?.isCarriable)
-  }
-  canReceiveAt(slotId: string, _carrier?: Component): boolean {
-    return slotId === SLOT_ID && !this.hasCarrierAt(slotId)
-  }
-  occupiedSlotIds(): ReadonlyArray<string> {
-    return this.hasCarrierAt(SLOT_ID) ? [SLOT_ID] : []
-  }
-  emptySlotIds(): ReadonlyArray<string> {
-    return this.hasCarrierAt(SLOT_ID) ? [] : [SLOT_ID]
-  }
-  obtainCarrier(slotId: string): Component | null {
-    if (slotId !== SLOT_ID) return null
-    return ((this as any).components ?? []).find((c: any) => c?.isCarriable) ?? null
-  }
+  // SingleSlotHolder hook overrides ───────────────────────────────────────────
+  _singleSlotId() { return SLOT_ID }
 
   /**
-   * carrier 도착 — components + 3D 로 reparent (Spot 패턴). processingTimeMs > 0
-   * 이면 status='processing' 으로 전환했다가 timer 후 'idle' 로 복귀.
+   * SlottedHolder duck (slotIds / hasCarrierAt / canReceiveAt / occupiedSlotIds
+   * / emptySlotIds / obtainCarrier / receiveAt / accept / receive / slotTargetAt
+   * / getSlotAttachObject3d) — SingleSlotHolder mixin 제공.
    *
-   * 단순 setTimeout — frameClock 통합(view-mode/일시정지 동기) 은 추후.
+   * receiveAt 후 부가 dwell 동작은 `_onCarrierReceived` hook 으로 위임.
    */
-  async receiveAt(_slotId: string, carrier: Component, options?: any): Promise<void> {
-    ;(this as any).reparent?.(carrier, { ...(options ?? {}), animated: false })
+  _onCarrierReceived(_carrier: Component, _options?: any) {
     const procMs = this.state.processingTimeMs ?? 0
-    if (procMs > 0) {
-      this.setState({ status: 'processing' as PickingStationStatus })
-      setTimeout(() => {
-        if ((this.state.status as PickingStationStatus) === 'processing') {
-          this.setState({ status: 'idle' as PickingStationStatus })
-        }
-      }, procMs)
-    }
-  }
-
-  async accept(carrier: Component, options?: any): Promise<void> {
-    return this.receiveAt(SLOT_ID, carrier, options)
-  }
-  async receive(carrier: Component, options?: any): Promise<void> {
-    return this.receiveAt(SLOT_ID, carrier, options)
-  }
-
-  slotTargetAt(slotId: string): SlotTarget { return new SlotTarget(this as any, slotId) }
-  getSlotAttachObject3d(_slotId: string): any {
-    return (this as any)._realObject?.getAttachFrame?.()
-  }
+    if (procMs <= 0) return
+    this.setState({ status: 'processing' as PickingStationStatus })
+    setTimeout(() => {
+      if ((this.state.status as PickingStationStatus) === 'processing') {
+        this.setState({ status: 'idle' as PickingStationStatus })
+      }
+    }, procMs)
+  }
+
+  // Phase ZT-V PR-6 ProcessStep ─────────────────────────────────────────────
+  readonly isProcessStep = true as const
+  get processingTimeMs() { return this.state.processingTimeMs ?? 0 }
 
   /** carrier 를 작업대(table) 상단에 안착. */
   attachPointFor(carrier: Component): AttachFrame | null {

package/src/rack-grid.ts

@@ -38,6 +38,7 @@ import * as THREE from 'three'
 import {
   CarrierHolder,
   Placeable,
+  RecordStorage,
   SlotTarget,
   componentBoundingBox,
   type AttachFrame,
@@ -268,11 +269,25 @@ export interface RackGridState extends State {
 
 @sceneComponent('rack-grid')
 export default class RackGrid
-  extends CarrierHolder(Placeable(ContainerAbstract))
+  extends RecordStorage<{ cellId: string; [key: string]: any }>()(
+    CarrierHolder(Placeable(ContainerAbstract))
+  )
   implements SlottedHolder
 {
   declare state: RackGridState
 
+  // RecordStorage mixin hook overrides.
+  // record.cellId 가 slotId (3-segment '{col}-{row}-{shelf}' format).
+  _recordToSlotId(record: { cellId: string }): string {
+    return record.cellId ?? ''
+  }
+  // 3D rebuild — rebuildStockMesh 우선, 없으면 mixin default.
+  _rebuildVisual(): void {
+    const ro = (this as any)._realObject
+    if (ro?.rebuildStockMesh) ro.rebuildStockMesh()
+    else if (ro?.update) ro.update()
+  }
+
   // Phase Auto-Nav (AN-PR-2) — Obstacle 자격. AMR / mover 의 자동 path planning
   // 시 회피 대상. `state.isObstacle` 명시 false 시 override (예외 처리).
   get isObstacle(): boolean {
@@ -417,63 +432,8 @@ export default class RackGrid
     ;(this._realObject as any)?.rebuildStockMesh?.()
   }
 
-  /** state.data 의 records — Plan A 의 stock 보관소. */
-  get records(): Array<{ cellId: string; [key: string]: any }> {
-    return (this.state.data as any) ?? []
-  }
+  // records / legendTarget / _onLegendChanged / resolveLegendColor — RecordStorage mixin 제공.
 
-  // ── Legend integration ──────────────────────────────────
-
-  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
-      }
-    }
-
-    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
-   */
   // ── View-mode click → rack-grid-cell-click event + popup ──
 
   get eventMap() {
@@ -516,24 +476,13 @@ export default class RackGrid
 
     const payload = { cellId, record, hitPoint: hit.point, instanceId, isStock }
     this.trigger('rack-grid-cell-click', payload)
-    this._invokePopup(cellId, record)
+    if (cellId) this._invokePopup(cellId, record ?? { cellId })
 
     // popup 외부 click 으로 인식되어 자동 close 되는 회귀 차단
     mouseEvent.stopPropagation?.()
   }
 
-  /** state.popupRef Popup 컴포넌트 invoke. anchor = 클릭된 cell 의 SlotTarget. */
-  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(`[rack-grid] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`)
-      return
-    }
-    const anchor = this.slotTargetAt(cellId)
-    popupComp.openPopup(record ?? { cellId }, { anchor })
-  }
+  // _invokePopup — RecordStorage mixin 제공 (signature 동일: slotId=cellId, payload=record).
 
   /** raycast → 우리 RackGrid 의 어떤 mesh 가 closest hit 인지. */
   private _raycastHit(mouseEvent: MouseEvent): THREE.Intersection | undefined {
@@ -612,35 +561,7 @@ export default class RackGrid
     return `${col}-${row}-${shelf}`
   }
 
-  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
-  }
+  // resolveLegendColor — RecordStorage mixin 제공.
 
   /**
    * 새 (rows × columns) 에 맞춰 children 재구성. rack-table.buildCells 정확 클론.
@@ -1251,7 +1172,7 @@ export default class RackGrid
     const cellId = this._resolveToCellId(slotIdOrLocation)
     if (!cellId) return false
     if (this._carrierChildAt(cellId)) return true
-    return this.records.some(r => r.cellId === cellId)
+    return this.records.some((r: any) => r.cellId === cellId)
   }
 
   /**

package/src/spot.ts

@@ -34,7 +34,7 @@ import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
-  SlotTarget,
+  SingleSlotHolder,
   type AttachFrame,
   type Alignment,
   type Heights,
@@ -69,7 +69,11 @@ const NATURE: ComponentNature = {
 // which forces `isHTMLElement(): true` and trips the 3D pipeline's
 // addObject DOM-skip gate. Spot is purely 3D.
 @sceneComponent('spot')
-export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
+export default class Spot extends SingleSlotHolder()(
+  CarrierHolder(Placeable(ContainerAbstract))
+) {
+  // SingleSlotHolder hook override — Spot 의 slot id 'pad'.
+  _singleSlotId() { return SPOT_SLOT_ID }
   declare state: SpotState
   declare _realObject?: Spot3D
 
@@ -169,63 +173,11 @@ export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
     }
   }
 
-  // ── SlottedHolder 자격 (single virtual slot) ───────────────────────────────
-  // Spot 은 CarrierHolder(child attach + attachPointFor 로 상판 위)라서 물리/시각은
-  // 완벽하다. 다만 transfer planner 의 getHoldersInScope(=isSlottedHolder duck-type)에
-  // 잡히고, multi-hop handoff 에서 다음 mover 가 obtainCarrier 로 carrier 를 승계하려면
-  // SlottedHolder duck-type 도 갖춰야 한다. carrier 는 child 로 그대로 유지(dispose
-  // 안 함) — virtual location 의 handoff buffer 동작.
-  slotIds(): string[] {
-    return [SPOT_SLOT_ID]
-  }
-  hasCarrierAt(slotId: string): boolean {
-    return slotId === SPOT_SLOT_ID &&
-      ((this as any).components ?? []).some((c: any) => c?.isCarriable)
-  }
-  canReceiveAt(slotId: string, _carrier?: Component): boolean {
-    return slotId === SPOT_SLOT_ID && !this.hasCarrierAt(slotId)
-  }
-  occupiedSlotIds(): ReadonlyArray<string> {
-    return this.hasCarrierAt(SPOT_SLOT_ID) ? [SPOT_SLOT_ID] : []
-  }
-  emptySlotIds(): ReadonlyArray<string> {
-    return this.hasCarrierAt(SPOT_SLOT_ID) ? [] : [SPOT_SLOT_ID]
-  }
-  obtainCarrier(slotId: string): Component | null {
-    if (slotId !== SPOT_SLOT_ID) return null
-    return ((this as any).components ?? []).find((c: any) => c?.isCarriable) ?? null
-  }
-  async receiveAt(_slotId: string, carrier: Component, options?: any): Promise<void> {
-    // Mover.place 의 dispatch → Transfer.handoff → SlotTarget.receive → 여기로 위임.
-    // carrier 를 논리 components + 3D 로 reparent 해야 다음 mover(crane 등)가
-    // obtainCarrier(components 조회)로 집어간다. dispose 하지 않고 상판에 유지
-    // (virtual location handoff buffer).
-    ;(this as any).reparent?.(carrier, { ...(options ?? {}), animated: false })
-  }
-  getSlotAttachObject3d(_slotId: string): any {
-    return (this as any)._realObject?.getAttachFrame?.()
-  }
-  slotTargetAt(slotId: string): SlotTarget {
-    return new SlotTarget(this as any, slotId)
-  }
-
-  /**
-   * Mover.place 의 Case A(dispatch → holder.receive)에서 호출. 기본 receive 는
-   * carrier 를 3D(object3d)로만 attach 해서 논리 tree(components)엔 안 들어간다 →
-   * 다음 mover 가 obtainCarrier(components 조회)로 못 찾아 'no-carrier'. reparent
-   * (CarrierHolder.reparent: addComponent[논리] + attach[3D])로 위임해 carrier 가
-   * components 에 들어가도록 한다 — handoff 의 carrier 승계가 동작.
-   */
-  // Transfer 의 handoff 는 `target.accept ?? target.receive` 순으로 호출한다 —
-  // accept 가 우선. Spot 은 carrier 를 논리 components + 3D 로 reparent 해야
-  // obtainCarrier 가 찾는다. accept/receive 둘 다 reparent 로 위임.
-  // 직접 dispatch(SlotTarget 미경유) 경로 대비 — accept/receive 도 reparent 로 위임.
-  async accept(carrier: Component, options?: any): Promise<void> {
-    ;(this as any).reparent?.(carrier, { ...(options ?? {}), animated: false })
-  }
-  async receive(carrier: Component, options?: any): Promise<void> {
-    ;(this as any).reparent?.(carrier, { ...(options ?? {}), animated: false })
-  }
+  // SlottedHolder duck (slotIds / hasCarrierAt / canReceiveAt / occupiedSlotIds /
+  // emptySlotIds / obtainCarrier / receiveAt / accept / receive / slotTargetAt /
+  // getSlotAttachObject3d) — SingleSlotHolder mixin 제공.
+  // virtual location handoff buffer 동작: receiveAt 가 reparent (components +
+  // 3D) 로 carrier 를 자식으로 유지 → 다음 mover 가 obtainCarrier 로 승계.
 }
 
 /** Spot 의 유일 virtual slot id. */

package/src/stockpile-grid.ts

@@ -22,6 +22,7 @@ import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
+  RecordStorage,
   SlotTarget,
   type AttachFrame,
   type Alignment,
@@ -96,7 +97,9 @@ const NATURE: ComponentNature = {
 }
 
 @sceneComponent('stockpile-grid')
-export default class StockpileGrid extends CarrierHolder(Placeable(ContainerAbstract)) {
+export default class StockpileGrid extends RecordStorage<StockpileGridCell>()(
+  CarrierHolder(Placeable(ContainerAbstract))
+) {
   declare state: StockpileGridState
   declare _realObject?: StockpileGrid3D
 
@@ -107,6 +110,14 @@ export default class StockpileGrid extends CarrierHolder(Placeable(ContainerAbst
   get nature(): ComponentNature { return NATURE }
   get anchors() { return [] }
 
+  // RecordStorage mixin 의 records / inventoryCount / addRecord / removeRecord 는
+  // cell-aware 시맨틱과 호환 안 됨. cell-nested data 라 *_recordsOf(col,row)_* 와
+  // _setCellRecords 를 사용. legend / popup / onLegendChanged 는 mixin 사용.
+  // _rebuildVisual hook 만 override.
+  _rebuildVisual(): void {
+    this._realObject?.update?.()
+  }
+
   // ── grid 좌표 helpers ─────────────────────────────────────
   get cols(): number { return Math.max(1, Math.floor(this.state.cols ?? 3)) }
   get rows(): number { return Math.max(1, Math.floor(this.state.rows ?? 3)) }
@@ -269,63 +280,9 @@ export default class StockpileGrid extends CarrierHolder(Placeable(ContainerAbst
     return carrier
   }
 
-  // ── Legend ─────────────────────────────────────────────────
-  private _legendTarget?: Component
-  get legendTarget(): Component | undefined {
-    if (this._legendTarget) return this._legendTarget
-    const id = this.state.legendTarget
-    if (id) {
-      const found = ((this as any).root)?.findById?.(id) as Component | undefined
-      if (found) {
-        this._legendTarget = found
-        ;(found as any).on?.('change', this._onLegendChanged, this)
-        return found
-      }
-    }
-    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 as any).root)
-    if (found) {
-      this._legendTarget = found
-      ;(found as any).on?.('change', this._onLegendChanged, this)
-    }
-    return found
-  }
-  private _onLegendChanged = (): void => { ;(this._realObject as any)?.update?.() }
-
-  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
-  }
+  // legendTarget / _onLegendChanged / resolveLegendColor — RecordStorage mixin 제공.
 
-  // ── Popup + click ─────────────────────────────────────────────
+  // ── Popup + click — mixin 의 _invokePopup 활용, cell payload 만 wrapper ──
   get eventMap() {
     return { '(self)': { '(self)': { click: this._onGridClick } } }
   }
@@ -334,28 +291,23 @@ export default class StockpileGrid extends CarrierHolder(Placeable(ContainerAbst
     const hit = this._raycastHit(mouseEvent)
     if (!hit) return
     const slotId = (hit.object?.userData?.slotId as string | undefined)
-    this._invokePopup(slotId)
+    this._dispatchCellPopup(slotId)
   }
-  private _invokePopup(slotId?: string): void {
-    const popupRefId = this.state.popupRef
-    if (!popupRefId) return
-    const popupComp: any = (this as any).root?.findById?.(popupRefId)
-    if (!popupComp || typeof popupComp.openPopup !== 'function') return
+  private _dispatchCellPopup(slotId?: string): void {
+    if (!this.state.popupRef) return
     if (slotId) {
       const p = this.parseCellId(slotId)
-      const anchor = this.slotTargetAt(slotId)
-      popupComp.openPopup({
+      this._invokePopup(slotId, {
         cellId: slotId,
         col: p?.col, row: p?.row,
         records: p ? this.recordsOf(p.col, p.row) : [],
         capacity: p ? this.capacityOf(p.col, p.row) : undefined
-      }, { anchor })
+      })
     } else {
-      const anchor = this.slotTargetAt(this.cellIdOf(0, 0))
-      popupComp.openPopup({
+      this._invokePopup(this.cellIdOf(0, 0), {
         componentId: (this.state as any).id,
         cols: this.cols, rows: this.rows
-      }, { anchor })
+      })
     }
   }