@operato/scene-storage 10.0.0-beta.56 → 10.0.0-beta.58

package/src/stockpile-3d.ts

@@ -13,12 +13,79 @@
 
 import * as THREE from 'three'
 import { RealObjectGroup } from '@hatiolab/things-scene'
+import { computeStackPositions } from '@operato/scene-base'
 
 import type Stockpile from './stockpile.js'
 import type { StackPattern, CarrierPreset } from './stockpile.js'
 
 const PAD_DEPTH = 2
 
+/**
+ * 그래프(root.__flowGraph)에서 이 stockpile 로 *들어오는* 노드(입구)를 찾아, 적치를 *입구
+ * 맞은편부터* 하도록 reverseX/Z 를 산출한다. storage 가 conveyance 를 import 하지 않고
+ * 캐시 속성만 일반적으로 읽음(토폴로지 viz 와 동일 방식). 입구/그래프 없으면 undefined →
+ * 기본(-x/-z 모서리부터). 입구 방향은 stockpile local frame 기준(회전 반영).
+ */
+function inflowFillOpts(stockpile: any): { advanceAlongX?: boolean; reverse?: boolean } | undefined {
+  const root = stockpile?.root
+  // 로드 직후(sim 전)엔 그래프 캐시가 없을 수 있다 — conveyance 가 globalThis 에 심은
+  // 빌더로 즉석 build(토폴로지 viz 와 동일). 없으면(컨베이어 미로드) 기본값.
+  if (root && !root.__flowGraph) {
+    try { (globalThis as any).__operatoBuildFlowGraph?.(root) } catch { /* ignore */ }
+  }
+  const cache = root?.__flowGraph
+  const out = cache?.graph?.out as Map<string, Array<string | null>> | undefined
+  const comps = cache?.components as Map<string, any> | undefined
+  // 그래프 빌더(flow-graph-coordinator collect)와 *동일* idOf — refid 는 set('refid') 로
+  // state.refid 에 저장되므로 c.refid 와 state.refid 를 둘 다 확인해야 한다. (c.refid 만 보면
+  // 명시 id 없는 stockpile 이 전부 undefined → bail → 기본값으로 떨어져 입구 도출 실패.)
+  const idOf = (c: any): string | undefined => {
+    const raw = c?.state?.id
+    if (typeof raw === 'string' && raw.length > 0) return raw
+    const refid = c?.refid ?? c?.state?.refid
+    return refid != null ? String(refid) : undefined
+  }
+  const myId = idOf(stockpile)
+  if (!out || !comps || !myId) return undefined
+  let feeder: any
+  out.forEach((targets, srcId) => {
+    if (!feeder && Array.isArray(targets) && targets.includes(myId)) feeder = comps.get(srcId)
+  })
+  const ss = stockpile?.state
+  // feeder(입구) 못 찾으면 기본값(undefined) — 마주한 슈트 없는 stockpile.
+  if (!feeder || !ss) return undefined
+  // 입구 흐름 = *소스 링크의 방향* — feeder(슈트)의 배출 anchor(이 stockpile 로 향하는) direction.
+  // (중심-중심 벡터가 아니라 링크 방향면을 써야 정확. 긴 슈트의 중심은 실제 유입면과 다를 수 있음.)
+  let dir: { x: number; z: number } | undefined
+  try {
+    const outs = feeder.getSegmentTopology?.()?.outbounds as Array<{ worldPos?: { x: number; z: number }; direction?: { x: number; z: number } }> | undefined
+    if (Array.isArray(outs) && outs.length) {
+      const sx = (ss.left ?? 0) + (ss.width ?? 0) / 2
+      const sz = (ss.top ?? 0) + (ss.height ?? 0) / 2
+      let best = outs[0]
+      let bestD = Infinity
+      for (const a of outs) {
+        if (!a?.worldPos || !a.direction) continue
+        const d = (a.worldPos.x - sx) ** 2 + (a.worldPos.z - sz) ** 2
+        if (d < bestD) { bestD = d; best = a } // stockpile 에 가장 가까운 배출 anchor
+      }
+      if (best?.direction) dir = best.direction
+    }
+  } catch { /* topology 못 얻으면 fallback 없음 → 기본 */ }
+  if (!dir) return undefined
+  // 흐름 방향(world)을 stockpile local frame 으로 (회전 -rot).
+  const rot = typeof ss.rotation === 'number' ? ss.rotation : 0
+  const cos = Math.cos(-rot)
+  const sin = Math.sin(-rot)
+  const lx = dir.x * cos - dir.z * sin
+  const lz = dir.x * sin + dir.z * cos
+  // 흐름이 x 우세면 x축 진행. items 는 흐름 방향 끝(먼저 닿는 곳)부터 쌓여 입구쪽으로 →
+  // 흐름이 + 면 + 끝부터(reverse).
+  const advanceAlongX = Math.abs(lx) >= Math.abs(lz)
+  const reverse = advanceAlongX ? lx > 0 : lz > 0
+  return { advanceAlongX, reverse }
+}
+
 /** carrierPreset 별 default 색 (state.carrierWidth/Height/Depth 미지정 시 크기와 함께). */
 const PRESET_COLOR: Record<CarrierPreset, number> = {
   box: 0xb87333,      // kraft brown
@@ -186,7 +253,15 @@ export class Stockpile3D extends RealObjectGroup {
       return presetDefaultColor
     }
 
-    const positions = this._computeStackPositions(pattern, count, areaW, areaH, cw, ch, cd, gap, state.stackHeightLimit)
+    // stackHeightLimit = *총 적치 높이*(scene unit) — 단(layer) 개수가 아니다. 아이템
+    // 한 단 높이(cd)로 나눠 최대 단 수로 환산해 전달. 예: 한도 60 + 아이템높이 10 → 6단.
+    const heightLimit = state.stackHeightLimit
+    const maxLayers = typeof heightLimit === 'number' && heightLimit > 0 && cd > 0
+      ? Math.max(1, Math.floor(heightLimit / cd))
+      : undefined
+    // 입구 맞은편부터 채우기 — 그래프에서 이 stockpile 로 들어오는 노드(입구)를 도출.
+    const fillOpts = inflowFillOpts(stockpile)
+    const positions = computeStackPositions(pattern, count, { w: areaW, h: areaH }, { w: cw, h: ch, d: cd }, gap, maxLayers, fillOpts)
     this._meshByRecordId.clear()
     const records = stockpile.records
     for (let i = 0; i < positions.length; i++) {
@@ -213,111 +288,6 @@ export class Stockpile3D extends RealObjectGroup {
     return this._meshByRecordId.get(recordId)
   }
 
-  /**
-   * stackPattern 별 각 carrier 의 local 좌표(영역 중심 기준). y 는 pad 위에 쌓이는
-   * 높이(cd 단위), x/z 는 영역 평면 위 분포.
-   */
-  private _computeStackPositions(
-    pattern: StackPattern,
-    count: number,
-    areaW: number,
-    areaH: number,
-    cw: number,
-    ch: number,
-    cd: number,
-    gap: number,
-    heightLimit?: number
-  ): Array<{ x: number; y: number; z: number }> {
-    const out: Array<{ x: number; y: number; z: number }> = []
-
-    // column — 한 자리에 수직 적층
-    if (pattern === 'column') {
-      const layers = heightLimit ?? count
-      for (let i = 0; i < count; i++) {
-        const layer = Math.min(i, layers - 1)
-        out.push({ x: 0, y: layer * cd + cd / 2, z: 0 })
-      }
-      return out
-    }
-
-    // 격자 cell — 행/열 수. cell stride = carrier + gap (인접 carrier 사이 분리).
-    const stridX = cw + gap
-    const stridZ = ch + gap
-    const cols = Math.max(1, Math.floor((areaW + gap) / stridX))
-    const rows = Math.max(1, Math.floor((areaH + gap) / stridZ))
-    const cellsPerLayer = cols * rows
-
-    // pyramid — 위로 갈수록 행/열 -1 씩 (사다리꼴)
-    if (pattern === 'pyramid') {
-      let remaining = count
-      let layer = 0
-      while (remaining > 0) {
-        const lcols = Math.max(1, cols - layer)
-        const lrows = Math.max(1, rows - layer)
-        const cellsThisLayer = lcols * lrows
-        const take = Math.min(remaining, cellsThisLayer)
-        for (let i = 0; i < take; i++) {
-          const c = i % lcols
-          const r = Math.floor(i / lcols)
-          // 가운데 정렬 — 줄어든 만큼 offset
-          const offsetCol = (cols - lcols) / 2
-          const offsetRow = (rows - lrows) / 2
-          const x = -areaW / 2 + (c + offsetCol + 0.5) * stridX
-          const z = -areaH / 2 + (r + offsetRow + 0.5) * stridZ
-          out.push({ x, y: layer * cd + cd / 2, z })
-        }
-        remaining -= take
-        layer++
-        if (lcols === 1 && lrows === 1) {
-          // 정상에 도달 — 남은 건 column 처럼 위로
-          for (let i = 0; i < remaining; i++) {
-            out.push({ x: 0, y: (layer + i) * cd + cd / 2, z: 0 })
-          }
-          break
-        }
-        if (heightLimit && layer >= heightLimit) break
-      }
-      return out
-    }
-
-    // pile — 자연 더미. row 와 비슷하되 가장자리는 약간 옆으로 흘러내림 효과
-    // (간단 구현 — 단마다 약간 random offset).
-    if (pattern === 'pile') {
-      // pseudo-random (인덱스 기반, deterministic)
-      const rng = (i: number) => ((Math.sin(i * 12.9898) * 43758.5453) % 1 + 1) % 1
-      for (let i = 0; i < count; i++) {
-        const layer = Math.floor(i / cellsPerLayer)
-        const idx = i % cellsPerLayer
-        const c = idx % cols
-        const r = Math.floor(idx / cols)
-        const jitterX = (rng(i * 2) - 0.5) * cw * 0.2
-        const jitterZ = (rng(i * 2 + 1) - 0.5) * ch * 0.2
-        const x = -areaW / 2 + (c + 0.5) * stridX + jitterX
-        const z = -areaH / 2 + (r + 0.5) * stridZ + jitterZ
-        out.push({ x, y: layer * cd + cd / 2, z })
-        if (heightLimit && layer >= heightLimit - 1 && idx === cellsPerLayer - 1) break
-      }
-      return out
-    }
-
-    // row (default) / staggered — 격자 적층
-    for (let i = 0; i < count; i++) {
-      const layer = Math.floor(i / cellsPerLayer)
-      if (heightLimit && layer >= heightLimit) break
-      const idx = i % cellsPerLayer
-      const c = idx % cols
-      const r = Math.floor(idx / cols)
-      let x = -areaW / 2 + (c + 0.5) * stridX
-      const z = -areaH / 2 + (r + 0.5) * stridZ
-      // staggered — 홀수 layer 는 1/2 cell offset (벽돌식)
-      if (pattern === 'staggered' && layer % 2 === 1) {
-        x += stridX / 2
-      }
-      out.push({ x, y: layer * cd + cd / 2, z })
-    }
-    return out
-  }
-
   /** carrierPreset 별 geometry. drum 은 cylinder, 나머지는 box. */
   private _carrierGeometry(preset: CarrierPreset, w: number, h: number, d: number): THREE.BufferGeometry {
     if (preset === 'drum') {

package/src/stockpile-grid-3d.ts

@@ -162,7 +162,11 @@ export class StockpileGrid3D extends RealObjectGroup {
     const ch = state.carrierHeight ?? def.h
     const cd = state.carrierDepth ?? def.d
     const gap = state.carrierGap ?? 10
-    const heightLimit = state.stackHeightLimit as number | undefined
+    // stackHeightLimit = *총 적치 높이*(scene unit) → 단(layer) 수로 환산 (아이템 한 단 = cd).
+    const rawHeightLimit = state.stackHeightLimit as number | undefined
+    const heightLimit = typeof rawHeightLimit === 'number' && rawHeightLimit > 0 && cd > 0
+      ? Math.max(1, Math.floor(rawHeightLimit / cd))
+      : undefined
 
     const cellW = grid.cellW
     const cellH = grid.cellH

package/src/stockpile-grid.ts

@@ -17,7 +17,7 @@
  */
 
 import * as THREE from 'three'
-import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, ContainerAbstract, Holdable, RealObject, sceneComponent } from '@hatiolab/things-scene'
 import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
@@ -99,7 +99,7 @@ const NATURE: ComponentNature = {
 
 @sceneComponent('stockpile-grid')
 export default class StockpileGrid extends RecordStorage<StockpileGridCell>()(
-  CarrierHolder(Placeable(ContainerAbstract))
+  Holdable(CarrierHolder(Placeable(ContainerAbstract)))
 ) implements SlottedHolder {
   declare state: StockpileGridState
   declare _realObject?: StockpileGrid3D
@@ -285,7 +285,7 @@ export default class StockpileGrid extends RecordStorage<StockpileGridCell>()(
     }
 
     const carrier = new CarrierClass(carrierState, (this as any)._app)
-    ;(this as any).addComponent(carrier, { silent: true })
+    ;(this as any).addHolding(carrier)  // transient carrier → _holdings (§1.2)
     void (carrier as any).realObject
     ;(carrier as any).applyHolderAttachPoint?.()
     return carrier

package/src/stockpile.ts

@@ -14,7 +14,7 @@
  */
 
 import * as THREE from 'three'
-import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, ContainerAbstract, Holdable, RealObject, sceneComponent } from '@hatiolab/things-scene'
 import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
@@ -63,6 +63,12 @@ export interface StockpileState extends State {
   /** 어느 끝에서 빼나. default 'lifo'. */
   pickPolicy?: PickPolicy
 
+  /**
+   * 라우팅 행선지 값 (RoutingTarget). sorter/router 가 carrier.destination 과 string
+   * 매칭해 이 StockPile 로 분배. 미설정 시 routingDestination() 가 state.id 로 fallback.
+   */
+  destination?: string
+
   /** click 시 invoke 할 Popup 컴포넌트 id (StorageRack / RackGrid 와 동일 패턴). */
   popupRef?: string
 
@@ -95,6 +101,7 @@ const NATURE: ComponentNature = {
     { type: 'number', label: 'stack-height-limit', name: 'stackHeightLimit' },
     { type: 'select', label: 'pick-policy', name: 'pickPolicy',
       property: { options: ['lifo', 'fifo'] } },
+    { type: 'string', label: 'destination', name: 'destination' },
     { type: 'id-input', label: 'popup-ref', name: 'popupRef',
       property: { component: 'popup' } },
     { type: 'id-input', label: 'legend-target', name: 'legendTarget',
@@ -106,7 +113,7 @@ const NATURE: ComponentNature = {
 
 @sceneComponent('stockpile')
 export default class Stockpile extends RecordStorage<StockpileRecord>()(
-  CarrierHolder(Placeable(ContainerAbstract))
+  Holdable(CarrierHolder(Placeable(ContainerAbstract)))
 ) implements SlottedHolder {
   declare state: StockpileState
   declare _realObject?: Stockpile3D
@@ -115,6 +122,22 @@ export default class Stockpile extends RecordStorage<StockpileRecord>()(
   static align: Alignment = 'bottom'
   static defaultDepth = (_h: Heights) => 5   // pad 두께
 
+  /**
+   * RoutingTarget — 자기 행선지 값 publish. sorter 가 carrier.destination 과 매칭.
+   * 미설정 시 자기 id 로 (단일 sink 직접 지정 fallback). chute 와 동일 규약.
+   */
+  routingDestination(): string {
+    return (this.state.destination as string | undefined) ?? (this.state.id as string)
+  }
+
+  // ── 그래프 참여 ─────────────────────────────────────────────────────────────
+  // StockPile 은 *방향 없는 받는 footprint*. 별도 면 anchor 를 publish 하지 않는다 —
+  // 어느 면으로 받는지는 의미 없고, 슈트/컨베이어의 *출구 anchor 가 자기 footprint 에
+  // 닿으면*(matchOutbounds 의 deliversInto, bounds 기반) 자동 연결된다. (사용자 명시
+  // 2026-06-14: "스톡파일은 슈트의 출구와 면한 부분이 있으면 그곳을 링크".) RoutingTarget
+  // (routingDestination) 만으로 그래프 노드로 수집되고, bounds 는 coordinator 가 채운다.
+  // 멀리 떨어진 타겟은 명시 링크(nextRef/RoutingLinks)로 연결.
+
   get nature(): ComponentNature { return NATURE }
   get anchors() { return [] }
 
@@ -136,6 +159,11 @@ export default class Stockpile extends RecordStorage<StockpileRecord>()(
     return true
   }
 
+  /** Transferable contract — dispatch/Transfer planning 이 capacity 확인에 호출. 단일 slot 위임. */
+  canReceive(carrier?: Component): boolean {
+    return this.canReceiveAt(SLOT_ID, carrier)
+  }
+
   occupiedSlotIds(): ReadonlyArray<string> {
     return this.inventoryCount > 0 ? [SLOT_ID] : []
   }
@@ -201,8 +229,11 @@ export default class Stockpile extends RecordStorage<StockpileRecord>()(
     }
 
     const carrier = new CarrierClass(carrierState, (this as any)._app)
-    // silent: refreshMappings cascade 차단 (transient 라 매핑 재계산 불필요)
-    ;(this as any).addComponent(carrier, { silent: true })
+    // transient carrier → _holdings (모델링 자식 `_components` 아님). Mover.pick
+    // 이 reparent 호출 시 ContainerAbstract.addComponent 가 oldContainer._holdings
+    // 도 자동 정리 (stale 방지, §1.2 직교). board JSON 직렬화 / Inspector 표시
+    // 자동 차단 — Spot 시범 패턴 (2026-06-16).
+    ;(this as any).addHolding(carrier)
     void (carrier as any).realObject
     ;(carrier as any).applyHolderAttachPoint?.()
     return carrier

package/src/storage-rack.ts

@@ -1,7 +1,7 @@
 /*
  * Copyright © HatioLab Inc. All rights reserved.
  */
-import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, ContainerAbstract, Holdable, RealObject, sceneComponent } from '@hatiolab/things-scene'
 import type { State, Material3D } from '@hatiolab/things-scene'
 import * as THREE from 'three'
 import {
@@ -168,7 +168,7 @@ function _nextCarrierRefid(): number {
 @sceneComponent('storage-rack')
 export default class Rack
   extends RecordStorage<{ cellId: string; [key: string]: any }>()(
-    CellContainer(CarrierHolder(Placeable(ContainerAbstract)))
+    CellContainer(Holdable(CarrierHolder(Placeable(ContainerAbstract))))
   )
   implements SlottedHolder
 {
@@ -516,7 +516,7 @@ export default class Rack
     // 만든 게 아니라 *내부적으로 잠시 빌리는 것*. 새 컴포넌트 추가 → root.onadded
     // → refreshMappings (1s debounce) → 모든 컴포넌트 매핑 재실행 의 cascade 차단.
     // (silent 모드: _silentAdd 플래그 set → refreshMappings skip)
-    ;(this as any).addComponent(carrier, { silent: true })
+    ;(this as any).addHolding(carrier)  // transient carrier → _holdings (§1.2)
 
     // 3D 강제 빌드 + attach (pipeline tick 없이도 즉시 표시 — Mover 가 곧 pick).
     void (carrier as any).realObject