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

package/package.json

@@ -2,7 +2,7 @@
   "name": "@operato/scene-storage",
   "description": "Storage-domain components for things-scene (smart factory / logistics) — pallet, box, parcel; AS/RS and shelves planned.",
   "author": "heartyoh",
-  "version": "10.0.0-beta.28",
+  "version": "10.0.0-beta.30",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -21,24 +21,29 @@
     "build": "tsc",
     "prepublishOnly": "tsc",
     "lint": "eslint src/ && prettier \"src/**/*.ts\" --check",
-    "format": "eslint src/ --fix && prettier \"src/**/*.ts\" --write"
+    "format": "eslint src/ --fix && prettier \"src/**/*.ts\" --write",
+    "test": "mocha --require should --require ./test/setup.js --node-option import=tsx \"test/**/test-*.ts\""
   },
   "dependencies": {
     "@hatiolab/things-scene": "^10.0.0-beta.1",
-    "@operato/scene-base": "^10.0.0-beta.24",
+    "@operato/scene-base": "^10.0.0-beta.30",
     "three": "^0.183.0"
   },
   "devDependencies": {
     "@hatiolab/prettier-config": "^1.0.0",
+    "@types/mocha": "^10.0.0",
     "@types/three": "^0.183.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.18.0",
     "eslint-config-prettier": "^10.0.1",
+    "mocha": "^11.0.0",
     "prettier": "^3.2.5",
+    "should": "^13.2.3",
     "tslib": "^2.3.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.4"
   },
   "prettier": "@hatiolab/prettier-config",
-  "gitHead": "40634f9afc681d852d6028a329cedb51cc4fb94f"
+  "gitHead": "06b35b1726ec4f27ee76657ce341c6c6f3ba1b3a"
 }

package/src/asrs-crane-3d.ts

@@ -167,6 +167,26 @@ export class AsrsCrane3D extends RealObjectGroup {
     // Place lamp near the corner of the base, away from the mast
     lampMesh.position.set(width * 0.3, baseY + railH + baseH + lampH / 2, height * 0.3)
     this.object3d.add(lampMesh)
+
+    // ── Carriage frame (invisible anchor for carrier attach) ──────────
+    // Placed at the top of the shuttle, where cargo rests.
+    this._carriageFrame = new THREE.Object3D()
+    this._carriageFrame.name = 'crane-carriage-tcp'
+    this._carriageFrame.position.set(0, carriageY - carriageH / 2 - shuttleH, 0)
+    this.object3d.add(this._carriageFrame)
+  }
+
+  /** Sub-frame where carriers attach during transport (fork tool-centre-point). */
+  private _carriageFrame?: THREE.Object3D
+
+  /**
+   * Return the carriage TCP anchor. Carriers attached to this frame will
+   * follow carriage movement as `carriageHeight` changes and the crane rebuilds.
+   *
+   * Callers should re-fetch this after any state change that triggers rebuild.
+   */
+  getCarriageFrame(): THREE.Object3D | undefined {
+    return this._carriageFrame
   }
 
   updateDimension() {}

package/src/asrs-crane.ts

@@ -1,13 +1,18 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { Component, ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, ContainerAbstract, ContainerCapacity, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { SlotDef } from '@hatiolab/things-scene'
 import {
+  CarrierHolder,
   Legendable,
+  Mover,
   Placeable,
+  type AttachFrame,
   type Alignment,
   type Heights,
   type LegendBinding,
+  type MoveOptions,
   type PlacementArchetype
 } from '@operato/scene-base'
 
@@ -72,27 +77,37 @@ const NATURE: ComponentNature = {
   help: 'scene/component/asrs-crane'
 }
 
-const Base = Legendable(Placeable(RectPath(Shape))) as unknown as typeof Component
-
+// Mixin chain: Mover → CarrierHolder → ContainerCapacity → Legendable → Placeable → ContainerAbstract
+//
+//   Mover:             pick / place / pickAndPlace / moveTo / engage primitives
+//   CarrierHolder:     attachPointFor() — where the carrier sits on the crane (carriage fork)
+//   ContainerCapacity: receive() / dispatch() / canReceive() / slots — slot tracking +
+//                      TRANSFER_SLOT_KEY bookkeeping during transit
+//   Legendable:        status → bodyColor / lampEmissive colour mapping
+//   Placeable:         floor-archetype 3D positioning
+//   ContainerAbstract: child management — carrier becomes a child while in transit
+//
+// Note: ContainerAbstract replaces Shape. The 2D outline is drawn manually in
+// render() below (a simple top-down rectangle), matching the old Shape output
+// without the Shape base-class overhead.
 /**
  * AsrsCrane — the stacker / retrieval crane that runs in the aisle of an
  * AS/RS, moving cargo between the load port and the rack cells.
  *
  * Structure: a tall vertical mast that translates along a floor + ceiling
  * rail (the aisle), with a carriage that slides up/down the mast carrying a
- * shuttle / forks. The whole assembly's footprint is narrow (mast width)
- * but its visual height is full ceiling — by far the tallest single
- * component in a typical scene.
+ * shuttle / forks.
+ *
+ * **Monitoring mode**: crane status is driven by data binding
+ * (`state.status`, `state.carriageHeight`). The carrier is referenced
+ * via data binding — it is NOT a child of the crane in monitoring mode.
  *
- * Currently Shape-based (no children). The carrier the crane is *currently
- * carrying* is best modeled via data binding (a `currentCarrier` data field
- * on the crane → looked up to a Pallet/Box elsewhere in the scene), as in
- * fmsim's CarrierManager pattern. Adding the carrier as a child would mix
- * static placement with the dynamic data-driven flow we deliberately keep
- * separate (see Phase A4 commit notes).
+ * **Simulation mode**: call `crane.pick(carrier)` / `crane.place(carrier, rackCell)`
+ * (or `crane.pickAndPlace(carrier, rackCell)`). Mover handles navigation +
+ * engage + reparent. During transit the carrier IS a child of the crane.
  */
 @sceneComponent('asrs-crane')
-export default class AsrsCrane extends Base {
+export default class AsrsCrane extends Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract))))) {
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'status', legend: BODY_LEGEND },
     lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
@@ -102,6 +117,9 @@ export default class AsrsCrane extends Base {
   static align: Alignment = 'bottom'
   static defaultDepth = (h: Heights) => h.ceiling - h.floor
 
+  /** Yaw offset: crane model is drawn with the aisle axis along X (right = forward). */
+  static yawOffset = 0
+
   get nature() {
     return NATURE
   }
@@ -110,21 +128,124 @@ export default class AsrsCrane extends Base {
     return []
   }
 
+  // ── ContainerCapacity ─────────────────────────────────────────────────────
+
+  /** Stacker crane carries at most one load at a time on its forks. */
+  get slots(): SlotDef[] {
+    return [{ id: 'forks', maxCount: 1 }]
+  }
+
+  // ── CarrierHolder — attach frame (carriage fork position) ─────────────────
+
+  /**
+   * Return the 3D attach frame on the crane's carriage (fork tip).
+   * Carriers are attached here while the crane is in transit (pick phase).
+   *
+   * The AsrsCrane3D exposes `getCarriageFrame()` — a sub-Object3D that
+   * tracks the carriage height and sits at the fork TCP. If the 3D object
+   * isn't built yet (e.g. before scene initialization), fall back to the
+   * crane's own object3d centre.
+   */
+  attachPointFor(carrier: Component): AttachFrame | null {
+    const ro = (this as any)._realObject as AsrsCrane3D | undefined
+    const frame = ro?.getCarriageFrame?.()
+    if (frame) {
+      const carrierDepth = resolveCarrierDepth(carrier)
+      return { attach: frame, localPosition: { x: 0, y: carrierDepth / 2, z: 0 } }
+    }
+    const root = (this as any)._realObject?.object3d
+    if (!root) return null
+    return { attach: root }
+  }
+
+  // ── Mover overrides ───────────────────────────────────────────────────────
+
+  /**
+   * Domain-specific actuation between arrival and reparent.
+   *
+   * Simulation sequence for PICK:
+   *   1. Mover.pick() navigates crane to carrier position (moveTo).
+   *   2. engage('pick') → snap carriage height + status 'loading'.
+   *   3. Carrier is reparented to crane (becomes child).
+   *
+   * For now: set status and snap carriage height. A full ASRS simulation
+   * would tween the carriageHeight here (animate AsrsCrane3D).
+   *
+   * Status lifecycle:
+   *   idle → (moveTo running) → engage fires → loading/unloading → (reparent) → idle
+   * The 'moving' state is not set from Mover.moveTo() because TypeScript
+   * can't call super.moveTo() on an `: any`-typed mixin. WCS data binding
+   * sets 'moving' in monitoring mode; override pick()/place() to set it
+   * in full simulation environments.
+   */
+  async engage(
+    target: Component,
+    kind: 'pick' | 'place',
+    _options: MoveOptions = {}
+  ): Promise<void> {
+    if (kind === 'pick') {
+      this.setState({ status: 'loading' as AsrsCraneStatus })
+      const carrierY = resolveCarrierCenterY(target)
+      if (carrierY !== null) {
+        this.setState({ carriageHeight: carrierY })
+      }
+    } else {
+      this.setState({ status: 'unloading' as AsrsCraneStatus })
+    }
+    // In a full simulation: await carriage-motion tween here.
+  }
+
+  // ── Domain aliases ────────────────────────────────────────────────────────
+
+  /** Fetch a carrier from a rack cell (semantically = pick). */
+  fetch(carrier: Component, options?: MoveOptions): Promise<void> {
+    return (this as any).pick(carrier, options)
+  }
+
+  /** Deposit a carrier into a rack cell (semantically = place). */
+  deposit(carrier: Component, cell: Component, options?: MoveOptions): Promise<void> {
+    return (this as any).place(carrier, cell, options)
+  }
+
+  // ── 2D rendering ─────────────────────────────────────────────────────────
+
   /**
    * 2D — top-down rectangle showing the crane's footprint along the aisle.
    * The crane is much taller than wide, so the 2D mark is small.
    */
   render(ctx: CanvasRenderingContext2D) {
     const { width, height, left, top } = this.state
+    const fillColor = (this.state.bodyColor as string) || '#888'
+    ctx.save()
+    ctx.fillStyle = fillColor
     ctx.beginPath()
     ctx.rect(left, top, width, height)
+    ctx.fill()
+    ctx.restore()
   }
 
-  get fillStyle() {
-    return (this.state.bodyColor as string) || '#888'
-  }
+  // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {
     return new AsrsCrane3D(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 resolveCarrierCenterY(c: Component): number | null {
+  const pos = (c as any).state
+  if (!pos) return null
+  // zPos is the 3D Y center of a Placeable component in things-scene
+  const zPos = numOr(pos.zPos, NaN)
+  if (!Number.isNaN(zPos)) return zPos
+  return null
+}
+
+function numOr(v: unknown, dflt: number): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : dflt
+}

package/src/asrs-rack.ts

@@ -3,7 +3,11 @@
  */
 import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
 import {
+  CellContainer,
+  CellMap,
+  CarrierHolder,
   Placeable,
+  type AttachFrame,
   type Alignment,
   type Heights,
   type PlacementArchetype
@@ -35,35 +39,31 @@ const NATURE: ComponentNature = {
 // `ContainerAbstract` (not `Container`) — Container = MixinHTMLElement(ContainerAbstract),
 // which forces `isHTMLElement(): true` and trips the 3D pipeline's
 // addObject DOM-skip gate. ASRS rack lives only in the 3D scene graph.
-const Base = Placeable(ContainerAbstract) as unknown as typeof Component
-
+//
+// Mixin chain: CellContainer → CarrierHolder → Placeable → ContainerAbstract
+//   CellContainer: cell topology (cellMap, cell(), findAvailableCell(), occupiedCellIds())
+//   CarrierHolder: 3D attach-point protocol (attachPointFor, containable gates)
+//   Placeable:     floor-archetype positioning
+//   ContainerAbstract: child component management
 /**
  * AsrsRack — a multi-level high-bay storage rack, the structural backbone of
  * an AS/RS (Automated Storage / Retrieval System).
  *
  * `levels` × `bays` cells form a vertical grid. Each cell holds one logistics
  * package (Pallet / Box / Parcel). A pair of AsrsRacks separated by an aisle
- * (where an AsrsCrane runs) is the typical AS/RS configuration; v1 ships the
- * single-rack unit and lets users compose multi-rack systems by placing them
- * side by side. A future `AsrsAisle` composite may bundle the pair + crane.
+ * (where an AsrsCrane runs) is the typical AS/RS configuration.
  *
- * **Placement**: `floor` archetype, full ceiling depth by default — AS/RS
- * racks typically span floor to ceiling, with levels sized to fit the tallest
- * pallet load. Users can shorten via explicit `state.depth` for warehouses
- * with smaller envelopes.
+ * **Monitoring mode** (default): pallets/boxes are direct children of the rack,
+ * placed by the WCS data binding. No RackCell children are created.
  *
- * **Container-based**. Cells host stored cargo as children — each child's
- * left/top within the rack's bounds determines which cell it occupies. The
- * stacking pass in `Placeable.computeDefaultZPos` ensures each child cargo's
- * z lands on the rack's overall bottom (parent.zPos + parent.depth = ceiling),
- * which isn't quite cell-level resolution — true per-cell z positioning is
- * a v3 concern (the cargo would need to know which cell-row it's in).
+ * **Simulation mode**: call `rack._buildCells()` after placing the rack on the
+ * scene. This creates RackCell children at the correct 3D positions. The
+ * AsrsCrane then navigates to individual RackCells for pick-and-place.
  *
- * No Legendable for v1 — racks are passive structures; their per-cell
- * occupancy state is implicit in the children, not a status flag.
+ * **Placement**: `floor` archetype, full ceiling depth by default.
  */
 @sceneComponent('asrs-rack')
-export default class AsrsRack extends Base {
+export default class AsrsRack extends CellContainer(CarrierHolder(Placeable(ContainerAbstract))) {
   static placement: PlacementArchetype = 'floor'
   static align: Alignment = 'bottom'
   static defaultDepth = (h: Heights) => h.ceiling - h.floor
@@ -76,13 +76,110 @@ export default class AsrsRack extends Base {
     return []
   }
 
-  /** Operation cargo (pallets / boxes / parcels) goes in the rack's cells. */
-  containable(component: Component) {
+  // ── CellContainer ─────────────────────────────────────────────────────────
+
+  /**
+   * Derive the cell topology from the rack's current dimensions and bay/level
+   * counts. The CellMap is rebuilt fresh each time (state changes trigger
+   * re-reads via things-scene's invalidation pipeline).
+   *
+   * Coordinate convention (matches things-scene 3D):
+   *   X = bay axis  (left → right)
+   *   Y = level axis (floor → ceiling, the rack's `depth` state property)
+   *   Z = row axis   (front → back, the rack's `height` state property)
+   */
+  get cellMap(): CellMap {
+    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 rackDepth = (this.state.depth as number) || 3000   // Y: floor→ceiling
+    const rackHeight = (this.state.height as number) || 600  // Z: front→back
+
+    return CellMap.grid({
+      bays,
+      rows: 1,
+      levels,
+      bayWidth: width / bays,
+      rowDepth: rackHeight,
+      levelHeight: rackDepth / levels
+    })
+  }
+
+  /**
+   * Create RackCell child components for each cell in the CellMap.
+   *
+   * Called explicitly to enter simulation mode — monitoring-mode racks
+   * never call this (pallets are direct children, no explicit cells).
+   *
+   * Idempotent: removes existing rack-cell children first.
+   */
+  _buildCells(): void {
+    // Remove existing rack-cell children
+    const existing = ((this as any).components as Component[] | undefined) ?? []
+    for (const child of [...existing]) {
+      if ((child as any).state?.type === 'rack-cell') {
+        ;(this as any).removeComponent?.(child)
+      }
+    }
+
+    // Create a RackCell for each cell in the map
+    const RackCellClass = (Component as any).register('rack-cell') as (new (...args: any[]) => Component) | undefined
+    if (!RackCellClass) {
+      console.warn('AsrsRack._buildCells: rack-cell type not registered. Import rack-cell.ts first.')
+      return
+    }
+
+    const context = (this as any)._app
+    for (const cell of this.cellMap.cells) {
+      const model = {
+        type: 'rack-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 as any).addComponent?.(rackCell)
+    }
+  }
+
+  // ── Container gates ───────────────────────────────────────────────────────
+
+  /**
+   * Allow:
+   *   - Carriable components (pallets, boxes, parcels) — direct children in monitoring mode.
+   *   - RackCell — created by _buildCells() in simulation mode.
+   *
+   * Block:
+   *   - Everything else (sensors, labels, etc. can be siblings of the rack, not children).
+   */
+  containable(component: Component): boolean {
+    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)
   }
 
+  // ── CarrierHolder — attach frame for direct carrier children ─────────────
+
+  /**
+   * Attach frame for carriers that are DIRECT children of the rack
+   * (monitoring mode, where pallets go directly into the rack without
+   * explicit RackCell components).
+   *
+   * 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).
+   */
+  attachPointFor(_carrier: Component): AttachFrame | null {
+    const root = (this as any)._realObject?.object3d
+    if (!root) return null
+    return { attach: root }
+  }
+
+  // ── 2D rendering ─────────────────────────────────────────────────────────
+
   /**
    * 2D — top-down rectangle showing the rack footprint, with subdivisions
    * suggesting the bay layout (lines parallel to the aisle).
@@ -106,6 +203,8 @@ export default class AsrsRack extends Base {
     return '#a0a0a8'
   }
 
+  // ── 3D ───────────────────────────────────────────────────────────────────
+
   buildRealObject(): RealObject | undefined {
     return new AsrsRack3D(this as any)
   }

package/src/box.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,
   Legendable,
@@ -54,8 +54,6 @@ const NATURE: ComponentNature = {
 
 // Carriable: a box can be a child of any CarrierHolder (Pallet for stacking,
 // AGV deck, robot-arm gripper, Spot for staging).
-const Base = Carriable(Legendable(Placeable(RectPath(Shape)))) as unknown as typeof Component
-
 /**
  * Box — a generic stackable container for goods. Wood crate or plastic tote
  * variants distinguished by `material` prop.
@@ -65,7 +63,7 @@ const Base = Carriable(Legendable(Placeable(RectPath(Shape)))) as unknown as typ
  * scene-tree). If a future use case needs nested boxes, extend Container.
  */
 @sceneComponent('box')
-export default class Box extends Base {
+export default class Box extends Carriable(Legendable(Placeable(RectPath(Shape)))) {
   static legends: Record<string, LegendBinding> = {
     bodyColor: { from: 'material', legend: BODY_LEGEND }
   }

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)
+  }
+}