@operato/scene-storage 10.0.0-beta.30 → 10.0.0-beta.32

package/src/asrs-rack.ts

@@ -2,6 +2,7 @@
  * Copyright © HatioLab Inc. All rights reserved.
  */
 import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CellContainer,
   CellMap,
@@ -15,6 +16,19 @@ import {
 
 import { AsrsRack3D } from './asrs-rack-3d.js'
 
+/** AsrsRack 컴포넌트 state */
+export interface AsrsRackState extends State {
+  // ── 토폴로지 ──
+  bays?: number
+  levels?: number
+
+  // ── 디버그 ──
+  debugCells?: boolean
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
 const NATURE: ComponentNature = {
   mutable: false,
   resizable: true,
@@ -64,6 +78,8 @@ const NATURE: ComponentNature = {
  */
 @sceneComponent('asrs-rack')
 export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(ContainerAbstract))) {
+  declare state: AsrsRackState
+
   static placement: PlacementArchetype = 'floor'
   static align: Alignment = 'bottom'
   static defaultDepth = (h: Heights) => h.ceiling - h.floor
@@ -115,10 +131,10 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
    */
   _buildCells(): void {
     // Remove existing rack-cell children
-    const existing = ((this as any).components as Component[] | undefined) ?? []
+    const existing = (this.components as Component[] | undefined) ?? []
     for (const child of [...existing]) {
       if ((child as any).state?.type === 'rack-cell') {
-        ;(this as any).removeComponent?.(child)
+        this.removeComponent(child)
       }
     }
 
@@ -129,7 +145,7 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
       return
     }
 
-    const context = (this as any)._app
+    const context = this._app
     for (const cell of this.cellMap.cells) {
       const model = {
         type: 'rack-cell',
@@ -139,7 +155,7 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
         depth: cell.size.height   // 3D Y = level height
       }
       const rackCell = new RackCellClass(model, context)
-      ;(this as any).addComponent?.(rackCell)
+      this.addComponent(rackCell)
     }
   }
 
@@ -157,7 +173,7 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
     if ((component as any).state?.type === 'rack-cell') return true
     const archetype = (component.constructor as any).placement
     if (archetype === 'operation') return true
-    return component.isDescendible(this as any)
+    return component.isDescendible(this)
   }
 
   // ── CarrierHolder — attach frame for direct carrier children ─────────────
@@ -173,7 +189,7 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
    * returns the rack's own object3d as the attach frame (default behavior).
    */
   attachPointFor(_carrier: Component): AttachFrame | null {
-    const root = (this as any)._realObject?.object3d
+    const root = this._realObject?.object3d
     if (!root) return null
     return { attach: root }
   }
@@ -206,6 +222,6 @@ export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(Cont
   // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {
-    return new AsrsRack3D(this as any)
+    return new AsrsRack3D(this)
   }
 }

package/src/box.ts

@@ -1,7 +1,16 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import {
+  ComponentNature,
+  RealObject,
+  RectPath,
+  Shape,
+  topApproachFrame,
+  getWorldPose,
+  sceneComponent
+} from '@hatiolab/things-scene'
+import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
   Legendable,
@@ -26,6 +35,15 @@ import { Box3D } from './box-3d.js'
  */
 export type BoxMaterial = 'wood' | 'plastic'
 
+/** Box 컴포넌트 state */
+export interface BoxState extends State {
+  // ── 외관 ──
+  material?: BoxMaterial
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
 const BODY_LEGEND = {
   wood: '#a87644',
   plastic: '#3a5078',
@@ -64,6 +82,8 @@ const NATURE: ComponentNature = {
  */
 @sceneComponent('box')
 export default class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {
+  declare state: BoxState
+
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'material', legend: BODY_LEGEND }
   }
@@ -92,6 +112,35 @@ export default class Box extends Carriable(Legendable(Placeable(RectPath(Shape))
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Box3D(this as any)
+    return new Box3D(this)
+  }
+
+  /**
+   * Phase H — pickup contract. Box 는 위에서 gripper / vacuum cup 으로 집기 —
+   * 단일 entry (top center). Box 의 dimensions 가 작아서 forklift fork 보다는
+   * gripper 가 일반적. forklift 로 들어올릴 box 는 통상 pallet 위에 stacking
+   * 후 pallet 째로 운반.
+   *
+   * tolerance 가 pallet 보다 빡빡 (gripper 정밀도 vs forklift pocket 폭).
+   */
+  pickupFrames(): PickupFrame[] {
+    const wp = getWorldPose(this)
+    const me: PoseSerialized = {
+      position: { x: wp.position.x, y: wp.position.y, z: wp.position.z },
+      rotation: { x: wp.rotation.x, y: wp.rotation.y, z: wp.rotation.z, w: wp.rotation.w }
+    }
+    const boxDepth = (this.constructor as any).defaultDepth ?? 300
+
+    return [
+      topApproachFrame({
+        carrierWorld: me,
+        topY: boxDepth,                  // Box top in carrier-local Y (depth = full height; top at depth)
+        approachDistance: 50,            // gripper 가 hover 하는 거리
+        toolType: 'gripper',
+        tolerance: { positionMm: 5, angleDeg: 1 },
+        priority: 0,
+        id: 'top-gripper'
+      })
+    ]
   }
 }

package/src/generic-container-3d.ts

@@ -31,7 +31,7 @@ export class GenericContainer3D extends RealObjectGLTF {
   }
 
   private _applyActuators() {
-    const state = this.component.state as any
+    const state = this.component.state
     applyActuators(this, state.actuators, state.actuatorValues)
   }
 

package/src/generic-container.ts

@@ -32,6 +32,7 @@ import {
   gltfNatureProperties,
   sceneComponent
 } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   Legendable,
   Placeable,
@@ -45,6 +46,20 @@ import { GenericContainer3D } from './generic-container-3d.js'
 import type { ActuatorDef } from '@operato/scene-base'
 
 export type ContainerStatus = 'empty' | 'partial' | 'full' | 'error'
+export type ContainerFill = ContainerStatus
+
+/** GenericContainer 컴포넌트 state */
+export interface GenericContainerState extends State {
+  // ── 운영 상태 ──
+  fill?: ContainerFill
+
+  // ── GLB 동적 노드 ──
+  actuators?: Record<string, ActuatorDef>
+  actuatorValues?: Record<string, number>
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
 
 const BODY_LEGEND = {
   empty: '#a8b8c4',
@@ -89,6 +104,8 @@ const NATURE: ComponentNature = {
 // (GenericFacility 와 동일 패턴)
 @sceneComponent('container')
 export default class GenericContainer extends GltfComponent(Legendable(Placeable(ContainerAbstract))) {
+  declare state: GenericContainerState
+
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'fill', legend: BODY_LEGEND },
     lampEmissive: { from: 'fill', legend: LAMP_EMISSIVE_LEGEND }
@@ -107,18 +124,18 @@ export default class GenericContainer extends GltfComponent(Legendable(Placeable
   }
 
   get actuators(): Record<string, ActuatorDef> {
-    return ((this.state as any).actuators as Record<string, ActuatorDef> | undefined) ?? {}
+    return this.state.actuators ?? {}
   }
 
   get actuatorValues(): Record<string, number> {
-    return ((this.state as any).actuatorValues as Record<string, number> | undefined) ?? {}
+    return this.state.actuatorValues ?? {}
   }
 
   containable(component: Component): boolean {
-    return component.isDescendible(this as any)
+    return component.isDescendible(this)
   }
 
   buildRealObject() {
-    return new GenericContainer3D(this as any)
+    return new GenericContainer3D(this)
   }
 }

package/src/pallet.ts

@@ -1,7 +1,17 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Component,
+  ComponentNature,
+  ContainerAbstract,
+  RealObject,
+  Pose6DOF,
+  rectangularFootprintFrames,
+  getWorldPose,
+  sceneComponent
+} from '@hatiolab/things-scene'
+import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
   Legendable,
@@ -26,6 +36,15 @@ import { Pallet3D } from './pallet-3d.js'
  */
 export type PalletMaterial = 'wood' | 'plastic'
 
+/** Pallet 컴포넌트 state */
+export interface PalletState extends State {
+  // ── 외관 ──
+  material?: PalletMaterial
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
 const BODY_LEGEND = {
   wood: '#a87644',
   plastic: '#5a6a78',
@@ -88,6 +107,8 @@ const NATURE: ComponentNature = {
  */
 @sceneComponent('pallet')
 export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbstract))) {
+  declare state: PalletState
+
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'material', legend: BODY_LEGEND }
   }
@@ -108,7 +129,7 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
   containable(component: Component) {
     const archetype = (component.constructor as any).placement
     if (archetype === 'operation') return true
-    return component.isDescendible(this as any)
+    return component.isDescendible(this)
   }
 
   /**
@@ -135,7 +156,7 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
     super.postrender?.(ctx)
 
     const { width, height, left, top } = this.state
-    const isPlastic = ((this.state as any).material as PalletMaterial) === 'plastic'
+    const isPlastic = this.state.material === 'plastic'
 
     ctx.save()
 
@@ -187,6 +208,48 @@ export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbst
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Pallet3D(this as any)
+    return new Pallet3D(this)
+  }
+
+  /**
+   * Phase H — pickup contract. EUR/EPAL pallet 의 fork 진입은 양 단면 (긴 변
+   * 두 군데). 'east' / 'west' = pallet 의 짧은 축 방향에서 fork 가 들어감.
+   *
+   * fork 진입 높이 (entryHeight) 는 pallet 의 fork pocket 위치 — pallet 의
+   * 바닥에서 약 50mm (top deck 와 bottom deck 사이의 stringer 영역). 표준
+   * EUR pallet 의 fork pocket 은 144mm 두께의 약 50% 지점.
+   *
+   * approachDistance 는 forklift 가 fork 끝을 pallet 에 닿기 직전 hover 자세 —
+   * pallet 길이만큼 떨어져서 fork 길이 (보통 1100mm) 가 다 들어가도록 한다.
+   * 여기선 conservative 하게 pallet 너비 + 200mm.
+   */
+  pickupFrames(): PickupFrame[] {
+    const { width = 1200, height = 800 } = this.state
+    const palletDepth = (this.constructor as any).defaultDepth ?? 150
+
+    // 4-way pallet: 모든 면에서 fork 진입 가능. 2-way 는 sides 를 ['east','west']
+    // 로 한정 — pallet 의 stringer 방향에 따라 다르나 default 는 4-way 가정.
+    // (state.palletType 같은 속성 추가 시 분기 가능 — 현재는 4-way 가정.)
+    const me: PoseSerialized = (() => {
+      const wp = getWorldPose(this)
+      return {
+        position: { x: wp.position.x, y: wp.position.y, z: wp.position.z },
+        rotation: { x: wp.rotation.x, y: wp.rotation.y, z: wp.rotation.z, w: wp.rotation.w }
+      }
+    })()
+
+    const longerAxis = Math.max(width, height)
+
+    return rectangularFootprintFrames({
+      carrierWorld: me,
+      width,
+      depth: height,
+      entryHeight: palletDepth * 0.4, // fork pocket 중심
+      approachDistance: longerAxis + 200,
+      sides: ['east', 'west', 'north', 'south'],
+      toolType: 'forklift-fork',
+      tolerance: { positionMm: 50, angleDeg: 5 },
+      priority: 0
+    })
   }
 }

package/src/parcel.ts

@@ -1,7 +1,16 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import {
+  ComponentNature,
+  RealObject,
+  RectPath,
+  Shape,
+  topApproachFrame,
+  getWorldPose,
+  sceneComponent
+} from '@hatiolab/things-scene'
+import type { State, Material3D, PickupFrame, PoseSerialized } from '@hatiolab/things-scene'
 import {
   Carriable,
   Placeable,
@@ -11,6 +20,15 @@ import {
 
 import { Parcel3D } from './parcel-3d.js'
 
+/** Parcel 컴포넌트 state */
+export interface ParcelState extends State {
+  // ── 정체 ──
+  trackingId?: string
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
 const NATURE: ComponentNature = {
   mutable: false,
   resizable: true,
@@ -45,6 +63,8 @@ const NATURE: ComponentNature = {
  */
 @sceneComponent('parcel')
 export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
+  declare state: ParcelState
+
   static placement: PlacementArchetype = 'operation'
   static align: Alignment = 'bottom'
   static defaultDepth = 150
@@ -69,6 +89,32 @@ export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Parcel3D(this as any)
+    return new Parcel3D(this)
+  }
+
+  /**
+   * Phase H — pickup contract. Parcel 은 위에서 vacuum gripper / suction cup 으로
+   * 집기 — Box 와 동일한 패턴이지만 cardboard 표면이라 더 큰 흡착 면 필요.
+   * tolerance 도 약간 완화 (cardboard 변형 가능성).
+   */
+  pickupFrames(): PickupFrame[] {
+    const wp = getWorldPose(this)
+    const me: PoseSerialized = {
+      position: { x: wp.position.x, y: wp.position.y, z: wp.position.z },
+      rotation: { x: wp.rotation.x, y: wp.rotation.y, z: wp.rotation.z, w: wp.rotation.w }
+    }
+    const parcelDepth = (this.constructor as any).defaultDepth ?? 150
+
+    return [
+      topApproachFrame({
+        carrierWorld: me,
+        topY: parcelDepth,
+        approachDistance: 80,            // gripper hover 거리 (Box 보다 더 — vacuum 펼침)
+        toolType: 'gripper',
+        tolerance: { positionMm: 10, angleDeg: 2 },  // cardboard 변형 감안
+        priority: 0,
+        id: 'top-suction'
+      })
+    ]
   }
 }

package/src/rack-cell-3d.ts

@@ -56,7 +56,7 @@ export class RackCell3D extends RealObjectGroup {
     const rack = (this.component as any).parent
     if (!rack?.cellMap) return
 
-    const cellId = (this.component as any).state?.cellId as string | undefined
+    const cellId = this.component.state.cellId as string | undefined
     if (!cellId) return
 
     const cell = rack.cellMap.findById(cellId)

package/src/rack-cell.ts

@@ -32,6 +32,7 @@ import {
   TRANSFER_SLOT_KEY,
   sceneComponent
 } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import { CarrierHolder, type AttachFrame } from '@operato/scene-base'
 
 import { RackCell3D } from './rack-cell-3d.js'
@@ -44,6 +45,16 @@ import { RackCell3D } from './rack-cell-3d.js'
  */
 export type RackCellType = 'single' | 'multi' | 'bulk'
 
+/** RackCell 컴포넌트 state */
+export interface RackCellState extends State {
+  // ── 식별 ──
+  cellId?: string
+  cellType?: RackCellType
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
 const NATURE: ComponentNature = {
   mutable: false,
   resizable: false,
@@ -84,14 +95,16 @@ const NATURE: ComponentNature = {
  */
 @sceneComponent('rack-cell')
 export default class RackCell extends CarrierHolder(ContainerAbstract) {
+  declare state: RackCellState
+
   // ── Identification ────────────────────────────────────────────────────────
 
   get cellId(): string {
-    return (this.state.cellId as string) || ''
+    return this.state.cellId ?? ''
   }
 
   get cellType(): RackCellType {
-    return ((this.state.cellType as RackCellType) || 'single')
+    return this.state.cellType ?? 'single'
   }
 
   /** Maximum carrier count for this cell based on cellType. */
@@ -117,7 +130,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
 
   /** True when fewer carriers are currently held than capacity. */
   canReceive(_component?: any): boolean {
-    const occupied = ((this as any).components as Component[] | undefined)?.length ?? 0
+    const occupied = (this.components as Component[] | undefined)?.length ?? 0
     return occupied < this.capacity
   }
 
@@ -128,7 +141,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
    */
   async receive(carrier: any, options: any = {}): Promise<void> {
     if (!this.canReceive(carrier)) {
-      ;(this as any).trigger?.('transfer-rejected', {
+      this.trigger('transfer-rejected', {
         type: 'transfer-rejected',
         component: carrier,
         container: this,
@@ -137,8 +150,8 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
       return
     }
     carrier[TRANSFER_SLOT_KEY] = this.cellId
-    ;(this as any).reparent?.(carrier, options)
-    ;(this as any).trigger?.('transfer-received', {
+    this.reparent(carrier, options)
+    this.trigger('transfer-received', {
       type: 'transfer-received',
       component: carrier,
       container: this,
@@ -152,7 +165,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
    */
   async dispatch(carrier: any, target: any, options: any = {}): Promise<void> {
     if (target?.canReceive && !target.canReceive(carrier)) {
-      ;(this as any).trigger?.('transfer-rejected', {
+      this.trigger('transfer-rejected', {
         type: 'transfer-rejected',
         component: carrier,
         container: this,
@@ -166,7 +179,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
     } else {
       ;(target as any).reparent?.(carrier, options)
     }
-    ;(this as any).trigger?.('transfer-dispatched', {
+    this.trigger('transfer-dispatched', {
       type: 'transfer-dispatched',
       component: carrier,
       container: this,
@@ -194,7 +207,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
    * rests at the cell's Y-center (which is levelHeight/2 above the beam).
    */
   attachPointFor(carrier: Component): AttachFrame | null {
-    const root = (this as any)._realObject?.object3d
+    const root = this._realObject?.object3d
     if (!root) return null
     const carrierDepth = resolveCarrierDepth(carrier)
     return {
@@ -213,7 +226,7 @@ export default class RackCell extends CarrierHolder(ContainerAbstract) {
   // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {
-    return new RackCell3D(this as any)
+    return new RackCell3D(this)
   }
 }
 

package/src/spot-3d.ts

@@ -37,7 +37,7 @@ export class Spot3D extends RealObjectGroup {
   build() {
     super.build()
 
-    const state = this.component.state as any
+    const state = this.component.state
     const w = Math.max(Math.abs(numOr(state.width, 100)), 1)
     const h = Math.max(Math.abs(numOr(state.height, 100)), 1)
     const d = this.effectiveDepth // 2 by default (thin pad)

package/src/spot.ts

@@ -30,6 +30,7 @@
  */
 
 import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
@@ -41,6 +42,13 @@ import {
 
 import { Spot3D } from './spot-3d.js'
 
+/** Spot 컴포넌트 state */
+export interface SpotState extends State {
+  // Spot has no component-specific state — it uses standard fillStyle /
+  // strokeStyle / lineWidth / alpha / text / font* / material3d.
+  material3d?: Material3D
+}
+
 const NATURE: ComponentNature = {
   mutable: false,
   resizable: true,
@@ -61,6 +69,9 @@ const NATURE: ComponentNature = {
 // addObject DOM-skip gate. Spot is purely 3D.
 @sceneComponent('spot')
 export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
+  declare state: SpotState
+  declare _realObject?: Spot3D
+
   static placement: PlacementArchetype = 'floor'
   static align: Alignment = 'bottom'
   static defaultDepth = (_h: Heights) => 2 // a thin pad
@@ -131,7 +142,7 @@ export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Spot3D(this as any)
+    return new Spot3D(this)
   }
 
   /**
@@ -147,7 +158,7 @@ export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
    * RealObject creation.
    */
   attachPointFor(carrier: Component): AttachFrame | null {
-    const ro = (this as any)._realObject as Spot3D | undefined
+    const ro = this._realObject
     const frame = ro?.getAttachFrame?.()
     if (!frame) return null
     const carrierDepth = resolveDepth(carrier)