@hatiolab/things-scene 10.0.0-beta.92 → 10.0.0-beta.93

package/dist-types/navigation/types.d.ts

@@ -0,0 +1,145 @@
+import type { Vec3 } from '../transfer/types.js';
+export interface LaneGeometry {
+    /** 중앙선의 점들 (시작 → 끝). */
+    centerPoints: Vec3[];
+    /** lane 의 폭 (vehicle 이 이 안에 들어가야 함). */
+    width: number;
+}
+export interface Lane {
+    id: string;
+    geometry: LaneGeometry;
+    /** oneway 면 centerPoints 의 시작→끝 방향만, twoway 면 양방향 허용. */
+    direction: 'oneway' | 'twoway';
+    /** 속도 제한 (scene units / sim sec). undefined = 무제한. */
+    speedLimit?: number;
+    /** 통과 가능한 도구 type (Pickable.toolType 과 같은 축). 빈 배열 = 모두 허용. */
+    allowedToolTypes?: string[];
+    /** 동시에 들어갈 수 있는 vehicle 수. 1 = 단독 점유 (1차원 큐). */
+    capacity: number;
+}
+/**
+ * 두 lane 의 진입쌍이 충돌하는지 표현. e.g. north→south 와 east→west 는 직각
+ * 교차로에서 충돌하지만 north→east 와 south→east 는 충돌 안 함 (병행).
+ */
+export interface ConflictPair {
+    fromLane: string;
+    toLane: string;
+    /** 어떤 우선순위 정책을 적용할지. */
+    resolveBy: 'fifo' | 'priority' | 'roundrobin';
+}
+export interface Intersection {
+    id: string;
+    lanes: string[];
+    conflicts: ConflictPair[];
+    /** 통과 시간 (vehicle 이 교차로 안에 머무는 sim ms). 보수적으로 추정. */
+    crossingTimeMs: number;
+}
+export interface NavPolygon {
+    vertices: Vec3[];
+}
+/**
+ * lane 으로 표현하기 어려운 넓은 영역 (open warehouse floor, dock plaza 등).
+ * 시공간 격자로 점유권을 관리.
+ */
+export interface OpenZone {
+    id: string;
+    boundary: NavPolygon;
+    /** 점유 격자의 cell 한 변 크기 (scene unit). 작을수록 정확하지만 reservation 많아짐. */
+    cellSize: number;
+}
+export interface TimeWindow {
+    /** sim time milliseconds. */
+    startSimMs: number;
+    endSimMs: number;
+}
+/**
+ * 어떤 resource 를 어떤 시간 window 동안 누가 점유하는가.
+ *
+ * resource 는 lane id / intersection id / open-zone cell key 등 resource 의
+ * 단일 식별자. cell 의 경우 e.g. `${zoneId}:cell:${i},${j}`.
+ */
+export interface Reservation {
+    id: string;
+    resource: string;
+    timeWindow: TimeWindow;
+    reserverId: string;
+    /** 낮을수록 우선. emergency = -1, task-bound = 0, idle = 10 등. */
+    priority: number;
+    /** 부수 메타 (어떤 task 의 일부인지, 어떤 carrier 를 운반 중인지 등). */
+    metadata?: Record<string, any>;
+}
+export interface SpeedProfile {
+    /** 최대 속도 (scene units / sim sec). */
+    max: number;
+    /** 가속도 (scene units / sim sec²). */
+    accel: number;
+    /** 감속도 (scene units / sim sec²). */
+    decel: number;
+}
+export interface PathSegment {
+    resource: string;
+    /** 이 segment 를 통과하는 sim time. */
+    timeWindow: TimeWindow;
+    /** segment 시작 / 끝 좌표 (시각화용). */
+    fromPos: Vec3;
+    toPos: Vec3;
+}
+export interface PathPlan {
+    segments: PathSegment[];
+    /** 전체 경로의 sim time 길이. */
+    totalDurationMs: number;
+    /** 전체 경로 길이 (scene unit). */
+    totalDistance: number;
+}
+export interface PathPlanOptions {
+    /** sim time 시작점. 미지정 시 현재 globalSimClock.now. */
+    startSimMs?: number;
+    /** vehicle 의 toolType — lane.allowedToolTypes 검사용. */
+    toolType?: string;
+    /** vehicle 의 speed profile. */
+    speed?: SpeedProfile;
+    /** 우선순위 (충돌 시 양보 결정용). */
+    priority?: number;
+    /** deadline (sim ms) — 이 시간 안에 도착 못 하면 null 반환. */
+    deadlineSimMs?: number;
+}
+/**
+ * Vehicle 이 navigation 능력을 노출하는 인터페이스. Mover 의 sub-trait.
+ *
+ * lifecycle:
+ *   1. planPath(target) → PathPlan | null     (lookup, 부수효과 없음)
+ *   2. reservePath(plan) → Reservation[] | null (table 에 add, 충돌 시 null)
+ *   3. followReservation(rs) → Promise<void>   (sim time 진행)
+ *   4. releaseReservation(rs)                  (도착 후 또는 cancel)
+ *
+ * 단계 분리로 충돌 감지가 commit 직전, replay 가 결정적, 디버깅이 가능.
+ */
+export interface Navigable {
+    toolType: string;
+    speedProfile: SpeedProfile;
+    /**
+     * 경로 계획. 시간-공간 reservation 가능성 검증 포함 (단, table 에 commit 안 함).
+     * null 반환 = 도달 가능 경로 없음 (deadline 초과 / 모든 lane 점유 등).
+     */
+    planPath(target: Vec3, options?: PathPlanOptions): PathPlan | null;
+    /**
+     * 계획된 경로를 reservation table 에 commit. 다른 vehicle 이 이미 점유한
+     * window 와 충돌 시 null — 호출자가 reroute 하든 대기하든 결정.
+     */
+    reservePath(plan: PathPlan, priority?: number): Reservation[] | null;
+    /**
+     * commit 된 reservation 따라 sim time 진행. resolve = 마지막 segment 도착.
+     */
+    followReservation(reservations: Reservation[]): Promise<void>;
+    /** 점유 해제. 도착 완료 또는 cancel 시 호출. */
+    releaseReservation(reservations: Reservation[]): void;
+}
+export type YieldDecision = 'a-yields' | 'b-yields' | 'replan-both';
+export interface YieldPolicy {
+    /**
+     * 두 reservation 이 시간-공간 충돌할 때 누가 양보하는가.
+     * 기본: priority 낮은 (수치 높은) 쪽이 양보. 같으면 fifo (먼저 만든 게 우선).
+     */
+    resolveConflict(a: Reservation, b: Reservation): YieldDecision;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist-types/navigation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/navigation/types.ts"],"names":[],"mappings":"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"}

package/dist-types/things-scene/index.d.ts

@@ -28,8 +28,14 @@ export type { SceneRenderContext, DrawOptions, StyleOptions, FillStyle, StrokeSt
 export type { LinkEnd } from '../decorator/decorators/link-decorator.js';
 export type { LAYOUT, LayoutRegistry } from '../interfaces/layout.js';
 export type { IRealObject } from '../interfaces/real-object.js';
-export type { Vec3, Size3, Bounds3, SlotArrangement, GridShape, SlotDef, SlotAssignment, TransferOptions, StaticPolicy, DynamicPolicy, PendingPolicy, ConnectionPolicy, Port, TransferEventType, TransferEvent, CarrierAttachPoint, ArrangementStrategy, Transferable, NavigationTarget, NavigationOptions, Movable, ArticulatedCapability, MissionStatus, VehicleMission, MissionExecutor, SensorPoint, SpawnPoint, SinkPoint, SimulationClock } from '../transfer/index.js';
-export { FixedSlotStrategy, CenteringSlotStrategy, ContainerCapacity, TRANSFER_SLOT_KEY, globalSimClock } from '../transfer/index.js';
+export type { Vec3, Size3, Bounds3, SlotArrangement, GridShape, SlotDef, SlotAssignment, TransferOptions, StaticPolicy, DynamicPolicy, PendingPolicy, ConnectionPolicy, Port, TransferEventType, TransferEvent, CarrierAttachPoint, ArrangementStrategy, Transferable, NavigationTarget, NavigationOptions, Movable, ArticulatedCapability, MissionStatus, VehicleMission, MissionExecutor, SensorPoint, SpawnPoint, SinkPoint, SimulationClock, TransferPhase, TransferTimeline, TransferReceipt, TransferReceiptJSON, TransferLogStats, PhysicalRunner, TransferInit, QuatLike, PoseSerialized, PickupFrame, PickupRequester, Pickable, RectangularFootprintOptions, TopApproachOptions } from '../transfer/index.js';
+export { FixedSlotStrategy, CenteringSlotStrategy, ContainerCapacity, TRANSFER_SLOT_KEY, globalSimClock, Transfer, transferLog, receiptToJSON, quatFromYaw, rectangularFootprintFrames, topApproachFrame, filterByToolType, chooseNearestPickupFrame } from '../transfer/index.js';
+export { Pose6DOF, getPose, getWorldPose, setPose, setWorldPose } from '../math/index.js';
+export type { PoseLike } from '../math/index.js';
+export { ReservationTable, reservationTable, standardYieldPolicy, NavGraph, buildNavGraph, planPathAStar, planToReservations } from '../navigation/index.js';
+export type { LaneGeometry, Lane, ConflictPair, Intersection, NavPolygon, OpenZone, TimeWindow, Reservation, SpeedProfile, PathSegment, PathPlan, PathPlanOptions, Navigable, YieldDecision, YieldPolicy, ReservationEvent, AddResult, Conflict, ConflictRecord, NavNode, NavEdge, BuildNavGraphOptions } from '../navigation/index.js';
+export { buildContractInspector, installContractInspector } from '../diagnostics/contract-inspector.js';
+export type { ContractInspector, InspectorComponentSummary, InspectorSimStatus } from '../diagnostics/contract-inspector.js';
 export { frameClock } from '../clock/index.js';
 export type { FrameClock, TickHandler, Unsubscribe, SubscribeOptions, SubscriptionInfo, FrameClockSnapshot, ExternalAnimationInfo, ExternalAnimationHandle } from '../clock/index.js';
 export { default as ReferenceMap } from '../core/reference-map.js';

package/dist-types/things-scene/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/things-scene/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/things-scene/index.ts"],"names":[],"mappings":"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"}

package/dist-types/transfer/container-capacity.d.ts

@@ -34,6 +34,78 @@ export declare function ContainerCapacity<TBase extends Constructor<Component>>(
          * Fires 'transfer-rejected'; subclasses may trigger fallback routing.
          */
         rejectRoute(component: any, reason?: string): void;
+        /**
+         * carrier 의 받아들일 회전 (parent-local quaternion). 기본 identity.
+         * 회전이 필요한 holder (induct = belt 진행 방향, rack cell = grid 정렬 등)
+         * 는 이 메소드만 override 하면 receive() 가 atomic 하게 적용한다.
+         *
+         * 반환값은 plain object {x,y,z,w} — THREE.Quaternion 도 그 인터페이스 만족.
+         */
+        acceptanceRotation(_carrier: any, _slot?: SlotDef): {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        } | undefined;
+        /**
+         * canReceive 의 풍부한 버전. ok 면 slot 동봉, 아니면 reason 명시.
+         * drag-over UI 가 사유 표시하기 위함. canReceive 와 동일 결정 사용.
+         */
+        canAccept(component: any): {
+            ok: true;
+            slot: SlotDef;
+        } | {
+            ok: false;
+            reason: string;
+        };
+        /**
+         * receive 의 alias — Phase G2 contract 의 명시적 이름. 기존 receive 호출자도
+         * 그대로 작동.
+         */
+        accept(component: any, options?: TransferOptions): Promise<void>;
+        /**
+         * Phase G5 — physical mover (robot-arm, AGV docking 등) 가 query 하는
+         * delivery world rotation. carrier 가 holder 에 도달했을 때 가져야 할
+         * world quaternion.
+         *
+         *   delivery.world = holder.world.quat × acceptanceRotation_local
+         *
+         * source 가 이걸 미리 알면 TCP yaw 를 점진적으로 맞춰 carrier 가
+         * acceptance pose 에 도달한 채로 release → handoff 시 zero-delta → 시각적
+         * 점프 없음.
+         *
+         * acceptanceRotation 미정의 OR _realObject 미빌드 시 undefined.
+         */
+        deliveryWorldRotation(carrier: any): {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        } | undefined;
+        /**
+         * Phase G9 — physical mover 가 query 하는 delivery world position.
+         *
+         * carrier 가 holder 에 도달했을 때 가져야 할 world XYZ. position 만 — rotation
+         * 은 deliveryWorldRotation 이 별도로 제공. 두 결과를 합치면 source 의 trajectory
+         * endpoint 가 됨.
+         *
+         * 기본 구현 — receivingSurfaceY 가 있으면 belt 표면 위, 없으면 slot.localPosition,
+         * 둘 다 없으면 holder object3d 원점.
+         *
+         *   surface_world_y = holder.localToWorld((0, receivingSurfaceY - geometricOffsetY, 0)).y
+         *   surface_world_xz = holder.world.xz
+         *
+         * receivingSurfaceY 의 정의가 cz-formula-tuned (= beltTopY + parent.geometricOffsetY)
+         * 라 그 차분 (- parent.geometricOffsetY) 으로 raw local 표면 Y 를 뽑아낸다.
+         *
+         * 호출 전제: holder 의 _realObject 가 빌드돼 있고 obj3d.matrixWorld 가 최신.
+         * 빌드 안 된 상태면 undefined → 호출자가 fallback (예: 2D bounds 기반).
+         */
+        deliveryWorldPosition(_carrier: any): {
+            x: number;
+            y: number;
+            z: number;
+        } | undefined;
         attachPointFor(component: any): CarrierAttachPoint | null;
         /** Count children currently assigned to `slotId`. */
         _countOccupied(slotId: string): number;

package/dist-types/transfer/container-capacity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container-capacity.d.ts","sourceRoot":"","sources":["../../src/transfer/container-capacity.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACjH,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AAGvD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,oBAAoB,CAAA;AAElD,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK;kBARtC,GAAG,EAAE;QAa9C,mDAAmD;qBACtC,OAAO,EAAE;QAItB;;;WAGG;mCACwB,mBAAmB;8BAMxB,GAAG,GAAG,OAAO;4BAKf,GAAG,GAAG,OAAO,GAAG,IAAI;2BAsBf,GAAG,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;4BA+DjD,GAAG,UAAU,YAAY,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;0BAuBhF,GAAG,GAAG,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;QAI1E;;;;WAIG;iCACsB,GAAG,WAAW,YAAY,GAAG,IAAI;QAI1D;;;WAGG;+BACoB,GAAG,oBAAwB,IAAI;kCAS5B,GAAG,GAAG,kBAAkB,GAAG,IAAI;QAgBzD,qDAAqD;+BAC9B,MAAM,GAAG,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAMzC"}
+{"version":3,"file":"container-capacity.d.ts","sourceRoot":"","sources":["../../src/transfer/container-capacity.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACjH,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AAOvD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,oBAAoB,CAAA;AAElD,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK;kBARtC,GAAG,EAAE;QAa9C,mDAAmD;qBACtC,OAAO,EAAE;QAItB;;;WAGG;mCACwB,mBAAmB;8BAMxB,GAAG,GAAG,OAAO;4BAKf,GAAG,GAAG,OAAO,GAAG,IAAI;2BAsBf,GAAG,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;4BA+EjD,GAAG,UAAU,YAAY,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;0BAoChF,GAAG,GAAG,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;QAI1E;;;;WAIG;iCACsB,GAAG,WAAW,YAAY,GAAG,IAAI;QAI1D;;;WAGG;+BACoB,GAAG,oBAAwB,IAAI;QAWtD;;;;;;WAMG;qCAC0B,GAAG,UAAU,OAAO,GAAG;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS;QAI9G;;;WAGG;6BACkB,GAAG,GAAG;YAAE,EAAE,EAAE,IAAI,CAAC;YAAC,IAAI,EAAE,OAAO,CAAA;SAAE,GAAG;YAAE,EAAE,EAAE,KAAK,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE;QAmBtF;;;WAGG;0BACe,GAAG,YAAY,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;QAIhE;;;;;;;;;;;;WAYG;uCAC4B,GAAG,GAAG;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS;QAe/F;;;;;;;;;;;;;;;;;;WAkBG;wCAC6B,GAAG,GAAG;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS;kCAwB3D,GAAG,GAAG,kBAAkB,GAAG,IAAI;QAgBzD,qDAAqD;+BAC9B,MAAM,GAAG,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAMzC"}

package/dist-types/transfer/index.d.ts

@@ -1,7 +1,13 @@
-export type { Vec3, Size3, Bounds3, SlotArrangement, GridShape, SlotDef, SlotAssignment, TransferOptions, StaticPolicy, DynamicPolicy, PendingPolicy, ConnectionPolicy, Port, TransferEventType, TransferEvent, CarrierAttachPoint, ArrangementStrategy, Transferable, NavigationTarget, NavigationOptions, Movable, ArticulatedCapability, MissionStatus, VehicleMission, MissionExecutor, SensorPoint, SpawnPoint, SinkPoint } from './types.js';
+export type { Vec3, Size3, Bounds3, SlotArrangement, GridShape, SlotDef, SlotAssignment, TransferOptions, StaticPolicy, DynamicPolicy, PendingPolicy, ConnectionPolicy, Port, TransferEventType, TransferEvent, CarrierAttachPoint, ArrangementStrategy, Transferable, NavigationTarget, NavigationOptions, Movable, ArticulatedCapability, MissionStatus, VehicleMission, MissionExecutor, SensorPoint, SpawnPoint, SinkPoint, QuatLike, PoseSerialized, PickupFrame, PickupRequester, Pickable } from './types.js';
+export { quatFromYaw, rectangularFootprintFrames, topApproachFrame, filterByToolType, chooseNearestPickupFrame } from './pickup-helpers.js';
+export type { RectangularFootprintOptions, TopApproachOptions } from './pickup-helpers.js';
 export { FixedSlotStrategy, fixedSlotStrategy } from './fixed-slot-strategy.js';
 export { CenteringSlotStrategy } from './centering-slot-strategy.js';
 export { ContainerCapacity, TRANSFER_SLOT_KEY } from './container-capacity.js';
 export type { SimulationClock } from './simulation-clock.js';
 export { globalSimClock } from './simulation-clock.js';
+export { Transfer, transferLog, receiptToJSON } from './transfer.js';
+export type { TransferPhase, TransferTimeline, TransferReceipt, TransferReceiptJSON, TransferLogStats, PhysicalRunner, TransferInit } from './transfer.js';
+export { ReservationTable, reservationTable, standardYieldPolicy, NavGraph, buildNavGraph, planPathAStar, planToReservations } from '../navigation/index.js';
+export type { LaneGeometry, Lane, ConflictPair, Intersection, NavPolygon, OpenZone, TimeWindow, Reservation, SpeedProfile, PathSegment, PathPlan, PathPlanOptions, Navigable, YieldDecision, YieldPolicy, ReservationEvent, AddResult, Conflict, ConflictRecord, NavNode, NavEdge, BuildNavGraphOptions } from '../navigation/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist-types/transfer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,IAAI,EACJ,KAAK,EACL,OAAO,EACP,eAAe,EACf,SAAS,EACT,OAAO,EACP,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,IAAI,EACJ,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,IAAI,EACJ,KAAK,EACL,OAAO,EACP,eAAe,EACf,SAAS,EACT,OAAO,EACP,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,IAAI,EACJ,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,UAAU,EACV,SAAS,EAET,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,QAAQ,EACT,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,WAAW,EACX,0BAA0B,EAC1B,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE1F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC9E,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAItD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACpE,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACb,MAAM,eAAe,CAAA;AAItB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACb,aAAa,EACb,kBAAkB,EACnB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,eAAe,EACf,SAAS,EACT,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,cAAc,EACd,OAAO,EACP,OAAO,EACP,oBAAoB,EACrB,MAAM,wBAAwB,CAAA"}

package/dist-types/transfer/pickup-helpers.d.ts

@@ -0,0 +1,65 @@
+import type { PickupFrame, PickupRequester, Vec3, QuatLike, PoseSerialized } from './types.js';
+/**
+ * Y 축 (3D vertical) 회전을 quaternion 으로. Three.js 없이 직접 계산 (cross-package
+ * 호환성).
+ *
+ *   q = (0, sin(θ/2), 0, cos(θ/2))
+ */
+export declare function quatFromYaw(yawRad: number): QuatLike;
+export interface RectangularFootprintOptions {
+    /** carrier 의 world pose — entry 들이 이 frame 기준으로 회전/병진된다. */
+    carrierWorld: PoseSerialized;
+    /** carrier 의 가로 (X 방향). */
+    width: number;
+    /** carrier 의 세로 (Z 방향). */
+    depth: number;
+    /** entry 가 carrier 의 어느 높이에 있는가 (carrier-local Y). */
+    entryHeight: number;
+    /** approach 가 engage 에서 얼마나 떨어진 거리. */
+    approachDistance: number;
+    /** 어느 면에 entry 를 둘지. 'east'+'west' = 2-way, 4 개 다 = 4-way. */
+    sides: ReadonlyArray<'east' | 'west' | 'north' | 'south'>;
+    /** entry 의 toolType. 모두 동일하면 string, 면별 다르면 map. */
+    toolType: string | Partial<Record<'east' | 'west' | 'north' | 'south', string>>;
+    /** entry 의 tolerance. */
+    tolerance?: PickupFrame['tolerance'];
+    /** entry 의 priority. */
+    priority?: number;
+}
+/**
+ * 직사각형 carrier 의 N-면 진입 entry 들을 한꺼번에 생성.
+ *
+ * 각 entry 의 engage 는 carrier 의 해당 면 중심 (carrier-local), approach 는
+ * 그 외부 approachDistance 만큼 떨어진 점. 도구는 carrier 쪽을 향한 채 (yaw)
+ * 다가오는 자세.
+ */
+export declare function rectangularFootprintFrames(options: RectangularFootprintOptions): PickupFrame[];
+export interface TopApproachOptions {
+    carrierWorld: PoseSerialized;
+    /** carrier 의 top 표면 Y (carrier-local). */
+    topY: number;
+    /** approach 가 top 에서 얼마나 위에 있는가. */
+    approachDistance: number;
+    toolType: string;
+    tolerance?: PickupFrame['tolerance'];
+    priority?: number;
+    id?: string;
+}
+/**
+ * 위쪽 한 점 진입 (예: vacuum gripper 로 box 집기, 자석으로 철판 들기).
+ *
+ * engage 는 carrier 의 top 표면 중심, approach 는 그 위 approachDistance.
+ * 도구는 carrier 위에서 수직 하강 — yaw 보존 (도구가 회전하지 않음).
+ */
+export declare function topApproachFrame(options: TopApproachOptions): PickupFrame;
+/**
+ * Pickable.pickupFramesFor 의 기본 구현. 도구 type 일치하는 entry 만 통과.
+ * tool footprint 까지 검사하고 싶으면 carrier 가 자체 override.
+ */
+export declare function filterByToolType(frames: PickupFrame[], requester: PickupRequester): PickupFrame[];
+/**
+ * 두 entry 중 source 위치에 더 가까운 것을 고르는 helper. distance 는 approach
+ * pose 위치 기준. priority 가 다르면 priority 우선.
+ */
+export declare function chooseNearestPickupFrame(frames: PickupFrame[], fromWorldPosition: Vec3): PickupFrame | null;
+//# sourceMappingURL=pickup-helpers.d.ts.map

package/dist-types/transfer/pickup-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pickup-helpers.d.ts","sourceRoot":"","sources":["../../src/transfer/pickup-helpers.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAI9F;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAQpD;AA2CD,MAAM,WAAW,2BAA2B;IAC1C,4DAA4D;IAC5D,YAAY,EAAE,cAAc,CAAA;IAC5B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,CAAA;IACzD,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/E,yBAAyB;IACzB,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACpC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAYD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,WAAW,EAAE,CAiD9F;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,cAAc,CAAA;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAoBzE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EAAE,EACrB,SAAS,EAAE,eAAe,GACzB,WAAW,EAAE,CAEf;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EAAE,EACrB,iBAAiB,EAAE,IAAI,GACtB,WAAW,GAAG,IAAI,CAkBpB"}

package/dist-types/transfer/transfer.d.ts

@@ -0,0 +1,168 @@
+import type { Transferable, TransferOptions } from './types.js';
+export type TransferPhase = 'pending' | 'planning' | 'physical' | 'handoff' | 'committed' | 'rolled-back';
+export interface TransferTimeline {
+    initiatedAt: number;
+    planStartAt?: number;
+    planEndAt?: number;
+    physicalStartAt?: number;
+    physicalEndAt?: number;
+    handoffAt?: number;
+    committedAt?: number;
+}
+export interface TransferReceipt {
+    transferId: string;
+    source: any;
+    target: any;
+    carrier: any;
+    /** Phase G7 — 직렬화 용. live refs 가 GC 되어도 보존되는 식별자. */
+    sourceId?: string;
+    targetId?: string;
+    carrierId?: string;
+    phase: TransferPhase;
+    timeline: TransferTimeline;
+    slotId?: string;
+    rejectReason?: string;
+}
+/**
+ * TransferReceipt 의 직렬화 형태 — live ref 제외, ID 만. JSON.stringify 안전.
+ * Phase G7 의 snapshot/replay 용.
+ */
+export interface TransferReceiptJSON {
+    transferId: string;
+    sourceId?: string;
+    targetId?: string;
+    carrierId?: string;
+    phase: TransferPhase;
+    timeline: TransferTimeline;
+    slotId?: string;
+    rejectReason?: string;
+}
+/**
+ * Receipt 의 plain JSON 변환. live ref 제외, undefined 필드 omit (JSON
+ * round-trip 결정성 보장).
+ */
+export declare function receiptToJSON(receipt: TransferReceipt): TransferReceiptJSON;
+/**
+ * Source 가 physical 단계에서 사용하는 운반 함수. logical-only source
+ * (Conveyor.dispatch 등) 는 noop 으로 즉시 resolve.
+ *
+ * 호출 시점: Transfer 의 physical phase 진입.
+ * 반환: physical 운반 완료 (carrier 가 target.deliveryPose 에 도달) 시 resolve.
+ */
+export type PhysicalRunner = () => Promise<void>;
+export interface TransferLogStats {
+    total: number;
+    byPhase: Record<string, number>;
+    committed: number;
+    rolledBack: number;
+    rejectionRate: number;
+    avgTransferDurationMs: number;
+}
+export interface TransferInit {
+    source: any;
+    target: Transferable;
+    carrier: any;
+    options?: TransferOptions;
+    /** physical 운반자 (RobotArm, AGV 등). 미지정 시 즉시 통과. */
+    physical?: PhysicalRunner;
+}
+/**
+ * Transfer — 한 carrier 의 source → target 이동 사건.
+ *
+ * 사용:
+ *   const t = new Transfer({ source, target, carrier, options })
+ *   const receipt = await t.execute()
+ *
+ * 또는 Transferable.dispatch 가 내부적으로:
+ *   const t = new Transfer({ source: this, target, carrier, options })
+ *   await t.execute()
+ */
+export declare class Transfer {
+    readonly id: string;
+    readonly source: any;
+    readonly target: Transferable;
+    readonly carrier: any;
+    readonly options: TransferOptions;
+    readonly physical: PhysicalRunner | null;
+    private _phase;
+    private _timeline;
+    private _slot;
+    private _rejectReason?;
+    constructor(init: TransferInit);
+    get phase(): TransferPhase;
+    get timeline(): Readonly<TransferTimeline>;
+    /**
+     * 5-phase 실행. 각 phase 진입 시 timeline 갱신, 완료 시 receipt 반환.
+     *
+     * Negotiate / Plan 단계에서 거부 → rolled-back receipt.
+     * Physical 단계에서 throw → rolled-back receipt.
+     * Handoff 이후 throw 는 일관성 깨질 수 있으므로 그대로 propagate.
+     */
+    execute(): Promise<TransferReceipt>;
+    /**
+     * physical / planning 도중 외부 취소. handoff 이후엔 호출 금지 (이미 commit 됨).
+     * 현재 구현은 phase 만 표시하고 carrier 의 상태는 건드리지 않음 — physical
+     * 운반자가 자체 cancel 책임.
+     */
+    rollback(): void;
+    private _buildReceipt;
+}
+/**
+ * 모든 Transfer 의 receipt 를 기록하는 singleton. observability 의 기반.
+ * Phase G7 — JSON snapshot/load 지원으로 외부 도구 (Chrome extension 등) 에서
+ * 라이브 또는 저장된 로그를 동일하게 시각화할 수 있다.
+ */
+declare class TransferLogImpl {
+    private _entries;
+    private _maxEntries;
+    private _listeners;
+    append(receipt: TransferReceipt): void;
+    /** 모든 receipt 반환 (read-only 사본). */
+    entries(): readonly TransferReceipt[];
+    /** carrier 별 transfer 이력. live ref 매칭 우선, fallback 으로 carrierId. */
+    forCarrier(carrier: any): readonly TransferReceipt[];
+    /** carrierId 로 직접 조회 (snapshot 복원 후 등 live ref 가 없을 때). */
+    forCarrierId(carrierId: string): readonly TransferReceipt[];
+    /** sourceId 로 조회 — 특정 vehicle / source 의 transfer 이력. */
+    forSourceId(sourceId: string): readonly TransferReceipt[];
+    /** targetId 로 조회 — 특정 holder 의 receive 이력. */
+    forTargetId(targetId: string): readonly TransferReceipt[];
+    /** phase 별 필터 (e.g. 'rolled-back' 만 — 실패 진단). */
+    forPhase(phase: TransferPhase): readonly TransferReceipt[];
+    /**
+     * sim-time 범위로 필터. transfer 의 initiatedAt 이 [startSimMs, endSimMs] 안에 있는지.
+     * 'overlap' 모드 — initiatedAt..committedAt 윈도우가 query 윈도우와 겹치면 포함.
+     */
+    inTimeRange(startSimMs: number, endSimMs: number, mode?: 'init' | 'overlap'): readonly TransferReceipt[];
+    /** rejectReason 별 그룹화 — 실패 패턴 진단. */
+    groupByRejectReason(): Map<string, readonly TransferReceipt[]>;
+    /** 통계 — 전체 / phase 별 / 거부율 / 평균 transfer 시간 등. */
+    stats(): TransferLogStats;
+    /** 새 receipt 마다 호출되는 listener 등록. */
+    subscribe(listener: (receipt: TransferReceipt) => void): () => void;
+    clear(): void;
+    setMaxEntries(n: number): void;
+    /**
+     * 모든 receipt 를 JSON 안전한 plain object 배열로. live ref 제외, ID 만 포함.
+     * JSON.stringify(transferLog.toJSON()) 안전.
+     */
+    toJSON(): TransferReceiptJSON[];
+    /**
+     * JSON 배열에서 entries 복원 (기존 entries 대체). 외부 viewer (extension) 가
+     * 저장된 로그를 로드해서 시각화할 때 사용.
+     *
+     * 복원된 receipt 는 source/target/carrier 의 live ref 가 undefined — ID 만으로
+     * 추적 (forCarrierId, sourceId, targetId 등). listener 에는 알림 안 함 (load
+     * 는 silent).
+     */
+    fromJSON(json: TransferReceiptJSON[]): void;
+    /**
+     * 저장된 로그를 listener 에게 순서대로 다시 발화 — extension 이 세션 시작 시
+     * 기존 entries 도 받고 싶을 때. listener 가 새 receipt 와 replayed receipt 를
+     * 구분 못 하므로 호출자가 의도적으로 사용.
+     */
+    replayTo(listener: (receipt: TransferReceipt) => void): void;
+}
+export declare const transferLog: TransferLogImpl;
+export {};
+//# sourceMappingURL=transfer.d.ts.map

package/dist-types/transfer/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAW,MAAM,YAAY,CAAA;AAGxE,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,UAAU,GACV,UAAU,GACV,SAAS,GACT,WAAW,GACX,aAAa,CAAA;AAEjB,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,GAAG,CAAA;IACX,MAAM,EAAE,GAAG,CAAA;IACX,OAAO,EAAE,GAAG,CAAA;IACZ,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,aAAa,CAAA;IACpB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,aAAa,CAAA;IACpB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AASD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,mBAAmB,CAe3E;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,GAAG,CAAA;IACX,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,GAAG,CAAA;IACZ,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAID;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IAExC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,aAAa,CAAC,CAAQ;gBAElB,IAAI,EAAE,YAAY;IAU9B,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAEzC;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC;IA8DzC;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAShB,OAAO,CAAC,aAAa;CAetB;AAID;;;;GAIG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,WAAW,CAAO;IAC1B,OAAO,CAAC,UAAU,CAAgD;IAElE,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQtC,oCAAoC;IACpC,OAAO,IAAI,SAAS,eAAe,EAAE;IAIrC,oEAAoE;IACpE,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,eAAe,EAAE;IAKpD,2DAA2D;IAC3D,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAI3D,yDAAyD;IACzD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAIzD,8CAA8C;IAC9C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAIzD,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,eAAe,EAAE;IAI1D;;;OAGG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,GAAG,SAAkB,GAAG,SAAS,eAAe,EAAE;IAchH,qCAAqC;IACrC,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAY9D,kDAAkD;IAClD,KAAK,IAAI,gBAAgB;IAuBzB,qCAAqC;IACrC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAOnE,KAAK,IAAI,IAAI;IAIb,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAM9B;;;OAGG;IACH,MAAM,IAAI,mBAAmB,EAAE;IAI/B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAgB3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;CAK7D;AAED,eAAO,MAAM,WAAW,iBAAwB,CAAA"}