@operato/scene-storage 10.0.0-beta.28 → 10.0.0-beta.31

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',
@@ -87,10 +102,10 @@ const NATURE: ComponentNature = {
 
 // 합성 순서: 안쪽부터 → ContainerAbstract → Placeable → Legendable → GltfComponent
 // (GenericFacility 와 동일 패턴)
-const Base = GltfComponent(Legendable(Placeable(ContainerAbstract))) as unknown as typeof Component
-
 @sceneComponent('container')
-export default class GenericContainer extends Base {
+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 }
@@ -109,18 +124,18 @@ export default class GenericContainer extends Base {
   }
 
   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/index.ts

@@ -10,6 +10,9 @@ export type { BoxMaterial } from './box.js'
 export { default as Parcel } from './parcel.js'
 
 export { default as AsrsRack } from './asrs-rack.js'
+export { default as RackCell } from './rack-cell.js'
+export type { RackCellType } from './rack-cell.js'
+export { RackCell3D } from './rack-cell-3d.js'
 export { default as AsrsCrane } from './asrs-crane.js'
 export type { AsrsCraneStatus } from './asrs-crane.js'
 

package/src/pallet.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 {
   Carriable,
   Legendable,
@@ -26,6 +27,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',
@@ -60,8 +70,6 @@ const NATURE: ComponentNature = {
 // `ContainerAbstract` (not `Container`) — Container = MixinHTMLElement(ContainerAbstract),
 // which forces `isHTMLElement(): true` and trips the 3D pipeline's
 // addObject DOM-skip gate. Pallet renders only as a 3D mesh.
-const Base = Carriable(Legendable(Placeable(ContainerAbstract))) as unknown as typeof Component
-
 /**
  * Pallet — a flat transport structure that goods are stacked and stored on.
  *
@@ -89,7 +97,9 @@ const Base = Carriable(Legendable(Placeable(ContainerAbstract))) as unknown as t
  * detection.
  */
 @sceneComponent('pallet')
-export default class Pallet extends Base {
+export default class Pallet extends Carriable(Legendable(Placeable(ContainerAbstract))) {
+  declare state: PalletState
+
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'material', legend: BODY_LEGEND }
   }
@@ -110,7 +120,7 @@ export default class Pallet extends Base {
   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)
   }
 
   /**
@@ -137,7 +147,7 @@ export default class Pallet extends Base {
     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()
 
@@ -189,6 +199,6 @@ export default class Pallet extends Base {
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Pallet3D(this as any)
+    return new Pallet3D(this)
   }
 }

package/src/parcel.ts

@@ -1,7 +1,8 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { Component, ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import { ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   Carriable,
   Placeable,
@@ -11,6 +12,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,
@@ -28,8 +38,6 @@ const NATURE: ComponentNature = {
 // Carriable: parcel can be a child of any CarrierHolder (Spot, robot-arm
 // gripper, AGV deck, …). Mixin wraps add() so the parcel's 3D object3d
 // is reattached to the holder's chosen mount frame.
-const Base = Carriable(Placeable(RectPath(Shape))) as unknown as typeof Component
-
 /**
  * Parcel — a cardboard package, the typical e-commerce / parcel-sortation unit.
  *
@@ -46,7 +54,9 @@ const Base = Carriable(Placeable(RectPath(Shape))) as unknown as typeof Componen
  * inspected indicators would add a status legend then.
  */
 @sceneComponent('parcel')
-export default class Parcel extends Base {
+export default class Parcel extends Carriable(Placeable(RectPath(Shape))) {
+  declare state: ParcelState
+
   static placement: PlacementArchetype = 'operation'
   static align: Alignment = 'bottom'
   static defaultDepth = 150
@@ -71,6 +81,6 @@ export default class Parcel extends Base {
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Parcel3D(this as any)
+    return new Parcel3D(this)
   }
 }

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

@@ -0,0 +1,101 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * RackCell 3D — invisible anchor group positioned at the cell's location
+ * within the parent rack's 3D coordinate space.
+ *
+ * RackCell has no geometry of its own. Its sole 3D purpose is to provide
+ * an Object3D that carriers can be attached to (via Three.js `.attach()`),
+ * placed at the exact cell position within the rack. The position is derived
+ * from the parent AsrsRack's CellMap (by cellId), not from 2D state fields —
+ * rack cells occupy 3D levels that have no 2D analogue.
+ *
+ * updateTransform() override: things-scene's standard updateTransform
+ * reads `component.center` (2D) and flattens it to 3D. For rack cells this
+ * is wrong — we need the 3D cell position (bay x, level y, row z) from the
+ * parent rack. So we override and read it directly from the CellMap.
+ */
+
+import * as THREE from 'three'
+import { RealObjectGroup } from '@hatiolab/things-scene'
+
+export class RackCell3D extends RealObjectGroup {
+  build() {
+    super.build()
+    this._repositionFromCellMap()
+  }
+
+  updateDimension() {
+    // intentional no-op — size comes from the cell definition, not state
+  }
+
+  updateTransform() {
+    this._repositionFromCellMap()
+  }
+
+  updateAlpha() {
+    // invisible — no materials to update
+  }
+
+  /**
+   * Position this group at the cell's localPosition within the rack's 3D space.
+   *
+   * CellMap.grid() places cell origins at:
+   *   x = b * bayWidth,  y = l * levelHeight,  z = r * rowDepth
+   * (starting from 0,0,0 at the rack's bottom-left-front corner).
+   *
+   * The rack's object3d is centered: X spans [-width/2, +width/2],
+   * Y spans [-depth/2, +depth/2], Z spans [-height/2, +height/2].
+   *
+   * So the cell centre in rack-local 3D space:
+   *   x3d = cellPos.x + bayWidth/2   - width/2
+   *   y3d = cellPos.y + levelHeight/2 - rackDepth/2
+   *   z3d = cellPos.z + rowDepth/2   - rackHeight/2
+   */
+  _repositionFromCellMap() {
+    const rack = (this.component as any).parent
+    if (!rack?.cellMap) return
+
+    const cellId = this.component.state.cellId as string | undefined
+    if (!cellId) return
+
+    const cell = rack.cellMap.findById(cellId)
+    if (!cell) return
+
+    const rs = rack.state as any
+    const rackWidth = (rs?.width as number) || 1000
+    const rackDepth = (rs?.depth as number) || 3000   // Y dimension (floor→ceiling)
+    const rackHeight = (rs?.height as number) || 600  // Z dimension (front→back, 2D height)
+    const bays = Math.max(1, Math.floor(rs?.bays || 5))
+    const levels = Math.max(1, Math.floor(rs?.levels || 4))
+    const rows = 1
+
+    const bayWidth = rackWidth / bays
+    const levelHeight = rackDepth / levels
+    const rowDepth = rackHeight / rows
+
+    const x3d = cell.localPosition.x + bayWidth / 2 - rackWidth / 2
+    const y3d = cell.localPosition.y + levelHeight / 2 - rackDepth / 2
+    const z3d = cell.localPosition.z + rowDepth / 2 - rackHeight / 2
+
+    this.object3d.position.set(x3d, y3d, z3d)
+
+    // Optionally visualise cells in debug mode (outline box, very faint)
+    if (process.env.NODE_ENV !== 'production' && (rack.state as any)?.debugCells) {
+      this._addDebugBox(bayWidth, levelHeight, rowDepth)
+    }
+  }
+
+  private _debugBox?: THREE.LineSegments
+
+  private _addDebugBox(w: number, h: number, d: number) {
+    if (this._debugBox) return
+    const geo = new THREE.BoxGeometry(w * 0.98, h * 0.98, d * 0.98)
+    const edges = new THREE.EdgesGeometry(geo)
+    this._debugBox = new THREE.LineSegments(
+      edges,
+      new THREE.LineBasicMaterial({ color: 0x00ff88, transparent: true, opacity: 0.2 })
+    )
+    this.object3d.add(this._debugBox)
+  }
+}

package/src/rack-cell.ts

@@ -0,0 +1,241 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * RackCell — a single storage slot within an AsrsRack.
+ *
+ * A RackCell is a virtual component: it occupies a specific (bay, row, level)
+ * coordinate within the parent rack and acts as a CarrierHolder for one carrier
+ * (or several, depending on `cellType`).
+ *
+ * The crane (AsrsCrane) navigates toward a RackCell as its `place()` destination —
+ * because the rack cell is a discrete component, Mover.moveTo() can target it
+ * directly and arrive at exactly the right bay × level position.
+ *
+ * Visual: invisible in 2D (no visible 2D footprint — rack cells don't make
+ * sense as 2D top-down boxes). In 3D, each cell is an invisible Group
+ * positioned within the rack's coordinate space (RackCell3D handles
+ * this via updateTransform override).
+ *
+ * Lifecycle: AsrsRack._buildCells() instantiates RackCell children.
+ * Do not create RackCell components manually — they are managed by the rack.
+ *
+ * Domain aliases:
+ *   cell.store(carrier)            ← cell.receive(carrier)
+ *   cell.retrieve(carrier, target) ← cell.dispatch(carrier, target)
+ */
+
+import {
+  Component,
+  ComponentNature,
+  ContainerAbstract,
+  RealObject,
+  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'
+
+/**
+ * How many carriers a cell can hold simultaneously.
+ * - single: exactly 1 (typical pallet bay)
+ * - multi:  small stack (up to 4, e.g. a multi-deep tray)
+ * - bulk:   unlimited (e.g. a floor area measured in slots)
+ */
+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,
+  rotatable: false,
+  properties: [
+    {
+      type: 'string',
+      label: 'cell-id',
+      name: 'cellId',
+      placeholder: 'e.g. 0-0-0'
+    },
+    {
+      type: 'select',
+      label: 'cell-type',
+      name: 'cellType',
+      property: {
+        options: [
+          { display: 'Single', value: 'single' },
+          { display: 'Multi', value: 'multi' },
+          { display: 'Bulk', value: 'bulk' }
+        ]
+      }
+    }
+  ],
+  help: 'scene/component/rack-cell'
+}
+
+/**
+ * RackCell — single-slot storage cell inside an AsrsRack.
+ *
+ * Mixin chain: CarrierHolder(ContainerAbstract)
+ *   - CarrierHolder: publishes attachPointFor(), gates containable() to Carriables
+ *   - ContainerAbstract: manages child carrier components
+ *
+ * No Placeable mixin — RackCell3D self-positions from the parent rack's
+ * CellMap (via updateTransform override), bypassing things-scene's standard
+ * 2D→3D coordinate mapping which cannot express 3D levels.
+ */
+@sceneComponent('rack-cell')
+export default class RackCell extends CarrierHolder(ContainerAbstract) {
+  declare state: RackCellState
+
+  // ── Identification ────────────────────────────────────────────────────────
+
+  get cellId(): string {
+    return this.state.cellId ?? ''
+  }
+
+  get cellType(): RackCellType {
+    return this.state.cellType ?? 'single'
+  }
+
+  /** Maximum carrier count for this cell based on cellType. */
+  get capacity(): number {
+    switch (this.cellType) {
+      case 'single': return 1
+      case 'multi': return 4
+      case 'bulk': return Infinity
+    }
+  }
+
+  // ── Interface ─────────────────────────────────────────────────────────────
+
+  get nature(): ComponentNature {
+    return NATURE
+  }
+
+  get anchors(): [] {
+    return []
+  }
+
+  // ── Transfer protocol ─────────────────────────────────────────────────────
+
+  /** True when fewer carriers are currently held than capacity. */
+  canReceive(_component?: any): boolean {
+    const occupied = (this.components as Component[] | undefined)?.length ?? 0
+    return occupied < this.capacity
+  }
+
+  /**
+   * Accept a carrier into this cell.
+   * Sets TRANSFER_SLOT_KEY = cellId on the carrier, then reparents.
+   * Fires 'transfer-received' so monitors can react.
+   */
+  async receive(carrier: any, options: any = {}): Promise<void> {
+    if (!this.canReceive(carrier)) {
+      this.trigger('transfer-rejected', {
+        type: 'transfer-rejected',
+        component: carrier,
+        container: this,
+        reason: 'no-slot'
+      })
+      return
+    }
+    carrier[TRANSFER_SLOT_KEY] = this.cellId
+    this.reparent(carrier, options)
+    this.trigger('transfer-received', {
+      type: 'transfer-received',
+      component: carrier,
+      container: this,
+      slotId: this.cellId
+    })
+  }
+
+  /**
+   * Release a carrier from this cell to `target`.
+   * Delegates to `target.receive()` if available, otherwise `target.reparent()`.
+   */
+  async dispatch(carrier: any, target: any, options: any = {}): Promise<void> {
+    if (target?.canReceive && !target.canReceive(carrier)) {
+      this.trigger('transfer-rejected', {
+        type: 'transfer-rejected',
+        component: carrier,
+        container: this,
+        reason: 'target-full'
+      })
+      return
+    }
+    delete carrier[TRANSFER_SLOT_KEY]
+    if (typeof target?.receive === 'function') {
+      await target.receive(carrier, options)
+    } else {
+      ;(target as any).reparent?.(carrier, options)
+    }
+    this.trigger('transfer-dispatched', {
+      type: 'transfer-dispatched',
+      component: carrier,
+      container: this,
+      target
+    })
+  }
+
+  // ── Domain aliases ────────────────────────────────────────────────────────
+
+  /** Alias for receive() — semantic sugar for the storage domain. */
+  store(carrier: any, options?: any): Promise<void> {
+    return this.receive(carrier, options)
+  }
+
+  /** Alias for dispatch() — semantic sugar for the storage domain. */
+  retrieve(carrier: any, target: any, options?: any): Promise<void> {
+    return this.dispatch(carrier, target, options)
+  }
+
+  // ── 3D attach frame ───────────────────────────────────────────────────────
+
+  /**
+   * Return the 3D attach frame for carriers placed in this cell.
+   * Carriers are lifted by their own halfDepth so the bottom face
+   * rests at the cell's Y-center (which is levelHeight/2 above the beam).
+   */
+  attachPointFor(carrier: Component): AttachFrame | null {
+    const root = this._realObject?.object3d
+    if (!root) return null
+    const carrierDepth = resolveCarrierDepth(carrier)
+    return {
+      attach: root,
+      localPosition: { x: 0, y: carrierDepth / 2, z: 0 }
+    }
+  }
+
+  // ── 2D rendering ──────────────────────────────────────────────────────────
+
+  /** RackCell has no 2D visual — the rack draws its own structure. */
+  render(_ctx: CanvasRenderingContext2D) {
+    // intentional no-op
+  }
+
+  // ── 3D ───────────────────────────────────────────────────────────────────
+
+  buildRealObject(): RealObject | undefined {
+    return new RackCell3D(this)
+  }
+}
+
+function resolveCarrierDepth(c: Component): number {
+  const eff = (c as any)._realObject?.effectiveDepth
+  if (typeof eff === 'number' && Number.isFinite(eff)) return eff
+  return numOr((c as any)?.state?.depth, 0)
+}
+
+function numOr(v: unknown, dflt: number): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : dflt
+}

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,9 +30,11 @@
  */
 
 import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
+  type AttachFrame,
   type Alignment,
   type Heights,
   type PlacementArchetype
@@ -40,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,
@@ -58,10 +67,11 @@ const NATURE: ComponentNature = {
 // `ContainerAbstract` (not `Container`) — Container = MixinHTMLElement(ContainerAbstract),
 // which forces `isHTMLElement(): true` and trips the 3D pipeline's
 // addObject DOM-skip gate. Spot is purely 3D.
-const Base = CarrierHolder(Placeable(ContainerAbstract)) as unknown as typeof Component
-
 @sceneComponent('spot')
-export default class Spot extends Base {
+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
@@ -132,7 +142,7 @@ export default class Spot extends Base {
   }
 
   buildRealObject(): RealObject | undefined {
-    return new Spot3D(this as any)
+    return new Spot3D(this)
   }
 
   /**
@@ -147,10 +157,10 @@ export default class Spot extends Base {
    * falling back to raw `state.depth` for components built before
    * RealObject creation.
    */
-  attachPointFor(carrier: Component) {
-    const ro = (this as any)._realObject as Spot3D | undefined
+  attachPointFor(carrier: Component): AttachFrame | null {
+    const ro = this._realObject
     const frame = ro?.getAttachFrame?.()
-    if (!frame) return undefined
+    if (!frame) return null
     const carrierDepth = resolveDepth(carrier)
     return {
       attach: frame,

package/src/templates/index.ts

@@ -1,6 +1,6 @@
 /*
  * things-scene catalog templates for the storage domain — pallet/box/parcel
- * variants, ASRS rack/crane, and the virtual `spot` placement marker.
+ * variants, ASRS rack/crane, ASRS aisle composite, and the virtual `spot` placement marker.
  */
 import spot from './spot.js'
 const pallet = new URL('../../icons/pallet.png', import.meta.url).href
@@ -109,5 +109,47 @@ export default [
       carriageHeight: 100
     }
   },
+  {
+    type: 'group',
+    description: 'AS/RS aisle — 4-level rack pair + stacker crane',
+    group: 'storage',
+    icon: asrsRack,
+    model: {
+      type: 'group',
+      top: 100,
+      left: 100,
+      width: 840,
+      height: 220,
+      components: [
+        {
+          type: 'asrs-rack',
+          top: 100,
+          left: 100,
+          width: 800,
+          height: 80,
+          levels: 4,
+          bays: 8
+        },
+        {
+          type: 'asrs-crane',
+          top: 140,
+          left: 420,
+          width: 60,
+          height: 220,
+          status: 'idle',
+          carriageHeight: 0
+        },
+        {
+          type: 'asrs-rack',
+          top: 320,
+          left: 100,
+          width: 800,
+          height: 80,
+          levels: 4,
+          bays: 8
+        }
+      ]
+    }
+  },
   spot
 ]