@operato/scene-storage 10.0.0-beta.22

package/src/pallet.ts

@@ -0,0 +1,125 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, Container, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Carriable,
+  Legendable,
+  Placeable,
+  type Alignment,
+  type LegendBinding,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Pallet3D } from './pallet-3d.js'
+
+/**
+ * Pallet material — drives both 2D fill color and 3D structure.
+ *
+ * - `wood`     — traditional EUR / EPAL pallet: parallel slats on top and
+ *                bottom, three perpendicular stringers between them.
+ * - `plastic`  — molded one-piece pallet: solid top deck with cutouts,
+ *                hollow underside with feet. Distinct ribbed underside.
+ *
+ * Adding a third material (e.g. metal, composite) is a one-line change to the
+ * legend + a 3D variant in pallet-3d.ts.
+ */
+export type PalletMaterial = 'wood' | 'plastic'
+
+const BODY_LEGEND = {
+  wood: '#a87644',
+  plastic: '#5a6a78',
+  default: '#a87644'
+}
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'select',
+      label: 'material',
+      name: 'material',
+      property: {
+        options: [
+          { display: 'Wood', value: 'wood' },
+          { display: 'Plastic', value: 'plastic' }
+        ]
+      }
+    }
+  ],
+  help: 'scene/component/pallet'
+}
+
+// Carriable: a pallet can sit on AGV / Forklift / robot-arm gripper / Spot
+// and also accept boxes / parcels as children (Container base provides the
+// child-container behavior; Carriable only adds the holder-mount hook).
+const Base = Carriable(Legendable(Placeable(Container))) as unknown as typeof Component
+
+/**
+ * Pallet — a flat transport structure that goods are stacked and stored on.
+ *
+ * Standard EUR pallet is 1200 × 800mm × 144mm; we don't enforce these
+ * dimensions but they're a good starting point for the catalog templates.
+ *
+ * **Container-based.** Boxes / parcels stacked on the pallet are added as
+ * children — same `containable()` archetype-filter pattern as Forklift / Agv.
+ * Visual stacking (children rendering on top of the pallet rather than at
+ * absolute operation level) is a v2 concern; see ARCHITECTURE NOTES below.
+ *
+ * **Placement = `operation`.** A pallet's *normal* state is loaded and in
+ * transit on a conveyor / AGV / forklift fork — at operation level. Empty
+ * pallets in a floor-storage area are an exceptional state where the user
+ * sets `state.zPos = 0` explicitly. Default to the common case.
+ *
+ * ## ARCHITECTURE NOTES — visual stacking
+ *
+ * When a Box (also `placement: 'operation'`) is added as a child of a
+ * Pallet, both default to z = operation_height. They overlap visually
+ * rather than the box sitting on top of the pallet. Solving this cleanly
+ * (parent-relative z derivation when the parent is a structural carrier)
+ * is a follow-up — fmsim's pattern is to detect parent type at render time
+ * (machine-3d.ts:113-122). v1 accepts the visual overlap; v2 will add the
+ * detection.
+ */
+@sceneComponent('pallet')
+export default class Pallet extends Base {
+  static legends: Record<string, LegendBinding> = {
+    bodyColor: { from: 'material', legend: BODY_LEGEND }
+  }
+
+  static placement: PlacementArchetype = 'operation'
+  static align: Alignment = 'bottom'
+  static defaultDepth = 150 // EUR pallet is 144mm; 150 is the round number convention
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /** Accept other operation-archetype cargo (boxes, parcels, smaller pallets) as stacked children. */
+  containable(component: Component) {
+    const archetype = (component.constructor as any).placement
+    if (archetype === 'operation') return true
+    return component.isDescendible(this as any)
+  }
+
+  /** 2D — top-down rectangle. */
+  render(ctx: CanvasRenderingContext2D) {
+    const { width, height, left, top } = this.state
+    ctx.beginPath()
+    ctx.rect(left, top, width, height)
+  }
+
+  get fillStyle() {
+    return (this.state.bodyColor as string) || '#a87644'
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Pallet3D(this as any)
+  }
+}

package/src/parcel-3d.ts

@@ -0,0 +1,90 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Parcel 3D — a cardboard package.
+ *
+ * Structure:
+ *   - main body box (cardboard color)
+ *   - tape line running across the top (the visual signature — what makes
+ *     this read as a "shipping parcel" rather than a generic box)
+ *   - small label area on top (white rectangle suggesting a shipping label)
+ *
+ * Kept very simple — parcels in a logistics scene are typically present in
+ * large numbers (sortation lines, fulfillment bays), so polygon count
+ * matters more than it does for one-off equipment.
+ */
+
+import * as THREE from 'three'
+import { RealObjectGroup } from '@hatiolab/things-scene'
+
+const CARDBOARD_COLOR = 0xc8a878
+const TAPE_COLOR = 0xddc899
+const LABEL_COLOR = 0xeeeeee
+
+export class Parcel3D extends RealObjectGroup {
+  build() {
+    super.build()
+
+    const { width, height, depth = 150 } = this.component.state
+    const baseY = -depth / 2
+
+    // ── Main body ────────────────────────────────────────────────────
+    const bodyGeo = new THREE.BoxGeometry(width, depth, height)
+    const bodyMaterial = new THREE.MeshStandardMaterial({
+      color: CARDBOARD_COLOR,
+      metalness: 0,
+      roughness: 0.9
+    })
+    const bodyMesh = new THREE.Mesh(bodyGeo, bodyMaterial)
+    bodyMesh.position.set(0, 0, 0)
+    bodyMesh.castShadow = true
+    bodyMesh.receiveShadow = true
+    this.object3d.add(bodyMesh)
+
+    // ── Tape line on top (running along the long axis) ───────────────
+    const tapeW = Math.min(width, height) * 0.10
+    const tapeT = depth * 0.02
+    const tapeAlongLong = width >= height
+    const tapeGeo = tapeAlongLong
+      ? new THREE.BoxGeometry(width * 1.005, tapeT, tapeW)
+      : new THREE.BoxGeometry(tapeW, tapeT, height * 1.005)
+    const tapeMaterial = new THREE.MeshStandardMaterial({
+      color: TAPE_COLOR,
+      metalness: 0.05,
+      roughness: 0.5
+    })
+    const tapeMesh = new THREE.Mesh(tapeGeo, tapeMaterial)
+    tapeMesh.position.set(0, baseY + depth + tapeT / 2 - 0.01, 0)
+    this.object3d.add(tapeMesh)
+
+    // ── Shipping label (small white rectangle on top) ────────────────
+    const labelW = Math.min(width, height) * 0.35
+    const labelH = labelW * 0.6
+    const labelGeo = new THREE.BoxGeometry(labelW, depth * 0.005, labelH)
+    const labelMaterial = new THREE.MeshStandardMaterial({
+      color: LABEL_COLOR,
+      metalness: 0,
+      roughness: 0.4
+    })
+    const labelMesh = new THREE.Mesh(labelGeo, labelMaterial)
+    // Position on top, off-center by ~25% of long axis
+    if (tapeAlongLong) {
+      labelMesh.position.set(width * 0.2, baseY + depth + depth * 0.0025, -height * 0.15)
+    } else {
+      labelMesh.position.set(width * 0.15, baseY + depth + depth * 0.0025, height * 0.2)
+    }
+    this.object3d.add(labelMesh)
+  }
+
+  updateDimension() {}
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if ('width' in after || 'height' in after || 'depth' in after) {
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  updateAlpha() {}
+}

package/src/parcel.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Carriable,
+  Placeable,
+  type Alignment,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Parcel3D } from './parcel-3d.js'
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'string',
+      label: 'tracking-id',
+      name: 'trackingId'
+    }
+  ],
+  help: 'scene/component/parcel'
+}
+
+// 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.
+ *
+ * Distinct from `Box` because parcels have:
+ *   - cardboard appearance (tan/brown corrugate, not wood / plastic)
+ *   - tape line down the center (the visual signature that says "package")
+ *   - typically a label on top (where shipping info goes)
+ *   - flatter / more elongated proportions in real-world parcel networks
+ *
+ * No `material` prop — parcels are always cardboard. If a future shipping
+ * domain needs metal cases or polybags, those become separate components.
+ *
+ * No Legendable for v1 — parcel color is fixed cardboard. Future damaged /
+ * inspected indicators would add a status legend then.
+ */
+@sceneComponent('parcel')
+export default class Parcel extends Base {
+  static placement: PlacementArchetype = 'operation'
+  static align: Alignment = 'bottom'
+  static defaultDepth = 150
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /** 2D — top-down rectangle in cardboard tan. */
+  render(ctx: CanvasRenderingContext2D) {
+    const { width, height, left, top } = this.state
+    ctx.beginPath()
+    ctx.rect(left, top, width, height)
+  }
+
+  get fillStyle() {
+    return '#c8a878'
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Parcel3D(this as any)
+  }
+}

package/src/spot-3d.ts

@@ -0,0 +1,200 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Spot 3D — translucent floor pad.
+ *
+ * Renders only the FLOOR face of the conceptual zone box; side walls are
+ * absent. Children (carriers) sit on the top face via an explicit attach
+ * frame; the pad doesn't occlude them (`depthWrite: false`).
+ *
+ * Standard things-scene properties read directly:
+ *   - state.fillStyle  → pad color (sole color source)
+ *   - state.strokeStyle → outline color (defaults to fillStyle)
+ *   - state.alpha      → pad transparency, multiplied with the base 0.35 tint
+ *   - state.text       → label, rendered as a CanvasTexture quad on the pad
+ *   - state.fontColor  → label fill (defaults to fillStyle)
+ *   - state.fontSize / fontFamily / bold / italic → label typography
+ *                        (composed via the things-scene fontStyle helper)
+ *   - state.material3d → metalness / roughness / castShadow / receiveShadow
+ *                        (resolved + applied via the things-scene helpers,
+ *                        no hard-coded numbers)
+ */
+
+import * as THREE from 'three'
+import {
+  RealObjectGroup,
+  resolveMaterial3d,
+  applyMaterial3dProps,
+  fontStyle,
+  opaqueColor,
+  type Material3D
+} from '@hatiolab/things-scene'
+
+const DEFAULT_PAD_COLOR = '#3a8fbd'
+const BASE_PAD_OPACITY = 0.35 // multiplied by state.alpha
+
+export class Spot3D extends RealObjectGroup {
+  build() {
+    super.build()
+
+    const state = this.component.state as any
+    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)
+    // opaqueColor strips alpha from rgba/hsla strings — THREE.Color doesn't
+    // honor alpha, would emit a console warning, and ignore the alpha bit.
+    // The actual transparency comes through the material.opacity below.
+    const padColor = opaqueColor((state.fillStyle as string) || DEFAULT_PAD_COLOR)
+    const alpha = clamp(numOr(state.alpha, 1), 0, 1)
+    const padOpacity = clamp(BASE_PAD_OPACITY * alpha, 0.05, 1)
+
+    // material3d: pulls user-set metalness / roughness / shadow / side.
+    // Local defaults (transparent + DoubleSide + depthWrite:false) come
+    // from the constructor below; user values override via applyMaterial3dProps.
+    const resolved = resolveMaterial3d(state.material3d as Material3D | undefined)
+
+    // ── Floor pad (the only visible surface of the conceptual zone box) ──
+    const padThickness = Math.max(d * 0.4, 0.5)
+    const padMat = new THREE.MeshStandardMaterial({
+      color: padColor,
+      transparent: true,
+      opacity: padOpacity,
+      side: THREE.DoubleSide,
+      depthWrite: false
+    })
+    applyMaterial3dProps(padMat, resolved)
+    const pad = new THREE.Mesh(new THREE.BoxGeometry(w, padThickness, h), padMat)
+    pad.position.set(0, -d / 2 + padThickness / 2, 0)
+    pad.castShadow = resolved.castShadow
+    pad.receiveShadow = resolved.receiveShadow
+    this.object3d.add(pad)
+
+    // ── Outline of the zone footprint (line on the floor) ──
+    const outlineGeo = new THREE.BufferGeometry().setFromPoints([
+      new THREE.Vector3(-w / 2, -d / 2 + padThickness + 0.05, -h / 2),
+      new THREE.Vector3(w / 2, -d / 2 + padThickness + 0.05, -h / 2),
+      new THREE.Vector3(w / 2, -d / 2 + padThickness + 0.05, h / 2),
+      new THREE.Vector3(-w / 2, -d / 2 + padThickness + 0.05, h / 2),
+      new THREE.Vector3(-w / 2, -d / 2 + padThickness + 0.05, -h / 2)
+    ])
+    const outlineMat = new THREE.LineBasicMaterial({
+      color: opaqueColor((state.strokeStyle as string) || padColor),
+      transparent: true,
+      opacity: 0.7 * alpha
+    })
+    const outline = new THREE.Line(outlineGeo, outlineMat)
+    this.object3d.add(outline)
+
+    // ── Label (uses standard text + font fields) ──
+    const text = state.text
+    if (typeof text === 'string' && text.length > 0) {
+      const label = this._buildLabel(text, state, padColor, w, h)
+      if (label) {
+        label.position.set(0, -d / 2 + padThickness + Math.max(w, h) * 0.05, 0)
+        this.object3d.add(label)
+      }
+    }
+  }
+
+  /**
+   * Build the label as a canvas-textured quad. Uses the same `fontStyle`
+   * helper things-scene uses for its 2D text rendering, so the label
+   * here matches what the property panel previews.
+   */
+  private _buildLabel(text: string, state: any, defaultColor: string, w: number, h: number): THREE.Mesh | null {
+    const fontSize = clamp(numOr(state.fontSize, 36), 8, 200)
+    const fontFamily = String(state.fontFamily ?? 'sans-serif')
+    const bold = !!state.bold
+    const italic = !!state.italic
+    const color = (state.fontColor as string) || defaultColor
+
+    const canvas = document.createElement('canvas')
+    canvas.width = 512
+    canvas.height = 128
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return null
+    ctx.clearRect(0, 0, canvas.width, canvas.height)
+    ctx.font = fontStyle(bold, italic, fontSize, fontFamily)
+    ctx.fillStyle = color
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(text, canvas.width / 2, canvas.height / 2)
+    const tex = new THREE.CanvasTexture(canvas)
+    tex.needsUpdate = true
+    const labelMat = new THREE.MeshBasicMaterial({
+      map: tex,
+      transparent: true,
+      depthWrite: false,
+      side: THREE.DoubleSide
+    })
+    const labelW = Math.min(w, h) * 0.6
+    const labelH = labelW * (canvas.height / canvas.width)
+    const mesh = new THREE.Mesh(new THREE.PlaneGeometry(labelW, labelH), labelMat)
+    mesh.rotation.x = -Math.PI / 2 // lay flat, readable from above
+    return mesh
+  }
+
+  /**
+   * The sub-frame that carrier components should mount onto.
+   *
+   * Semantically Spot is a virtual cuboid SPACE — it marks "stuff goes
+   * here" — and carriers are placed INSIDE that space, resting on the
+   * cuboid's BOTTOM face. So the attach frame sits at the cuboid's
+   * bottom (`y = -d/2` in spot-local), NOT at the top of the rendered
+   * pad. The pad is just a translucent visual marker for the zone; the
+   * floor of the conceptual volume is what carriers stand on.
+   *
+   * The Spot.attachPointFor mixin lifts the carrier by its own halfDepth
+   * (in the +Y direction within this frame), placing the carrier's
+   * BOTTOM face exactly at the cuboid floor.
+   */
+  getAttachFrame(): THREE.Object3D {
+    if (!this._attachFrame) {
+      const d = this.effectiveDepth
+      this._attachFrame = new THREE.Object3D()
+      this._attachFrame.position.set(0, -d / 2, 0)
+      this.object3d.add(this._attachFrame)
+    }
+    return this._attachFrame
+  }
+
+  private _attachFrame?: THREE.Object3D
+
+  updateDimension() {}
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if (
+      'width' in after ||
+      'height' in after ||
+      'depth' in after ||
+      'fillStyle' in after ||
+      'strokeStyle' in after ||
+      'alpha' in after ||
+      'text' in after ||
+      'fontColor' in after ||
+      'fontSize' in after ||
+      'fontFamily' in after ||
+      'bold' in after ||
+      'italic' in after ||
+      'material3d' in after
+    ) {
+      this._attachFrame = undefined
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  // alpha is rebuilt into the materials on every build; opt out of the
+  // base RealObject's "multiply existing material opacity" pass to avoid
+  // double-application.
+  updateAlpha() {}
+}
+
+function clamp(v: number, lo: number, hi: number) {
+  return Math.max(lo, Math.min(hi, v))
+}
+
+function numOr(v: unknown, dflt: number): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : dflt
+}

package/src/spot.ts

@@ -0,0 +1,197 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Spot — virtual pickup / drop zone.
+ *
+ * A modeling-time anchor for "this is where things land" — the destination
+ * of a robot arm pick-and-place, the slot of an AGV stop, the staging
+ * zone next to a conveyor. Spot itself does not move and does
+ * not perform any logistics action; it only marks a location and accepts
+ * carrier components as children.
+ *
+ * Visual identity:
+ *   - 2D: outlined rectangle with corner "L" marks (so it reads as a
+ *     virtual zone, not a solid object).
+ *   - 3D: a thin translucent floor pad — only the floor of the conceptual
+ *     box is rendered, the side walls are absent.
+ *
+ * Standard things-scene properties used (no component-specific extras —
+ * keep the property-panel UX uniform with other components):
+ *   - `fillStyle`               — pad / outline color (sole color source)
+ *   - `strokeStyle`             — outline color override (defaults to fillStyle)
+ *   - `lineWidth` / `lineDash`  — outline stroke style
+ *   - `alpha`                   — overall transparency, framework-applied
+ *   - `text` / `fontColor` / `fontSize` / `fontFamily` / `bold` / `italic`
+ *                               — label rendered by the standard text pipeline
+ *   - `material3d` (3D)         — metalness / roughness / castShadow / receiveShadow
+ *
+ * Role: `CarrierHolder` — accepts any Carrier as a child and lays it on
+ * the top face of the pad (overrides default attachPointFor).
+ */
+
+import { Component, ComponentNature, Container, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import {
+  CarrierHolder,
+  Placeable,
+  type Alignment,
+  type Heights,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Spot3D } from './spot-3d.js'
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  // No component-specific properties — fillStyle / strokeStyle / lineWidth /
+  // alpha / text / font* are framework-standard, surfaced by the property
+  // panel automatically.
+  properties: [],
+  help: 'scene/component/spot'
+}
+
+// Container base — Spot accepts carrier children (parcel/box/pallet/...).
+// CarrierHolder mixin only publishes the attach-point hook; the actual
+// child-list management comes from the things-scene Container.
+const Base = CarrierHolder(Placeable(Container)) as unknown as typeof Component
+
+@sceneComponent('spot')
+export default class Spot extends Base {
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (_h: Heights) => 2 // a thin pad
+
+  get nature(): ComponentNature {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /**
+   * 2D — outlined rectangle + corner L marks. The pad body is drawn with a
+   * fixed low alpha (0.15) on top of the user's `fillStyle` so the zone reads
+   * as virtual even when fillStyle is fully opaque. Outline + corner marks
+   * use `strokeStyle` (or fall back to `fillStyle`) at the user's `lineWidth`
+   * and `lineDash`. The text label is drawn by the framework's standard
+   * postrender pipeline using `text` / `fontColor` / `fontSize` / etc.
+   */
+  render(ctx: CanvasRenderingContext2D) {
+    const { left = 0, top = 0, width = 100, height = 100 } = this.state
+    const fillStyle = (this.state.fillStyle as string) || '#3a8fbd'
+    const strokeStyle = (this.state.strokeStyle as string) || fillStyle
+    const lineWidth = numOr(this.state.lineWidth, 1)
+    const lineDashStyle = String(this.state.lineDash ?? 'dash')
+
+    // ── Pad body (fixed-low-alpha tint of fillStyle) ───────────────────
+    ctx.save()
+    ctx.fillStyle = fillStyle
+    ctx.globalAlpha = 0.15
+    ctx.fillRect(left, top, width, height)
+    ctx.restore()
+
+    // ── Outline ────────────────────────────────────────────────────────
+    ctx.save()
+    ctx.strokeStyle = strokeStyle
+    ctx.lineWidth = lineWidth
+    applyLineDash(ctx, lineDashStyle, lineWidth)
+    ctx.strokeRect(
+      left + lineWidth / 2,
+      top + lineWidth / 2,
+      width - lineWidth,
+      height - lineWidth
+    )
+    ctx.setLineDash([])
+    ctx.restore()
+
+    // ── Corner L marks (solid, slightly heavier than outline) ──────────
+    const ml = Math.min(width, height) * 0.18
+    const cornerW = Math.max(lineWidth * 1.5, 1.5)
+    ctx.save()
+    ctx.strokeStyle = strokeStyle
+    ctx.lineWidth = cornerW
+    for (const [cx, cy, sx, sy] of [
+      [left, top, 1, 1],
+      [left + width, top, -1, 1],
+      [left + width, top + height, -1, -1],
+      [left, top + height, 1, -1]
+    ] as [number, number, number, number][]) {
+      ctx.beginPath()
+      ctx.moveTo(cx + sx * ml, cy)
+      ctx.lineTo(cx, cy)
+      ctx.lineTo(cx, cy + sy * ml)
+      ctx.stroke()
+    }
+    ctx.restore()
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Spot3D(this as any)
+  }
+
+  /**
+   * Mount carriers on the TOP of the pad (Spot3D's `getAttachFrame` is
+   * already at pad-top in spot-local). Then lift the carrier by its
+   * own halfDepth so the carrier's BOTTOM rests ON the pad surface, not
+   * its volumetric center — without this lift, half the carrier would
+   * sink below the pad / floor.
+   *
+   * Reads `_realObject.effectiveDepth` first (the framework-resolved
+   * value, accounting for `static defaultDepth` and parent context),
+   * falling back to raw `state.depth` for components built before
+   * RealObject creation.
+   */
+  attachPointFor(carrier: Component) {
+    const ro = (this as any)._realObject as Spot3D | undefined
+    const frame = ro?.getAttachFrame?.()
+    if (!frame) return undefined
+    const carrierDepth = resolveDepth(carrier)
+    return {
+      attach: frame,
+      localPosition: { x: 0, y: carrierDepth / 2, z: 0 }
+    }
+  }
+}
+
+function resolveDepth(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
+}
+
+/**
+ * Map a things-scene `lineDash` string to a Canvas dash pattern. Mirrors
+ * the keys understood by things-scene's `drawer/stroke.ts` so users see
+ * consistent options across components. Unknown strings fall through to
+ * a plain dashed pattern instead of throwing on setLineDash.
+ */
+function applyLineDash(ctx: CanvasRenderingContext2D, style: string, lw: number) {
+  switch (style) {
+    case 'solid':
+      ctx.setLineDash([])
+      return
+    case 'round-dot':
+      ctx.setLineDash([0.1, lw * 2])
+      ctx.lineCap = 'round'
+      return
+    case 'square-dot':
+      ctx.setLineDash([lw, lw])
+      return
+    case 'long-dash':
+      ctx.setLineDash([lw * 6, lw * 3])
+      return
+    case 'dash-dot':
+      ctx.setLineDash([lw * 4, lw * 2, lw, lw * 2])
+      return
+    case 'dash':
+    default:
+      ctx.setLineDash([lw * 4, lw * 1.5])
+      return
+  }
+}