@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.42

package/dist/storage-rack.d.ts

@@ -1,10 +1,53 @@
 import { Component, ComponentNature, RealObject } from '@hatiolab/things-scene';
 import type { State, Material3D } from '@hatiolab/things-scene';
-import { CellMap, type AttachFrame, type Alignment, type Heights, type PlacementArchetype } from '@operato/scene-base';
+import * as THREE from 'three';
+import { CellMap, SlotTarget, type AttachFrame, type Alignment, type Heights, type PlacementArchetype, type SlottedHolder } from '@operato/scene-base';
 /** Rack 컴포넌트 state */
 export interface StorageRackState extends State {
     bays?: number;
     levels?: number;
+    /**
+     * Level 1 (첫 shelf) 의 *시작 높이* (mm, rack 의 3D Y 축, 바닥부터). 미명시 0
+     * (바닥 = 첫 shelf). 양수 시 그만큼 위로 올라가 stocker port / conveyor 같은
+     * 컴포넌트가 들어갈 *빈 공간* 확보. Frame uprights 는 바닥 ~ 천장 그대로.
+     */
+    shelfBaseHeight?: number;
+    /**
+     * 적재 시각화 데이터. 배열의 각 record 는 최소 `cellId` 필드가 필요. cellMap 에
+     * 존재하는 cellId 만 InstancedMesh 의 instance 로 렌더링됨 (한 박스 = 한 cell).
+     * Plan A: 이 record 들이 *"매트릭스 안"* 의 carrier — obtainCarrier 가 materialize
+     * 시 record 빠짐, receiveAt 시 record push. pickAndPlace 와 양방향 atomic sync.
+     */
+    data?: Array<{
+        cellId: string;
+        [key: string]: any;
+    }>;
+    /**
+     * RackCell 컴포넌트의 eager 생성 여부.
+     *  - `undefined` (default): state.data 있으면 false (batched, 메모리 절약),
+     *    없으면 true (legacy non-batched, RackCell-based Mover 호환).
+     *  - `true`: 명시적 eager — 모든 cell 을 RackCell 로 생성.
+     *  - `false`: 명시적 skip — Plan A 의 slot API 만 사용 (obtainCarrier / slotTargetAt).
+     */
+    eagerCells?: boolean;
+    /**
+     * Legend 컴포넌트의 id. legend 의 `state.status = {field, ranges:[{value|min,max, color}], defaultColor}`
+     * 를 사용해 각 record 의 `field` 값을 색상으로 매핑. 미명시 시 scene-wide auto-discovery
+     * (type='legend' 인 첫 번째 컴포넌트).
+     */
+    legendTarget?: string;
+    /**
+     * Cell 클릭 시 invoke 할 things-scene `Popup` 컴포넌트의 id. Popup 컴포넌트는 scene
+     * 어딘가에 일반 컴포넌트로 배치되어 있고, 그 자체의 state (board / modal / closable /
+     * draggable / tether / billboard 등) 가 popup 동작을 정의. rack 은 *anchor 만 동적으로*
+     * override 해 호출 — 클릭된 cell 위에 popup 이 뜸.
+     *
+     * 미명시 시 popup 비활성 (rack-cell-click 이벤트는 여전히 발사 — 외부 consumer 가
+     * 직접 처리 가능).
+     */
+    popupRef?: string;
+    /** 가로 frame (beam) 만 숨김 — uprights 는 유지. */
+    hideHorizontalFrame?: boolean;
     debugCells?: boolean;
     material3d?: Material3D;
 }
@@ -15,16 +58,12 @@ declare const Rack_base: any;
  *
  * `levels` × `bays` cells form a vertical grid. Each cell holds one logistics
  * package (Pallet / Box / Parcel). A picker (Crane / Forklift / robot arm)
- * accesses individual cells via Phase G/H Pickable contract — the picker is
- * Rack-agnostic, knowing only how to interact with a cell.
+ * accesses individual cells via the Plan A slot API — the picker interacts
+ * with `SlotTarget` (no explicit cell-component required).
  *
- * **Monitoring mode** (default): carriers are direct children of the rack,
- * placed by external data binding. No RackCell children are created.
- *
- * **Simulation mode**: call `rack._buildCells()` after placing the rack on the
- * scene. This creates RackCell children at the correct 3D positions. A picker
- * (Crane / Forklift / ...) then navigates to individual RackCells for
- * pick-and-place.
+ * **Plan A**: carriers are direct children of the rack, addressed by
+ * `state.cellId`. Stock visualization uses InstancedMesh (batched). Slot
+ * lookup / pick / place via `obtainCarrier` / `receiveAt` / `slotTargetAt`.
  *
  * **Placement**: `floor` archetype, full ceiling depth by default.
  *
@@ -32,13 +71,18 @@ declare const Rack_base: any;
  * extension can be added later for AGV-mounted or cart-mounted variants —
  * the cell topology and pickable contract stay the same.
  */
-export default class Rack extends Rack_base {
+export default class Rack extends Rack_base implements SlottedHolder {
     state: StorageRackState;
     static placement: PlacementArchetype;
     static align: Alignment;
     static defaultDepth: (h: Heights) => number;
     get nature(): ComponentNature;
     get anchors(): never[];
+    /**
+     * Runtime — bays / levels 변경 시 anchor 캐시 무효화. cell 위치가 바뀌므로 다음
+     * `_ensureCellAttachObject3d` 호출이 새 좌표로 갱신.
+     */
+    onchange(after: Record<string, unknown>, _before: Record<string, unknown>): void;
     /**
      * Derive the cell topology from the rack's current dimensions and bay/level
      * counts. The CellMap is rebuilt fresh each time (state changes trigger
@@ -50,41 +94,218 @@ export default class Rack extends Rack_base {
      *   Z = row axis   (front → back, the rack's `height` state property)
      */
     get cellMap(): CellMap;
-    /**
-     * Create RackCell child components for each cell in the CellMap.
-     *
-     * Called explicitly to enter simulation mode — monitoring-mode racks
-     * never call this (carriers are direct children, no explicit cells).
-     *
-     * Idempotent: removes existing rack-cell children first.
-     */
-    _buildCells(): void;
     /**
      * Allow:
-     *   - Carriable components (pallets, boxes, parcels) — direct children in monitoring mode.
-     *   - RackCell — created by _buildCells() in simulation mode.
+     *   - Carriable components (pallets, boxes, parcels) — direct children, operation archetype.
      *
      * Block:
      *   - Everything else (sensors, labels, etc. can be siblings of the rack, not children).
      */
     containable(component: Component): boolean;
     /**
-     * Attach frame for carriers that are DIRECT children of the rack
-     * (monitoring mode, where carriers go directly into the rack without
-     * explicit RackCell components).
+     * Attach frame for direct-child carriers — Plan A 의 모든 carrier 가 rack 의
+     * 직접 자식이므로 매번 호출됨. carrier 의 state.cellId 에 해당하는 *cell-local
+     * anchor object3d* 를 반환 → carrier 의 object3d 가 자동으로 셀 위치에 정렬됨.
+     */
+    attachPointFor(carrier: Component): AttachFrame | null;
+    /** state.data 의 record 목록 (읽기 전용 뷰). */
+    get records(): ReadonlyArray<{
+        cellId: string;
+        [key: string]: any;
+    }>;
+    /**
+     * 1-based (bay, row, level) → 0-based cellId 문자열.
+     *
+     *   rack.cellIdOf(1, 1, 6)  →  '0-0-5'
+     *   rack.cellIdOf(3, 1, 4)  →  '2-0-3'
+     */
+    cellIdOf(bay: number, row?: number, level?: number): string;
+    /** cellId 에 carrier 가 있는가 — child carrier 또는 state.data record 어느 쪽이든. */
+    hasCarrierAt(cellId: string): boolean;
+    /** cellId 매칭되는 rack 의 직접 자식 carrier (operation archetype). */
+    private _carrierChildAt;
+    /**
+     * carrier 를 obtain — 이미 child 면 그대로, 아니면 state.data record 로 transient
+     * materialize 후 rack 의 직접 자식으로 add 하고 state.data 에서 그 record 제거.
+     * record 도 child 도 없으면 null.
+     *
+     * Signature overloads:
+     *   obtainCarrier('0-0-5')                — string cellId 직접
+     *   obtainCarrier(1, 1, 6)                — 1-based (bay, row, level)
+     *   obtainCarrier(1) ≡ obtainCarrier(1,1,1)
+     */
+    obtainCarrier(idOrBay: string | number, row?: number, level?: number): Component | null;
+    /**
+     * State.data 의 *internal* 갱신 — Plan A 의 obtainCarrier / receiveAt 가 사용.
+     * `setState` 와 달리 *'change' 이벤트 / onchangeData / mapping cascade 를 우회*.
+     *
+     * 이유: mapping 시스템이 state.data 변경 시 *자동으로 script fire*. Plan A 의
+     * setState 가 그 cascade 를 트리거하면 사용자 script 가 *재귀적으로 자기 자신을 호출*
+     * 하는 회귀 (board 의 의도된 binding 일 수도, 우연일 수도) 발생.
+     *
+     * 대신 *직접 _state 갱신 + rebuildStockMesh 직접 호출* — 시각화는 갱신되지만 외부
+     * mapping 은 fire 안 됨. External (WMS / application setState) 호출은 그대로 setState
+     * 거치므로 그쪽 mapping 은 정상 동작.
+     */
+    private _setDataSilently;
+    /**
+     * cell 이 carrier 를 받을 수 있는가.
+     *
+     * 규칙:
+     *  - state.data 에 record 가 있으면 점유 → false
+     *  - carrier-child 가 있고 *그 child 가 들여오려는 carrier 자기 자신이 아니면* → false
+     *  - 들여오려는 carrier 가 *바로 그 cell 의 child 자기 자신* 이면 → true (idempotent —
+     *    obtain('A') 직후 receive('A', sameCarrier) 가 *자기 자리 복귀* 로 동작)
+     */
+    canReceiveAt(cellId: string, carrier?: Component): boolean;
+    /**
+     * Carrier 가 rack 의 slot 으로 들어옴 — "매트릭스 진입": 즉시 dispose + state.data 에
+     * record 로 환원. 결과: InstancedMesh 가 다시 그 자리에 instance 표시, rack 의 자식
+     * 컴포넌트 트리는 깨끗.
+     */
+    receiveAt(cellId: string, carrier: Component, _options?: any): Promise<void>;
+    /**
+     * Carrier 의 state 를 state.data record 로 추출. application 이 carrier subclass 별
+     * 추가 필드 인코딩 원하면 override. transform/position 관련은 record 와 무관해 skip.
+     */
+    recordFromCarrier(carrier: Component, cellId: string): {
+        cellId: string;
+        [key: string]: any;
+    };
+    /**
+     * SlottedHolder 컨트랙 — slot 의 attach object3d 반환. SlotTarget 이 자기
+     * `_realObject.object3d` proxy 로 사용하고, Carriable.applyHolderAttachPoint 도
+     * 이걸 attach frame 으로 사용 (transit 중 carrier 가 slot 위치에 정렬).
+     */
+    getSlotAttachObject3d(cellId: string): THREE.Object3D | undefined;
+    /**
+     * SlottedHolder 컨트랙 — slot 의 *expected carrier* 의 3D 크기 (slot 자체의 기하 크기가
+     * 아님). Crane 의 `resolveCarrierBottomY = centerY - depth/2` 에서 *carrier 가 놓일 때
+     * 예상되는 carrier depth* 를 써야 fork 가 *carrier 바닥 = shelf* 에 정확히 진입.
+     *
+     * 즉:
+     *   depth  = stockD (= levelHeight * 0.7) — *carrier 의 vertical extent*. 전체 셀 높이
+     *            (levelHeight) 가 아닌 *실제 stock 박스 깊이*. anchor 가 stock 시각 중심 (
+     *            shelf + stockD/2) 에 위치하므로 depth = stockD 여야 bottom 계산이 shelf.
+     *   width  = bayWidth — 그대로
+     *   height = rowDepth — 그대로 (2D 의 Z 축 폭)
+     */
+    getSlotSize(cellId: string): {
+        width: number;
+        height: number;
+        depth: number;
+    } | undefined;
+    /**
+     * SlottedHolder 컨트랙 — cellId 에 대한 SlotTarget. Mover.pickAndPlace 의 dest 로 넘김.
      *
-     * 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).
+     * Signature overloads:
+     *   slotTargetAt('0-0-5')                  — string cellId 직접
+     *   slotTargetAt(1, 1, 6)                  — 1-based (bay, row, level)
+     */
+    slotTargetAt(idOrBay: string | number, row?: number, level?: number): SlotTarget;
+    /**
+     * SlotTarget 의 2D center 위임 — Mover.moveTo 의 2D path 계산에 사용.
+     *
+     * 반환값은 *rack 자체의 local frame* (rack 의 left/top 미포함) — 즉 cell 의 위치를
+     * rack 의 *내부 좌표계로* 표현. SlotTarget.toScene 이 rack.toScene 을 위임해 *rack 의
+     * rotation / 부모 chain 변환 포함* 한 절대 좌표로 변환.
+     *
+     * 이전 결함: rack.left/top 을 포함해 model-layer 프레임 좌표 반환 + toScene 미구현 →
+     * rack 이 rotated 또는 nested 일 때 X 가 어긋났음.
+     */
+    cellCenter2D(cellId: string): {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * SlotTarget 의 toScene 위임 — *rack-local* 좌표를 *scene-absolute* 로 변환.
+     * rack.toScene 이 rack 의 rotation / translation / parent chain 모두 처리.
+     */
+    cellToScene(localX: number, localY: number): {
+        x: number;
+        y: number;
+    };
+    /** cellId 별 attach anchor object3d cache (rack.object3d 의 자식). */
+    private _attachAnchorByCell;
+    /**
+     * cellId 위치에 lightweight anchor object3d 를 *singleton 으로* 보장 + 갱신.
+     * 이 anchor 가:
+     *   - Carriable.applyHolderAttachPoint 가 attach 하는 frame
+     *   - SlotTarget._realObject.object3d 의 proxy
+     *   - 두 용도가 *같은 object3d* 를 공유해 carrier 가 transient 동안 SlotTarget 의
+     *     pose 와 정확히 동기화.
      */
-    attachPointFor(_carrier: Component): AttachFrame | null;
+    private _ensureCellAttachObject3d;
     /**
-     * 2D — top-down rectangle showing the rack footprint, with subdivisions
-     * suggesting the bay layout.
+     * 2D — top-down rectangle showing the rack footprint with bay subdivisions.
+     * 편집/배치 가 가능하도록 *명시 fill + stroke* — pipeline 분기 무관하게 항상
+     * 보임. fill 은 반투명 (carrier / cell 위 overlay).
      */
     render(ctx: CanvasRenderingContext2D): void;
     get fillStyle(): string;
+    onchangeData(): void;
+    private _legendTarget?;
+    /**
+     * Legend 컴포넌트 lookup. 우선순위:
+     *  1) state.legendTarget id 명시
+     *  2) scene 전체에서 `type='legend'` 첫 번째 컴포넌트 (자동 발견)
+     */
+    get legendTarget(): Component | undefined;
+    private _onLegendChanged;
+    /**
+     * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
+     *   - `range.value === recordValue` (카테고리 일치)
+     *   - `range.min ≤ Number(v) < range.max` (수치 범위)
+     *   - 매칭 없으면 `defaultColor` 또는 undefined
+     */
+    resolveLegendColor(record: any): string | undefined;
+    /**
+     * things-scene EventManager3D 가 raycast → object3d.userData.context.component 의
+     * `trigger("click", mouseEvent)` 을 호출 → eventMap 으로 receive.
+     * `(self).(self).click` 으로 등록해 *우리 rack 의 어떤 mesh 든 클릭됐을 때* 발사.
+     */
+    get eventMap(): {
+        '(self)': {
+            '(self)': {
+                click: (mouseEvent: MouseEvent) => void;
+            };
+        };
+    };
+    private _onRackClick;
+    /**
+     * state.popupRef 가 가리키는 Popup 컴포넌트를 invoke. anchor 를 SlotTarget 으로
+     * 지정 — SlotTarget._realObject.object3d 가 cellId 위치의 anchor object3d 를
+     * 가리켜 tether / projectToScreen 정확.
+     *
+     * - popupRef 미설정 → no-op (event 만 발사된 상태로 남음)
+     * - 다른 cell 클릭 시 popup 이 새 anchor 로 "이동" (Popup 의 board 등 설정 유지)
+     * - frame/empty 영역 클릭 시 호출 안 됨 → popup 그대로 유지
+     * - 명시적 close 버튼은 popup 자체의 closable 옵션이 처리
+     */
+    private _invokePopup;
+    /**
+     * 클릭 시 framework 의 mouse NDC (이미 InteractionManager 가 set 한 상태) 를 재사용해
+     * raycast → *우리 rack* 의 어떤 mesh 가 closest hit 인지 반환. 다른 object 가 더 가까우면
+     * undefined (다른 rack 또는 무관 mesh 의 hit).
+     *
+     * 접근 경로:
+     *  1. ThreeCapability — ModelLayer 는 `_threeCapability`, ThreeContainer 는 `_capability`.
+     *     capability 의 `getObjectsByRaycast()` 가 *동일한* mouse NDC 로 framework 가 click
+     *     처리 직전에 쓴 그 raycaster 를 재사용 (가장 정확).
+     *  2. capability 가 없는 컨테이너 — public scene3d / renderer3d / camera + mouseEvent
+     *     좌표로 자체 ndc 변환 후 fresh raycaster.
+     */
+    private _raycastRackHit;
+    /**
+     * world point → cellId 역산.
+     *
+     *   1. rack 의 `matrixWorld.invert()` 로 world → rack-local 변환 (rack 의 회전·이동
+     *      반영)
+     *   2. rack-local point 의 `(x, y)` 를 (bay, level) 격자에 매핑
+     *
+     * 범위 밖이면 `"out-of-bounds(...)"` 문자열 반환 (caller 가 무시).
+     */
+    private _cellIdFromWorldPoint;
     buildRealObject(): RealObject | undefined;
 }
 export {};