@iyulab/chat-components 0.3.0 → 0.5.0

package/dist/types/Intents.js

@@ -0,0 +1,30 @@
+//#region src/types/Intents.ts
+/** 프리셋 Intent 비트 플래그 */
+var PresetIntent = /* @__PURE__ */ function(PresetIntent) {
+	PresetIntent[PresetIntent["Questions"] = 1] = "Questions";
+	PresetIntent[PresetIntent["All"] = 1] = "All";
+	return PresetIntent;
+}({});
+/** 프리셋 Intent 목록 (비트 플래그 순서대로) */
+var PRESET_INTENT_LIST = [PresetIntent.Questions];
+/** 프리셋 Intent 정의 매핑 */
+var PRESET_INTENT_DEFINITIONS = new Map([[PresetIntent.Questions, {
+	type: "question",
+	description: "Present a question to the user with clickable choices",
+	properties: {
+		question: {
+			type: "string",
+			description: "Optional question text displayed above the choices (e.g. \"What would you like to explore?\")"
+		},
+		choices: {
+			type: "array",
+			items: { type: "string" },
+			minItems: 1,
+			maxItems: 5,
+			description: "Clickable choice buttons (1–5 items)"
+		}
+	},
+	required: ["choices"]
+}]]);
+//#endregion
+export { PRESET_INTENT_DEFINITIONS, PRESET_INTENT_LIST, PresetIntent };

package/dist/types/JsonSchema.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 위젯 정의용 JSON Schema 타입
+ *
+ * 위젯의 속성을 LLM에게 설명하기 위한 최소한의 스키마 정의만 포함.
+ * 복잡한 검증 기능이나 메타 정보는 제외하여 단순화함.
+ *
+ * 제외된 기능들:
+ * - $schema, $id 등 메타 정보 (위젯 정의에 불필요)
+ * - pattern, format 등 고급 검증 (LLM이 직접 생성하므로 불필요)
+ * - allOf, anyOf 등 조합 스키마 (복잡도 증가, 위젯에 과도함)
+ * - 조건부 스키마 if/then/else (위젯 속성에 불필요)
+ * - 고급 object/array 검증들 (단순한 구조만으로 충분)
+ */
+export interface BaseJsonSchema {
+    /** 속성에 대한 설명 (LLM용) */
+    description?: string;
+    /** 기본값 */
+    default?: any;
+    /** 허용 가능한 값들 (제한된 선택지) */
+    enum?: any[];
+    /** 예시 값들 (LLM이 이해하기 쉽도록) */
+    examples?: any[];
+}
+export interface BooleanJsonSchema extends BaseJsonSchema {
+    type: 'boolean';
+}
+export interface StringJsonSchema extends BaseJsonSchema {
+    type: 'string';
+    /** 최소 문자열 길이 */
+    minLength?: number;
+    /** 최대 문자열 길이 */
+    maxLength?: number;
+}
+export interface NumberJsonSchema extends BaseJsonSchema {
+    type: 'number' | 'integer';
+    /** 최솟값 */
+    minimum?: number;
+    /** 최댓값 */
+    maximum?: number;
+}
+export interface ArrayJsonSchema extends BaseJsonSchema {
+    type: 'array';
+    /** 배열 아이템의 스키마 */
+    items?: JsonSchema;
+    /** 최소 아이템 개수 */
+    minItems?: number;
+    /** 최대 아이템 개수 */
+    maxItems?: number;
+}
+export interface ObjectJsonSchema extends BaseJsonSchema {
+    type: 'object';
+    /** 객체의 속성들 */
+    properties?: Record<string, JsonSchema>;
+    /** 필수 속성 목록 */
+    required?: string[];
+    /** 정의되지 않은 추가 속성 허용 여부 */
+    additionalProperties?: boolean;
+}
+export type JsonSchema = BooleanJsonSchema | StringJsonSchema | NumberJsonSchema | ArrayJsonSchema | ObjectJsonSchema;

package/dist/types/Views.d.ts

@@ -0,0 +1,34 @@
+import { JsonSchema } from './JsonSchema.js';
+/**
+ * View를 정의하는 구조체
+ */
+export interface ViewDefinition {
+    /** 등록할 커스텀 엘리먼트 클래스 */
+    element: CustomElementConstructor;
+    /** 등록할 커스텀 엘리먼트 태그명 */
+    tag: string;
+    /** LLM용 설명 */
+    description: string;
+    /** LLM용 속성 스키마 */
+    properties?: Record<string, JsonSchema>;
+    /** 필수 속성 목록 */
+    required?: string[];
+}
+/**
+ * 프리셋 View 비트 플래그
+ */
+export declare enum PresetView {
+    Images = 1,
+    Video = 2,
+    Map = 8,
+    Chart = 16,
+    All = 27
+}
+/**
+ * 전체 프리셋 View 플래그 목록
+ */
+export declare const PRESET_VIEW_LIST: readonly [PresetView.Images, PresetView.Video, PresetView.Map, PresetView.Chart];
+/**
+ * 프리셋 View 정의
+ */
+export declare const PRESET_VIEW_DEFINITIONS: Map<PresetView, ViewDefinition>;

package/dist/types/Views.js

@@ -0,0 +1,150 @@
+import { UImagesView } from "../components/views/UImagesView.js";
+import { UVideoView } from "../components/views/UVideoView.js";
+import { UMapView } from "../components/views/UMapView.js";
+import { UChartView } from "../components/views/UChartView.js";
+//#region src/types/Views.ts
+/**
+* 프리셋 View 비트 플래그
+*/
+var PresetView = /* @__PURE__ */ function(PresetView) {
+	PresetView[PresetView["Images"] = 1] = "Images";
+	PresetView[PresetView["Video"] = 2] = "Video";
+	PresetView[PresetView["Map"] = 8] = "Map";
+	PresetView[PresetView["Chart"] = 16] = "Chart";
+	PresetView[PresetView["All"] = 27] = "All";
+	return PresetView;
+}({});
+/** 
+* 전체 프리셋 View 플래그 목록 
+*/
+var PRESET_VIEW_LIST = [
+	PresetView.Images,
+	PresetView.Video,
+	PresetView.Map,
+	PresetView.Chart
+];
+/** 
+* 프리셋 View 정의 
+*/
+var PRESET_VIEW_DEFINITIONS = new Map([
+	[PresetView.Images, {
+		element: UImagesView,
+		tag: "u-images-view",
+		description: "Display multiple images in a scrollable gallery",
+		properties: { items: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					src: {
+						type: "string",
+						description: "Image URL"
+					},
+					alt: {
+						type: "string",
+						description: "Alt text for accessibility"
+					},
+					caption: {
+						type: "string",
+						description: "Image caption"
+					}
+				},
+				required: ["src"]
+			},
+			minItems: 1,
+			description: "Array of image objects"
+		} },
+		required: ["items"]
+	}],
+	[PresetView.Video, {
+		element: UVideoView,
+		tag: "u-video-view",
+		description: "Embed video from YouTube, Vimeo, or Others. Provide a direct video file URL or a platform URL.",
+		properties: {
+			src: {
+				type: "string",
+				description: "Video URL (YouTube, Vimeo, or direct video file URL)"
+			},
+			poster: {
+				type: "string",
+				description: "Poster image URL"
+			},
+			ratio: {
+				type: "string",
+				enum: [
+					"16:9",
+					"4:3",
+					"1:1"
+				],
+				default: "16:9",
+				description: "Video aspect ratio"
+			}
+		},
+		required: ["src"]
+	}],
+	[PresetView.Map, {
+		element: UMapView,
+		tag: "u-map-view",
+		description: "Display a map showing a single location",
+		properties: {
+			lat: {
+				type: "number",
+				description: "Latitude coordinate"
+			},
+			lng: {
+				type: "number",
+				description: "Longitude coordinate"
+			},
+			zoom: {
+				type: "integer",
+				minimum: 1,
+				maximum: 20,
+				default: 15,
+				description: "Map zoom level"
+			},
+			label: {
+				type: "string",
+				description: "Location title"
+			},
+			description: {
+				type: "string",
+				description: "Location description"
+			}
+		},
+		required: ["lat", "lng"]
+	}],
+	[PresetView.Chart, {
+		element: UChartView,
+		tag: "u-chart-view",
+		description: "Display charts using Chart.js v4 format. Use standard Chart.js configuration (type, data, options). The View accepts the exact same structure as Chart.js - no conversion needed.",
+		properties: {
+			type: {
+				type: "string",
+				enum: [
+					"bar",
+					"line",
+					"pie",
+					"doughnut",
+					"radar",
+					"polarArea",
+					"bubble",
+					"scatter"
+				],
+				description: "Chart.js chart type"
+			},
+			data: {
+				type: "object",
+				description: "Chart.js data configuration",
+				additionalProperties: true
+			},
+			options: {
+				type: "object",
+				description: "Chart.js options configuration (optional)",
+				additionalProperties: true
+			}
+		},
+		required: ["type", "data"]
+	}]
+]);
+//#endregion
+export { PRESET_VIEW_DEFINITIONS, PRESET_VIEW_LIST, PresetView };

package/dist/utilities/IntentPromptBuilder.d.ts

@@ -0,0 +1,40 @@
+import { PresetIntent, IntentDefinition, IntentSchema } from '../types/Intents.js';
+/**
+ * Intent 등록, LLM 인스트럭션 빌드, 텍스트 추출을 통합 제공하는 유틸리티
+ *
+ * @example
+ * IntentPromptBuilder.use(PresetIntent.All);
+ * const prompt = IntentPromptBuilder.buildPrompt();
+ * const [clean, templates] = IntentPromptBuilder.extractPrompt(llmText);
+ */
+export declare class IntentPromptBuilder {
+    private static _instance;
+    private intents;
+    /**
+     * 싱글톤 인스턴스를 반환합니다. 최초 호출 시 인스턴스가 생성됩니다.
+     */
+    static get instance(): IntentPromptBuilder;
+    /**
+     * Intent 정의를 등록합니다. 같은 type이 이미 등록되어 있으면 에러를 던집니다.
+     * @throws {Error} 같은 type의 intent가 이미 등록된 경우
+     */
+    add(definition: IntentDefinition): IntentPromptBuilder;
+    /**
+     * 미리 정의된 프리셋 Intent를 등록합니다.
+     * @example
+     * IntentPromptBuilder.use(PresetIntent.Questions);
+     * IntentPromptBuilder.use(PresetIntent.All);
+     */
+    use(flags: PresetIntent): IntentPromptBuilder;
+    /**
+     * 등록된 intent들에 대한 LLM 시스템 프롬프트 인스트럭션을 생성합니다.
+     */
+    build(): string;
+    /**
+     * LLM 응답 텍스트에서 `intent-json` 코드블록을 추출합니다.
+     *
+     * @param value - LLM 응답 텍스트
+     * @returns `[intents, rest]` — intents는 파싱된 JSON 객체 배열, rest는 블록이 제거된 나머지 텍스트
+     */
+    parse(value: string): [IntentSchema[], string];
+}

package/dist/utilities/IntentPromptBuilder.js

@@ -0,0 +1,95 @@
+import { PRESET_INTENT_DEFINITIONS, PRESET_INTENT_LIST } from "../types/Intents.js";
+import intent_prompt_md_default from "../_virtual/_glob-assets_raw/intent-prompt.md.1907474e.js";
+//#region src/utilities/IntentPromptBuilder.ts
+/**
+* Intent 등록, LLM 인스트럭션 빌드, 텍스트 추출을 통합 제공하는 유틸리티
+*
+* @example
+* IntentPromptBuilder.use(PresetIntent.All);
+* const prompt = IntentPromptBuilder.buildPrompt();
+* const [clean, templates] = IntentPromptBuilder.extractPrompt(llmText);
+*/
+var IntentPromptBuilder = class IntentPromptBuilder {
+	constructor() {
+		this.intents = /* @__PURE__ */ new Map();
+	}
+	/**
+	* 싱글톤 인스턴스를 반환합니다. 최초 호출 시 인스턴스가 생성됩니다.
+	*/
+	static get instance() {
+		if (!this._instance) this._instance = new IntentPromptBuilder();
+		return this._instance;
+	}
+	/**
+	* Intent 정의를 등록합니다. 같은 type이 이미 등록되어 있으면 에러를 던집니다.
+	* @throws {Error} 같은 type의 intent가 이미 등록된 경우
+	*/
+	add(definition) {
+		if (this.intents.has(definition.type)) throw new Error(`Intent with type "${definition.type}" is already registered.`);
+		this.intents.set(definition.type, definition);
+		return this;
+	}
+	/**
+	* 미리 정의된 프리셋 Intent를 등록합니다.
+	* @example
+	* IntentPromptBuilder.use(PresetIntent.Questions);
+	* IntentPromptBuilder.use(PresetIntent.All);
+	*/
+	use(flags) {
+		for (const flag of PRESET_INTENT_LIST) if (flags & flag) {
+			const definition = PRESET_INTENT_DEFINITIONS.get(flag);
+			if (definition && !this.intents.has(definition.type)) this.intents.set(definition.type, definition);
+		}
+		return this;
+	}
+	/**
+	* 등록된 intent들에 대한 LLM 시스템 프롬프트 인스트럭션을 생성합니다.
+	*/
+	build() {
+		if (this.intents.size === 0) return "";
+		const docs = Array.from(this.intents.values()).map((def) => {
+			return [
+				`### ${def.type}`,
+				"",
+				"**JSON Schema:**",
+				"```intent-json",
+				JSON.stringify({
+					type: "object",
+					description: def.description,
+					properties: {
+						type: {
+							type: "string",
+							enum: [def.type]
+						},
+						properties: {
+							type: "object",
+							properties: def.properties || {},
+							required: def.required || []
+						}
+					},
+					required: ["type"]
+				}, null, 2),
+				"```"
+			].join("\n");
+		}).join("\n\n---\n\n");
+		return intent_prompt_md_default.replace("{{INTENT_DOCS}}", docs);
+	}
+	/**
+	* LLM 응답 텍스트에서 `intent-json` 코드블록을 추출합니다.
+	* 
+	* @param value - LLM 응답 텍스트
+	* @returns `[intents, rest]` — intents는 파싱된 JSON 객체 배열, rest는 블록이 제거된 나머지 텍스트
+	*/
+	parse(value) {
+		const pattern = /```(?:intent-json)\s*([\s\S]*?)```/g;
+		const intents = [];
+		return [intents, value.replace(pattern, (_, json) => {
+			try {
+				intents.push(JSON.parse(json.trim()));
+			} catch {}
+			return "";
+		}).trim()];
+	}
+};
+//#endregion
+export { IntentPromptBuilder };

package/dist/utilities/ViewPromptBuilder.d.ts

@@ -0,0 +1,28 @@
+import { PresetView, ViewDefinition } from '../types/Views.js';
+/**
+ * 뷰 등록, LLM 인스트럭션 빌드, HTML 렌더링을 통합 제공하는 유틸리티
+ */
+export declare class ViewPromptBuilder {
+    private static _instance;
+    private views;
+    /**
+     * 싱글톤 인스턴스를 반환합니다. 최초 호출 시 인스턴스가 생성됩니다.
+     */
+    static get instance(): ViewPromptBuilder;
+    /**
+     * 뷰 정의를 등록합니다. 같은 이름의 뷰이 이미 등록되어 있으면 에러를 던집니다.
+     * @throws {Error} 같은 이름의 뷰이 이미 등록된 경우 또는 같은 태그의 커스텀 요소가 다른 클래스에 의해 정의된 경우
+     */
+    add(definition: ViewDefinition): ViewPromptBuilder;
+    /**
+     * 미리 정의된 프리셋 뷰을 사용합니다.
+     * @example
+     * ViewRegistry.use(View.Images | View.Chart);
+     * ViewRegistry.use(View.All);
+     */
+    use(flags: PresetView): ViewPromptBuilder;
+    /**
+     * 등록된 뷰들에 대한 LLM 인스트럭션 문자열을 생성합니다.
+     */
+    build(): string;
+}

package/dist/utilities/ViewPromptBuilder.js

@@ -0,0 +1,76 @@
+import { PRESET_VIEW_DEFINITIONS, PRESET_VIEW_LIST } from "../types/Views.js";
+import view_prompt_md_default from "../_virtual/_glob-assets_raw/view-prompt.md.e0dbcffe.js";
+//#region src/utilities/ViewPromptBuilder.ts
+/**
+* 뷰 등록, LLM 인스트럭션 빌드, HTML 렌더링을 통합 제공하는 유틸리티
+*/
+var ViewPromptBuilder = class ViewPromptBuilder {
+	constructor() {
+		this.views = /* @__PURE__ */ new Map();
+	}
+	/**
+	* 싱글톤 인스턴스를 반환합니다. 최초 호출 시 인스턴스가 생성됩니다.
+	*/
+	static get instance() {
+		if (!this._instance) this._instance = new ViewPromptBuilder();
+		return this._instance;
+	}
+	/**
+	* 뷰 정의를 등록합니다. 같은 이름의 뷰이 이미 등록되어 있으면 에러를 던집니다.
+	* @throws {Error} 같은 이름의 뷰이 이미 등록된 경우 또는 같은 태그의 커스텀 요소가 다른 클래스에 의해 정의된 경우
+	*/
+	add(definition) {
+		if (this.views.has(definition.tag)) throw new Error(`View with tag "${definition.tag}" is already registered.`);
+		const constructor = customElements.get(definition.tag);
+		if (constructor && constructor !== definition.element) throw new Error(`Custom element with tag "${definition.tag}" is already defined to a different class.`);
+		this.views.set(definition.tag, definition);
+		return this;
+	}
+	/**
+	* 미리 정의된 프리셋 뷰을 사용합니다.
+	* @example
+	* ViewRegistry.use(View.Images | View.Chart);
+	* ViewRegistry.use(View.All);
+	*/
+	use(flags) {
+		for (const flag of PRESET_VIEW_LIST) if (flags & flag) {
+			const definition = PRESET_VIEW_DEFINITIONS.get(flag);
+			if (definition) this.add(definition);
+		}
+		return this;
+	}
+	/**
+	* 등록된 뷰들에 대한 LLM 인스트럭션 문자열을 생성합니다.
+	*/
+	build() {
+		if (this.views.size === 0) return "";
+		const docs = Array.from(this.views.values()).map((def) => {
+			return [
+				`### ${def.tag}`,
+				"",
+				"**JSON Schema:**",
+				"```view-json",
+				JSON.stringify({
+					type: "object",
+					description: def.description,
+					properties: {
+						tag: {
+							type: "string",
+							enum: [def.tag]
+						},
+						properties: {
+							type: "object",
+							properties: def.properties || {},
+							required: def.required || []
+						}
+					},
+					required: ["tag"]
+				}, null, 2),
+				"```"
+			].join("\n");
+		}).join("\n\n---\n\n");
+		return view_prompt_md_default.replace("{{VIEW_DOCS}}", docs);
+	}
+};
+//#endregion
+export { ViewPromptBuilder };

package/dist/utilities/dom-agent/DOMAgent.d.ts

@@ -0,0 +1,74 @@
+import { DOMScanner } from './DOMScanner.js';
+import { DOMController } from './DOMController.js';
+import { ScanResult, ScanOptions, DOMCommand, ExecutionResult, HistoryItem, AutomationOptions, LLMCallback, ScanDiff } from './types.js';
+/**
+ * DOM Agent 통합 오케스트레이터
+ * Scanner와 Controller를 조합하여 전체 워크플로우 관리
+ */
+export declare class DOMAgent extends EventTarget {
+    private scanner;
+    private controller;
+    private history;
+    private currentScan;
+    private lastScanRoot;
+    constructor();
+    /**
+     * 초기 스캔 및 세션 시작
+     */
+    start(root?: Element | ShadowRoot, options?: ScanOptions & {
+        includeScreenshot?: boolean;
+    }): Promise<ScanResult>;
+    /**
+     * 명령 실행 후 재스캔
+     */
+    executeAndRescan(commands: DOMCommand | DOMCommand[], options?: ScanOptions & {
+        includeScreenshot?: boolean;
+    }): Promise<{
+        execution: ExecutionResult[];
+        scan: ScanResult;
+    }>;
+    /**
+     * 현재 상태 가져오기
+     */
+    getCurrentState(): ScanResult | null;
+    /**
+     * 히스토리 조회
+     */
+    getHistory(): HistoryItem[];
+    /**
+     * 히스토리 초기화
+     */
+    clearHistory(): void;
+    /**
+     * 자동 모드: LLM 콜백과 함께 반복 실행
+     */
+    automate(llmCallback: LLMCallback, options?: AutomationOptions): Promise<void>;
+    /**
+     * 특정 요소 스캔
+     */
+    scanElement(elementId: string, options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * 에러 이벤트 발생
+     */
+    private dispatchError;
+    /**
+     * 스크린샷 캡처 (html2canvas 사용)
+     */
+    private captureScreenshot;
+    /**
+     * Scanner 인스턴스 가져오기 (고급 사용)
+     */
+    getScanner(): DOMScanner;
+    /**
+     * Controller 인스턴스 가져오기 (고급 사용)
+     */
+    getController(): DOMController;
+    /**
+     * 이전 스캔과 현재 스캔 비교 (Diff)
+     */
+    scanDiff(previousScan: ScanResult, currentScan: ScanResult): ScanDiff;
+    /**
+     * 요소 변경 여부 확인
+     */
+    private isElementModified;
+}

package/dist/utilities/dom-agent/DOMController.d.ts

@@ -0,0 +1,78 @@
+import { DOMCommand, ExecutionResult } from './types.js';
+import { DOMScanner } from './DOMScanner.js';
+/**
+ * DOM 명령 실행 엔진
+ * LLM의 명령을 파싱하고 실제 DOM 조작 수행
+ */
+export declare class DOMController {
+    private scanner;
+    constructor(scanner: DOMScanner);
+    /**
+     * 단일 명령 실행
+     */
+    execute(command: DOMCommand): Promise<ExecutionResult>;
+    /**
+     * 여러 명령 순차 실행
+     */
+    executeMany(commands: DOMCommand[]): Promise<ExecutionResult[]>;
+    /**
+     * 명령 실행 (내부)
+     */
+    private executeCommand;
+    /**
+     * 클릭 이벤트 실행
+     */
+    private click;
+    /**
+     * 텍스트 입력 (자연스러운 타이핑 시뮬레이션)
+     */
+    private input;
+    /**
+     * 옵션 선택
+     */
+    private selectOption;
+    /**
+     * 포커스
+     */
+    private focus;
+    /**
+     * 블러 (포커스 해제)
+     */
+    private blur;
+    /**
+     * 스크롤
+     */
+    private scroll;
+    /**
+     * 요소로 스크롤
+     */
+    private scrollTo;
+    /**
+     * 마우스 오버 (호버)
+     */
+    private hover;
+    /**
+     * 입력 필드 초기화
+     */
+    private clear;
+    /**
+     * 체크박스/라디오 토글
+     */
+    private check;
+    /**
+     * 대기
+     */
+    private wait;
+    /**
+     * 페이지 네비게이션 대기
+     */
+    private waitForNavigation;
+    /**
+     * 사람처럼 보이는 랜덤 딜레이
+     */
+    private simulateHumanDelay;
+    /**
+     * ID로 요소 가져오기 (Scanner의 매핑 활용)
+     */
+    private getElement;
+}