@hatiolab/things-scene 10.0.0-beta.14 → 10.0.0-beta.140

package/dist-types/flow/segment-topology.d.ts

@@ -0,0 +1,225 @@
+import { rectFaceAnchors } from './face-anchors.js';
+export { rectFaceAnchors };
+/** XZ 평면 vector (= scene world 좌표의 X/Z, Y 는 floor-level 무시). */
+export interface Anchor2D {
+    /** scene world position (x = state.left + offset, z = state.top + offset). */
+    worldPos: {
+        x: number;
+        z: number;
+    };
+    /** 진행 방향 단위 vector (carrier 의 속도 vector 와 일치). */
+    direction: {
+        x: number;
+        z: number;
+    };
+    /**
+     * 면(face) 의 절반 길이 — anchor 가 *면* 에서 유래한 경우. anchorsConnect 가
+     * 접선 방향 판정을 중심 거리 근사가 아닌 *면 segment 겹침* 으로 수행하는 데
+     * 사용. 미지정 (점 anchor) 시 기존 중심 거리 판정 fallback.
+     */
+    halfSpan?: number;
+}
+/** Segment 의 입출구 anchor 들. inbound/outbound 각 1개 이상. */
+export interface SegmentTopology {
+    /** 입구 anchor 들. carrier 가 들어올 수 있는 면. 미구현 segment = 빈 배열. */
+    inbounds: Anchor2D[];
+    /** 출구 anchor 들. carrier 가 나갈 수 있는 면. 미구현 segment = 빈 배열. */
+    outbounds: Anchor2D[];
+}
+/** Anchor 매칭 tolerance (= 자동 연결 판정 기준). */
+export interface MatchTolerance {
+    /** 좌표 distance 임계 (scene unit). default 5. */
+    distance?: number;
+    /** 방향 dot product 임계 (= cosine). 1 = 완전 일치, 0.95 ≈ 18° 이내. default 0.9. */
+    cosine?: number;
+    /** sink(outbound 없는 종착: StockPile/Dock 등) footprint-배달 margin. default 30 —
+     *  딱 안 붙어도 인접하면 자동링크. 흐름연속 후보는 영향 없음(6 고정). */
+    sinkMargin?: number;
+}
+/**
+ * State 기반 *_straight segment_* 의 topology. 가장 흔한 케이스 — Conveyor /
+ * cross-belt-line / induct-station 등. orientation 자동 추정 (horizontal /
+ * vertical / auto by aspect).
+ *
+ * 가정:
+ *   - state.left/top = 좌상단, width/height = 크기
+ *   - rotation = 중심 기준 회전 (radian, CW positive — things-scene 표준)
+ *   - 흐름 방향 = *_긴 축_* (orientation auto 시 width vs height 비교)
+ *   - status='reverse' 시 흐름 반대 (= inbound/outbound swap)
+ *
+ * 결과:
+ *   - inbound  = 시작 짧은 면의 중앙
+ *   - outbound = 끝   짧은 면의 중앙
+ *   - direction = 시작 → 끝 단위 vector
+ */
+export declare function straightSegmentTopology(state: {
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    orientation?: 'horizontal' | 'vertical' | '';
+    status?: string;
+}, reverseOverride?: boolean): SegmentTopology;
+/**
+ * Straight segment 의 *기하 끝점* (start/end) — status/reverse 무관. flow-orientation
+ * 이 흐름 방향을 추론할 때 순환(현재 reverse 가 다음 추론에 영향) 을 피하려 *고정된*
+ * 기하 끝점이 필요. straightSegmentTopology 의 startPos/endPos 와 동일 좌표.
+ * 반환: { start, end } — start→end 가 intrinsic forward (reverse=false 일 때 흐름).
+ */
+export declare function straightSegmentEndpoints(state: {
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    orientation?: 'horizontal' | 'vertical' | '';
+}): {
+    start: {
+        x: number;
+        z: number;
+    };
+    end: {
+        x: number;
+        z: number;
+    };
+} | null;
+/**
+ * Arc (curve) segment topology — cross-belt-curve / conveyor-join 같은 *_도넛
+ * 섹터_* segment. carrier 가 호 위를 따라 시작→끝 각도로 흐름.
+ *
+ * State shape (도넛 섹터):
+ *   - cx, cy: 호 중심 (scene absolute 좌표)
+ *   - rx, ry: 외측 반지름 (x/y 다름 = ellipse 호 가능)
+ *   - ratio (0..100): 내측 반지름 비율 (innerRx = rx * ratio/100)
+ *   - startAngle, endAngle: 시작/끝 각도 (radian, things-scene 컨벤션)
+ *
+ * 호 위 점 공식 (line 348 의 ConveyorJoin.controls 와 일치):
+ *   P(θ) = (cx + r*sin(θ), cy - r*cos(θ))
+ *   tangent (carrier 진행 방향) = (cos(θ), sin(θ))
+ *
+ * Anchor:
+ *   - inbound at startAngle: midR 거리 + 진행 방향 (= θ 증가 방향)
+ *   - outbound at endAngle:  midR 거리 + 진행 방향
+ *   - reverse 시 swap + direction 반전
+ */
+export declare function arcSegmentTopology(state: {
+    cx?: number;
+    cy?: number;
+    rx?: number;
+    ry?: number;
+    ratio?: number;
+    startAngle?: number;
+    endAngle?: number;
+    status?: string;
+}): SegmentTopology;
+/**
+ * Multi-inbound straight segment — 합류 (merger) 의 토대. 흐름축은 그대로 (1
+ * outbound 한 면) 인데, *_나머지 모든 면이 inbound_* (= 어느 옆 conveyor 가
+ * 와도 합류 가능).
+ *
+ *   - outbounds = straightSegmentTopology(state).outbounds (= 1 face)
+ *   - inbounds  = 직교 (흐름축 시작 + 양 perpendicular) + 측면 사선 (45° 전진 편향)
+ *
+ * 사선 anchor — 실물 merger 는 양쪽에서 *사선* 으로 모이는 Y자 합류가 통상.
+ * 측면 (흐름과 perpendicular) inbound 마다 본선 진행방향으로 45° 기운 anchor 를
+ * 추가 선언 — 회전시킨 일반 conveyor 가 비스듬히 닿으면 자동 연결 (새 컴포넌트
+ * 불요). 가로 본선 기준 top 면은 ↘, bottom 면은 ↗ 로 자연 분리돼 양쪽 사선
+ * 합류가 성립. 직교 anchor 보존 (직교 합류도 유효).
+ *
+ * Direction 검사 가 *_같은 방향만 매칭_* 보장 — 옆 conveyor 가 방향 일치
+ * (직교 또는 사선) 시에만 자동 매칭. 의도 안 한 합류 차단.
+ */
+export declare function straightSegmentMultiInbound(state: {
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    orientation?: 'horizontal' | 'vertical' | '';
+    status?: string;
+}): SegmentTopology;
+/**
+ * 두 anchor 가 연결 가능한지 (= 자동 routing 후보). A 의 outbound 가 B 의
+ * inbound 와 *_위치 + 방향_* 일치하면 true.
+ *
+ *   - 위치: distance <= tolerance.distance
+ *   - 방향: outbound.direction · inbound.direction >= tolerance.cosine
+ *     (둘 다 *_carrier 의 진행 방향_*이므로 같은 방향이어야 함)
+ */
+export declare function anchorsConnect(out: Anchor2D, inn: Anchor2D, tolerance?: MatchTolerance): boolean;
+/** 컴포넌트의 board footprint (rotation 포함). matchOutbounds 의 배달 판정용. */
+export interface SegmentBounds {
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+}
+/**
+ * 점 (px, pz) 가 회전된 사각 footprint 안인지 — margin 만큼 확장.
+ * board (x = left, z = top) 좌표계.
+ */
+export declare function pointInRotatedRect(px: number, pz: number, b: SegmentBounds, margin?: number): boolean;
+/**
+ * Ray-rectangle 절대값 거리 — chute 출구점을 통과하는 face normal 의 *_양방향 직선_*
+ * 과 사각형의 가장 가까운 교점까지 거리. 광선이 사각형 안에서 출발하면 (겹침) 가까운
+ * face 쪽 거리. 교차 없으면 Infinity.
+ *
+ * # 왜 이 metric 인가 (2026-06-17 사용자 통찰)
+ *
+ * 이전 matchOutbounds 의 ② 단계 tie-break = *_chute 출구점 ↔ stockpile center 의 유클리드
+ * 거리_*. 단점:
+ *   - 큰 stockpile 의 center 가 *_chute face 와 평행하지만 멀게_* 측정됨
+ *   - chute 가 *_정면으로_* 향한 stockpile 이 *_center 가 우연히 가까운_* 다른 sink 에 밀림
+ *
+ * 직교거리 (face normal 방향 ray cast) 가 *_물리적으로 자연_*:
+ *   - "chute 가 정면으로 가까운 face" 가 정확히 측정됨
+ *   - 큰 stockpile 의 긴 face 가 *_chute face 와 평행_* 일 때 hit 거리 짧음
+ *   - 컴포넌트 center 위치와 무관 — center 왜곡 제거
+ *
+ * # 절대값 (양방향) 이유
+ * chute 출구점이 stockpile 영역 안 (겹침) 인 경우도 자연스럽게 처리. 정방향 hit 가 더 멀어도
+ * 역방향에 더 가까운 face 가 있으면 그 거리. 진행 방향 의존성 제거.
+ */
+export declare function rayAbsDistanceToRect(origin: {
+    x: number;
+    z: number;
+}, direction: {
+    x: number;
+    z: number;
+}, rect: SegmentBounds): number;
+/**
+ * source 배출 anchor 가 target footprint 로 *배달* 되는지 — anchor 끝-끝
+ * 매칭의 보완. 사용자가 컴포넌트를 (회전·겹침 포함) 손으로 놓아 배출 끝점이
+ * 상대 입구를 파고들어도 (= 겹침) 자동 연결되도록.
+ *
+ *   - 끝점이 footprint 안 (+ margin) — 물리적으로 들이밀고 있음
+ *   - 방향이 전진 호환 — candidateFlow (target 흐름) 와 dot ≥ 0 (역류 차단).
+ *     flow 없으면 (sink) footprint 중심을 향하는지로 대체.
+ *
+ * 끝-끝 정밀 매칭 (anchorsConnect) 의 거리 tolerance(5) 가 hand-place 겹침
+ * (10~25 unit) 을 갭으로 거부하던 결함 보완 (2026-06-08 보고).
+ */
+export declare function deliversInto(out: Anchor2D, bounds: SegmentBounds, candidateFlow?: {
+    x: number;
+    z: number;
+}, margin?: number): boolean;
+/**
+ * 자기 outbound 각각에 대해 *_연결 가능한 인근 segment_* 의 id 를 매칭.
+ *
+ *   - candidates: scene 안 모든 segment (자기 자신 제외). 각 항목은
+ *     { id, topology } — pure helper 라 component 객체가 아닌 추출 정보만.
+ *   - 결과: outbound index → matched candidate id (또는 null). 자기 outbound
+ *     수 만큼.
+ *
+ * 매칭 우선순위:
+ *   - 정확 일치 후보가 여럿이면 *_가장 가까운 worldPos_*.
+ *   - 그래도 동률이면 id 사전순 (결정성).
+ */
+export declare function matchOutbounds(selfTopology: SegmentTopology, candidates: ReadonlyArray<{
+    id: string;
+    topology: SegmentTopology;
+    bounds?: SegmentBounds;
+}>, tolerance?: MatchTolerance): Array<string | null>;
+//# sourceMappingURL=segment-topology.d.ts.map

package/dist-types/flow/segment-topology.d.ts.map

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

package/dist-types/interfaces/event-handler.d.ts

@@ -0,0 +1,40 @@
+/** 지원 trigger — DOM 이벤트 + 의미적 alias. */
+export type EventTrigger = 'click' | 'tap' | 'dblclick' | 'mouseenter' | 'hover' | 'mouseleave' | 'longpress' | 'mousedown' | 'mouseup' | 'pressed';
+/** 단일 이벤트 핸들러 spec. */
+export interface EventHandler {
+    /** trigger — 어느 DOM 이벤트에 반응할지. */
+    trigger: EventTrigger;
+    /**
+     * action — 'script' 자유 코드 또는 declarative action name.
+     * 'script' / 'data-toggle' / 'data-set' / 'emphasize' / 'info-window' / ...
+     * 빈 문자열 또는 미설정 시 no-op.
+     */
+    action?: string;
+    /** action='script' 시 JS 코드 (await 지원). */
+    code?: string;
+    /** Target selector — script 의 `targets` 또는 declarative action 의 대상. */
+    target?: string;
+    /** Value — script 의 `value` 또는 action 의 value (`component.access(value)` 적용). */
+    value?: any;
+    /** action 의 부가 옵션 (emphasize / restore / pressed / options 등). */
+    options?: Record<string, any>;
+    /** 비활성화. UI 토글용. */
+    disabled?: boolean;
+}
+/**
+ * legacy `{ tap, hover, dblclick, longpress }` 객체를 `EventHandler[]` 로 변환.
+ * Component constructor 의 *자동 마이그레이션* + UI 의 fallback 변환 모두 사용.
+ */
+export declare function migrateLegacyEvent(legacy: any): EventHandler[];
+/**
+ * 두 속성 통합 — 신규 `state.eventHandlers` 우선, 없으면 legacy `state.event`
+ * (객체) 를 *read-only* 변환해 반환. 컴포넌트 constructor 의 자동 마이그레이션이
+ * 처리 못 한 케이스 (런타임 state mutation 등) 의 fallback.
+ *
+ * 정책:
+ *   - `state.event` (legacy) — *손대지 않음* (rollback 안전망 + 옛 코드 호환)
+ *   - `state.eventHandlers` (신규) — UI / 자동 마이그레이션이 write
+ *   - dispatcher: 신규 우선 / 없으면 legacy fallback
+ */
+export declare function normalizeEventHandlers(state: any): EventHandler[];
+//# sourceMappingURL=event-handler.d.ts.map

package/dist-types/interfaces/event-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-handler.d.ts","sourceRoot":"","sources":["../../src/interfaces/event-handler.ts"],"names":[],"mappings":"AAiBA,wCAAwC;AACxC,MAAM,MAAM,YAAY,GACpB,OAAO,GAAG,KAAK,GACf,UAAU,GACV,YAAY,GAAG,OAAO,GACtB,YAAY,GACZ,WAAW,GACX,WAAW,GAAG,SAAS,GACvB,SAAS,CAAA;AAEb,uBAAuB;AACvB,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,OAAO,EAAE,YAAY,CAAA;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iFAAiF;IACjF,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC7B,oBAAoB;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,GAAG,GAAG,YAAY,EAAE,CAoC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,GAAG,GAAG,YAAY,EAAE,CAKjE"}

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

@@ -2,4 +2,6 @@ export * from './types';
 export * from './providers';
 export * from './layout';
 export type { IRealObject } from './real-object.js';
+export type { EventHandler, EventTrigger } from './event-handler.js';
+export { normalizeEventHandlers } from './event-handler.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist-types/interfaces/layout.d.ts

@@ -1,5 +1,7 @@
+import type Component from '../components/component.js';
+import type Container from '../components/container.js';
 /**
- * 레이아웃 인터페이스
+ * 레이아웃 인터페이스 (구현체용)
  */
 export interface LAYOUT {
     reflow(container: any, component?: any): void;
@@ -9,6 +11,38 @@ export interface LAYOUT {
     keyNavigate?(container: any, component: any, e: KeyboardEvent): any | undefined;
     joinType?: boolean;
 }
+/**
+ * 레이아웃 인터페이스 (Public API — 외부 타입 어노테이션용)
+ *
+ * A layout strategy defines how a container arranges its child components.
+ * Only components with `position: 'static'` should be affected by layout.
+ */
+export interface Layout {
+    /**
+     * Recalculates the positions and sizes of child components.
+     */
+    reflow(container: Container, component?: Component): void;
+    /**
+     * Returns components that are eligible for interaction.
+     */
+    capturables(container: Container): Component[];
+    /**
+     * Returns components that should be rendered.
+     */
+    drawables(container: Container): Component[];
+    /**
+     * Determines whether the given component is "stuck" in its layout position.
+     */
+    isStuck(component: Component): boolean;
+    /**
+     * (Optional) Key navigation handler for keyboard interaction within the layout.
+     */
+    keyNavigate?(container: Container, component: Component, e: KeyboardEvent): Component | undefined;
+    /**
+     * (Optional) Whether the layout joins component types.
+     */
+    joinType?: boolean;
+}
 /**
  * 레이아웃 레지스트리 인터페이스
  */

package/dist-types/interfaces/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/interfaces/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IAC7C,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,CAAA;IAClC,SAAS,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,CAAA;IAChC,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAA;IAChC,WAAW,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,aAAa,GAAG,GAAG,GAAG,SAAS,CAAA;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,IAAI,IAAI;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CACnC"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/interfaces/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AACvD,OAAO,KAAK,SAAS,MAAM,4BAA4B,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IAC7C,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,CAAA;IAClC,SAAS,CAAC,SAAS,EAAE,GAAG,GAAG,GAAG,EAAE,CAAA;IAChC,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAA;IAChC,WAAW,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,aAAa,GAAG,GAAG,GAAG,SAAS,CAAA;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAEzD;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,CAAA;IAE9C;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,CAAA;IAE5C;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAA;IAEtC;;OAEG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,CAAA;IAEjG;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,IAAI,IAAI;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CACnC"}

package/dist-types/interfaces/providers.d.ts

@@ -1,35 +1,47 @@
 import type { SceneMode } from '../const';
 import type { Scene } from '../types/scene';
 /**
- * 참조 제공자 인터페이스
+ * Provides sub-board references for board-to-board linking (goto, link-open).
+ * Implementations should cache loaded scenes and handle lifecycle (release).
  */
 export interface ReferenceProvider {
+    /** All registered board IDs */
     get ids(): string[];
+    /** Register a board scene by ID */
     add(id: string, target?: any): Promise<Scene & {
         release: () => void;
     }>;
+    /** Get a board scene by ID, optionally creating if not found */
     get(id: string, createIf?: boolean): Promise<Scene & {
         release: () => void;
     }>;
+    /** Create a new board scene by ID */
     create(id: string): Promise<Scene & {
         release: () => void;
     }>;
 }
 /**
- * 데이터 구독 제공자 인터페이스
+ * Provides real-time data subscriptions for components with a `tag` property.
+ * Components receive live data via `component.data = ...` when subscribed.
  */
 export interface DataSubscriptionProvider {
+    /** Subscribe a component to a data tag. Returns an unsubscribe handle. */
     subscribe(tag: string, component: any): Promise<{
         unsubscribe: () => void;
     }>;
+    /** Dispose all active subscriptions */
     dispose(): void;
 }
 /**
- * 영속성 데이터 저장소 인터페이스
+ * Per-component persistent data storage for saving/restoring component state
+ * across sessions (e.g. user inputs, slider positions).
  */
 export interface PersistentDataStorage {
+    /** Load persisted data for a component */
     load(key: object): Promise<any>;
+    /** Save data for a component */
     save(key: object, value: any): Promise<void>;
+    /** Clear persisted data for a component */
     clear(key: object): Promise<void>;
 }
 /**
@@ -50,6 +62,18 @@ export interface ApplicationContext {
     PPI?: number;
     /** Command executor for undo/redo operations (edit mode) */
     commander?: any;
+    /** Loading monitor */
+    loadTracker?: import('../diagnostics/load-tracker.js').LoadTracker;
+    adoptLoadTracker?(tracker: import('../diagnostics/load-tracker.js').LoadTracker): void;
+    /** Data lag monitor (optional, created when dataLagMonitor configured) */
+    lagTracker?: import('../diagnostics/data-lag-tracker.js').DataLagTracker;
+    /**
+     * 모델링 포커스 dim 필터(transient/비영속) — 반환 false 컴포넌트는 편집 모드에서
+     * dim + 선택/이동(gizmo) 제외. undefined = 미적용.
+     */
+    focusFilter?: (component: any) => boolean;
+    /** 마퀴(selbox) 영역 선택 드래그 진행 중 여부 — 드래그 중 UI 갱신 억제용(transient). */
+    isSelecting?: boolean;
     url(x: string): string;
     dispose(): void;
     subscribe?(tag: string, component: any): Promise<any>;

package/dist-types/interfaces/providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/interfaces/providers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,GAAG,IAAI,MAAM,EAAE,CAAA;IACnB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IACvE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC5E,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAA;IAC3C,QAAQ,CAAC,wBAAwB,EAAE,wBAAwB,CAAA;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAE5B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,SAAS,CAAC,EAAE,GAAG,CAAA;IAEf,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,OAAO,IAAI,IAAI,CAAA;IACf,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;CACtD"}
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/interfaces/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,IAAI,GAAG,IAAI,MAAM,EAAE,CAAA;IACnB,mCAAmC;IACnC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IACvE,gEAAgE;IAChE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC7E,qCAAqC;IACrC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,0EAA0E;IAC1E,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC5E,uCAAuC;IACvC,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IAC/B,gCAAgC;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5C,2CAA2C;IAC3C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAA;IAC3C,QAAQ,CAAC,wBAAwB,EAAE,wBAAwB,CAAA;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAE5B,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,SAAS,CAAC,EAAE,GAAG,CAAA;IAEf,sBAAsB;IACtB,WAAW,CAAC,EAAE,OAAO,gCAAgC,EAAE,WAAW,CAAA;IAClE,gBAAgB,CAAC,CAAC,OAAO,EAAE,OAAO,gCAAgC,EAAE,WAAW,GAAG,IAAI,CAAA;IACtF,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,oCAAoC,EAAE,cAAc,CAAA;IAExE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,KAAK,OAAO,CAAA;IAEzC,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,OAAO,IAAI,IAAI,CAAA;IACf,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;CACtD"}

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

@@ -4,9 +4,16 @@ import type { Properties } from './types.js';
  * Component의 3D 표현을 담당하는 객체가 구현해야 하는 계약.
  * 실제 구현은 src/threed/real-object.ts에서 제공.
  *
- * Three.js 의존성 없음 — THREE 관련 멤버는 IThreeRealObject(src/threed/interfaces.ts)에서 확장.
+ * Three.js 직접 import 의존성은 없지만, 모든 실 구현(RealObject<T extends THREE.Object3D>)이
+ * object3d 를 갖기 때문에 인터페이스에도 노출. 타입은 any — 명시 타입이 필요한
+ * 곳은 IThreeRealObject(src/threed/interfaces.ts) 또는 구체 구현 클래스로 좁혀 사용.
  */
 export interface IRealObject {
+    /**
+     * THREE.Object3D 인스턴스. THREE 의존성 회피를 위해 any 로 노출.
+     * 명시 THREE.Object3D 타입이 필요하면 IThreeRealObject 로 narrow.
+     */
+    object3d?: any;
     /** 3D 오브젝트 업데이트 (build + dimension + transform + 외관) */
     update(): void;
     /** 리소스 해제 */

package/dist-types/interfaces/real-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object.d.ts","sourceRoot":"","sources":["../../src/interfaces/real-object.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAE1B,wDAAwD;IACxD,MAAM,IAAI,IAAI,CAAA;IACd,aAAa;IACb,OAAO,IAAI,IAAI,CAAA;IAGf,0CAA0C;IAC1C,eAAe,IAAI,IAAI,CAAA;IACvB,oDAAoD;IACpD,eAAe,IAAI,IAAI,CAAA;IACvB,eAAe;IACf,cAAc,IAAI,IAAI,CAAA;IAGtB,gBAAgB;IAChB,WAAW,IAAI,IAAI,CAAA;IACnB,eAAe;IACf,YAAY,IAAI,IAAI,CAAA;IACpB,iBAAiB;IACjB,eAAe,IAAI,IAAI,CAAA;IACvB,eAAe;IACf,iBAAiB,IAAI,IAAI,CAAA;IACzB,gBAAgB;IAChB,UAAU,IAAI,IAAI,CAAA;IAGlB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IAGrD,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAA;CACjB"}
+{"version":3,"file":"real-object.d.ts","sourceRoot":"","sources":["../../src/interfaces/real-object.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAA;IAGd,wDAAwD;IACxD,MAAM,IAAI,IAAI,CAAA;IACd,aAAa;IACb,OAAO,IAAI,IAAI,CAAA;IAGf,0CAA0C;IAC1C,eAAe,IAAI,IAAI,CAAA;IACvB,oDAAoD;IACpD,eAAe,IAAI,IAAI,CAAA;IACvB,eAAe;IACf,cAAc,IAAI,IAAI,CAAA;IAGtB,gBAAgB;IAChB,WAAW,IAAI,IAAI,CAAA;IACnB,eAAe;IACf,YAAY,IAAI,IAAI,CAAA;IACpB,iBAAiB;IACjB,eAAe,IAAI,IAAI,CAAA;IACvB,eAAe;IACf,iBAAiB,IAAI,IAAI,CAAA;IACzB,gBAAgB;IAChB,UAAU,IAAI,IAAI,CAAA;IAGlB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;IAGrD,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAA;CACjB"}

package/dist-types/interfaces/rendering.d.ts

@@ -12,59 +12,131 @@ export interface DrawOptions {
     override?: Record<string, any>;
 }
 /**
- * 스타일 옵션을 정의하는 인터페이스
+ * 스타일 옵션 — gradient / pattern 타입 fillStyle 의 공통 베이스.
+ *
+ * 주의: 'solid' 채우기는 객체가 아니라 단순 색상 문자열이다 (`state.fillStyle = '#ff0000'`).
+ * 이 인터페이스는 객체 형태일 때만 (gradient / pattern) 적용된다.
  */
 export interface StyleOptions {
     type?: string;
-    gradientType?: string;
+    gradientType?: 'linear' | 'radial';
     rotation?: number;
     color?: string;
-    colors?: string[];
-    stops?: number[];
+    /** 인덱스 시그니처 — pattern 의 fitPattern / align / offsetX / offsetY 등 자유 필드 허용. */
     [key: string]: any;
 }
 /**
- * 채우기 스타일을 정의하는 인터페이스
+ * 채우기 스타일 — `state.fillStyle` 타입.
+ *
+ * 실제 형식 (drawer/fill.ts 검증):
+ *   - **solid**: 그냥 색상 문자열 — 객체 아님. e.g., `state.fillStyle = '#ff0000'` 또는 `'rgba(...)'`.
+ *   - **gradient**: 객체 — `{ type: 'gradient', gradientType, colorStops: [{position, color}], rotation, ... }`
+ *   - **pattern**: 객체 — `{ type: 'pattern', image, fitPattern?, noRepeat?, align?, offsetX?, offsetY?, width?, height?, color? }`
+ *   - **none**: `undefined` 또는 `null`.
+ *
+ * 따라서 `state.fillStyle` 의 실제 타입은 `string | FillStyle | undefined`.
  */
+export type FillStyleValue = string | FillStyle | undefined;
 export interface FillStyle extends StyleOptions {
-    type: 'solid' | 'gradient' | 'pattern' | 'image';
-    color?: string;
+    type: 'gradient' | 'pattern';
+    /** gradient: 색상-위치 stops. drawer/fill.ts:79 가 사용. */
+    colorStops?: Array<{
+        position: number;
+        color: string;
+    }>;
+    /** pattern: 이미지 URL 또는 asset 참조. */
+    image?: string;
+    /** pattern: 영역에 맞춰 비율 조정. */
+    fitPattern?: boolean;
+    /** pattern: 반복 안 함 (1회만). */
+    noRepeat?: boolean;
+    /** pattern: 영역 내 정렬. */
+    align?: 'center' | 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' | 'left' | 'right' | 'top' | 'bottom';
+    /** pattern: fitPattern=false 일 때 영역 내 위치. */
+    offsetX?: number;
+    offsetY?: number;
+    /** pattern: 패턴 크기 (기본은 이미지 원본 크기). */
+    width?: number;
+    height?: number;
+    /** 컴포넌트 alpha 와 별개 — gradient/pattern 의 자체 투명도. */
     opacity?: number;
 }
 /**
- * 선 스타일을 정의하는 인터페이스
+ * 선 / 테두리 스타일 — **state 에 top-level flat 으로 저장되는 필드들**.
+ *
+ * 실제 형식 (drawer/stroke.ts:6 destructure 검증):
+ *   `{ strokeStyle, lineDash, lineWidth, lineCap, lineJoin, alpha } = component.state`
+ *
+ * - `state.strokeStyle`: 색상 문자열 (Canvas API 의 strokeStyle 직접 대입)
+ * - `state.lineWidth`: number
+ * - `state.lineDash`: STRING preset 이름 — 'solid' / 'round-dot' / 'square-dot' /
+ *   'dash' / 'dash-dot' / 'long-dash' / 'long-dash-dot' / 'long-dash-dot-dot'
+ * - `state.lineCap`: 'butt' | 'round' | 'square'
+ * - `state.lineJoin`: 'miter' | 'round' | 'bevel'
+ *
+ * 이 인터페이스는 historic 한 객체 구조 — 실제로는 사용 안 됨. 참고용.
+ * 새 코드는 state 의 top-level 필드를 직접 사용할 것.
  */
 export interface StrokeStyle {
+    /** @deprecated 실제로는 `state.lineWidth` (top-level). */
     width?: number;
+    /** @deprecated 실제로는 `state.strokeStyle` (string color). */
     color?: string;
+    /** @deprecated 실제로는 컴포넌트 `state.alpha` 가 stroke 에도 적용. */
     opacity?: number;
+    /** @deprecated 실제로는 `state.lineCap`. */
     lineCap?: CanvasLineCap;
+    /** @deprecated 실제로는 `state.lineJoin`. */
     lineJoin?: CanvasLineJoin;
-    lineDash?: number[];
+    /** @deprecated 실제로는 `state.lineDash` — number[] 가 아닌 STRING preset 이름. */
+    lineDash?: string;
+    /** @deprecated 미사용. */
     lineDashOffset?: number;
 }
 /**
- * 텍스트 스타일을 정의하는 인터페이스
+ * 텍스트 / 폰트 스타일 — **state 에 top-level flat 으로 저장**.
+ *
+ *   `state.fontFamily / fontSize / fontStyle / fontWeight / fontColor /
+ *    textAlign / textBaseline / lineHeight`
+ *
+ * 이 인터페이스는 필드 이름 reference 용 — 객체로 묶어 저장하지 않는다.
  */
 export interface TextStyle {
-    font?: string;
-    fontSize?: number;
-    fontColor?: string;
     fontFamily?: string;
+    fontSize?: number;
     fontStyle?: string;
     fontWeight?: string;
+    fontColor?: string;
     textAlign?: CanvasTextAlign;
     textBaseline?: CanvasTextBaseline;
     lineHeight?: number;
+    /** @deprecated 사용처 없음. */
+    font?: string;
 }
 /**
- * 그림자 효과를 정의하는 인터페이스
+ * 그림자 효과 — `state.shadow` 객체 형식.
+ *
+ * Canonical 이름 (CSS box-shadow / Canvas API 와 일치):
+ *   `{ offsetX, offsetY, blur, color } = state.shadow`
+ *
+ * Backwards compatibility — 옛 이름 (`left`, `top`, `blurSize`) 도 drawer 가
+ * fallback 으로 읽음. 영속된 옛 데이터는 마이그레이션 없이 그대로 렌더링.
+ * 새 코드는 canonical 이름 사용.
  */
 export interface Shadow {
     color?: string;
+    /** Horizontal offset (CSS box-shadow 의 offset-x, Canvas 의 shadowOffsetX). */
     offsetX?: number;
+    /** Vertical offset (CSS box-shadow 의 offset-y, Canvas 의 shadowOffsetY). */
     offsetY?: number;
+    /** Blur radius (CSS box-shadow 의 blur-radius, Canvas 의 shadowBlur). */
     blur?: number;
+    /** @deprecated `offsetX` 사용. drawer 가 fallback 으로 읽음 — 옛 데이터 호환용. */
+    left?: number;
+    /** @deprecated `offsetY` 사용. drawer 가 fallback 으로 읽음 — 옛 데이터 호환용. */
+    top?: number;
+    /** @deprecated `blur` 사용. drawer 가 fallback 으로 읽음 — 옛 데이터 호환용. */
+    blurSize?: number;
 }
 /** Fill drawer — 그라디언트, 패턴, 이미지 채우기 */
 export interface IFillDrawer {

package/dist-types/interfaces/rendering.d.ts.map

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

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

@@ -8,8 +8,27 @@ export type Class = {
 export type Properties = {
     [key: string]: any;
 };
-export type State = Properties;
 export type Style = Properties;
+/**
+ * Component state — 임의 필드를 갖는 동적 객체.
+ *
+ * 컴포넌트별로 자기 state 형태를 선언하고 싶으면 이 인터페이스를 extends 하여
+ * 필드를 추가하고, 컴포넌트 클래스에서 `declare state: MyState` 로 좁히면 된다:
+ *
+ *   interface MyState extends State {
+ *     mySpecificField: number
+ *     myStatus: 'idle' | 'busy'
+ *   }
+ *   class MyComponent extends RectPath(Shape) {
+ *     declare state: MyState  // 타입 narrowing — 런타임 영향 없음
+ *   }
+ *
+ * 기존 `state.foo` 접근 코드는 인덱스 시그니처로 호환된다.
+ * 추후 단계적으로 공통 필드(left/top/width/height/...)를 명시적으로 추가할 수 있다.
+ */
+export interface State {
+    [key: string]: any;
+}
 /**
  * 좌표, 위치, 크기 관련 타입
  */