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

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,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
 ]

package/test/setup.js

@@ -0,0 +1,279 @@
+/*
+ * Browser polyfills for Node.js test environment.
+ * Required when importing @hatiolab/things-scene bundle which uses browser globals at module scope.
+ */
+
+var noop = function () {}
+
+// Image polyfill (used at module scope in move-handle.ts)
+if (typeof global.Image === 'undefined') {
+  global.Image = class Image {
+    constructor() {
+      this.onload = null
+      this.onerror = null
+      this.src = ''
+      this.width = 0
+      this.height = 0
+    }
+    set src(v) { this._src = v }
+    get src() { return this._src || '' }
+    addEventListener(evt, fn) {}
+    removeEventListener() {}
+  }
+}
+
+// HTMLCanvasElement polyfill
+if (typeof global.HTMLCanvasElement === 'undefined') {
+  global.HTMLCanvasElement = class HTMLCanvasElement {
+    constructor() { this.width = 0; this.height = 0 }
+    getContext() { return null }
+    toDataURL() { return '' }
+    addEventListener() {}
+    removeEventListener() {}
+  }
+}
+
+// HTMLElement / HTMLVideoElement stubs
+if (typeof global.HTMLElement === 'undefined') {
+  global.HTMLElement = class HTMLElement {}
+}
+if (typeof global.HTMLVideoElement === 'undefined') {
+  global.HTMLVideoElement = class HTMLVideoElement {}
+}
+
+// MutationObserver polyfill
+if (typeof global.MutationObserver === 'undefined') {
+  global.MutationObserver = class MutationObserver {
+    constructor(callback) {}
+    observe() {}
+    disconnect() {}
+    takeRecords() { return [] }
+  }
+}
+
+// ResizeObserver polyfill
+if (typeof global.ResizeObserver === 'undefined') {
+  global.ResizeObserver = class ResizeObserver {
+    constructor(callback) {}
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+}
+
+// Mini-DOM Node implementation
+function createNode(nodeType, tagName) {
+  var node = {
+    nodeType: nodeType,
+    tagName: tagName || '',
+    parentNode: null,
+    parentElement: null,
+    childNodes: [],
+    firstChild: null,
+    lastChild: null,
+    nextSibling: null,
+    previousSibling: null,
+    style: nodeType === 1 ? new Proxy({}, {
+      set: function(t,p,v){ t[p]=v; return true },
+      get: function(t,p){ if(p==='setProperty') return function(k,v){ t[k]=v }; return t[p] || '' }
+    }) : {},
+    textContent: '',
+    data: '',
+    setAttribute: noop,
+    getAttribute: function () { return null },
+    removeAttribute: noop,
+    addEventListener: noop,
+    removeEventListener: noop,
+    getContext: function() { return null },
+    contains: function () { return false },
+    querySelector: function() { return null },
+    querySelectorAll: function() { return [] },
+
+    appendChild: function (child) {
+      if (child.nodeType === 11) {
+        while (child.childNodes.length > 0) node.appendChild(child.childNodes[0])
+        return child
+      }
+      if (child.parentNode) child.parentNode.removeChild(child)
+      node.childNodes.push(child)
+      child.parentNode = node
+      child.parentElement = nodeType === 1 ? node : null
+      if (node.childNodes.length > 1) {
+        var prev = node.childNodes[node.childNodes.length - 2]
+        prev.nextSibling = child
+        child.previousSibling = prev
+      }
+      child.nextSibling = null
+      node.firstChild = node.childNodes[0]
+      node.lastChild = child
+      return child
+    },
+
+    removeChild: function (child) {
+      var idx = node.childNodes.indexOf(child)
+      if (idx === -1) return child
+      node.childNodes.splice(idx, 1)
+      if (child.previousSibling) child.previousSibling.nextSibling = child.nextSibling
+      if (child.nextSibling) child.nextSibling.previousSibling = child.previousSibling
+      child.parentNode = null; child.parentElement = null
+      child.previousSibling = null; child.nextSibling = null
+      node.firstChild = node.childNodes[0] || null
+      node.lastChild = node.childNodes[node.childNodes.length - 1] || null
+      return child
+    },
+
+    remove: function () { if (node.parentNode) node.parentNode.removeChild(node) },
+
+    insertBefore: function (newChild, refChild) {
+      if (!refChild) return node.appendChild(newChild)
+      if (newChild.nodeType === 11) {
+        var children = newChild.childNodes.slice()
+        for (var i = 0; i < children.length; i++) node.insertBefore(children[i], refChild)
+        return newChild
+      }
+      if (newChild.parentNode) newChild.parentNode.removeChild(newChild)
+      var idx = node.childNodes.indexOf(refChild)
+      if (idx === -1) return node.appendChild(newChild)
+      node.childNodes.splice(idx, 0, newChild)
+      newChild.parentNode = node
+      newChild.parentElement = nodeType === 1 ? node : null
+      newChild.nextSibling = refChild
+      newChild.previousSibling = refChild.previousSibling
+      if (refChild.previousSibling) refChild.previousSibling.nextSibling = newChild
+      refChild.previousSibling = newChild
+      node.firstChild = node.childNodes[0]
+      node.lastChild = node.childNodes[node.childNodes.length - 1]
+      return newChild
+    },
+
+    cloneNode: function (deep) {
+      var clone = createNode(nodeType, tagName)
+      clone.data = node.data; clone.textContent = node.textContent
+      if (deep && node.childNodes.length) {
+        for (var i = 0; i < node.childNodes.length; i++) clone.appendChild(node.childNodes[i].cloneNode(true))
+      }
+      return clone
+    },
+
+    replaceChild: function (newChild, oldChild) {
+      node.insertBefore(newChild, oldChild); node.removeChild(oldChild); return oldChild
+    }
+  }
+
+  if (nodeType === 1) {
+    node.children = []
+    if (tagName === 'template') {
+      node.content = createNode(11, '')
+      Object.defineProperty(node, 'innerHTML', {
+        get: function () { return '' },
+        set: function (html) { node.content = createNode(11, '') }
+      })
+    } else {
+      node.innerHTML = ''
+    }
+  }
+  return node
+}
+
+// document polyfill
+if (typeof global.document === 'undefined') {
+  global.document = {
+    documentElement: {},
+    fonts: { ready: Promise.resolve() },
+    createElement: function (tagName) { return createNode(1, tagName) },
+    createComment: function (data) { var n = createNode(8, ''); n.data = data || ''; return n },
+    createTextNode: function (data) { var n = createNode(3, ''); n.data = data || ''; return n },
+    createDocumentFragment: function () { return createNode(11, '') },
+    createTreeWalker: function (root, whatToShow) {
+      var walker = {
+        currentNode: root,
+        nextNode: function () {
+          var cur = walker.currentNode
+          if (!cur) return null
+          if (cur.childNodes && cur.childNodes.length > 0) { walker.currentNode = cur.childNodes[0]; return walker.currentNode }
+          var node = cur
+          while (node && node !== root) {
+            if (node.nextSibling) { walker.currentNode = node.nextSibling; return walker.currentNode }
+            node = node.parentNode
+          }
+          return null
+        }
+      }
+      return walker
+    },
+    importNode: function (node, deep) { return node && node.cloneNode ? node.cloneNode(deep) : node },
+    adoptNode: function (node) { return node },
+    querySelector: function() { return null },
+    querySelectorAll: function() { return [] },
+    body: createNode(1, 'body'),
+    head: createNode(1, 'head')
+  }
+}
+
+// getComputedStyle polyfill
+if (typeof global.getComputedStyle !== 'function') {
+  global.getComputedStyle = function () {
+    return { getPropertyValue: function () { return '' }, fontFamily: 'sans-serif' }
+  }
+}
+
+// window polyfill
+if (typeof global.window === 'undefined') {
+  global.window = global
+}
+
+global.addEventListener = global.addEventListener || noop
+global.removeEventListener = global.removeEventListener || noop
+
+if (!global.window.location) {
+  global.window.location = { hostname: 'localhost', href: 'http://localhost/' }
+}
+
+// screen polyfill
+if (typeof global.screen === 'undefined') {
+  global.screen = { width: 1280, height: 800 }
+}
+
+// requestAnimationFrame polyfill
+if (typeof global.requestAnimationFrame === 'undefined') {
+  var lastTime = 0
+  global.requestAnimationFrame = function (callback) {
+    var currTime = Date.now()
+    var timeToCall = Math.max(0, 16 - (currTime - lastTime))
+    var id = setTimeout(function () { callback(currTime + timeToCall) }, timeToCall)
+    lastTime = currTime + timeToCall
+    return id
+  }
+  global.cancelAnimationFrame = function (id) { clearTimeout(id) }
+}
+
+// performance polyfill
+if (typeof global.performance === 'undefined') {
+  global.performance = {}
+}
+if (!global.performance.now) {
+  var nowOffset = Date.now()
+  global.performance.now = function () { return Date.now() - nowOffset }
+}
+
+// WebGL stub (Three.js renderer check)
+if (typeof global.WebGLRenderingContext === 'undefined') {
+  global.WebGLRenderingContext = class WebGLRenderingContext {}
+}
+
+// CSS polyfill
+if (typeof global.CSS === 'undefined') {
+  global.CSS = { supports: function() { return false } }
+}
+
+// CustomEvent polyfill
+if (typeof global.CustomEvent === 'undefined') {
+  global.CustomEvent = class CustomEvent {
+    constructor(type, init) { this.type = type; this.detail = (init || {}).detail }
+  }
+}
+
+// URL polyfill (Node.js has this but in some versions it may be missing from global)
+if (typeof global.URL === 'undefined') {
+  global.URL = require('url').URL
+}