@hatiolab/things-scene 10.0.0-beta.99 → 10.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-helpers.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer-helpers.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG;;;EAK3C;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,IAAI,CAUN;AAED,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,oBAAoB,CAAA"}

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

@@ -9,6 +9,30 @@ export interface TransferTimeline {
     handoffAt?: number;
     committedAt?: number;
 }
+/**
+ * Transfer 의 negotiation / interaction 세부 trace. 각 contract method 호출 시점에
+ * Transfer.execute 가 기록 — 어떤 컴포넌트의 어떤 contract 가 호출되었고 결과가
+ * 무엇이었는지 시각화.
+ *
+ *   role       : 'source' | 'target' | 'carrier' | 'transfer'
+ *   contract   : 호출한 contract 이름 (e.g. 'canAccept', 'findSlot', 'accept', 'physical')
+ *   componentId: 호출 대상 컴포넌트의 id
+ *   componentType: 컴포넌트의 type
+ *   atSimMs    : sim time 기준 호출 시점
+ *   args       : 인자의 *serializable summary* (carrier id, slot id 등)
+ *   result     : 반환값의 *serializable summary* (ok / reason / slotId 등)
+ *   error      : throw 시 메시지
+ */
+export interface TransferTraceEvent {
+    role: 'source' | 'target' | 'carrier' | 'transfer';
+    contract: string;
+    componentId?: string;
+    componentType?: string;
+    atSimMs: number;
+    args?: any;
+    result?: any;
+    error?: string;
+}
 export interface TransferReceipt {
     transferId: string;
     source: any;
@@ -22,6 +46,14 @@ export interface TransferReceipt {
     timeline: TransferTimeline;
     slotId?: string;
     rejectReason?: string;
+    /** Phase G10 — negotiation / interaction trace events. */
+    traceEvents?: TransferTraceEvent[];
+    /**
+     * Phase G11 — open-ended metadata. physical phase 가 *target-specific* 정보를
+     * 기록 (예: sorter 의 carrierId, cross-belt-line 의 carrier index). panel 의
+     * 컬럼 등 진단 시각화에서 사용.
+     */
+    meta?: Record<string, unknown>;
 }
 /**
  * TransferReceipt 의 직렬화 형태 — live ref 제외, ID 만. JSON.stringify 안전.
@@ -87,10 +119,52 @@ export declare class Transfer {
     private _phase;
     private _timeline;
     private _slot;
+    /** Phase 4c — 라이프사이클 예약(reserve→commit). null = 예약 미사용(capability-only/비-라이프사이클 target). */
+    private _reservation;
     private _rejectReason?;
+    private _traceEvents;
+    /**
+     * Phase G11 — target-specific metadata. physical phase 가 *sorter carrier
+     * index* 등 contract 외 진단 정보 기록. receipt 의 meta 로 시각화.
+     */
+    readonly meta: Record<string, unknown>;
     constructor(init: TransferInit);
+    /**
+     * Transfer trace 에 contract 호출 이벤트 push. Transfer.execute 가 명시 contract
+     * 호출 시 직접 사용 + FlowNode.receive 등 *내부 contract* 도 *current
+     * transfer* 의 trace 에 push 가능 (currentTransfer module-level singleton).
+     */
+    pushTrace(event: Omit<TransferTraceEvent, 'atSimMs'> & {
+        atSimMs?: number;
+    }): void;
     get phase(): TransferPhase;
     get timeline(): Readonly<TransferTimeline>;
+    /** rolled-back receipt 생성 (this._rejectReason 은 호출자가 먼저 설정). */
+    private _rollback;
+    /**
+     * planning(canAccept verdict → slot 결정) + reserve. 조기 거부 시 rolled-back
+     * receipt 를, 계속 진행이면 null 을 반환. this._slot / this._reservation 설정.
+     *
+     * 협상 분기는 "메서드 존재" 추측이 아니라 홀더가 선언한 slot 모델 유무(canAccept 의
+     * verdict)로 나뉜다. no-slots-defined = slot 식이 아님 → capability-only(handoff 의
+     * holder.receive 가 자체 게이트 책임). canReceive fallback 은 canAccept 미구현 최소 mock 용.
+     */
+    private _planAndReserve;
+    /** physical 실패 공통 처리 — 예약 롤백 + rolled-back receipt. */
+    private _physicalFailed;
+    /** handoff 실패 공통 처리 — rolled-back receipt 등록 후 throw(호출자 전파). */
+    private _handoffFailed;
+    /**
+     * handoff commit 분기 — 예약이 있으면 commit(원자 확정) 후 true. 예약 없으면 false
+     * (호출자가 receive fallback 담당). commit throw → 예약 롤백 + _handoffFailed(throw).
+     */
+    private _commitReserved;
+    /** committed receipt 생성. */
+    private _finishCommitted;
+    private _runPhysicalSync;
+    private _runPhysicalAsync;
+    private _runReceiveSync;
+    private _runReceiveAsync;
     /**
      * 5-phase 실행. 각 phase 진입 시 timeline 갱신, 완료 시 receipt 반환.
      *
@@ -99,6 +173,16 @@ export declare class Transfer {
      * Handoff 이후 throw 는 일관성 깨질 수 있으므로 그대로 propagate.
      */
     execute(): Promise<TransferReceipt>;
+    /**
+     * Sync 흐름 (= _tickLiveItems 매 frame iteration 안에서 dispatch) 전용 변형.
+     * physical / handoff 가 sync function 일 때만 동작 — async 면 *fire-and-forget*
+     * 으로 백그라운드 실행 (receipt 는 sync committed 표시).
+     *
+     * Async transfer 가 매 frame 동기 iteration 안에서 *sync 결과 필요* (= 박스 처리
+     * 끝 신호) 한 케이스. _tryDispatchToSorter / _ejectComponent 의 sync 흐름과 호환.
+     */
+    executeSync(): TransferReceipt;
+    private _executeImpl;
     /**
      * physical / planning 도중 외부 취소. handoff 이후엔 호출 금지 (이미 commit 됨).
      * 현재 구현은 phase 만 표시하고 carrier 의 상태는 건드리지 않음 — physical
@@ -112,56 +196,61 @@ export declare class Transfer {
  * Phase G7 — JSON snapshot/load 지원으로 외부 도구 (Chrome extension 등) 에서
  * 라이브 또는 저장된 로그를 동일하게 시각화할 수 있다.
  */
+/**
+ * TransferLogImpl — Step 1 정공 (2026-06-20):
+ *
+ * Raw receipt 1000 보관 폐기 → aggregated O(1) maintain. 본체 runtime 은 raw 사용 0
+ * (모든 reader 는 diagnostics — extension/devtools RPC). 본체가 extension buffer 역할
+ * 하던 안티패턴 제거.
+ *
+ * raw 가 필요한 도구 (carrier 별 timeline 등) 는 `subscribe` 패턴으로 extension 측
+ * 자체 누적 (Step 7).
+ */
 declare class TransferLogImpl {
-    private _entries;
-    private _maxEntries;
+    private _flows;
+    private _targetCount;
+    private _byPhase;
+    private _byRejectReason;
+    private _total;
+    private _committedDurationSum;
+    private _committedCount;
     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 시간 등. */
+    /** "src>tgt" → committed transfer count. inspector.topologyStats 활용. */
+    flows(): ReadonlyMap<string, number>;
+    /** targetId → 도착 count. distribution 계산 source. */
+    targetCounts(): ReadonlyMap<string, number>;
+    /** 통계 — aggregated 기반 O(1). */
     stats(): TransferLogStats;
-    /** 새 receipt 마다 호출되는 listener 등록. */
+    /** rejectReason 별 count — aggregated O(1). */
+    rejectReasonCounts(): ReadonlyMap<string, number>;
+    /** 새 receipt 마다 호출되는 listener 등록. extension 측 raw 누적 path. */
     subscribe(listener: (receipt: TransferReceipt) => void): () => void;
     clear(): void;
-    setMaxEntries(n: number): void;
-    /**
-     * 모든 receipt 를 JSON 안전한 plain object 배열로. live ref 제외, ID 만 포함.
-     * JSON.stringify(transferLog.toJSON()) 안전.
-     */
+    /** @deprecated raw entries 보관 폐기. extension 측 subscribe 패턴 사용. */
+    entries(): readonly TransferReceipt[];
+    /** @deprecated */
+    forCarrier(_carrier: any): readonly TransferReceipt[];
+    /** @deprecated */
+    forCarrierId(_carrierId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forSourceId(_sourceId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forTargetId(_targetId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forPhase(_phase: TransferPhase): readonly TransferReceipt[];
+    /** @deprecated */
+    inTimeRange(_startSimMs: number, _endSimMs: number, _mode?: 'init' | 'overlap'): readonly TransferReceipt[];
+    /** @deprecated raw entries 폐기. rejectReasonCounts() 사용. */
+    groupByRejectReason(): Map<string, readonly TransferReceipt[]>;
+    /** @deprecated raw 보관 폐기 — toJSON 빈 array. */
     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;
+    /** @deprecated raw 보관 폐기 — fromJSON noop. */
+    fromJSON(_json: TransferReceiptJSON[]): void;
+    /** @deprecated raw 보관 폐기 — replayTo noop. */
+    replayTo(_listener: (receipt: TransferReceipt) => void): void;
+    /** @deprecated raw 보관 폐기 — setMaxEntries noop. */
+    setMaxEntries(_n: number): void;
 }
 export declare const transferLog: TransferLogImpl;
 export {};

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

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

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

@@ -0,0 +1,275 @@
+import type { SlotDef, TransferOptions, Transferable as ITransferable, Reservation, SlotReservation } from './types.js';
+import type Component from '../components/component.js';
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * Transferable (move) 믹스인. Capacity 위에 합성되어 receive/dispatch 를 제공.
+ */
+export declare function Transferable<TBase extends Constructor<Component>>(Base: TBase): {
+    new (...args: any[]): {
+        /**
+         * 자리 잠정 확보 (Phase 4c 라이프사이클) — slot 노드는 findSlot 이 곧 예약.
+         * 순수: 점유는 _items 에서 live 파생되므로 별도 마킹 불필요(마크 side-effect 없음).
+         * null = 지금 받을 수 없음.
+         */
+        reserve(component: any, _ctx?: any): SlotReservation | null;
+        /** 예약 취소 — slot 노드는 마크가 없어 noop (idempotent). */
+        release(_reservation: Reservation): void;
+        receive(component: any, options?: TransferOptions): Promise<void>;
+        /**
+         * 예약 확정 (Phase 4c) — attach + 안착을 단일 원자 setState 로 적용. Phase G 불변 보존.
+         * reserve 로 확보한 slot 에 carrier 를 reparent + 6DOF 안착.
+         */
+        commit(reservation: SlotReservation, component: any, options?: TransferOptions): void;
+        dispatch(component: any, target: ITransferable, options?: TransferOptions): Promise<void>;
+        route(_component: any): ITransferable | null | Promise<ITransferable | null>;
+        /** WCS resolves a pending route. Override in BeltContainer / WheelSorter. */
+        resolveRoute(_component: any, _target: ITransferable): void;
+        /** WCS rejects or times out a pending route. */
+        rejectRoute(component: any, reason?: string): void;
+        /**
+         * canReceive 의 풍부한 버전. ok 면 slot 동봉, 아니면 reason 명시 (drag-over UI 용).
+         */
+        canAccept(component: any): {
+            ok: true;
+            slot: SlotDef;
+        } | {
+            ok: false;
+            reason: string;
+        };
+        /** receive 의 alias — Phase G2 contract 의 명시적 이름. */
+        accept(component: any, options?: TransferOptions): Promise<void>;
+        _app: any;
+        _model: any;
+        _state: any;
+        _delta: any;
+        _animation: any;
+        _animate: any;
+        _parent: any;
+        _disposed: any;
+        _textHidden: any;
+        _text_substitutor: any;
+        _value_substitutor: any;
+        _mappings: any;
+        _realObject: import("../index.js").IRealObject | undefined;
+        _cachedState: any;
+        updatedAt: any;
+        fontSize: any;
+        __cache__: any;
+        created(): void;
+        added(parent: import("../types/component.js").Container): void;
+        removed(parent: import("../types/component.js").Container): void;
+        ready(): Promise<void>;
+        _readyInvoked: boolean;
+        invokeReady(): void | Promise<void>;
+        touch(): void;
+        clearCache(...attrs: string[]): void;
+        removeSelf(completely?: boolean): void;
+        resetAnimation(): void;
+        dispose(): void;
+        get nature(): import("../index.js").ComponentNature;
+        get disposed(): boolean;
+        isLayer(): boolean;
+        isGroup(): boolean;
+        isContainer(): this is import("../types/component.js").Container;
+        isLine(): boolean;
+        isRoot(): boolean;
+        isRootModel(): boolean;
+        is3dish(): boolean;
+        get is3dMode(): boolean;
+        isIn3DSpace(): boolean;
+        isTemplate(): boolean;
+        isHTMLElement(): boolean;
+        isConnectable(): boolean;
+        isIdentifiable(): boolean;
+        isPositionable(): boolean;
+        replaceRefids(replaceMap: Record<string, string>): void;
+        get(property: string): any;
+        set(props: any, propval?: any): any;
+        getState(property: string): any;
+        setState(props: Partial<import("../index.js").State> | string, propval?: any): any;
+        get model(): any;
+        get state(): import("../index.js").State;
+        get refid(): any;
+        get hierarchy(): any;
+        get volatile(): string[];
+        _applyProps(target: Record<string, any>, props: Record<string, any>, options: import("../components/component.js").ApplyPropsOptions): /*elided*/ any;
+        contains(x: number, y: number): boolean;
+        move(offset: {
+            x: number;
+            y: number;
+        }, ...args: boolean[]): void;
+        symmetryX(x?: number): void;
+        symmetryY(y: number): void;
+        adjustResize(bounds: import("../index.js").BOUNDS, origin_bounds: import("../index.js").BOUNDS, diagonal: boolean): {
+            left: any;
+            top: any;
+            width: any;
+            height: any;
+        };
+        adjustRotation(rotation: number, step: boolean): number;
+        outline(progress: number): any;
+        get bounds(): import("../index.js").BOUNDS;
+        set bounds(b: import("../index.js").BOUNDS);
+        get center(): import("../index.js").POINT;
+        set center(p: import("../index.js").POINT);
+        get location(): import("../index.js").POINT;
+        set location(l: import("../index.js").POINT);
+        get rotate(): import("../index.js").POINT;
+        set rotate(r: import("../index.js").POINT);
+        get dimension(): import("../index.js").DIMENSION;
+        set dimension(d: import("../index.js").DIMENSION);
+        get path(): import("../index.js").POINT[];
+        set path(p: import("../index.js").POINT[]);
+        get drawPath(): import("../index.js").POINT[];
+        get rotatePoint(): import("../index.js").POINT;
+        get mutable(): boolean;
+        get resizable(): boolean;
+        get rotatable(): boolean;
+        buildRealObject(): import("../index.js").IRealObject | undefined;
+        get realObject(): import("../index.js").IRealObject | undefined;
+        draw(context?: import("../index.js").SceneRenderContext): void;
+        prerender(context: import("../index.js").SceneRenderContext): void;
+        render(context: import("../index.js").SceneRenderContext): void;
+        postrender(context: import("../index.js").SceneRenderContext): void;
+        prepare(resolve: (component: Component) => void, reject: (reason: any) => void): void;
+        prepareIf(condition: boolean): void;
+        drawText(context: import("../index.js").SceneRenderContext): void;
+        drawStroke(context: import("../index.js").SceneRenderContext, override?: Record<string, unknown>): void;
+        drawFill(context: import("../index.js").SceneRenderContext, override?: Record<string, unknown>): void;
+        get strokeStyle(): any;
+        set strokeStyle(v: any);
+        get fillStyle(): any;
+        set fillStyle(v: any);
+        get fontColor(): string;
+        set fontColor(v: string);
+        get rotation(): number;
+        set rotation(v: number);
+        get decorators(): string[];
+        get decotag(): string;
+        get hidden(): boolean;
+        set hidden(v: boolean);
+        get tag(): string;
+        set tag(v: string);
+        get appendum(): any;
+        set appendum(v: any);
+        defaultTextSubstitutor(): string;
+        textLines(context?: import("../index.js").SceneRenderContext): any[][];
+        get font(): string;
+        get lineHeight(): number;
+        get textSubstitutor(): () => string;
+        get text(): string;
+        set text(v: string);
+        get textBounds(): import("../index.js").BOUNDS;
+        get textRotation(): number;
+        get textHidden(): boolean;
+        set textHidden(v: boolean);
+        get hasTextProperty(): boolean;
+        animate(opts: import("../index.js").AnimationConfig): any;
+        effect(context: import("../index.js").SceneRenderContext, model: any): void;
+        serialize(...others: any[]): string;
+        trim(): void;
+        closeScene(data: any): void;
+        delta(attr?: string | object, value?: any): any;
+        invalidate(): void;
+        get value(): any;
+        set value(v: any);
+        get data(): any;
+        set data(v: any);
+        set tap(v: any);
+        get mappings(): any[];
+        get retention(): number;
+        get animation(): import("../index.js").AnimationController | undefined;
+        get started(): boolean;
+        set started(v: boolean);
+        get controls(): import("../index.js").Control[] | undefined;
+        findFirst(finder: string | ((c: Component) => boolean), ...others: any[]): Component | undefined;
+        findAll(s: string | ((c: Component) => boolean), ...others: any[]): any[] | undefined;
+        capture(x: number, y: number, except?: (c: Component) => boolean): any;
+        findAnchor(name: string): any;
+        isDescendible(container: Component | any): boolean;
+        getContext(component?: unknown): any;
+        get root(): Component;
+        get rootModel(): Component;
+        get parent(): Component;
+        set parent(v: Component);
+        get anchors(): import("../index.js").Anchor[];
+        get scalable(): boolean;
+        get stuck(): boolean;
+        get capturable(): boolean;
+        get position(): string;
+        get origin(): string;
+        get offset(): import("../index.js").POINT;
+        get app(): import("../index.js").ApplicationContext;
+        drawEffect(context: import("../index.js").SceneRenderContext): void;
+        prepareFill(resolve: Function, reject: Function): void;
+        prepareFillIf(condition: boolean): void;
+        onchangeFill(after: Record<string, any>, before: Record<string, any>): void;
+        drawImage(context: import("../index.js").SceneRenderContext, image: HTMLImageElement, left: number, top: number, width: number, height: number): void;
+        mutateBounds(logic: ((bounds: import("../index.js").BOUNDS) => import("../index.js").BOUNDS | void) | null, context?: any): void;
+        mutatePath(beforeLogic: ((path: import("../index.js").POINT[]) => import("../index.js").POINT[] | void) | null, afterLogic: ((path: import("../index.js").POINT[]) => import("../index.js").POINT[] | void) | null, context?: any): void;
+        access(accessor: string): any;
+        substitute(template: string, data: any): string | undefined;
+        onchangeMappings(after: Record<string, any>, before: Record<string, any>): void;
+        onchangeData(after: Record<string, any>, before: Record<string, any>): void;
+        buildMappings(): void;
+        executeMappings(force?: boolean): void;
+        disposeMappings(): void;
+        ondropfile(transfered: FileList, files: string[]): void;
+        transcoordS2P(x: number, y: number, rp?: import("../index.js").POINT): import("../index.js").POINT;
+        transcoordP2S(x: number, y: number, rp?: import("../index.js").POINT): import("../index.js").POINT;
+        transcoordS2T(x: number, y: number, top?: Component): import("../index.js").POINT;
+        transcoordT2P(x: number, y: number, top?: Component): import("../index.js").POINT;
+        transcoordT2S(x: number, y: number, top?: Component): import("../index.js").POINT;
+        transcoordS2TR(x: number, y: number, top?: Component): import("../index.js").POINT;
+        transcoordS2O(x: number, y: number, target: Component): import("../index.js").POINT;
+        transcoordC2S(x: number, y: number, top?: Component): import("../index.js").POINT;
+        transcoordS2C(x: number, y: number, top?: Component): import("../index.js").POINT;
+        toParent(x: number, y: number, rp?: import("../index.js").POINT): import("../index.js").POINT;
+        fromParent(x: number, y: number, rp?: import("../index.js").POINT): import("../index.js").POINT;
+        toScene(x: number, y: number, top?: Component): import("../index.js").POINT;
+        fromScene(x: number, y: number, top?: Component): import("../index.js").POINT;
+        toLocal(x: number, y: number, top?: Component): import("../index.js").POINT;
+        toGlobal(x: number, y: number, top?: Component): import("../index.js").POINT;
+        toOther(x: number, y: number, target: Component): import("../index.js").POINT;
+        on<K extends keyof import("../index.js").ComponentEventMap>(name: K, callback: (...args: import("../index.js").ComponentEventMap[K]) => void, context?: any): /*elided*/ any;
+        on(name: string | object, callback: Function, context?: any): /*elided*/ any;
+        off<K extends keyof import("../index.js").ComponentEventMap>(name: K, callback?: ((...args: import("../index.js").ComponentEventMap[K]) => void) | undefined, context?: any): /*elided*/ any;
+        off(name?: string | object, callback?: Function, context?: any): /*elided*/ any;
+        once<K extends keyof import("../index.js").ComponentEventMap>(name: K, callback: (...args: import("../index.js").ComponentEventMap[K]) => void, context?: any): /*elided*/ any;
+        once(name: string | object, callback: Function, context?: any): /*elided*/ any;
+        trigger<K extends keyof import("../index.js").ComponentEventMap>(name: K, ...args: import("../index.js").ComponentEventMap[K]): /*elided*/ any;
+        trigger(name: string, ...args: any[]): /*elided*/ any;
+        delegate_on(delegator: any): /*elided*/ any;
+        delegate_off(delegator: any): /*elided*/ any;
+        onchange(after: Record<string, any>, before: Record<string, any>): void;
+        calculateBounds?(): void;
+        oncreate_element?(element: HTMLElement): void;
+        removeComponent(component: Component, ghost?: boolean): void;
+        addComponent(component: Component, ghost?: boolean): void;
+        insertComponentAt(component: Component, index: number, ghost?: boolean): void;
+        getOverlay(component: Component): HTMLElement | undefined;
+        findById(id: string): Component | undefined;
+        findByRefid(ref: string | number): Component | undefined;
+        findAllById(id: string): Component[];
+        resize(): void;
+        fit(type?: string): void;
+        get components(): Component[] | undefined;
+        get layout(): any;
+        get auxOverlay(): HTMLElement | undefined;
+        get isReady(): boolean;
+        get unitScale(): number;
+        get selected(): Component[];
+        set selected(_v: Component[]);
+        get focused(): Component | null;
+        set focused(_v: Component | null);
+        get hasSameParentForAllSelected(): boolean;
+        set hasSameParentForAllSelected(_v: boolean);
+        get fitMode(): string | undefined;
+        set fitMode(_v: string | undefined);
+        get element(): HTMLElement | null;
+        set element(_v: HTMLElement | null);
+    };
+    __hasTransferable: boolean;
+} & TBase;
+export {};
+//# sourceMappingURL=transferable-mixin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transferable-mixin.d.ts","sourceRoot":"","sources":["../../src/transfer/transferable-mixin.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,IAAI,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACvH,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AAMvD,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AAExD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,SAAS,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK;kBALjC,GAAG,EAAE;QAU9C;;;;WAIG;2BACgB,GAAG,SAAS,GAAG,GAAG,eAAe,GAAG,IAAI;QAM3D,iDAAiD;8BAC3B,WAAW,GAAG,IAAI;2BAIf,GAAG,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;QAsB3E;;;WAGG;4BACiB,eAAe,aAAa,GAAG,YAAW,eAAe,GAAQ,IAAI;4BA8H/D,GAAG,UAAU,aAAa,YAAW,eAAe,GAAQ,OAAO,CAAC,IAAI,CAAC;0BAiCjF,GAAG,GAAG,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;QAI5E,6EAA6E;iCACpD,GAAG,WAAW,aAAa,GAAG,IAAI;QAI3D,gDAAgD;+BACzB,GAAG,oBAAwB,IAAI;QAStD;;WAEG;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;QAuBtF,oDAAoD;0BAClC,GAAG,YAAY,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAInE"}

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

@@ -133,8 +133,20 @@ export interface PoseSerialized {
 export interface PickupFrame {
     id: string;
     toolType: string;
+    /** 도구가 결합 직전 hover 하는 world 자세 (motion 목표). */
     approach: PoseSerialized;
+    /** 도구가 결합(grab)하는 world 자세 — carrier 에 닿는 지점 (fork 가 구멍 진입 등). */
     engage: PoseSerialized;
+    /**
+     * *운반 중* carrier 가 도구에 실리는 관계 (선택). approach/engage 가 *도구의 world
+     * 이동 목표* 인 반면, mount 는 *carrier-LOCAL* 자세 — carrier 의 어느 지점(하중면)이
+     * 도구의 carry attach point 에 오는지. grab(engage) 과 carried(mount) 는 다르다:
+     * fork 는 구멍(engage)으로 들어가 *상판 아래면*(mount)으로 실리고, deck 는 밑(engage)
+     * 에서 *바닥*(mount)으로, vacuum 은 상단으로 매달린다. 미지정 시 도구 default(carrier
+     * 바닥이 attach 에 = 얹기). **랙/평치 *보관* 은 이 mount 가 아니라 seating(placementFor)
+     * 이 담당 — mount 는 pickup 도구 운반 전용.**
+     */
+    mount?: PoseSerialized;
     tolerance?: {
         positionMm?: number;
         angleDeg?: number;
@@ -185,6 +197,45 @@ export interface ArrangementStrategy {
     /** Maximum number of items this strategy can hold in one slot. */
     capacity(slotDef: SlotDef): number;
 }
+/** 안착 산술의 carrier 입력 — 치수만. width/height = 2D footprint, depth = 3D 높이. */
+export interface CarrierDims {
+    width: number;
+    height: number;
+    depth: number;
+}
+/** placementFor 의 ctx — 모두 선택. 미지정 시 holder 가 현재 점유 기준 기본값 결정. */
+export interface PlacementContext {
+    /** 대상 slot — 미지정 시 첫 가용 slot. */
+    slot?: SlotDef;
+    /** ArrangementStrategy 위임용 점유 index — 미지정 시 현재 점유 수. */
+    index?: number;
+    /** 점유 총원 — 미지정 시 index 와 동일 (receive 의 호출 형태 미러). */
+    occupantCount?: number;
+    /** line / slide 형 holder 의 경로 진행도 [0, 1]. */
+    t?: number;
+}
+/** 안착 pose — holder RealObject object3d local frame. */
+export interface SeatingPose {
+    /** carrier *중심* 위치 (holder object3d local). */
+    position: Vec3;
+    /** holder-local 자세. undefined = carrier 의 들어오는 자세 보존. */
+    rotation?: QuatLike;
+}
+/**
+ * 수용 예약 — `reserve()` 가 발급, `commit()`/`release()` 가 소비하는 opaque token.
+ *
+ * 모든 핸드오버는 동일한 트랜잭션 라이프사이클(canReceive → reserve → commit → release)을
+ * 갖는다. slot 노드는 reserve/commit 이 원자로 붕괴한 degenerate 케이스(자리가 정지),
+ * CarrierLine 은 그 라이프사이클이 시간축으로 펼쳐진 원형(빈 캐리어가 움직임). 예약 자체는
+ * opaque — 발급한 구현만 내부 필드를 해석한다.
+ */
+export interface Reservation {
+    readonly token: symbol;
+}
+/** slot 노드의 예약 — 확보된 slot 을 동봉. */
+export interface SlotReservation extends Reservation {
+    readonly slot: SlotDef;
+}
 /**
  * The central abstraction for anything that can receive and dispatch components.
  *
@@ -195,14 +246,25 @@ export interface ArrangementStrategy {
  */
 export interface Transferable {
     /**
-     * Pure, synchronous capacity check.
+     * Pure, synchronous capacity check — "이 item 을 받을 수 있나?"
      * Must NOT mutate state — called on every drag-over frame.
+     *
+     * ctx.slotId 를 주면 *특정 slot* 에 받을 수 있는지, 없으면 *아무 slot이나* 가능한지.
+     * (위치는 이 보편 게이트의 매개변수 — 별도 canReceiveAt 방언을 두지 않는다. Phase 3 #4.)
      */
-    canReceive(component: any): boolean;
+    canReceive(component: any, ctx?: {
+        slotId?: string;
+    }): boolean;
     /** Returns the best available SlotDef for `component`, or null if none. */
     findSlot(component: any): SlotDef | null;
     /** Reparent `component` into this container. Fires 'transfer-received'. */
     receive(component: any, options?: TransferOptions): Promise<void> | void;
+    /** 자리를 잠정 확보. null = 지금 받을 수 없음. 게이트 판정은 canReceive 가 담당(순수). */
+    reserve?(component: any, ctx?: any): Reservation | null;
+    /** 예약을 원자적으로 확정 — attach + 안착(단일 setState). 실패 시 throw. */
+    commit?(reservation: Reservation, component: any, options?: TransferOptions): void;
+    /** 예약 취소 — 마크 해제. idempotent. commit 후 호출 시 noop. */
+    release?(reservation: Reservation): void;
     /** Move `component` to `target.receive()`. Fires 'transfer-dispatched'. */
     dispatch(component: any, target: Transferable, options?: TransferOptions): Promise<void> | void;
     /**
@@ -223,6 +285,17 @@ export interface Transferable {
     rejectRoute(component: any, reason?: string): void;
     /** Returns the 3D attach frame for a payload held in this container. */
     attachPointFor(component: any): CarrierAttachPoint | null;
+    /**
+     * Phase PS — carrier 가 이 holder 의 ctx 지점에 안착할 때의 pose.
+     * holder RealObject object3d local frame, 순수 함수. null = 이 ctx 에 안착
+     * 정의 없음 (호출자가 현재 위치 보존 fallback).
+     *
+     * `carrier` 는 치수 객체 또는 component (state.width/height/depth 보유) —
+     * component 를 주면 dimension-aware ArrangementStrategy 가 그대로 활용.
+     * 기본 구현은 FlowNode 가 제공 (기존 receivingSurfaceY +
+     * ArrangementStrategy + acceptanceRotation 합성과 수치 동일 — I5).
+     */
+    placementFor?(carrier: CarrierDims | any, ctx?: PlacementContext): SeatingPose | null;
     /**
      * carrier 가 이 holder 안에서 가져야 할 회전 (parent-local quaternion).
      * 기본값 identity (carrier 의 들어오는 자세 보존).