@hatiolab/things-scene 10.0.0-beta.12 → 10.0.0-beta.120

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/placement/index.d.ts

@@ -0,0 +1,3 @@
+export type { Placement, PlacementPolicy } from './placement.js';
+export { DEFAULT_PLACEMENT, isStateDriven } from './placement.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/placement/index.ts"],"names":[],"mappings":"AAMA,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

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

@@ -0,0 +1,53 @@
+/**
+ * 컴포넌트의 placement 결정 정책.
+ *
+ * - **state-driven** (default): state.left/top/zPos/rotation/... 이 obj3d 에 반영.
+ *   현재 things-scene 의 모든 컴포넌트가 묵시적으로 따르는 정책.
+ *
+ * - **carried**: 다른 holder 의 attach frame 에 부착. holder 의 movement 를
+ *   scene-graph 통해 자동 추종. carrier policy (world-preserve / belt-aligned /
+ *   world-fixed 등) 는 holder 가 결정. 예: AGV 위 박스, sorter carrier 위 파레트.
+ *
+ * - **animated**: animation system 이 일시적으로 obj3d 를 override. animation
+ *   종료 시 다른 정책으로 복귀.
+ *
+ * - **fixed**: world 좌표 고정 (parent 변경 무관). HUD / screenFixed 컴포넌트.
+ *
+ * - **transitioning**: reparent 중 TransitionEffect 가 보간 제어. transition
+ *   완료 시 keepSuppressed 면 carried 또는 manual, 아니면 state-driven 으로 복귀.
+ *
+ * - **manual**: 컴포넌트 코드가 직접 obj3d.position/quaternion 을 매 frame
+ *   조작. framework 는 개입 안 함. 예: cross-belt-line 의 _tickSim, IK
+ *   smoothing, URDF physics.
+ */
+export type PlacementPolicy = 'state-driven' | 'carried' | 'animated' | 'fixed' | 'transitioning' | 'manual';
+/**
+ * Placement 선언. 컴포넌트의 RealObject 가 이 객체를 반환하면 framework 가
+ * 정책에 따라 동작.
+ *
+ * Step 1 에선 policy 만 정의. 후속 step 에서 정책별 metadata (예: carried 의
+ * carryPolicy 'world-preserve' / 'belt-aligned', transitioning 의 transition 객체)
+ * 를 추가.
+ */
+export interface Placement {
+    policy: PlacementPolicy;
+    /**
+     * 정책별 metadata. 선언 시점에 정책에 따라 추가 정보를 담음.
+     * Step 1 에선 미사용. 향후 정책 별로 타입 좁히기 (discriminated union) 적용.
+     */
+    meta?: Record<string, unknown>;
+}
+/** 기본 placement = 현재 동작 = state pipeline 이 obj3d 를 결정. */
+export declare const DEFAULT_PLACEMENT: Placement;
+/**
+ * Placement 정책이 state pipeline 적용을 허용하는가.
+ *
+ * - state-driven: ✓ 적용
+ * - 그 외: framework 가 obj3d 를 건드리지 않음 (다른 시스템 또는 컴포넌트가 책임).
+ *
+ * 현재 RealObject 의 `suppressTransform` 플래그와 의미가 겹침. 마이그레이션
+ * 단계 (Step 2~7) 에서 suppressTransform 이 점진적으로 `placement.policy !==
+ * 'state-driven'` 으로 흡수됨. 호환성 위해 두 메커니즘 일정 기간 병존.
+ */
+export declare function isStateDriven(placement: Placement): boolean;
+//# sourceMappingURL=placement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../../src/placement/placement.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,SAAS,GACT,UAAU,GACV,OAAO,GACP,eAAe,GACf,QAAQ,CAAA;AAEZ;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,eAAe,CAAA;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAE,SAAsC,CAAA;AAEtE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAE3D"}

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

@@ -0,0 +1,3 @@
+export { SceneSearchEngine, type SearchResult, type SearchOptions } from './scene-search-engine.js';
+export { SearchOverlay, type SearchOverlayHost } from './search-overlay.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACnG,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist-types/search/scene-search-engine.d.ts

@@ -0,0 +1,65 @@
+import type Component from '../components/component.js';
+/**
+ * 검색 결과 하나를 나타낸다.
+ */
+export interface SearchResult {
+    /** 매칭된 컴포넌트 */
+    component: Component;
+    /** 매칭 카테고리 */
+    matchType: 'id' | 'name' | 'tag' | 'type' | 'class' | 'text' | 'data' | 'property';
+    /** 매칭된 필드 이름 (예: 'accessor', 'fillStyle') */
+    matchField: string;
+    /** 매칭된 값 */
+    matchValue: string;
+}
+export interface SearchOptions {
+    /** 검색할 필드 범위 (기본: 전체) */
+    fields?: SearchResult['matchType'][];
+    /** 대소문자 구분 (기본: false) */
+    caseSensitive?: boolean;
+    /** hidden 컴포넌트 포함 (기본: false) */
+    includeHidden?: boolean;
+    /** 최대 결과 수 (기본: 무제한) */
+    maxResults?: number;
+}
+/**
+ * things-scene 컴포넌트 트리를 대상으로 텍스트 검색을 수행하는 엔진.
+ *
+ * 에디터/뷰어, 2D/3D 모드 공용.
+ * 검색 대상: id, name, tag, type, class, text, data-binding(accessor/target/property), 주요 속성값.
+ */
+export declare class SceneSearchEngine {
+    private _results;
+    private _currentIndex;
+    private _lastQuery;
+    get results(): readonly SearchResult[];
+    get currentIndex(): number;
+    get currentResult(): SearchResult | undefined;
+    get resultCount(): number;
+    /**
+     * 컴포넌트 트리에서 query를 검색한다.
+     * 동일 컴포넌트가 여러 필드에서 매칭되면 첫 번째 매칭만 결과에 포함한다.
+     */
+    search(root: Component, query: string, options?: SearchOptions): SearchResult[];
+    /** 다음 결과로 이동 */
+    navigateNext(): SearchResult | undefined;
+    /** 이전 결과로 이동 */
+    navigatePrev(): SearchResult | undefined;
+    /** 특정 인덱스로 이동 */
+    navigateTo(index: number): SearchResult | undefined;
+    /** 검색 결과 초기화 */
+    clear(): void;
+    private _traverse;
+    private _matchComponent;
+    /**
+     * data-binding 설정(mappings)에서 검색.
+     * accessor, target, property, source 필드를 대상으로 한다.
+     */
+    private _matchDataBinding;
+    /**
+     * 주요 속성값에서 검색.
+     * fillStyle(문자열), strokeStyle(문자열), ref, src 등.
+     */
+    private _matchProperties;
+}
+//# sourceMappingURL=scene-search-engine.d.ts.map

package/dist-types/search/scene-search-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-search-engine.d.ts","sourceRoot":"","sources":["../../src/search/scene-search-engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,SAAS,EAAE,SAAS,CAAA;IACpB,cAAc;IACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAA;IAClF,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY;IACZ,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,CAAA;IACpC,0BAA0B;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iCAAiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAMD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IAEvB,IAAI,OAAO,IAAI,SAAS,YAAY,EAAE,CAErC;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,aAAa,IAAI,YAAY,GAAG,SAAS,CAE5C;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE;IAmC/E,gBAAgB;IAChB,YAAY,IAAI,YAAY,GAAG,SAAS;IAMxC,gBAAgB;IAChB,YAAY,IAAI,YAAY,GAAG,SAAS;IAMxC,iBAAiB;IACjB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAMnD,gBAAgB;IAChB,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,eAAe;IAoEvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiCzB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAkCzB"}

package/dist-types/search/search-overlay.d.ts

@@ -0,0 +1,95 @@
+import type Component from '../components/component.js';
+import { SceneSearchEngine } from './scene-search-engine.js';
+/**
+ * SearchOverlayHost: 검색 오버레이가 동작하기 위한 호스트 인터페이스.
+ * Scene이 이 인터페이스를 구현한다.
+ */
+export interface SearchOverlayHost {
+    /** 검색 대상 루트 컴포넌트 */
+    readonly root: Component & {
+        selected?: Component[];
+    };
+    /** 오버레이를 붙일 DOM element */
+    readonly element: HTMLElement | null;
+    /** 컴포넌트로 카메라/뷰포트 이동 */
+    centerTo(component: Component, animated?: boolean): void;
+    /** 선택 변경 */
+    setSelected(components: Component[]): void;
+    /** 3D outline 하이라이트 (있으면) */
+    highlightSearchResults?(components: Component[]): void;
+    /** 2D invalidate */
+    invalidate?(): void;
+}
+/**
+ * 2D/3D 모드 공용 검색 오버레이 UI.
+ *
+ * 호스트의 DOM element에 겹쳐 놓는 가벼운 검색 바.
+ * F키로 토글, ↑↓ 결과 네비게이션, Enter 선택, Esc 닫기.
+ * 입력 히스토리(↑↓), Shift+Tab으로 input 복귀, 마우스+키보드 심리스 전환.
+ */
+export declare class SearchOverlay {
+    private _host?;
+    private _engine;
+    private _container?;
+    private _input?;
+    private _statusEl?;
+    private _resultListEl?;
+    private _visible;
+    private _debounceTimer?;
+    private _queryHistory;
+    private _historyIndex;
+    private _savedInput;
+    private static MAX_HISTORY;
+    private _keyboardNav;
+    get isVisible(): boolean;
+    get engine(): SceneSearchEngine;
+    setup(host: SearchOverlayHost): void;
+    /**
+     * 오버레이 토글. 이미 열려 있으면 입력 필드에 포커스.
+     */
+    toggle(): void;
+    show(): void;
+    hide(): void;
+    destroy(): void;
+    private _buildDOM;
+    /**
+     * 드래그 핸들 설정. mousedown on `handle` 에서 시작, document 의 mousemove 로
+     * container 위치 추적, mouseup 으로 종료. input/button/icon 같은 인터랙티브
+     * 요소 위에서 시작된 mousedown 은 드래그로 잡지 않음 (본연의 click/focus 보존).
+     */
+    private _setupDrag;
+    private _buttonStyle;
+    private _doSearch;
+    private _addToHistory;
+    private _navigateHistory;
+    private _isHistoryMode;
+    /**
+     * input 의 raw 값을 host 에 query-submit 으로 전달. Enter 키 / 돋보기 아이콘 클릭
+     * 공통 진입점.
+     * - VIEW 모드: input 의 raw 값을 query-submit 으로 host 에 dispatch. 결과 유무
+     *   무관하게 입력값 자체를 정확한 ID 로 host 가 처리 (예: 미래 ID 영구 추적).
+     * - EDIT 모드: things-scene 기본 동작 위임 — 결과가 있으면 첫 결과 _selectResult.
+     * @returns input value 가 비어있지 않아 submit 처리했으면 true.
+     */
+    private _submitQuery;
+    /**
+     * VIEW 모드의 디폴트 query-submit 동작 — application 의 onSearchSubmit override
+     * 가 있으면 그것 호출. 반환 true 시 디폴트 (host.tracker.start) skip.
+     */
+    private _invokeViewSubmit;
+    /**
+     * VIEW 모드의 디폴트 close 동작 — application override (onSearchClose) 가 있으면
+     * 호출. 반환 true 시 디폴트 (host.tracker.stop) skip.
+     */
+    private _invokeViewClose;
+    private _focusResult;
+    private _isEditMode;
+    private _selectResult;
+    private _clearHighlight;
+    private _updateStatus;
+    private _renderResultList;
+    private _updateResultListSelection;
+    private _hideResultList;
+    private _truncate;
+}
+//# sourceMappingURL=search-overlay.d.ts.map

package/dist-types/search/search-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-overlay.d.ts","sourceRoot":"","sources":["../../src/search/search-overlay.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAqB,MAAM,0BAA0B,CAAA;AAE/E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG;QAAE,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAA;KAAE,CAAA;IACrD,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IACpC,uBAAuB;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACxD,YAAY;IACZ,WAAW,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IAC1C,6BAA6B;IAC7B,sBAAsB,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IACtD,oBAAoB;IACpB,UAAU,CAAC,IAAI,IAAI,CAAA;CACpB;AAaD;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,OAAO,CAAC,MAAM,CAAC,CAAkB;IACjC,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,cAAc,CAAC,CAA+B;IAGtD,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAAC,WAAW,CAAK;IAG/B,OAAO,CAAC,YAAY,CAAQ;IAE5B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED,KAAK,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAKpC;;OAEG;IACH,MAAM,IAAI,IAAI;IAad,IAAI,IAAI,IAAI;IAqBZ,IAAI,IAAI,IAAI;IAkBZ,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,SAAS;IA8JjB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAqClB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,gBAAgB;IA4BxB,OAAO,CAAC,cAAc;IAItB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAoBpB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;IA8CrB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,iBAAiB;IA+HzB,OAAO,CAAC,0BAA0B;IAmBlC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,SAAS;CAGlB"}

package/dist-types/things-scene/api/add-start.d.ts

@@ -1,2 +1,27 @@
 export declare function startAddMode(this: any, models: any): void;
+/** bulk-create 모드 결과 — 사용자가 영역 드래그 완료 시 area, ESC/취소 시 null. */
+export interface BulkCreateResult {
+    area: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    template: any;
+}
+/**
+ * Bulk-create 모드 진입. AddLayer 가 캔버스 위에 드래그 박스 그림. 사용자가 영역을
+ * 선택하면 `{area, template}` 로 resolve, ESC/취소 시 null 로 resolve.
+ *
+ * 내부적으로 'bulkareaselected' / 'addstop' event 의 lifecycle 을 캡슐화 — consumer 가
+ * listener 등록/정리 boilerplate 없이 한 줄 `await` 로 처리.
+ *
+ * @param template 복사 원본 모델. bulkareaselected event payload 와 결과 객체에 그대로 전달.
+ * @param options.boxStrokeStyle addbox 의 stroke 색. 기본 'black' (일반 add 와 동일).
+ *
+ * this should be root-container.
+ */
+export declare function startBulkCreateMode(this: any, template: any, options?: {
+    boxStrokeStyle?: string;
+}): Promise<BulkCreateResult | null>;
 //# sourceMappingURL=add-start.d.ts.map

package/dist-types/things-scene/api/add-start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-start.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/add-start.ts"],"names":[],"mappings":"AAKA,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,QAMlD"}
+{"version":3,"file":"add-start.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/add-start.ts"],"names":[],"mappings":"AAKA,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,QAMlD;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAClE,QAAQ,EAAE,GAAG,CAAA;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,GAAG,EACb,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAsBlC"}

package/dist-types/things-scene/api/align.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/align.ts"],"names":[],"mappings":"AA4GA,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAYpD"}
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/align.ts"],"names":[],"mappings":"AA2JA,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAYpD"}

package/dist-types/things-scene/api/distribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"distribute.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/distribute.ts"],"names":[],"mappings":"AAsDA,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAYzD"}
+{"version":3,"file":"distribute.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/distribute.ts"],"names":[],"mappings":"AAqFA,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAYzD"}

package/dist-types/things-scene/api/ids.d.ts

@@ -1,2 +1,5 @@
-export declare function getIds(this: any): any[];
+export declare function getIds(this: any): {
+    key: any;
+    value: any;
+}[];
 //# sourceMappingURL=ids.d.ts.map

package/dist-types/things-scene/api/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/ids.ts"],"names":[],"mappings":"AAKA,wBAAgB,MAAM,CAAC,IAAI,EAAE,GAAG,SAgB/B"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/ids.ts"],"names":[],"mappings":"AAKA,wBAAgB,MAAM,CAAC,IAAI,EAAE,GAAG;;;IAoB/B"}

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

@@ -13,6 +13,6 @@ export { symmetryX, symmetryY } from './symmetry.js';
 export { change, undoableChange } from './change.js';
 export { getIds } from './ids.js';
 export { default as place } from './place.js';
-export { startAddMode } from './add-start.js';
+export { startAddMode, startBulkCreateMode, type BulkCreateResult } from './add-start.js';
 export { startStylePasteMode, stopStylePasteMode, startDatabindPasteMode, stopDatabindPasteMode } from './paste-start.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,kBAAkB,CAAA"}

package/dist-types/things-scene/api/place.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/place.ts"],"names":[],"mappings":"AAkFA,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAapD"}
+{"version":3,"file":"place.d.ts","sourceRoot":"","sources":["../../../src/things-scene/api/place.ts"],"names":[],"mappings":"AAkFA,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAcpD"}

package/dist-types/things-scene/application-context.d.ts

@@ -1,9 +1,19 @@
+import { DataLagTracker } from '../diagnostics/data-lag-tracker.js';
+import type { LagMonitorConfig } from '../diagnostics/data-lag-tracker.js';
+import { LoadTracker } from '../diagnostics/load-tracker.js';
+import type { LoadingOptions } from '../diagnostics/load-tracker.js';
 export default class ApplicationContext {
     _mode: number;
     _screen: number;
     _baseUrl: string | null;
     _refProvider: unknown;
     _postprocessing: boolean;
+    /**
+     * Z-fighting 완화용 로그 depth buffer 강제. undefined = "auto" (포스트프로세싱 +
+     * 환경 프리셋 추천에 따라 자동 결정). true/false = 명시 override.
+     * **Renderer 생성 시점에만 적용** — 런타임 변경은 renderer 재생성 필요.
+     */
+    _logarithmicDepth?: boolean;
     _rotateStep: number;
     _rotateStepForced: boolean;
     _dataSubscriptionProvider: {
@@ -14,8 +24,21 @@ export default class ApplicationContext {
     _PPI: number;
     _PPM: number;
     _commander: unknown;
+    _loadTracker?: LoadTracker;
+    _loadTrackerOwned: boolean;
+    _lagTracker?: DataLagTracker;
+    /** 영구 플래그 (런타임 setter로 조작) */
+    _suppressAnimationsFlag: boolean;
+    /** 스코프드 API 의 중첩 호출용 ref count */
+    _suppressScopeCount: number;
     trigger: (event: string, ...args: unknown[]) => void;
     constructor(mode: number, refProvider: unknown);
+    initLoadTracker(options?: LoadingOptions): LoadTracker;
+    get loadTracker(): LoadTracker | undefined;
+    /** 앱에서 미리 생성한 LoadTracker를 받아서 사용 (dispose 책임은 앱에 있음) */
+    adoptLoadTracker(tracker: LoadTracker): void;
+    initLagTracker(config: LagMonitorConfig | LagMonitorConfig[]): DataLagTracker;
+    get lagTracker(): DataLagTracker | undefined;
     dispose(): void;
     _calcScreen(): void;
     subscribe(tag: string, component: unknown): unknown;
@@ -50,5 +73,31 @@ export default class ApplicationContext {
     set dataStorage(dataStorage: unknown);
     get postprocessing(): boolean;
     set postprocessing(value: boolean);
+    /** 로그 depth buffer 강제 (z-fighting 완화). undefined = auto. */
+    get logarithmicDepth(): boolean | undefined;
+    set logarithmicDepth(value: boolean | undefined);
+    /**
+     * 애니메이션 억제 상태 (영구 플래그 OR 활성 스코프 중 하나라도 해당되면 true).
+     *
+     * 확인 지점: Animation.start, animate(), ValueHolder.animOnValueChange,
+     * DecoratorRegistry.addToOverlay, AnimatedIconDecorator.start
+     */
+    get suppressAnimations(): boolean;
+    /** 런타임에 영구 플래그 토글. 스코프드 카운트와 OR 로 병합됨. */
+    set suppressAnimations(value: boolean);
+    /**
+     * 주어진 콜백을 애니메이션 억제 상태에서 실행.
+     *  - 중첩 호출 안전 (ref-count)
+     *  - sync/async 자동 판별 — Promise 리턴 시 완료될 때까지 억제 유지
+     *  - 예외 발생 시에도 카운터 정상 복구
+     */
+    withSuppressedAnimations<T>(fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * 수동 제어용 disposable. `end()` 를 반드시 호출해야 함.
+     * 스코프가 콜백 경계를 넘어서는 경우 (이벤트 핸들러 사이 등) 사용.
+     */
+    beginSuppressAnimations(): {
+        end(): void;
+    };
 }
 //# sourceMappingURL=application-context.d.ts.map

package/dist-types/things-scene/application-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application-context.d.ts","sourceRoot":"","sources":["../../src/things-scene/application-context.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAG,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,YAAY,EAAE,OAAO,CAAA;IACrB,eAAe,EAAE,OAAO,CAAO;IAC/B,WAAW,EAAG,MAAM,CAAA;IACpB,iBAAiB,EAAG,OAAO,CAAA;IAC3B,yBAAyB,EAAE;QAAE,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,IAAI,IAAI,CAAA;KAAE,GAAG,SAAS,CAAA;IACjH,YAAY,EAAE,OAAO,CAAA;IACrB,IAAI,EAAG,MAAM,CAAA;IACb,IAAI,EAAG,MAAM,CAAA;IACb,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;gBAEzC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO;IAY9C,OAAO;IAKP,WAAW;IAUX,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;IAIzC,IAAI,WAAW,YAEd;IAED,IAAI,wBAAwB,CAAC,wBAAwB;wBA1CR,MAAM,aAAa,OAAO,GAAG,OAAO;oBAAc,IAAI;iBA0C9C,EAEpD;IAED,IAAI,wBAAwB;wBA9CiB,MAAM,aAAa,OAAO,GAAG,OAAO;oBAAc,IAAI;kBAgDlG;IAED,IAAI,SAAS,CAAC,SAAS,SAAA,EAEtB;IAED,IAAI,SAAS,YAEZ;IAED,IAAI,MAAM,WAET;IAED,IAAI,MAAM,CAAC,MAAM,QAAA,EAGhB;IAED,IAAI,IAAI,WAEP;IAED,IAAI,GAAG,WAEN;IAED,IAAI,GAAG,WAEN;IAED,IAAI,IAAI,WAEP;IAED,IAAI,IAAI,CAAC,IAAI,QAAA,EAMZ;IAED,IAAI,UAAU,YAEb;IAED,IAAI,UAAU,YAEb;IAED,IAAI,OAAO,kBAEV;IAED,IAAI,OAAO,CAAC,OAAO,eAAA,EASlB;IAED,GAAG,CAAC,CAAC,EAAE,MAAM;IAiBb,IAAI,UAAU,WAEb;IAED,IAAI,UAAU,CAAC,IAAI,QAAA,EAElB;IAOD,IAAI,gBAAgB,YAEnB;IAED,IAAI,gBAAgB,CAAC,KAAK,SAAA,EAEzB;IAGD,IAAI,WAAW,YAEd;IAED,IAAI,WAAW,CAAC,WAAW,SAAA,EAE1B;IAED,IAAI,cAAc,IAIQ,OAAO,CAFhC;IAED,IAAI,cAAc,CAAC,KAAK,EAAE,OAAO,EAEhC;CACF"}
+{"version":3,"file":"application-context.d.ts","sourceRoot":"","sources":["../../src/things-scene/application-context.ts"],"names":[],"mappings":"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"}

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

@@ -1,20 +1,60 @@
 import type { SceneMode } from '../const.js';
 import type { FITMODE } from '../interfaces/types.js';
 import type { ReferenceProvider, DataSubscriptionProvider, PersistentDataStorage } from '../interfaces/providers.js';
+import type { LoadingOptions } from '../diagnostics/load-tracker.js';
+import type { Model } from '../interfaces/model.js';
 import Scene from './scene.js';
+/**
+ * Options for creating a Scene instance.
+ *
+ * @example
+ * ```ts
+ * const scene = create({
+ *   target: document.getElementById('board'),
+ *   model: boardModel,
+ *   mode: SCENE_MODE.VIEW,
+ *   handlers: ['zoom-handler', 'shift-handler'],
+ *   refProvider: myProvider
+ * })
+ * ```
+ */
 export interface SceneCreateOptions {
+    /** DOM element (or element ID) where the scene will be rendered */
     target?: HTMLElement | string;
-    model?: any;
+    /** Board model — component tree as a JSON-compatible object */
+    model?: Model;
+    /** Theme style map (name → value) applied to the scene */
     style?: Record<string, any>;
-    layers?: any[];
+    /** Additional layer configurations (e.g. scroll-layer, movement-layer) */
+    layers?: {
+        type: string;
+        id?: string;
+        [key: string]: any;
+    }[];
+    /** Event handler names to attach (e.g. 'zoom-handler', 'shift-handler') */
     handlers?: string[];
+    /** Scene mode: MODE_VIEW (0) for monitoring, MODE_EDIT (1) for modelling */
     mode?: SceneMode;
+    /** Reference provider for sub-board linking */
     refProvider?: ReferenceProvider;
+    /** Real-time data subscription provider (e.g. GraphQL subscription) */
     dataSubscriptionProvider?: DataSubscriptionProvider;
+    /** Per-component persistent data storage (e.g. IndexedDB) */
     dataStorage?: PersistentDataStorage;
+    /** Base URL for resources (images, GLTF models, etc.) */
     baseUrl?: string;
+    /** Initial fit mode: 'ratio' | 'both' | 'width' | 'height' | 'none' */
     fitMode?: FITMODE;
+    /** Enable 3D post-processing effects (OutlinePass, SMAAPass). Default: true */
     postprocessing?: boolean;
+    /**
+     * 로그 depth buffer 강제 (겹친 면 z-fighting 완화). 미지정 시 환경 프리셋 추천
+     * (실내 = true, 실외 = false) 또는 postprocessing 기본값을 따름. Renderer 생성
+     * 시점에만 적용 — 런타임 변경 불가 (재생성 필요).
+     */
+    logarithmicDepth?: boolean;
+    /** Loading monitor options */
+    loading?: LoadingOptions;
 }
-export default function create({ target, model, style, layers, handlers, mode, refProvider, dataSubscriptionProvider, dataStorage, baseUrl, fitMode, postprocessing }: SceneCreateOptions): Scene;
+export default function create({ target, model, style, layers, handlers, mode, refProvider, dataSubscriptionProvider, dataStorage, baseUrl, fitMode, postprocessing, logarithmicDepth, loading: loadingOptions }: SceneCreateOptions): Scene;
 //# sourceMappingURL=create.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/things-scene/create.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAEpH,OAAO,KAAK,MAAM,YAAY,CAAA;AAE9B,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC7B,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,MAAM,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAUD,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAW,EACX,QAAa,EACb,IAAsB,EACtB,WAAW,EACX,wBAAwB,EACxB,WAAkC,EAClC,OAAO,EACP,OAAO,EACP,cAAqB,EACtB,EAAE,kBAAkB,SAyCpB"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/things-scene/create.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AACpH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,OAAO,KAAK,MAAM,YAAY,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC7B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,0EAA0E;IAC1E,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,EAAE,CAAA;IAC5D,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,uEAAuE;IACvE,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD,6DAA6D;IAC7D,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,8BAA8B;IAC9B,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAUD,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAW,EACX,QAAa,EACb,IAAsB,EACtB,WAAW,EACX,wBAAwB,EACxB,WAAkC,EAClC,OAAO,EACP,OAAO,EACP,cAAqB,EACrB,gBAAgB,EAChB,OAAO,EAAE,cAAc,EACxB,EAAE,kBAAkB,SAkDpB"}