@operato/scene-storage 10.0.0-beta.33 → 10.0.0-beta.35

package/src/crane.ts

@@ -0,0 +1,555 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, ContainerAbstract, ContainerCapacity, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { SlotDef, State, Material3D } 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'
+
+import { Crane3D } from './crane-3d.js'
+
+/**
+ * Crane status — the operating state of a stacker crane.
+ *
+ * - `idle`       — parked at home position
+ * - `moving`     — translating (horizontal) or along the mast (vertical);
+ *                  typically combined
+ * - `loading`    — extracting a carrier from a rack cell
+ * - `unloading`  — placing a carrier into a rack cell
+ * - `error`      — fault / e-stop / collision warning
+ */
+export type CraneStatus = 'idle' | 'moving' | 'loading' | 'unloading' | 'error'
+
+/** Crane 컴포넌트 state */
+export interface CraneState extends State {
+  // ── 운영 상태 ──
+  status?: CraneStatus
+
+  /**
+   * Crane 이 서비스 할 타깃 컴포넌트의 refid (또는 id).
+   * 명시되면 그 컴포넌트 (또는 그 children) 의 위치를 stop point 로 사용 — heuristic
+   * 으로 sibling 추정 안 함. 미명시면 sibling 안에서 추측.
+   * 예: RackGrid 의 refid 를 지정하면 그 안의 cell 들 사이에서만 이동.
+   */
+  target?: string
+
+  // ── 액추에이터 ──
+  /** 마스트 따라 carriage 의 수직 위치 (mm). */
+  carriageHeight?: number
+  /**
+   * Fork prong 의 최대 신축 가능 길이 (mm). cell 깊이 + 여유.
+   * 일반적으로 pallet 깊이 (1200mm) + 여유 ≈ 1300mm 또는 그 이하 (default 600).
+   */
+  forkLength?: number
+  /**
+   * Fork 의 *현재 신축 거리* (mm). 0 = collapsed (shuttle 안 들어가있음),
+   * forkLength = fully extended (cell 안 carrier 의 fork pocket 도달).
+   *
+   * 시뮬레이션 흐름:
+   *   idle: 0
+   *   approach → 0
+   *   pick / place: 0 → forkLength (extending) → 0 (retracting with carrier)
+   */
+  forkExtension?: number
+  /**
+   * Fork 의 *carrier 들어올림 높이* (mm). 0 = neutral (cell shelf 와 같은 면),
+   * +값 = carrier 를 *위로* 들어올림 (fork pocket 안으로 진입 후 위로 lifting).
+   */
+  forkLift?: number
+
+  // ── 3D 재질 ──
+  material3d?: Material3D
+}
+
+const BODY_LEGEND = {
+  idle: '#888',
+  moving: '#aabbcc',
+  loading: '#ffaa00',
+  unloading: '#ffaa00',
+  error: '#c66',
+  default: '#888'
+}
+
+const LAMP_EMISSIVE_LEGEND = {
+  idle: '#222222',
+  moving: '#44ff44',
+  loading: '#ffaa00',
+  unloading: '#ffaa00',
+  error: '#ff3333',
+  default: '#222222'
+}
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'select',
+      label: 'status',
+      name: 'status',
+      property: {
+        options: [
+          { display: 'Idle', value: 'idle' },
+          { display: 'Moving', value: 'moving' },
+          { display: 'Loading', value: 'loading' },
+          { display: 'Unloading', value: 'unloading' },
+          { display: 'Error', value: 'error' }
+        ]
+      }
+    },
+    {
+      type: 'string',
+      label: 'target',
+      name: 'target',
+      placeholder: 'refid of target (e.g., a RackGrid) — crane serves only its cells'
+    },
+    {
+      type: 'number',
+      label: 'carriage-height',
+      name: 'carriageHeight',
+      placeholder: 'mm — height of carriage on mast'
+    },
+    {
+      type: 'number',
+      label: 'fork-length',
+      name: 'forkLength',
+      placeholder: 'mm — fork prong 최대 신축 길이 (default 600)'
+    },
+    {
+      type: 'number',
+      label: 'fork-extension',
+      name: 'forkExtension',
+      placeholder: 'mm — 현재 신축 거리 (0 = collapsed)'
+    },
+    {
+      type: 'number',
+      label: 'fork-lift',
+      name: 'forkLift',
+      placeholder: 'mm — carrier 들어올림 높이 (+ 위로)'
+    }
+  ],
+  help: 'scene/component/crane'
+}
+
+// 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.
+/**
+ * Crane — a stacker / retrieval picker. Picker contract instance.
+ *
+ * Moves carriers between rack cells (or any Placeable target). The crane
+ * is *picker-side* of the Phase G/H Pickable contract — it knows how to
+ * `pick(carrier)` / `place(carrier, target)` and `engage(target, kind)`
+ * to align its actuators. It is *storage-agnostic* — any Rack / Cell /
+ * Spot / Conveyor that implements the receive/dispatch protocol is a
+ * valid target.
+ *
+ * Structure: a tall vertical mast that translates horizontally on a rail
+ * or free floor path, with a carriage that slides up/down the mast carrying
+ * a shuttle / forks.
+ *
+ * **Monitoring mode**: crane status is driven by external data binding
+ * (`state.status`, `state.carriageHeight`). The carrier is referenced
+ * via data binding — it is NOT a child of the crane in monitoring mode.
+ *
+ * **Simulation mode**: call `crane.pick(carrier)` / `crane.place(carrier, target)`
+ * (or `crane.pickAndPlace(carrier, target)`). Mover handles navigation +
+ * engage + reparent. During transit the carrier IS a child of the crane.
+ */
+@sceneComponent('crane')
+export default class Crane extends Mover(CarrierHolder(ContainerCapacity(Legendable(Placeable(ContainerAbstract))))) {
+  declare state: CraneState
+  declare _realObject?: Crane3D
+
+  static legends: Record<string, LegendBinding> = {
+    bodyColor: { from: 'status', legend: BODY_LEGEND },
+    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
+  }
+
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (h: Heights) => h.ceiling - h.floor
+
+  /** Yaw offset: crane model is drawn with the rail axis along X (right = forward). */
+  static yawOffset = 0
+
+  /**
+   * Phase H — the crane uses telescoping forks to pick up a carrier in a rack
+   * cell. Same mechanism as a forklift fork — engages the pallet's fork pocket.
+   * (Mover mixin chain is `: any` so override keyword is not usable, only the
+   * getter is defined.)
+   */
+  get toolType(): string {
+    return 'forklift-fork'
+  }
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    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 Crane3D 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._realObject
+    const frame = ro?.getCarriageFrame?.()
+    if (frame) {
+      const carrierDepth = resolveCarrierDepth(carrier)
+      // fork blade 위 (top surface) 에 pallet pocket 끼우듯 얹힘. y = blade top + carrier/2.
+      // z = blade 중심 (forkLength 의 반쪽 위치 — pallet center 가 blade 중간에 위치).
+      const platformTopY = ro?.platformTopY ?? 0
+      const bladeMidZ = ro?.bladeMidZ ?? 0
+      return {
+        attach: frame,
+        localPosition: { x: 0, y: platformTopY + carrierDepth / 2, z: bladeMidZ }
+      }
+    }
+    const root = this._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 simulation
+   * would tween the carriageHeight here (animate Crane3D).
+   *
+   * 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. External 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 CraneStatus })
+      const carrierY = resolveCarrierCenterY(target)
+      if (carrierY !== null) {
+        this.setState({ carriageHeight: carrierY })
+      }
+    } else {
+      this.setState({ status: 'unloading' as CraneStatus })
+    }
+    // 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.pick(carrier, options)
+  }
+
+  /** Deposit a carrier into a rack cell (semantically = place). */
+  deposit(carrier: Component, cell: Component, options?: MoveOptions): Promise<void> {
+    return this.place(carrier, cell, options)
+  }
+
+  // ── 2D rendering ─────────────────────────────────────────────────────────
+
+  /**
+   * 2D — top-down rectangle showing the crane's footprint along the rail.
+   * 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()
+  }
+
+  // ── 3D ───────────────────────────────────────────────────────────────────
+
+  buildRealObject(): RealObject | undefined {
+    if (!this._simStarted) {
+      this._simStarted = true
+      // 초기 지연 800~2800ms 사이 random — 여러 crane 이 동기적으로 시작하지 않도록.
+      const initialDelay = 800 + Math.random() * 2000
+      setTimeout(() => {
+        this.simulate().catch(e => console.error('[Crane] simulate', e))
+      }, initialDelay)
+    }
+    return new Crane3D(this)
+  }
+
+  // ── Random animation (visual smoke test) ─────────────────────────────────
+  // things-scene 의 component.animate() (frameClock 기반, pause/speed 대응) 를 사용.
+
+  private _simStarted = false
+  private _simRunning = false
+  private _simAbort = false
+  // Rail = crane 의 *로컬 X 축* (state.rotation 적용). simulate 진입 시 1회 계산해서 캐시.
+  private _railOriginX = 0
+  private _railOriginY = 0
+  private _railCos = 1
+  private _railSin = 0
+  private _railMin = NaN      // local-X 축 rail offset min
+  private _railMax = NaN      // local-X 축 rail offset max
+  private _targetSide = 1     // +Z (fork +Z 로 뻗어야 하나) / -Z
+
+  /** Continuous random pick → transport → place cycles. Visual smoke test. */
+  async simulate(): Promise<void> {
+    if (this._simRunning) return
+    this._simRunning = true
+    this._simAbort = false
+    try {
+      this._initRailRange()
+      while (!this._simAbort) {
+        await this._oneCycle()
+      }
+    } finally {
+      this._simRunning = false
+    }
+  }
+
+  /**
+   * state.target bbox 를 crane 의 *로컬 X 축* 으로 projection 해서 rail range 1회 계산.
+   * Rotation 적용된 crane 의 local X (= rail) 방향으로 움직이도록 cos/sin 캐시.
+   */
+  private _initRailRange(): void {
+    this._railMin = this._railMax = NaN
+
+    // 1순위: state.target refid 로 명시. 2순위: crane 의 parent 컴포넌트 (자연스러운
+    // "이 컨테이너 안에서만 움직여" 기본값).
+    const targetRefId = (this.state as any).target as string | undefined
+    const root = (this as any).root
+    let target = targetRefId ? root?.findById?.(targetRefId) : null
+    if (!target) {
+      const parent = (this as any).parent
+      // parent 가 root/model-layer 같은 top-level 이면 bbox 가 의미없음 → skip
+      if (parent && parent !== root && (parent.state as any)?.width > 0) {
+        target = parent
+      }
+    }
+    if (!target) return
+
+    const tState = target.state ?? {}
+    const tl = numOr(tState.left, 0)
+    const tt = numOr(tState.top, 0)
+    const tw = numOr(tState.width, 0)
+    const th = numOr(tState.height, 0)
+    if (tw <= 0 || th <= 0) return
+
+    const W = numOr((this.state as any).width, 100)
+    const H = numOr((this.state as any).height, 100)
+    const rotation = numOr((this.state as any).rotation, 0)
+    const cos = Math.cos(rotation)
+    const sin = Math.sin(rotation)
+
+    // Rail origin = crane 의 현재 canvas center. 이 점에서 local X 방향으로 ±rail offset.
+    this._railOriginX = numOr((this.state as any).left, 0) + W / 2
+    this._railOriginY = numOr((this.state as any).top, 0) + H / 2
+    this._railCos = cos
+    this._railSin = sin
+
+    // Target bbox 4 corner 를 crane local frame 으로 projection.
+    // local X (rail) = dx*cos + dy*sin
+    // local Z (aisle) = -dx*sin + dy*cos
+    const corners = [
+      { x: tl, y: tt },
+      { x: tl + tw, y: tt },
+      { x: tl, y: tt + th },
+      { x: tl + tw, y: tt + th }
+    ]
+    let minRail = Infinity
+    let maxRail = -Infinity
+    let aisleSum = 0
+    for (const c of corners) {
+      const dx = c.x - this._railOriginX
+      const dy = c.y - this._railOriginY
+      const rail = dx * cos + dy * sin
+      const aisle = -dx * sin + dy * cos
+      if (rail < minRail) minRail = rail
+      if (rail > maxRail) maxRail = rail
+      aisleSum += aisle
+    }
+    // Crane 자체 W 만큼 안쪽으로 좁혀 — crane center 가 [minRail+W/2, maxRail-W/2] 안에
+    // 있으면 crane 전체가 target bbox 안 (local X 방향).
+    this._railMin = minRail + W / 2
+    this._railMax = Math.max(this._railMin, maxRail - W / 2)
+    this._targetSide = aisleSum >= 0 ? +1 : -1
+  }
+
+  stopSimulate(): void {
+    this._simAbort = true
+    // 진행 중인 animate() controller 도 즉시 정지 — onComplete 가 호출되어 _tween Promise
+    // 가 resolve → simulate() while 루프가 다음 반복에서 _simAbort 보고 종료. 이걸로
+    // 루프 stack 의 strong ref 해소, frameClock subscription 해제.
+    const ctrl = (this as any)._animate
+    if (ctrl && typeof ctrl.stop === 'function') {
+      try { ctrl.stop() } catch {}
+    }
+  }
+
+  /**
+   * 컴포넌트 dispose 시 (보드 종료, scene reload 등) 진행 중 simulate 루프와 animate
+   * subscription 을 정리. 미정리 시 루프의 await stack 이 component 를 strong reference
+   * 로 잡아 GC 안 됨 + frameClock 콜백 살아남음.
+   */
+  dispose(): void {
+    this.stopSimulate()
+    super.dispose?.()
+  }
+
+  private async _oneCycle(): Promise<void> {
+    const W = numOr((this.state as any).width, 100)
+    const H = numOr((this.state as any).height, 100)
+    const D = numOr((this.state as any).depth, W * 4)
+    const forkLen = numOr((this.state as any).forkLength, H * 0.6)
+
+    if (!Number.isFinite(this._railMin) || !Number.isFinite(this._railMax)) {
+      await new Promise(r => setTimeout(r, 800))
+      return
+    }
+
+    const pickRail = () => this._railMin + Math.random() * Math.max(0, this._railMax - this._railMin)
+    const toLeftTop = (rail: number) => ({
+      left: this._railOriginX + rail * this._railCos - W / 2,
+      top: this._railOriginY + rail * this._railSin - H / 2
+    })
+
+    const source = toLeftTop(pickRail())
+    const dest = toLeftTop(pickRail())
+
+    const sourceCH = Math.random() * D * 0.75
+    const destCH = Math.random() * D * 0.75
+    const liftH = Math.max(20, D * 0.02)
+    const side = this._targetSide
+
+    // Tween duration 은 base 의 70~130% 사이 random — 여러 crane 이 같은 타이밍으로 안 보이도록.
+    const jitter = (base: number): number => base * (0.7 + Math.random() * 0.6)
+
+    // 이동: crane local X 방향 → canvas (left, top) 둘 다 동시 변경 (rotation 적용 시 diagonal)
+    await this._tween({ status: 'moving', left: source.left, top: source.top, carriageHeight: sourceCH }, jitter(1500))
+    await this._tween({ status: 'loading', forkExtension: side * forkLen }, jitter(700))
+    await this._tween({ forkLift: liftH }, jitter(400))
+    await this._tween({ forkExtension: 0 }, jitter(700))
+    await this._tween({ status: 'moving', left: dest.left, top: dest.top, carriageHeight: destCH }, jitter(1500))
+    await this._tween({ status: 'unloading', forkExtension: side * forkLen }, jitter(700))
+    await this._tween({ forkLift: 0 }, jitter(400))
+    await this._tween({ status: 'idle', forkExtension: 0 }, jitter(700))
+
+    // 사이클 사이 짧은 idle (200~1000ms) — 자연스러운 phase 분산
+    await new Promise(r => setTimeout(r, 200 + Math.random() * 800))
+  }
+
+  /**
+   * things-scene 의 `component.animate()` 로 한 구간 tween. step 콜백에서 setState 호출.
+   * frameClock.simTime 기반이라 scene pause / speed change / suppressAnimations 모두 자동 대응.
+   */
+  private _tween(targets: Record<string, any>, duration: number): Promise<void> {
+    const start: Record<string, number> = {}
+    for (const k of Object.keys(targets)) {
+      if (k === 'status') continue
+      const v = (this.state as any)[k]
+      start[k] = typeof v === 'number' && Number.isFinite(v) ? v : 0
+    }
+    if (typeof targets.status === 'string') {
+      this.setState({ status: targets.status })
+    }
+    return new Promise<void>(resolve => {
+      let resolved = false
+      const finish = () => {
+        if (resolved) return
+        resolved = true
+        resolve()
+      }
+      const controller = (this as any).animate({
+        duration,
+        ease: 'inout',
+        delta: 'quad',
+        step: (dx: number) => {
+          if (this._simAbort) {
+            controller.stop?.()
+            return finish()
+          }
+          const update: Record<string, number> = {}
+          for (const k of Object.keys(start)) {
+            const tgt = targets[k]
+            if (typeof tgt !== 'number') continue
+            update[k] = start[k] + (tgt - start[k]) * dx
+          }
+          this.setState(update as any)
+        },
+        onComplete: finish
+      })
+      controller.start()
+    })
+  }
+}
+
+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/index.ts

@@ -9,12 +9,19 @@ 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'
+export { default as StorageRack } from './storage-rack.js'
+export type { StorageRackState } from './storage-rack.js'
+export { StorageRack3D } from './storage-rack-3d.js'
+export { default as RackGrid } from './rack-grid.js'
+export type { RackGridState } from './rack-grid.js'
+export { RackGrid3D } from './rack-grid-3d.js'
+export { default as MobileStorageRack } from './mobile-storage-rack.js'
+export { default as StorageCell } from './storage-cell.js'
+export type { StorageCellType } from './storage-cell.js'
+export { StorageCell3D } from './storage-cell-3d.js'
+export { default as Crane } from './crane.js'
+export type { CraneState, CraneStatus } from './crane.js'
+export { Crane3D } from './crane-3d.js'
 
 export { default as Spot } from './spot.js'
 export { Spot3D } from './spot-3d.js'

package/src/mobile-storage-rack.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * MobileRack — a Rack that can also move.
+ *
+ * The whole point of the storage abstraction: `Mover(Rack)` mixin gives a
+ * *moving storage* without changing Rack's role. Use cases — an AGV-mounted
+ * rack, a cart, a tote-on-conveyor, a mobile shelving unit, etc.
+ *
+ * The cells, the cell-map topology, the Pickable contract, the carrier
+ * attach-point — all unchanged. Only thing added: the rack can `moveTo(...)`,
+ * `pick(...)`, `place(...)`, `pickAndPlace(...)`.
+ *
+ * Component type: `mobile-rack`. Use `<mobile-rack levels=...>` on the
+ * board same as a Rack; pickers (Crane / Forklift / robot arm) interact
+ * with its cells via the same RackCell-side contract.
+ *
+ * Note: a moving rack is itself a *picker target* from another picker's
+ * point of view — the same RackCell.acceptanceRotation contract applies
+ * because cells, not racks, are the picker's interlocutor.
+ */
+
+import { Component, ContainerCapacity, sceneComponent } from '@hatiolab/things-scene'
+import type { SlotDef } from '@hatiolab/things-scene'
+import { Mover } from '@operato/scene-base'
+
+import StorageRack from './storage-rack.js'
+
+// `Mover(Rack)` adds moveTo / pick / place / engage. `ContainerCapacity` is
+// also added so the rack itself participates in slot bookkeeping when it
+// behaves as a (mobile) carrier holder during transit. Rack already extends
+// `CarrierHolder + Placeable`, so the full chain becomes:
+//   Mover → ContainerCapacity → Rack(=CellContainer → CarrierHolder → Placeable → ContainerAbstract)
+@sceneComponent('mobile-storage-rack')
+export default class MobileRack extends Mover(ContainerCapacity(StorageRack as any)) {
+  /**
+   * Mobile racks carry their cells as cargo. The crane that *moves* a
+   * MobileRack treats the rack itself as the carrier — one slot, one rack.
+   */
+  get slots(): SlotDef[] {
+    return [{ id: 'self', maxCount: 1 }]
+  }
+
+  /**
+   * The toolType for a fork/clamp that lifts an entire mobile rack.
+   * Different from the per-pallet tooling used to extract a carrier from
+   * a cell inside the rack.
+   */
+  get toolType(): string {
+    return 'rack-clamp'
+  }
+}
+
+// Re-export `Component` import to keep the file self-contained for IDEs that
+// flatten dependency graphs. (Used implicitly by the parent mixin chain.)
+export { Component }