@iyulab/chat-components 0.4.0 → 0.5.1

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

@@ -0,0 +1,83 @@
+import { ScanResult, ScanOptions } from './types.js';
+/**
+ * DOM 스캔 엔진
+ * Shadow DOM을 포함한 전체 DOM 트리를 순회하며 인터랙티브 요소를 추출
+ */
+export declare class DOMScanner {
+    private elementMap;
+    private idMap;
+    private totalElementsScanned;
+    private debug;
+    private cachedScan;
+    private prioritizeLandmarks;
+    /**
+     * DOM 스캔 수행 (Shadow DOM 포함)
+     * @param root 스캔 시작 루트 (기본값 document.body)
+     * @param options 스캔 옵션
+     */
+    scan(root?: Element | ShadowRoot, options?: ScanOptions): ScanResult;
+    /**
+     * ID로 요소 객체 가져오기 (빠른 조회)
+     */
+    getElement(id: string): Element | undefined;
+    /**
+     * 요소에서 ID 가져오기
+     */
+    getElementId(element: Element): string | undefined;
+    /**
+     * 단일 요소를 스캔하고 Shadow DOM도 탐색
+     */
+    private scanElement;
+    /**
+     * Shadow DOM 내부 스캔
+     */
+    private scanShadowRoot;
+    /**
+     * 인터랙티브 요소 여부 판단
+     */
+    private isInteractive;
+    /**
+     * 필터링 기준 충족 여부 (LLM에게 보여줄 가치가 있는지)
+     */
+    private shouldInclude;
+    /**
+     * 짧은 랜덤 ID 생성 (예: elm_a1b2c3)
+     */
+    private generateId;
+    /**
+     * 요소 정보 추출
+     */
+    private getElementInfo;
+    /**
+     * 요소의 레이블 가져오기
+     */
+    private getLabel;
+    /**
+     * 요소 타입 결정
+     */
+    private getElementType;
+    /**
+     * 요소가 시각적으로 보이는지 확인
+     */
+    private isVisible;
+    /**
+     * 우선순위 계산
+     */
+    private calculatePriority;
+    /**
+     * 요소 트리를 평탄화
+     */
+    private flattenElements;
+    /**
+     * 우선순위 기반 필터링
+     */
+    private filterByPriority;
+    /**
+     * DOM 해시 생성 (변경 감지용)
+     */
+    private generateDOMHash;
+    /**
+     * 디버그 로그 출력 (debug 모드일 때만)
+     */
+    private log;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * DOM Interaction Module
+ * LLM이 웹 페이지를 스캔하고 인터랙션할 수 있게 하는 유틸리티
+ */
+export { DOMScanner } from './DOMScanner.js';
+export { DOMController } from './DOMController.js';
+export { DOMAgent } from './DOMAgent.js';
+export { DOMPromptBuilder } from './DOMPromptBuilder.js';
+export type { ElementType, ScannedElement, ScanResult, FilterStrategy, ScanOptions, DOMAction, DOMCommand, ExecutionResult, DOMAgentEvents, AutomationOptions, HistoryItem, LLMCallback } from './types.js';

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

@@ -0,0 +1,209 @@
+/**
+ * DOM Interaction Types
+ * LLM이 웹 페이지를 스캔하고 인터랙션할 수 있게 하는 타입 정의
+ */
+/**
+ * 스캔된 요소의 타입
+ */
+export type ElementType = 'button' | 'input' | 'link' | 'select' | 'textarea' | 'checkbox' | 'radio' | 'custom' | 'other';
+/**
+ * 스캔된 DOM 요소
+ */
+export interface ScannedElement {
+    /** 랜덤 생성된 고유 식별자 (예: elm_a1b2c3) */
+    id: string;
+    /** 요소 타입 */
+    type: ElementType;
+    /** HTML 태그명 */
+    tag: string;
+    /** 텍스트 콘텐츠 */
+    text?: string;
+    /** input 값 */
+    value?: string;
+    /** placeholder 텍스트 */
+    placeholder?: string;
+    /** aria-label 또는 연결된 label */
+    label?: string;
+    /** data-llm-description 값 (LLM을 위한 설명) */
+    description?: string;
+    /** ARIA role */
+    role?: string;
+    /** disabled 상태 */
+    disabled: boolean;
+    /** 시각적으로 보이는지 여부 */
+    visible: boolean;
+    /** 포커스 상태 */
+    focused: boolean;
+    /** 체크 상태 (checkbox/radio) */
+    checked?: boolean;
+    /** Shadow DOM 내부 요소 여부 */
+    inShadowDom: boolean;
+    /** 화면 상 x 위치 */
+    x: number;
+    /** 화면 상 y 위치 */
+    y: number;
+    /** 너비 */
+    width: number;
+    /** 높이 */
+    height: number;
+    /** 우선순위 점수 (필터링용) */
+    priority: number;
+    /** 자식 요소들 (필터링된) */
+    children?: ScannedElement[];
+}
+/**
+ * DOM 스캔 결과
+ */
+export interface ScanResult {
+    /** 스캔 타임스탬프 */
+    timestamp: number;
+    /** 현재 URL */
+    url: string;
+    /** 페이지 제목 */
+    title: string;
+    /** 스캔된 요소들 */
+    elements: ScannedElement[];
+    /** Base64 인코딩된 스크린샷 (optional) */
+    screenshot?: string;
+    /** 스크롤 위치 */
+    scrollPosition: {
+        x: number;
+        y: number;
+    };
+    /** 뷰포트 크기 */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** 전체 DOM 요소 수 */
+    totalElements: number;
+    /** LLM에게 제공되는 필터링된 요소 수 */
+    filteredElements: number;
+}
+/**
+ * 필터링 전략
+ */
+export type FilterStrategy = 'all' | 'interactive' | 'described' | 'visible';
+/**
+ * 스캔 옵션
+ */
+export interface ScanOptions {
+    /** 스크린샷 포함 여부 */
+    includeScreenshot?: boolean;
+    /** 최대 요소 수 제한 */
+    maxElements?: number;
+    /** 최대 깊이 제한 */
+    maxDepth?: number;
+    /** 필터링 전략 */
+    filterStrategy?: FilterStrategy;
+    /** 디버그 로그 활성화 (기본값: false) */
+    debug?: boolean;
+    /** 캐싱 사용 여부 (기본값: true) */
+    useCache?: boolean;
+    /** iframe 포함 여부 (기본값: false) */
+    includeIframes?: boolean;
+    /** ARIA Landmark 우선순위 증가 (기본값: true) */
+    prioritizeLandmarks?: boolean;
+}
+/**
+ * DOM 명령 액션
+ */
+export type DOMAction = 'click' | 'input' | 'select' | 'focus' | 'blur' | 'scroll' | 'scrollTo' | 'hover' | 'clear' | 'check' | 'wait';
+/**
+ * DOM 명령
+ */
+export interface DOMCommand {
+    /** 실행할 액션 */
+    action: DOMAction;
+    /** 대상 요소 ID (DOMScanner가 생성한 랜덤 ID) */
+    target?: string;
+    /** 명령 값 (input 텍스트, select 옵션 등) */
+    value?: string | number | boolean;
+    /** 추가 옵션 */
+    options?: {
+        /** 명령 실행 전 대기 시간 (ms) */
+        delay?: number;
+        /** 네비게이션 대기 여부 */
+        waitForNavigation?: boolean;
+    };
+}
+/**
+ * 명령 실행 결과
+ */
+export interface ExecutionResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** 실행된 명령 */
+    command: DOMCommand;
+    /** 에러 메시지 (실패 시) */
+    error?: string;
+    /** 실행 타임스탬프 */
+    timestamp: number;
+    /** 페이지 네비게이션 발생 여부 */
+    navigationOccurred?: boolean;
+}
+/**
+ * DOMAgent 이벤트 타입
+ */
+export interface DOMAgentEvents {
+    /** 스캔 완료 */
+    scan: ScanResult;
+    /** 명령 수신 */
+    command: DOMCommand;
+    /** 명령 실행 완료 */
+    execute: ExecutionResult;
+    /** 에러 발생 */
+    error: Error;
+    /** 반복 횟수 */
+    iteration: number;
+}
+/**
+ * 자동화 옵션
+ */
+export interface AutomationOptions {
+    /** 최대 반복 횟수 */
+    maxIterations?: number;
+    /** 중지 조건 함수 */
+    stopCondition?: (scan: ScanResult) => boolean;
+    /** 스크린샷 포함 여부 */
+    includeScreenshot?: boolean;
+}
+/**
+ * 히스토리 항목
+ */
+export interface HistoryItem {
+    /** 스캔 결과 */
+    scan: ScanResult;
+    /** 실행된 명령들 */
+    commands: DOMCommand[];
+    /** 실행 결과들 */
+    results: ExecutionResult[];
+}
+/**
+ * LLM 콜백 함수 타입
+ */
+export type LLMCallback = (scan: ScanResult) => Promise<DOMCommand[]>;
+/**
+ * 캐시 항목
+ */
+export interface CachedScan {
+    /** 캐시된 스캔 결과 */
+    result: ScanResult;
+    /** 캐시 생성 시간 */
+    timestamp: number;
+    /** DOM 해시 (변경 감지용) */
+    domHash: string;
+}
+/**
+ * Diff 결과
+ */
+export interface ScanDiff {
+    /** 추가된 요소 */
+    added: ScannedElement[];
+    /** 제거된 요소 */
+    removed: ScannedElement[];
+    /** 변경된 요소 */
+    modified: ScannedElement[];
+    /** 변경되지 않은 요소 */
+    unchanged: ScannedElement[];
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/chat-components",
   "description": "llm chat components for building chat interfaces",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "author": "iyulab",
   "license": "MIT",
   "keywords": [
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
     "CHANGELOG.md",
@@ -31,34 +32,50 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./dist/*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*"
-    }
+    "./dist/*": "./dist/*",
+    "./react": "./dist/react/index.js",
+    "./react/*": "./dist/react/*"
   },
   "scripts": {
     "test": "vite",
     "build": "eslint && vite build"
   },
   "dependencies": {
-    "@iyulab/components": "^0.4.0",
-    "chart.js": "^4.5.1",
+    "@iyulab/components": "^1.0.3",
     "highlight.js": "^11.11.1",
+    "html2canvas": "^1.4.1",
     "lit": "^3.3.2",
-    "marked": "^17.0.3",
+    "marked": "^17.0.5",
     "marked-katex-extension": "^5.1.7"
   },
+  "peerDependencies": {
+    "@lit/react": ">=1.0.8",
+    "chart.js": ">=4.5.1",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@lit/react": {
+      "optional": true
+    },
+    "chart.js": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@eslint/js": "^9.39.3",
-    "@lit/react": "^1.0.8",
-    "@types/node": "^25.3.2",
-    "eslint": "^9.39.3",
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^25.5.0",
+    "chart.js": "^4.5.1",
+    "eslint": "^9.39.4",
     "eslint-plugin-lit": "^2.2.1",
-    "globals": "^17.3.0",
-    "openai": "^6.25.0",
+    "glob": "^13.0.6",
+    "globals": "^17.4.0",
+    "openai": "^6.33.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vite": "^7.3.1",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^8.0.3",
     "vite-plugin-dts": "^4.5.4"
   }
 }

package/skills/iyulab-chat-components/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: iyulab-chat-components
+description: LLM chat UI component library. Covers all u-* custom elements for building chat interfaces — message rendering, chat input, markdown/code blocks, file attachments, reference citations, and the Intent/View system. Use when working with @iyulab/chat-components package.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.5.0"
+---
+
+# @iyulab/chat-components
+
+Web component library for building LLM chat interfaces, built on [Lit](https://lit.dev/). All components are custom elements (`u-*` tags) that work in any framework or vanilla HTML.
+
+## Quick Start
+
+```bash
+npm install @iyulab/chat-components
+```
+
+Import all components at once:
+
+```ts
+import '@iyulab/chat-components';
+```
+
+Import individual components (tree-shakable):
+
+```ts
+import '@iyulab/chat-components/dist/components/message/UMessage.js';
+import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
+```
+
+> For detailed setup and usage patterns, see [./references/usage.md](./references/usage.md).
+
+---
+
+## Components
+
+### Message & Input
+
+- [`u-message`](./references/components/message.md) — Chat message wrapper. Slot-based block layout, loading animation, bubble/default style variants
+- [`u-prompt`](./references/components/prompt.md) — Chat input component. File attachment preview, auto-resize textarea, integrated send/stop button
+
+### Content Blocks
+
+- [`u-marked-block`](./references/components/marked-block.md) — Renders markdown to HTML. KaTeX math, code highlighting, citation insertion, view-json/intent-json handling
+- [`u-code-block`](./references/components/code-block.md) — Highlight.js code block with language label and clipboard copy
+- [`u-text-block`](./references/components/text-block.md) — Plain text display or editable textarea
+- [`u-think-block`](./references/components/think-block.md) — LLM reasoning (thinking) block. Collapse/expand, auto-scroll
+- [`u-tool-block`](./references/components/tool-block.md) — Tool call input/output display. Collapse/expand
+- [`u-file-block`](./references/components/file-block.md) — File attachment card. Type icon, upload status, download, remove
+- [`u-ref-block`](./references/components/ref-block.md) — Reference source group block. Collapse/expand, grid of ref cards
+- [`u-json-block`](./references/components/json-block.md) — Visualizes JSON data as a collapsible tree
+- [`u-table-block`](./references/components/table-block.md) — Markdown table renderer. Column sort, search filter, CSV/XLS download
+
+### Action Buttons
+
+- [`u-copy-button`](./references/components/copy-button.md) — Clipboard copy button; icon changes after copy
+- [`u-vote-button`](./references/components/vote-button.md) — Thumbs-up / thumbs-down vote button pair
+- [`u-attach-button`](./references/components/attach-button.md) — File picker button; fires `attach` event with selected files
+
+### Reference Components
+
+- [`u-ref-tag`](./references/components/ref-tag.md) — Inline citation tag. Tooltip and external-link icon
+- [`u-ref-card`](./references/components/ref-card.md) — Reference source card. web/document type, favicon, tags
+- [`u-ref-card-group`](./references/components/ref-card-group.md) — Paginated group of reference cards
+
+### Intent Components
+
+- [`u-question-intent`](./references/components/question-intent.md) — LLM-generated question with clickable choice buttons
+
+### View Components
+
+- [`u-images-view`](./references/components/images-view.md) — Image gallery (carousel + lightbox)
+- [`u-video-view`](./references/components/video-view.md) — YouTube / Vimeo / direct video file player
+- [`u-chart-view`](./references/components/chart-view.md) — Chart.js charts (bar, line, pie, etc.)
+- [`u-map-view`](./references/components/map-view.md) — OpenStreetMap embed
+- [`u-view`](./references/components/view.md) — Dynamic custom element renderer (runtime for view-json blocks)
+
+---
+
+## Utilities
+
+- [`IntentPromptBuilder`](./references/utilities/intent-prompt-builder.md) — Build LLM system prompt instructions for intents and parse intent-json responses
+- [`ViewPromptBuilder`](./references/utilities/view-prompt-builder.md) — Build LLM system prompt instructions for views
+
+---
+
+## Types
+
+- [`BlockItem`](./references/types.md) — Union type for message content blocks (text, markdown, file, tool, reference, thinking)
+- `ReferenceSource` / `ReferenceCitation` — Citation source and inline citation position types
+- `IntentDefinition` / `PresetIntent` — Intent definition and preset bit flags
+- `ViewDefinition` / `PresetView` — View definition and preset bit flags
+
+---
+
+## Events
+
+| Event | Source | Detail Type | Description |
+|-------|--------|-------------|-------------|
+| `send` | `u-prompt` | `unknown` | Send button clicked or Enter pressed |
+| `stop` | `u-prompt` | `unknown` | Stop button clicked while loading |
+| `attach` | `u-attach-button` | `{ files: File[] }` | File selection completed |
+| `choice` | `u-question-intent` | `{ value: string }` | Choice button clicked |
+| `change` | `u-vote-button` | `Event` | Vote state changed |
+| `remove` | `u-file-block` | `RemoveEventDetail` | Remove button clicked |

package/skills/iyulab-chat-components/references/components/attach-button.md

@@ -0,0 +1,69 @@
+# u-attach-button
+
+```ts
+import '@iyulab/chat-components/dist/components/buttons/UAttachButton.js';
+```
+
+**Tag:** `u-attach-button`
+
+Opens a file picker dialog. Fires an `attach` event with the selected files. Place in `u-prompt`'s `left-actions` slot.
+
+```html
+<!-- Basic usage -->
+<u-attach-button></u-attach-button>
+
+<!-- Images only -->
+<u-attach-button accept="image/*">Add image</u-attach-button>
+
+<!-- Multiple files allowed -->
+<u-attach-button multiple accept="image/*,application/pdf">Attach files</u-attach-button>
+
+<!-- Inside u-prompt -->
+<u-prompt>
+  <u-attach-button
+    slot="left-actions"
+    multiple
+    accept="image/*,application/pdf,text/*"
+    @attach=${handleAttach}
+  >
+    Files
+  </u-attach-button>
+</u-prompt>
+```
+
+```ts
+const attachBtn = document.querySelector('u-attach-button');
+
+attachBtn.addEventListener('attach', (e) => {
+  const { files } = e.detail; // File[]
+  console.log('Selected files:', files.map(f => f.name));
+});
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip label text |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `accept` | `string` | `undefined` | Accepted MIME types (comma-separated). E.g. `"image/*"`, `"image/*,application/pdf"` |
+| `multiple` | `boolean` | `false` | Allow selecting multiple files |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `attach` | `{ files: File[] }` | Fired after file selection. The file input is reset automatically |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The button element (`u-button`) |
+| `icon` | Paperclip icon |

package/skills/iyulab-chat-components/references/components/chart-view.md

@@ -0,0 +1,65 @@
+# u-chart-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UChartView.js';
+```
+
+**Tag:** `u-chart-view`
+
+Renders charts using Chart.js (lazy-loaded). Supports PNG and JSON download. Automatically re-renders when the page theme changes.
+
+```html
+<!-- Bar chart -->
+<u-chart-view
+  type="bar"
+  .data=${{
+    labels: ['Jan', 'Feb', 'Mar'],
+    datasets: [{ label: 'Revenue', data: [100, 200, 150] }]
+  }}
+></u-chart-view>
+
+<!-- Line chart with options -->
+<u-chart-view
+  type="line"
+  .data=${{
+    labels: ['A', 'B', 'C', 'D'],
+    datasets: [{ label: 'Trend', data: [10, 40, 30, 60], fill: true }]
+  }}
+  .options=${{ plugins: { legend: { position: 'bottom' } } }}
+></u-chart-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-chart-view",
+  "properties": {
+    "type": "bar",
+    "data": {
+      "labels": ["Jan", "Feb", "Mar"],
+      "datasets": [{ "label": "Revenue", "data": [100, 200, 150] }]
+    }
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `ChartType` | `undefined` | Chart type: `'bar'`, `'line'`, `'pie'`, `'doughnut'`, `'radar'`, `'polarArea'`, `'bubble'`, `'scatter'` |
+| `data` | `ChartData` | `undefined` | Chart.js data object with `labels` and `datasets` |
+| `options` | `ChartOptions` | `undefined` | Chart.js options object |
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Lazy load | Chart.js is dynamically imported on first render |
+| Download | Export chart as PNG or raw JSON data |
+| Theme sync | Watches `document.documentElement[theme]` and re-renders on change |

package/skills/iyulab-chat-components/references/components/code-block.md

@@ -0,0 +1,42 @@
+# u-code-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UCodeBlock.js';
+```
+
+**Tag:** `u-code-block`
+
+Syntax-highlighted code block powered by Highlight.js. Shows a language label, clipboard copy button, and loading spinner. Automatically rendered inside `u-marked-block` for fenced code blocks.
+
+```html
+<!-- Direct usage -->
+<u-code-block lang="typescript" .value=${"const x: number = 42;"}></u-code-block>
+
+<!-- Without header -->
+<u-code-block lang="json" headless .value=${JSON.stringify({key: 'value'}, null, 2)}></u-code-block>
+
+<!-- Loading state (streaming) -->
+<u-code-block lang="python" loading .value=${"def hello():"}></u-code-block>
+
+<!-- Inject code via slot -->
+<u-code-block lang="javascript">
+  console.log("Hello from slot");
+</u-code-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `lang` | `string` | `'plaintext'` | ✓ | Code language. Falls back to `plaintext` if not supported by Highlight.js |
+| `value` | `string` | `undefined` | — | Code content. Can also be set via slot `textContent` |
+| `loading` | `boolean` | `false` | ✓ | Loading state. Replaces the code icon with a spinner in the header |
+| `headless` | `boolean` | `false` | ✓ | Hides the header (language label + copy button) |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default, hidden)* | Code text injected directly as content; updates `value` on `slotchange` |