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

package/src/generic-container.ts

@@ -87,10 +87,8 @@ 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))) {
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'fill', legend: BODY_LEGEND },
     lampEmissive: { from: 'fill', legend: LAMP_EMISSIVE_LEGEND }

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

@@ -60,8 +60,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 +87,7 @@ 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))) {
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'material', legend: BODY_LEGEND }
   }

package/src/parcel.ts

@@ -1,7 +1,7 @@
 /*
  * 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 {
   Carriable,
   Placeable,
@@ -28,8 +28,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 +44,7 @@ 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))) {
   static placement: PlacementArchetype = 'operation'
   static align: Alignment = 'bottom'
   static defaultDepth = 150

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 as any).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,228 @@
+/*
+ * 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 { 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'
+
+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) {
+  // ── Identification ────────────────────────────────────────────────────────
+
+  get cellId(): string {
+    return (this.state.cellId as string) || ''
+  }
+
+  get cellType(): RackCellType {
+    return ((this.state.cellType as RackCellType) || '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 as any).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 as any).trigger?.('transfer-rejected', {
+        type: 'transfer-rejected',
+        component: carrier,
+        container: this,
+        reason: 'no-slot'
+      })
+      return
+    }
+    carrier[TRANSFER_SLOT_KEY] = this.cellId
+    ;(this as any).reparent?.(carrier, options)
+    ;(this as any).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 as any).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 as any).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 as any)._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 as any)
+  }
+}
+
+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.ts

@@ -33,6 +33,7 @@ import { Component, ComponentNature, ContainerAbstract, RealObject, sceneCompone
 import {
   CarrierHolder,
   Placeable,
+  type AttachFrame,
   type Alignment,
   type Heights,
   type PlacementArchetype
@@ -58,10 +59,8 @@ 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)) {
   static placement: PlacementArchetype = 'floor'
   static align: Alignment = 'bottom'
   static defaultDepth = (_h: Heights) => 2 // a thin pad
@@ -147,10 +146,10 @@ export default class Spot extends Base {
    * falling back to raw `state.depth` for components built before
    * RealObject creation.
    */
-  attachPointFor(carrier: Component) {
+  attachPointFor(carrier: Component): AttachFrame | null {
     const ro = (this as any)._realObject as Spot3D | undefined
     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,12 +1,10 @@
 /*
  * 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 palletWood = new URL('../../icons/pallet-wood.png', import.meta.url).href
-const palletPlastic = new URL('../../icons/pallet-plastic.png', import.meta.url).href
-const boxWood = new URL('../../icons/box-wood.png', import.meta.url).href
-const boxPlastic = new URL('../../icons/box-plastic.png', import.meta.url).href
+const pallet = new URL('../../icons/pallet.png', import.meta.url).href
+const box = new URL('../../icons/box.png', import.meta.url).href
 const parcel = new URL('../../icons/parcel.png', import.meta.url).href
 const asrsRack = new URL('../../icons/asrs-rack.png', import.meta.url).href
 const asrsCrane = new URL('../../icons/asrs-crane.png', import.meta.url).href
@@ -16,7 +14,7 @@ export default [
     type: 'pallet',
     description: 'wood pallet (EUR / EPAL)',
     group: 'storage',
-    icon: palletWood,
+    icon: pallet,
     model: {
       type: 'pallet',
       top: 100,
@@ -30,7 +28,7 @@ export default [
     type: 'pallet',
     description: 'plastic pallet',
     group: 'storage',
-    icon: palletPlastic,
+    icon: pallet,
     model: {
       type: 'pallet',
       top: 100,
@@ -44,7 +42,7 @@ export default [
     type: 'box',
     description: 'wood crate',
     group: 'storage',
-    icon: boxWood,
+    icon: box,
     model: {
       type: 'box',
       top: 100,
@@ -58,7 +56,7 @@ export default [
     type: 'box',
     description: 'plastic tote',
     group: 'storage',
-    icon: boxPlastic,
+    icon: box,
     model: {
       type: 'box',
       top: 100,
@@ -111,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
 ]

package/src/templates/spot.ts

@@ -1,5 +1,5 @@
 // Reuse parcel.png as a placeholder icon until a dedicated spot icon is drawn.
-const icon = new URL('../../icons/parcel.png', import.meta.url).href
+const icon = new URL('../../icons/spot.png', import.meta.url).href
 
 export default {
   type: 'spot',