@hatiolab/things-scene 10.0.0-beta.9 → 10.0.0-beta.90

package/dist-types/threed/ratio-lock-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 3축의 변화율 중 가장 큰 것을 기준으로 균일 비율을 반환한다.
+ * 모든 변화가 threshold 미만이면 null 반환 (변경 없음).
+ *
+ * @param ratios - [x, y, z] 각 축의 변화 비율 (1.0 = 변화 없음)
+ * @returns 균일 비율 또는 null
+ */
+export declare function getUniformRatio(ratios: [number, number, number]): number | null;
+//# sourceMappingURL=ratio-lock-utils.d.ts.map

package/dist-types/threed/ratio-lock-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratio-lock-utils.d.ts","sourceRoot":"","sources":["../../src/threed/ratio-lock-utils.ts"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAW/E"}

package/dist-types/threed/real-object-dom-element.d.ts

@@ -3,6 +3,7 @@ import { RealObject } from './real-object.js';
 export declare class RealObjectDomElement extends RealObject<CSS3DObject> {
     /** 평면 오브젝트: 바닥 위로 올려 z-fighting 방지 */
     protected get syncZPosOffset(): number;
+    get geometricOffsetY(): number;
     protected getObject3dInstance(): CSS3DObject;
     /**
      * CSS3DObject는 geometry가 없으므로 Euler rotation으로 바닥에 눕힘.

package/dist-types/threed/real-object-dom-element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-dom-element.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-dom-element.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAA;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,qBAAa,oBAAqB,SAAQ,UAAU,CAAC,WAAW,CAAC;IAC/D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,SAAS,CAAC,mBAAmB;IAI7B;;;OAGG;IACH,IAAI,QAAQ;;;;MAQX;IAED;;OAEG;IACH,gBAAgB;IAiChB,KAAK;IAeL,eAAe;IAWf,WAAW;CAUZ"}
+{"version":3,"file":"real-object-dom-element.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-dom-element.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAA;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,qBAAa,oBAAqB,SAAQ,UAAU,CAAC,WAAW,CAAC;IAC/D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,IAAa,gBAAgB,WAE5B;IAED,SAAS,CAAC,mBAAmB;IAI7B;;;OAGG;IACH,IAAI,QAAQ;;;;MAQX;IAED;;OAEG;IACH,gBAAgB;IAqChB,KAAK;IAsBL,eAAe;IAsBf,WAAW;CAUZ"}

package/dist-types/threed/real-object-dom-texture.d.ts

@@ -3,7 +3,10 @@ import { RealObject } from './real-object.js';
 export declare class RealObjectDomTexture extends RealObject<THREE.Mesh> {
     /** 평면 오브젝트: 바닥 위로 올려 z-fighting 방지 */
     protected get syncZPosOffset(): number;
+    get geometricOffsetY(): number;
     private _debounceTimer?;
+    private _origInvalidate?;
+    constructor(component: any);
     protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
     build(): void;
     updateDimension(): void;
@@ -11,9 +14,15 @@ export declare class RealObjectDomTexture extends RealObject<THREE.Mesh> {
     updateHidden(): void;
     private _debouncedRebuild;
     private _rebuildTexture;
+    /**
+     * 기존 캔버스/텍스처를 유지한 채 그림만 다시 그린다. 애니메이션 프레임용 경량 경로.
+     * 캔버스는 세팅된 상태에서만 호출되므로 canvas/texture가 아직 없으면 no-op.
+     */
+    private _refreshTextureNow;
     updateFillStyle(): void;
     updateStrokeStyle(): void;
     updateText(): void;
+    onchange(after: Record<string, any>, before: Record<string, any>): void;
     updateMaterial3d(): void;
     clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
     dispose(): void;

package/dist-types/threed/real-object-dom-texture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-dom-texture.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-dom-texture.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAO7C,qBAAa,oBAAqB,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IAC9D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,OAAO,CAAC,cAAc,CAAC,CAA+B;IAEtD,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IA4BL,eAAe;IAOf,WAAW;IAKX,YAAY;IAIZ,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,eAAe;IAQvB,eAAe;IAIf,iBAAiB;IAIjB,UAAU;IAIV,gBAAgB;IAahB,KAAK;IASL,OAAO;CAOR"}
+{"version":3,"file":"real-object-dom-texture.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-dom-texture.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAe7C,qBAAa,oBAAqB,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IAC9D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,IAAa,gBAAgB,WAE5B;IAED,OAAO,CAAC,cAAc,CAAC,CAA+B;IACtD,OAAO,CAAC,eAAe,CAAC,CAAY;gBAExB,SAAS,EAAE,GAAG;IAiB1B,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IA4BL,eAAe;IAMf,WAAW;IAKX,YAAY;IAIZ,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAW1B,eAAe;IAIf,iBAAiB;IAIjB,UAAU;IAIV,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAYhE,gBAAgB;IAahB,KAAK;IASL,OAAO;CAWR"}

package/dist-types/threed/real-object-external-model.d.ts

@@ -0,0 +1,24 @@
+import * as THREE from 'three';
+import { RealObject } from './real-object.js';
+export declare abstract class RealObjectExternalModel<TData = unknown> extends RealObject {
+    /**
+     * 로드 세대 카운터. build() 호출마다 증가한다.
+     * 비동기 load 콜백은 gen 비교로 stale 여부를 판단해야 한다.
+     */
+    protected _loadGen: number;
+    /** 모델 subtree의 직접 부모. clear() 시 통째로 disposeObject3D된다. */
+    protected pivot?: THREE.Object3D;
+    protected _objectSize?: THREE.Vector3;
+    get objectSize(): THREE.Vector3 | undefined;
+    build(): void;
+    updateSource(): void;
+    protected abstract _loadExternal(url: string): Promise<TData>;
+    protected abstract _onLoaded(data: TData): void;
+    protected abstract get _formatLabel(): string;
+    /** 빈 상태 placeholder의 색상. 포맷별로 식별 색 override 가능. */
+    protected get _placeholderColor(): number;
+    protected _showEmptyPlaceholder(): void;
+    protected _showErrorPlaceholder(): void;
+    clear(): THREE.Object3D<THREE.Object3DEventMap>;
+}
+//# sourceMappingURL=real-object-external-model.d.ts.map

package/dist-types/threed/real-object-external-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-object-external-model.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-external-model.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8BAAsB,uBAAuB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,UAAU;IAC/E;;;OAGG;IACH,SAAS,CAAC,QAAQ,SAAI;IAEtB,0DAA0D;IAC1D,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAA;IAEhC,SAAS,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,OAAO,CAAsB;IAE3D,IAAI,UAAU,IAAI,KAAK,CAAC,OAAO,GAAG,SAAS,CAE1C;IAED,KAAK;IAqCL,YAAY;IAMZ,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7D,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAC/C,SAAS,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAA;IAI7C,mDAAmD;IACnD,SAAS,KAAK,iBAAiB,IAAI,MAAM,CAExC;IAED,SAAS,CAAC,qBAAqB;IA8B/B,SAAS,CAAC,qBAAqB;IAa/B,KAAK;CASN"}

package/dist-types/threed/real-object-extrude.d.ts

@@ -27,6 +27,12 @@ export declare class RealObjectExtrude extends RealObject {
     updateAlpha(): void;
     updateStrokeStyle(): void;
     updateFillStyle(): void;
+    updateText(): void;
+    /**
+     * cap 면(앞/뒤)에 fillStyle + 텍스트를 합성한 텍스처를 적용한다.
+     * 텍스트가 없으면 fillStyle만 적용한다.
+     */
+    private _applyCapTexture;
     updateDimension(): void;
 }
 //# sourceMappingURL=real-object-extrude.d.ts.map

package/dist-types/threed/real-object-extrude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-extrude.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-extrude.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAMhE;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,iBAAiB,CAAC,EAAE,gBAAgB,CAAA;IACpC,OAAO,CAAC,KAAK,CAAC,CAAY;IAE1B,KAAK;IAKL,IAAI,KAAK,IAAI,GAAG,CAEf;IAED,IAAI,gBAAgB,qBAInB;IAED,KAAK;IAoCL,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc;IAoBxD,eAAe,IAAI,KAAK,CAAC,QAAQ,EAAE;IAuBnC,aAAa;IAoCb,OAAO,CAAC,YAAY;IAMpB,gBAAgB;IAqBhB,WAAW;IAUX,iBAAiB;IAQjB,eAAe;IAiBf,eAAe;CAKhB"}
+{"version":3,"file":"real-object-extrude.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-extrude.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAOhE;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,iBAAiB,CAAC,EAAE,gBAAgB,CAAA;IACpC,OAAO,CAAC,KAAK,CAAC,CAAY;IAE1B,KAAK;IAKL,IAAI,KAAK,IAAI,GAAG,CAEf;IAED,IAAI,gBAAgB,qBAInB;IAED,KAAK;IAoCL,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc;IAoBxD,eAAe,IAAI,KAAK,CAAC,QAAQ,EAAE;IAcnC,aAAa;IAqBb,OAAO,CAAC,YAAY;IAMpB,gBAAgB;IAYhB,WAAW;IAUX,iBAAiB;IAQjB,eAAe;IAIf,UAAU;IAIV;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+DxB,eAAe;CAMhB"}

package/dist-types/threed/real-object-gltf.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
 import type { Properties } from '../interfaces/types.js';
-import { RealObject } from './real-object.js';
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { RealObjectExternalModel } from './real-object-external-model.js';
+import { GLTF, GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 export interface GLTFNodeState {
     color?: string;
     visible?: boolean;
@@ -16,25 +16,41 @@ export interface GLTFAnimationState {
     weight?: number;
     loop?: 'once' | 'repeat' | 'pingpong';
 }
-export declare class RealObjectGLTF extends RealObject {
+export declare class RealObjectGLTF extends RealObjectExternalModel<GLTF> {
+    protected get _formatLabel(): string;
     private static _topViewCache;
+    private static _gltfCache;
     private static _sharedLoader;
+    private static _sharedSnapshotRenderer?;
+    /**
+     * 탑뷰 스냅샷 전용 공유 renderer. 헤드리스 환경 등 미지원 시 undefined 반환.
+     * 컨텍스트 lost 감지 시 정리 후 재생성.
+     */
+    private static getSharedSnapshotRenderer;
     /**
      * DRACO/KTX2/Meshopt/SpecGloss가 모두 설정된 공유 GLTFLoader를 반환한다.
      * renderer를 전달하면 KTX2 detectSupport를 갱신한다.
      * 2D 스냅샷 등 renderer 없이도 호출 가능하다.
      */
     static getSharedLoader(renderer?: THREE.WebGLRenderer): GLTFLoader;
-    private pivot?;
-    private objectSize?;
+    /**
+     * URL로 GLTF를 로드한다. 동일 URL은 캐시하여 1회만 파싱한다.
+     * 로드 실패 시 캐시에서 제거하여 재시도 가능.
+     */
+    static loadGLTF(url: string, renderer?: THREE.WebGLRenderer): Promise<GLTF>;
     private _nodeIndex;
     private _originals;
-    private _animationActions;
+    _animationActions: Map<string, THREE.AnimationAction>;
     private _fillStyleOriginals;
-    private _loadGen;
-    build(): void;
-    private gltfLoaded;
-    private _renderTopViewSnapshot;
+    private _clonedMaterials;
+    /**
+     * mesh의 material이 아직 복제되지 않았으면 복제하여 독립 인스턴스로 만든다.
+     * GLTF 캐시로 인해 동일 소스의 오브젝트들이 material을 공유하므로,
+     * material을 변경하기 전에 반드시 호출해야 한다.
+     */
+    private _ensureOwnMaterial;
+    protected _loadExternal(url: string): Promise<GLTF>;
+    protected _onLoaded(gltf: GLTF): void;
     /**
      * 오프스크린 렌더러로 Object3D의 탑뷰(Y축 위→아래) 스냅샷을 생성한다.
      * GLTFObject에서 2D 모드 독립 로딩 시에도 사용한다.
@@ -44,6 +60,16 @@ export declare class RealObjectGLTF extends RealObject {
     static getTopViewCache(source: string): HTMLCanvasElement | undefined;
     /** 캐시에 스냅샷을 저장한다 */
     static setTopViewCache(source: string, canvas: HTMLCanvasElement): void;
+    /**
+     * GLTF 파싱 캐시와 탑뷰 스냅샷 캐시를 모두 비운다.
+     * Scene(보드) 전환 시 호출하여 메모리를 회수한다.
+     * clone()은 geometry/texture를 공유 참조하므로,
+     * 모든 컴포넌트가 dispose된 후에만 호출해야 한다.
+     *
+     * 공유 snapshot renderer 도 함께 dispose — 보드 전환 시 GPU 메모리 회수.
+     * 다음 보드에서 GLB 컴포넌트가 ready 되면 lazy 하게 재생성된다.
+     */
+    static flushCache(): void;
     private _buildNodeIndex;
     getNode(name: string): THREE.Object3D | undefined;
     get nodeNames(): string[];
@@ -57,14 +83,18 @@ export declare class RealObjectGLTF extends RealObject {
      */
     private _resetAllNodes;
     private _setupAnimations;
+    /**
+     * playTargets에 따라 해당 애니메이션만 재생.
+     * '*' → 전체, undefined/'none'/[] → 없음, [...] → 선택된 것만
+     * (fillStyleTargets와 동일한 규칙)
+     */
+    _playTargetAnimations(): void;
     private _applyAnimationStates;
     get animationNames(): string[];
-    private _showErrorPlaceholder;
     updateFillStyle(): void;
     private _restoreFillStyleTargets;
     clear(): THREE.Object3D<THREE.Object3DEventMap>;
     updateDimension(): void;
-    updateSource(): void;
     onchange(after: Properties, before: Properties): void;
 }
 //# sourceMappingURL=real-object-gltf.d.ts.map

package/dist-types/threed/real-object-gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-gltf.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-gltf.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,OAAO,EAAQ,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAO3E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;CACtC;AAQD,qBAAa,cAAe,SAAQ,UAAU;IAE5C,OAAO,CAAC,MAAM,CAAC,aAAa,CAAuC;IAGnE,OAAO,CAAC,MAAM,CAAC,aAAa,CAA0B;IAEtD;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,UAAU;IA2BlE,OAAO,CAAC,KAAK,CAAC,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAqC;IAGxD,OAAO,CAAC,UAAU,CAAoC;IAGtD,OAAO,CAAC,UAAU,CASd;IAGJ,OAAO,CAAC,iBAAiB,CAA2C;IAGpE,OAAO,CAAC,mBAAmB,CAKvB;IAGJ,OAAO,CAAC,QAAQ,CAAI;IAEpB,KAAK;IAiCL,OAAO,CAAC,UAAU;IAmElB,OAAO,CAAC,sBAAsB;IAO9B;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,iBAAiB;IAwD/D,qBAAqB;IACrB,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIrE,oBAAoB;IACpB,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB;IAMhE,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IAIjD,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAID,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAoBlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,qBAAqB;IA8B7B,IAAI,cAAc,IAAI,MAAM,EAAE,CAE7B;IAED,OAAO,CAAC,qBAAqB;IAU7B,eAAe;IA2Cf,OAAO,CAAC,wBAAwB;IA2BhC,KAAK;IAiBL,eAAe;IAUf,YAAY;IAIZ,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU;CA0C/C"}
+{"version":3,"file":"real-object-gltf.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-gltf.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAGxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AAEzE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAoC3E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;CACtC;AAQD,qBAAa,cAAe,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IAC/D,SAAS,KAAK,YAAY,WAAoB;IAE9C,OAAO,CAAC,MAAM,CAAC,aAAa,CAAuC;IAGnE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAmC;IAG5D,OAAO,CAAC,MAAM,CAAC,aAAa,CAA0B;IAMtD,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAqB;IAE5D;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAyBxC;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,UAAU;IA2BlE;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3E,OAAO,CAAC,UAAU,CAAoC;IAGtD,OAAO,CAAC,UAAU,CASd;IAGJ,iBAAiB,qCAA2C;IAG5D,OAAO,CAAC,mBAAmB,CAKvB;IAIJ,OAAO,CAAC,gBAAgB,CAAgC;IAExD;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAU1B,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI;IAiH9B;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,iBAAiB;IAwE/D,qBAAqB;IACrB,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIrE,oBAAoB;IACpB,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB;IAIhE;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU;IAajB,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IAIjD,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAID,OAAO,CAAC,gBAAgB;IA0CxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAoBlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,gBAAgB;IAqBxB;;;;OAIG;IACH,qBAAqB;IAarB,OAAO,CAAC,qBAAqB;IA8B7B,IAAI,cAAc,IAAI,MAAM,EAAE,CAE7B;IAID,eAAe;IA2Df,OAAO,CAAC,wBAAwB;IA2BhC,KAAK;IAWL,eAAe;IAUf,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU;CA8C/C"}

package/dist-types/threed/real-object-group.d.ts

@@ -2,5 +2,7 @@ import * as THREE from 'three';
 import { RealObject } from './real-object.js';
 export declare class RealObjectGroup extends RealObject<THREE.Group> {
     protected getObject3dInstance(): THREE.Group<THREE.Object3DEventMap>;
+    /** Group은 translate만 허용 (rotate/scale은 ungroup 시 정확한 분해가 어려움) */
+    get allowedGizmoModes(): string[] | null;
 }
 //# sourceMappingURL=real-object-group.d.ts.map

package/dist-types/threed/real-object-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-group.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-group.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,qBAAa,eAAgB,SAAQ,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1D,SAAS,CAAC,mBAAmB;CAG9B"}
+{"version":3,"file":"real-object-group.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-group.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,qBAAa,eAAgB,SAAQ,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1D,SAAS,CAAC,mBAAmB;IAI7B,iEAAiE;IACjE,IAAI,iBAAiB,IAAI,MAAM,EAAE,GAAG,IAAI,CAEvC;CACF"}

package/dist-types/threed/real-object-line.d.ts

@@ -0,0 +1,83 @@
+import * as THREE from 'three';
+import { Line2 } from 'three/examples/jsm/lines/Line2.js';
+import { RealObject } from './real-object.js';
+import type { Properties } from '../interfaces/types.js';
+/**
+ * 선형 컴포넌트(line, polyline, path 등)를 3D에서 Line2(fat line)로 렌더링하는 베이스 클래스.
+ *
+ * RealObjectMesh, RealObjectExtrude와 동급의 추상 클래스.
+ * 서브클래스는 worldPath를 구현하여 컴포넌트별 좌표 변환 로직을 제공한다.
+ */
+export declare abstract class RealObjectLine extends RealObject<THREE.Group> {
+    protected _line2?: Line2;
+    /** 서브클래스가 오버라이드: 컴포넌트 path → 3D 로컬 좌표 배열 반환 */
+    abstract get worldPath(): THREE.Vector3[];
+    protected getObject3dInstance(): THREE.Group<THREE.Object3DEventMap>;
+    /** 선형 컴포넌트도 기즈모 변환 가능 — 결과를 path 좌표에 베이킹 */
+    get gizmoTransformable(): boolean;
+    /** 선형 컴포넌트는 볼륨이 없으므로 바닥면에 위치 */
+    protected get syncZPosOffset(): number;
+    /** Line의 object3d origin은 볼륨 바닥(실제로 볼륨 없음) */
+    get geometricOffsetY(): number;
+    /**
+     * 기즈모 드래그 중에는 컴포넌트 상태를 변경하지 않는다.
+     * object3d가 움직이면서 Line2가 함께 이동하므로 시각적으로는 정상.
+     * 드래그 종료 시 onGizmoDragEnd에서 일괄 베이킹한다.
+     */
+    syncFromObject3D(): void;
+    /**
+     * scale 기즈모 드래그 중에도 dimension 변경을 방지한다.
+     */
+    applyDimensionFromGizmo(_props: Record<string, number>): void;
+    build(): void;
+    /**
+     * round 속성을 적용하여 worldPath를 보간한 최종 positions을 반환한다.
+     */
+    protected get smoothedPath(): THREE.Vector3[];
+    protected _buildLine(): void;
+    /**
+     * 팁 오브젝트를 위치/회전/색상 설정하여 object3d에 추가한다.
+     */
+    private _placeTip;
+    private _getResolution;
+    /**
+     * 기즈모 드래그 종료 시 호출.
+     * object3d의 현재 transform(translate/rotate/scale)을
+     * path vertex 좌표에 베이킹하고, object3d transform을 리셋한다.
+     *
+     * 핵심: line/path 컴포넌트는 position/rotation/scale 속성을 갖지 않는다.
+     * 오직 vertex 좌표만으로 형태를 결정한다.
+     */
+    onGizmoDragEnd(_mode: string): void;
+    /**
+     * object3d의 transform matrix를 path vertex에 적용한 새 parent 좌표를 계산한다.
+     * 순수 함수로 추출하여 단위 테스트 가능.
+     *
+     * @param path - 컴포넌트 path (local coords, rotation=0이므로 parent coords와 동일)
+     * @param center - component.center (parent coords)
+     * @param parentSize - 부모 컨테이너의 bounds { width, height }
+     * @param object3d - 기즈모에 의해 변환된 Object3D
+     * @returns 새 path (parent coords)
+     */
+    static computeBakedPath(path: Array<{
+        x: number;
+        y: number;
+        z?: number;
+    }>, center: {
+        x: number;
+        y: number;
+    }, parentSize: {
+        width: number;
+        height: number;
+    }, object3d: THREE.Object3D): Array<{
+        x: number;
+        y: number;
+        z?: number;
+    }>;
+    updateStrokeStyle(): void;
+    updateAlpha(): void;
+    updateDimension(): void;
+    onchange(after: Properties, before: Properties): void;
+    clear(): THREE.Group<THREE.Object3DEventMap>;
+}
+//# sourceMappingURL=real-object-line.d.ts.map

package/dist-types/threed/real-object-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-object-line.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-line.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAKzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAyDxD;;;;;GAKG;AACH,8BAAsB,cAAe,SAAQ,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;IAClE,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,CAAA;IAExB,+CAA+C;IAC/C,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,CAAA;IAEzC,SAAS,CAAC,mBAAmB;IAI7B,4CAA4C;IAC5C,IAAa,kBAAkB,IAAI,OAAO,CAEzC;IAED,gCAAgC;IAChC,SAAS,KAAK,cAAc,IAAI,MAAM,CAErC;IAED,8CAA8C;IAC9C,IAAa,gBAAgB,IAAI,MAAM,CAEtC;IAED;;;;OAIG;IACM,gBAAgB,IAAI,IAAI;IAIjC;;OAEG;IACM,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAItE,KAAK;IAKL;;OAEG;IACH,SAAS,KAAK,YAAY,IAAI,KAAK,CAAC,OAAO,EAAE,CAqD5C;IAED,SAAS,CAAC,UAAU;IA0FpB;;OAEG;IACH,OAAO,CAAC,SAAS;IAwCjB,OAAO,CAAC,cAAc;IAStB;;;;;;;OAOG;IACM,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAuC5C;;;;;;;;;OASG;IACH,MAAM,CAAC,gBAAgB,CACrB,IAAI,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EACjD,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAChC,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC7C,QAAQ,EAAE,KAAK,CAAC,QAAQ,GACvB,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiC9C,iBAAiB;IAKjB,WAAW;IAIX,eAAe;IAKf,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU;IAgB9C,KAAK;CAYN"}

package/dist-types/threed/real-object-mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-mesh.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-mesh.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8BAAsB,cAAe,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IACjE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IASL,WAAW;IAMX,YAAY;IAIZ,eAAe;IAsBf,iBAAiB;IAuBjB,eAAe,IAAI,IAAI;IAqBvB,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,IAAI;IAExC,aAAa,IAAI,IAAI;IAerB,gBAAgB;IAiBhB,KAAK;CAKN"}
+{"version":3,"file":"real-object-mesh.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-mesh.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8BAAsB,cAAe,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IACjE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IASL,WAAW;IAMX,YAAY;IAIZ,eAAe;IAsBf,iBAAiB;IAuBjB,eAAe,IAAI,IAAI;IAqBvB,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,IAAI;IAExC,aAAa,IAAI,IAAI;IAOrB,gBAAgB;IAShB,KAAK;CAKN"}

package/dist-types/threed/real-object-plane-2d.d.ts

@@ -3,16 +3,39 @@ import { RealObject } from './real-object.js';
 export declare class RealObjectPlane2D extends RealObject<THREE.Mesh> {
     /** 평면 오브젝트: 바닥 위로 올려 z-fighting 방지 */
     protected get syncZPosOffset(): number;
+    /** object3d origin이 볼륨 상단 위치(실제로는 얇은 plane) */
+    get geometricOffsetY(): number;
+    private _debounceTimer?;
+    private _origInvalidate?;
+    constructor(component: any);
     protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
     build(): void;
     updateAlpha(): void;
     updateHidden(): void;
+    get dimension(): {
+        width: number;
+        height: number;
+        depth: number;
+    };
+    get scale(): {
+        x: number;
+        y: any;
+        z: number;
+    };
     updateDimension(): void;
+    private _debouncedRebuild;
+    /**
+     * 기존 캔버스/텍스처를 그대로 두고 그림만 다시 그린다. 애니메이션 프레임용 경량 경로.
+     * 캔버스는 세팅된 상태에서만 호출되므로 canvas/texture가 아직 없으면 no-op.
+     */
+    private _refreshTextureNow;
     update(): void;
+    onchange(after: Record<string, any>, before: Record<string, any>): void;
     updateFillStyle(): void;
     updateStrokeStyle(): void;
     updateText(): void;
     updateMaterial3d(): void;
     clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    dispose(): void;
 }
 //# sourceMappingURL=real-object-plane-2d.d.ts.map

package/dist-types/threed/real-object-plane-2d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-plane-2d.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-plane-2d.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAO7C,qBAAa,iBAAkB,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IA2BL,WAAW;IAKX,YAAY;IAIZ,eAAe;IAOf,MAAM;IAQN,eAAe;IAIf,iBAAiB;IAIjB,UAAU;IAIV,gBAAgB;IAahB,KAAK;CAIN"}
+{"version":3,"file":"real-object-plane-2d.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-plane-2d.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAc7C,qBAAa,iBAAkB,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3D,sCAAsC;IACtC,SAAS,KAAK,cAAc,WAE3B;IAED,+CAA+C;IAC/C,IAAa,gBAAgB,WAE5B;IAED,OAAO,CAAC,cAAc,CAAC,CAA+B;IACtD,OAAO,CAAC,eAAe,CAAC,CAAY;gBAExB,SAAS,EAAE,GAAG;IAkB1B,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IA4BL,WAAW;IAKX,YAAY;IAIZ,IAAI,SAAS;;;;MAGZ;IAED,IAAI,KAAK;;;;MAIR;IAED,eAAe;IAIf,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAW1B,MAAM;IAQN,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAWhE,eAAe;IAIf,iBAAiB;IAIjB,UAAU;IAIV,gBAAgB;IAahB,KAAK;IASL,OAAO;CAWR"}

package/dist-types/threed/real-object-service.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from 'three';
+import { RealObject } from './real-object.js';
+export declare class RealObjectService extends RealObject<THREE.Mesh> {
+    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    build(): void;
+    updateAlpha(): void;
+    updateHidden(): void;
+    updateDimension(): void;
+    updateFillStyle(): void;
+    updateStrokeStyle(): void;
+    updateText(): void;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+}
+//# sourceMappingURL=real-object-service.d.ts.map

package/dist-types/threed/real-object-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-object-service.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-service.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAM7C,qBAAa,iBAAkB,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3D,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IAyBL,WAAW;IAOX,YAAY;IAIZ,eAAe;IAef,eAAe;IACf,iBAAiB;IACjB,UAAU;IAEV,KAAK;CAIN"}

package/dist-types/threed/real-object-sprite.d.ts

@@ -4,7 +4,13 @@ export declare abstract class RealObjectSprite extends RealObject<THREE.Sprite>
     protected getObject3dInstance(): THREE.Sprite<THREE.Object3DEventMap>;
     build(): void;
     abstract buildMaterial(): void;
-    get cz(): any;
+    get cz(): number;
+    /**
+     * Sprite는 2D bounds.height를 3D Y 크기로 사용 (billboard).
+     * object3d는 zPos + height/2(볼륨 중심)에 위치 → geometricOffsetY = height/2.
+     * 이 값이 자식 컴포넌트의 parent offset 보정에 사용된다.
+     */
+    get geometricOffsetY(): number;
     updateAlpha(): void;
     updateHidden(): void;
     updateFillStyle(): void;

package/dist-types/threed/real-object-sprite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-sprite.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-sprite.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,8BAAsB,gBAAiB,SAAQ,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;IACrE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IAML,QAAQ,CAAC,aAAa,IAAI,IAAI;IAI9B,IAAI,EAAE,QAML;IAED,WAAW;IAMX,YAAY;IAIZ,eAAe;CAqBhB"}
+{"version":3,"file":"real-object-sprite.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-sprite.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,8BAAsB,gBAAiB,SAAQ,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;IACrE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IAML,QAAQ,CAAC,aAAa,IAAI,IAAI;IAI9B,IAAI,EAAE,WAWL;IAED;;;;OAIG;IACH,IAAa,gBAAgB,IAAI,MAAM,CAGtC;IAED,WAAW;IAMX,YAAY;IAIZ,eAAe;CAqBhB"}

package/dist-types/threed/real-object-text.d.ts

@@ -5,7 +5,10 @@ import { RealObjectMesh } from './real-object-mesh.js';
 export declare class RealObjectText extends RealObjectMesh {
     /** 평면 오브젝트: 바닥(Y=0.5) 위로 올려 z-fighting 방지 */
     protected get syncZPosOffset(): number;
+    get geometricOffsetY(): number;
     buildGeometry(): void;
+    updateStrokeStyle(): void;
+    updateFillStyle(): void;
     updateDimension(): void;
     updateText(): void;
     updateAlpha(): void;

package/dist-types/threed/real-object-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-text.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-text.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAGtD;;GAEG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,6CAA6C;IAC7C,SAAS,KAAK,cAAc,WAE3B;IAED,aAAa;IAEb,eAAe;IAiBf,UAAU;IA4CV,WAAW;CAOZ"}
+{"version":3,"file":"real-object-text.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-text.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAGtD;;GAEG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,6CAA6C;IAC7C,SAAS,KAAK,cAAc,WAE3B;IAED,IAAa,gBAAgB,WAE5B;IAED,aAAa;IAKb,iBAAiB;IAEjB,eAAe;IAKf,eAAe;IAiBf,UAAU;IAyDV,WAAW;CASZ"}

package/dist-types/threed/real-object.d.ts

@@ -8,28 +8,34 @@ export declare abstract class RealObject<T extends THREE.Object3D = THREE.Object
     protected _focused: boolean;
     protected _focusedAt?: number;
     protected _suppressOnchange: boolean;
+    private _lastText?;
     object3d: T;
     private _onchangeWrapper;
-    static buildFillStyleTexture(component: Component): THREE.CanvasTexture<HTMLCanvasElement> | THREE.Texture<HTMLImageElement> | undefined;
-    private static buildGradientTexture;
+    static buildFillStyleTexture(component: Component, fillStyleOverride?: unknown): THREE.Texture<unknown> | undefined;
     constructor(component: Component);
     update(): void;
     protected getObject3dInstance(): T;
     build(): void;
     updateMaterial3d(): void;
+    private _applyShadow;
+    /** 기즈모(translate/rotate/scale)를 통한 변환이 가능한지 여부. 기본 true. */
+    get gizmoTransformable(): boolean;
+    /** 허용되는 기즈모 모드. null이면 모든 모드 허용. */
+    get allowedGizmoModes(): string[] | null;
     get component(): Component;
     get threeContainer(): ThreeDimensionalContainer | undefined;
     get focused(): boolean;
     set focused(focused: boolean);
     dispose(): void;
     clear(): T;
+    suppressTransform: boolean;
     /**
      * Component의 상태값의 변화를 Object3D에 반영 - translate, rotation, scale
      */
     updateTransform(): void;
     get position(): {
         x: number;
-        y: any;
+        y: number;
         z: number;
     };
     get rotation(): {
@@ -44,11 +50,79 @@ export declare abstract class RealObject<T extends THREE.Object3D = THREE.Object
     };
     get cx(): number;
     get cy(): number;
-    get cz(): any;
+    get cz(): number;
+    /**
+     * 이 컨테이너가 아이템을 받는 표면의 Y (자신의 object3d local space 기준).
+     * 서브클래스에서 오버라이드하면 ContainerCapacity.receive()가 수용된 아이템의
+     * zPos를 0으로 설정하고, cz 계산 시 이 값만큼 자동으로 보정된다.
+     * 결과: 수용된 아이템의 zPos=0 이 "이 표면 위에 놓임"을 의미하게 됨.
+     *
+     * 반환값: object3d local Y에서 표면의 위치. 0 = 표면 없음(기본값).
+     */
+    get receivingSurfaceY(): number;
+    /**
+     * 실제 사용되는 zPos 값. depth의 effectiveDepth와 짝을 이루는 NaN-safe getter.
+     *
+     * Resolution chain:
+     *   1. `state.zPos` — 명시 값 (단, finite number 만 인정 — `0` 도 valid)
+     *   2. `component.effectiveZPos` — Placeable 의 archetype-derived zPos
+     *      (placement + align + parent context 고려)
+     *   3. `0` — 최후 fallback. 바닥에 놓는 의미.
+     *
+     * NaN/Infinity 가 명시적 값으로 들어오면 1단계에서 거부되어 2~3단계로
+     * 흘러간다. property panel 의 빈 input 이 NaN 으로 commit 되어도 이 게터를
+     * 통하면 위치가 무한대로 튀지 않는다.
+     *
+     * Note: depth 와 달리 `0` 은 valid 한 zPos 값(바닥). Number.isFinite 만
+     * 체크하고 양수 검사는 하지 않는다 — 음수 zPos 도 매달린 컴포넌트에서
+     * 정상 사용 사례.
+     */
+    get effectiveZPos(): number;
+    /**
+     * object3d.position과 볼륨 바닥면 사이의 Y 거리. (= syncZPosOffset 중 "기하" 부분)
+     *
+     * scene root의 `state.placement`에 따라 origin 관점이 달라진다:
+     *   - 'floor'(기본): `+depth/2` — zPos는 바닥 높이, 볼륨은 zPos 위로
+     *   - 'space':       `0`        — zPos는 볼륨 중심 Y, 바닥 개념 없음
+     *   - 'inverted':    `-depth/2` — zPos는 천장, 볼륨이 아래로 매달림 (beta)
+     *
+     * 중첩된 3D 자식이 parent의 geometric shift를 상쇄하는 데 사용된다.
+     * syncZPosOffset이 placement(매달림/얹힘 등)와 geometric을 모두 포함하는 경우,
+     * subclass는 이 getter를 override해 geometric 부분만 반환해야 한다.
+     */
+    get geometricOffsetY(): number;
+    /**
+     * scene의 placement 모드. 씬 전체에 일관 적용.
+     * 'floor' | 'space' | 'inverted'. 기본 'floor'.
+     *
+     * 저장 위치: rootModel (= ModelLayer) — property editor가 이곳에 기록.
+     * `component.root`(= RootContainer, 최상위)가 아닌 `component.rootModel`(= 3D 모델의 루트)을 읽어야 한다.
+     */
+    protected get scenePlacement(): 'floor' | 'space' | 'inverted';
+    private _components3D?;
+    /**
+     * 팩토리가 bottom-up 좌표계(y=0이 바닥, +Y 방향으로 쌓음)로 자체 mesh를 추가할 group.
+     * object3d에 `-geometricOffsetY`만큼 미리 shift된 상태로 관리되므로, 팩토리는
+     * center-origin과 bottom-up을 잇는 -d/2 shift를 신경쓸 필요 없음.
+     *
+     * 사용: `this.components3D.add(mesh)` (팩토리는 자신의 mesh 로컬 y를 바닥 기준으로 설정)
+     * 주의: things-scene 기본 컴포넌트 중 `geometry.center()`로 center-local 기하를
+     *       쓰는 것들은 기존처럼 `this.object3d.add(...)`를 계속 사용.
+     *
+     * clear()가 호출되면 자동 재생성됨 (object3d 자식 전체가 clear되므로).
+     */
+    get components3D(): THREE.Group;
     get center(): {
         x: number;
         y: number;
-        z: any;
+        z: number;
+    };
+    freezeDimension(): void;
+    unfreezeDimension(): void;
+    _frozenDimension?: {
+        width: number;
+        height: number;
+        depth: number;
     };
     get dimension(): {
         width: number;
@@ -58,6 +132,18 @@ export declare abstract class RealObject<T extends THREE.Object3D = THREE.Object
     /**
      * 실제 사용되는 depth 값. 서브클래스가 auto-compute depth를 사용하면 오버라이드한다.
      * (예: conveyor의 effectiveDepth = depth || Math.min(width, height) * 1.5)
+     *
+     * Resolution chain (each layer used only if the previous yielded a valid
+     * positive finite number):
+     *   1. `state.depth` — explicit user value
+     *   2. `component.effectiveDepth` — Placeable's resolution (uses the
+     *      class's `static defaultDepth` against current Heights config).
+     *      Undefined if the component isn't Placeable or has no defaultDepth.
+     *   3. `1` — last-resort sentinel that keeps geometry from collapsing.
+     *
+     * NaN explicitly handled in step 1: a property-panel input that produces
+     * NaN (e.g. parseFloat of an empty string) won't poison every downstream
+     * Math.* call. Falls through to the placement default instead.
      */
     get effectiveDepth(): number;
     updatePosition(): void;
@@ -75,20 +161,59 @@ export declare abstract class RealObject<T extends THREE.Object3D = THREE.Object
     updateStrokeStyle(): void;
     updateFillStyle(): void;
     updateText(): void;
+    /**
+     * Raycast opt-out for atmospheric / decoration / environment components.
+     *
+     * Some components (Decal, Backdrop, future Camera/Light volumes) are
+     * physically large but conceptually "container-less wrappers" — they
+     * shouldn't catch clicks on their main geometry because doing so would
+     * block selection of the contents placed within or on top of them.
+     *
+     * Resolution order (each layer overrides the previous):
+     *   1. class.raycastTargetDefault  — sticky default per component class
+     *      (ThreeDOnly mixin sets this to false; normal components leave true)
+     *   2. state.raycastTarget         — per-instance override from the
+     *      component's state. Lets the user opt back in or out.
+     *
+     * When the resolved value is false, every descendant has `raycast` replaced
+     * with a no-op — EXCEPT children marked `userData.alwaysRaycast = true`
+     * (e.g. selection handles created by `createSelectionHandle3D`). That
+     * preserves a small, intentional click target while the bulk of the
+     * geometry stays click-through.
+     */
+    protected _applyRaycastTarget(): void;
     /**
      * 기즈모 드래그 결과를 컴포넌트 상태에 역변환하여 반영한다.
      * Object3D → Component 방향의 동기화.
      */
     /**
      * cz 계산 및 역변환에 사용되는 Y축 오프셋.
-     * 볼륨체(extrude): depth/2 (기하 중심), 평면(plane/text): depth (윗면 위치).
+     * `state.zPos` → `object3d.position.y` 변환 시 더해지는 값.
+     *
+     * scene placement 모드별 zPos 기준점:
+     *   - 'floor'(기본): zPos=볼륨 바닥 → syncZPosOffset=+d/2 (object3d는 볼륨 중심)
+     *   - 'space':      zPos=볼륨 중심 → syncZPosOffset=0    (object3d는 zPos 그대로)
+     *   - 'inverted':   zPos=볼륨 상단 → syncZPosOffset=-d/2 (object3d는 zPos 아래)
+     *
+     * subclass가 고유 origin 컨벤션을 쓰는 경우(Plane/Text/Line/Sprite/MCS) 이 getter를
+     * override하여 placement와 무관한 고정값 반환 가능.
      */
     protected get syncZPosOffset(): number;
+    /**
+     * object3d 중심에서 텍스트 표면(상단)까지의 로컬 Y 오프셋.
+     * 볼륨체(extrude): depth/2, 평면(plane/text): 0.
+     */
+    get textSurfaceYOffset(): number;
     /**
      * 기즈모 드래그 결과를 컴포넌트 상태에 역변환하여 반영한다 (translate/rotate 모드 전용).
      * Object3D → Component 방향의 동기화. scale은 dimension으로 처리하므로 여기서는 제외.
      */
     syncFromObject3D(): void;
+    /**
+     * 기즈모 드래그 종료 시 호출. 서브클래스가 오버라이드하여
+     * 기즈모 결과를 컴포넌트 데이터에 베이킹할 수 있다.
+     */
+    onGizmoDragEnd(_mode: string): void;
     /**
      * scale 기즈모 드래그 결과를 dimension으로 역산하여 컴포넌트에 적용한다.
      * _suppressOnchange로 피드백 루프를 방지한다.