@operato/scene-storage 10.0.0-beta.43 → 10.0.0-beta.46

package/dist/rack-grid.d.ts

@@ -1,7 +1,7 @@
 import { Component, ComponentNature, Control, Properties, RealObject } from '@hatiolab/things-scene';
 import type { State } from '@hatiolab/things-scene';
 import * as THREE from 'three';
-import { SlotTarget, type Alignment, type Heights, type PlacementArchetype, type SlotRecord, type SlottedHolder } from '@operato/scene-base';
+import { SlotTarget, type AttachFrame, type Alignment, type Heights, type PlacementArchetype, type SlotRecord, type SlottedHolder } from '@operato/scene-base';
 import RackGridCell from './rack-grid-cell.js';
 /** 한 (col, row) 위치의 메타데이터. 명시되지 않은 위치는 *룰의 기본값* 적용 (= location 없음). */
 export interface CellOverride {
@@ -150,6 +150,35 @@ export default class RackGrid extends RackGrid_base implements SlottedHolder {
      * truth, 없으면 cellOverrides[posKey].isEmpty fallback.
      */
     isBayEmpty(col: number, row?: number): boolean;
+    /**
+     * 모든 slot id 의 목록. columns × rackRows × shelves 조합. *isEmpty bay 는 제외*
+     * (물리적으로 없는 위치). SlottedHolder.slotIds — capability 기반 enumeration
+     * entry point.
+     */
+    slotIds(): ReadonlyArray<string>;
+    /**
+     * 점유된 slot 의 id 목록 — state.data record + child *carrier* 둘 다.
+     *
+     * 중요: RackGridCell (시각 proxy) 의 *state.cellId 는 bayKey ("col-row")
+     * 형식* (`_syncChildCellIds` 가 set). slot 의 *full id ("col-row-shelf")* 와
+     * 다르다 — RackGridCell 은 *carrier 아닌 시각 proxy* 라 *occupied 카운트
+     * 대상 아님*. carriable child (= 실 carrier) 만 sweep.
+     *
+     * @param filter  predicate — 통과하는 slotId 만. sweep 중 즉시 reject.
+     */
+    occupiedSlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string>;
+    /** 비어있는 slot 의 id 목록 — slotIds() - occupiedSlotIds(). isEmpty bay 자동 제외. */
+    emptySlotIds(filter?: (slotId: string) => boolean): ReadonlyArray<string>;
+    /**
+     * slot 의 *world position* — anchor object3d *생성 없이* 직접 계산. crane 의
+     * reach 검사 같은 *match 전 단계* 에서 *anchor 생성 0* 으로 사용 가능.
+     * match 후 *실제 attach* 가 필요할 때 `getSlotAttachObject3d` 가 lazy 생성.
+     */
+    slotWorldPosition(slotId: string): {
+        x: number;
+        y: number;
+        z: number;
+    } | undefined;
     buildRealObject(): RealObject | undefined;
     get layout(): any;
     get widths(): number[];
@@ -165,8 +194,8 @@ export default class RackGrid extends RackGrid_base implements SlottedHolder {
     /** posKey = `${col-1}-${row-1}` (0-based, 2 segments). 1-based input. */
     posKeyOf(col: number, row?: number): string;
     /** cellId = `${col-1}-${row-1}-${shelf-1}` (0-based, 3 segments). 1-based input. */
-    cellIdOf(col: number, row?: number, shelf?: number): string;
-    parseCellId(cellId: string): {
+    slotIdOf(col: number, row?: number, shelf?: number): string;
+    parseSlotId(cellId: string): {
         col: number;
         row: number;
         shelf: number;
@@ -220,18 +249,73 @@ export default class RackGrid extends RackGrid_base implements SlottedHolder {
      * 자식의 grid 위치 식별: 자식의 state.column / state.row (1-based) 명시. RackGrid 가
      * 자식 추가 시 자동 할당 또는 사용자가 명시.
      */
-    private _childRackAt;
-    hasCarrierAt(slotId: string): boolean;
+    /**
+     * cellId 매칭되는 RackGrid 의 직접 자식 carrier (operation archetype).
+     * RackGrid 의 자식 중 rack-grid-cell (시각 proxy) 외에 obtainCarrier 가 add 한
+     * transient carrier 들이 섞임 — 그 중 cellId / placement='operation' 매칭.
+     * storage-rack 의 동일 패턴.
+     */
+    private _carrierChildAt;
+    /**
+     * state.data 의 internal 갱신 — obtainCarrier / receiveAt 가 사용.
+     * setState 와 달리 'change' / onchangeData / mapping cascade 우회 — 사용자 script
+     * 의 자기-자신 호출 회귀 차단. 시각 갱신은 직접 RealObject.rebuildStockMesh 호출.
+     * storage-rack 의 동일 패턴.
+     */
+    private _setDataSilently;
+    /** state.data record 또는 이미 transient materialize 된 carrier child 가 있는가. */
+    hasCarrierAt(slotIdOrLocation: string): boolean;
+    /**
+     * carrier 를 obtain — 이미 child 면 그대로, 아니면 state.data record 로 transient
+     * materialize 후 RackGrid 의 직접 자식으로 add 하고 state.data 에서 그 record 제거.
+     * record 도 child 도 없으면 null.
+     */
     obtainCarrier(slotIdOrLocation: string): Component | null;
+    /**
+     * cell 이 carrier 를 받을 수 있는가.
+     *  - isEmpty 위치 는 거부 (modeling 차원 location-less)
+     *  - state.data 에 record 있으면 점유 → false
+     *  - 자기 자신 carrier 가 child 면 idempotent true (자기 자리 복귀)
+     */
     canReceiveAt(slotIdOrLocation: string, carrier?: Component): boolean;
-    receiveAt(slotIdOrLocation: string, carrier: Component, options?: any): Promise<void>;
-    recordFromCarrier(carrier: Component, slotId: string): SlotRecord;
+    /**
+     * Carrier 가 RackGrid 의 slot 으로 들어옴 — 즉시 dispose + state.data 에 record 로
+     * 환원. 결과: stock InstancedMesh 가 그 자리에 instance 표시, RackGrid 의 자식 트리는
+     * 깨끗 (rack-grid-cell 만 남음).
+     */
+    receiveAt(slotIdOrLocation: string, carrier: Component, _options?: any): Promise<void>;
+    /**
+     * Carrier 의 state 를 state.data record 로 추출. transform/position 관련은 record
+     * 와 무관해 skip. (storage-rack 의 동일 패턴.)
+     */
+    recordFromCarrier(carrier: Component, cellId: string): SlotRecord;
+    /**
+     * children gate — CarrierHolder.containable 의 *carriable-only* 제한을 완화.
+     * RackGrid 의 자식은 두 종류:
+     *  - RackGridCell : modeling-time visual proxy (carriable 아님)
+     *  - carrier      : Plan A 의 obtainCarrier 가 materialize (carriable)
+     * 둘 다 허용해야 정상 동작.
+     */
+    containable(component: Component): boolean;
+    /**
+     * Attach frame for direct-child carrier — `applyHolderAttachPoint` 가 이 결과의
+     * `attach` 에 carrier obj3d 를 attach 하고 `localPosition` 을 set. cell anchor
+     * 반환 + carried placement 와 함께 동작 — carrier 가 cell 위치에 고정.
+     */
+    attachPointFor(carrier: Component): AttachFrame | null;
     /**
      * Slot 의 attach object3d — Stock InstancedMesh 의 instance 와 *같은 world 위치* 에
-     * 위치한 invisible Object3D. popup tether / Carriable.applyHolderAttachPoint 가 이
-     * object3d 의 matrixWorld 를 사용. lazy 생성 + cache.
+     * 위치한 invisible Object3D. popup tether 등이 이 object3d 의 matrixWorld 를
+     * 사용. lazy 생성 + cache.
+     */
+    private _attachAnchorBySlot;
+    /**
+     * Anchor position cache 의 signature — rack 의 차원 state 변경 시 무효화 trigger.
+     * 동일 signature 인 동안 *anchor.position.set 재계산 skip*. crane 의 첫
+     * findAdjacentSlots 가 *수많은 anchor 의 position.set 매 호출* — *동일 차원
+     * state 일 때* 의 *중복 계산 차단*.
      */
-    private _attachAnchorByCell;
+    private _attachAnchorSig?;
     getSlotAttachObject3d(slotId: string): THREE.Object3D | undefined;
     getSlotSize(slotId: string): {
         width: number;