@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/capacitor-plugin-intent/README.md

@@ -0,0 +1,235 @@
+# @simplysm/capacitor-plugin-intent
+
+> Android 인텐트 플러그인. 브로드캐스트 송수신, 실행 인텐트 조회, 새 인텐트 이벤트 수신, `startActivityForResult`를 제공한다. 산업용 디바이스 연동(바코드 스캐너, PDA 등)을 위해 설계되었다. `@capacitor/core ^7` peerDependency. 외부 런타임 의존성 없음.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-intent
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 바코드 스캐너 등 브로드캐스트 수신 | 이 문서의 `Intent.subscribe` |
+| 브로드캐스트 전송 (스캔 트리거 등) | 이 문서의 `Intent.send` |
+| 외부 Activity 실행 후 결과 수신 | 이 문서의 `Intent.startActivityForResult` |
+| 앱 실행 인텐트 데이터 조회 | 이 문서의 `Intent.getLaunchIntent` |
+
+## API Overview
+
+### `Intent`
+
+Android 인텐트 플러그인 정적 파사드 클래스.
+
+#### When to use
+
+- ✅ 산업용 디바이스(바코드 스캐너, PDA)에서 브로드캐스트 수신/전송이 필요할 때
+- ✅ 외부 앱(결제 등)을 `startActivityForResult`로 호출하고 결과를 받을 때
+- ✅ 딥링크 또는 실행 인텐트 데이터를 조회할 때
+- ❌ 브라우저 환경에서 실제 동작 기대 → 웹 폴백은 경고 로그만 표시하고 스텁 값을 반환한다
+
+#### Signature
+
+```typescript
+export abstract class Intent {
+  static async subscribe(
+    filters: string[],
+    callback: (result: IntentResult) => void,
+  ): Promise<() => Promise<void>>;
+  static async unsubscribeAll(): Promise<void>;
+  static async send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>;
+  static async getLaunchIntent(): Promise<IntentResult>;
+  static async addListener(
+    eventName: "newIntent",
+    callback: (result: IntentResult) => void,
+  ): Promise<PluginListenerHandle>;
+  static async removeAllListeners(): Promise<void>;
+  static async startActivityForResult(
+    options: StartActivityForResultOptions,
+  ): Promise<StartActivityForResultResult>;
+}
+```
+
+#### Members
+
+| Member | Kind | Return | Description |
+|--------|------|--------|-------------|
+| `subscribe` | static method | `Promise<() => Promise<void>>` | 브로드캐스트 수신기 등록. 구독 해제 함수를 반환한다. 초기 resolve 콜백(`action == null`)은 자동 필터링된다. |
+| `unsubscribeAll` | static method | `Promise<void>` | 모든 브로드캐스트 수신기 구독 해제 |
+| `send` | static method | `Promise<void>` | 브로드캐스트 전송 |
+| `getLaunchIntent` | static method | `Promise<IntentResult>` | 앱 실행 인텐트 조회 |
+| `addListener` | static method | `Promise<PluginListenerHandle>` | 앱 실행 중 수신되는 새 인텐트 이벤트 리스너 등록. `handle.remove()`로 해제한다. |
+| `removeAllListeners` | static method | `Promise<void>` | 모든 이벤트 리스너 제거 |
+| `startActivityForResult` | static method | `Promise<StartActivityForResultResult>` | 외부 Activity를 실행하고 결과를 수신한다 |
+
+#### Usage
+
+##### 최소 예제 — 브로드캐스트 수신
+
+```typescript
+import { Intent } from "@simplysm/capacitor-plugin-intent";
+
+const unsub = await Intent.subscribe(
+  ["com.symbol.datawedge.api.RESULT_ACTION"],
+  (result) => {
+    // result.extras에서 스캔 데이터 처리
+  },
+);
+
+// 구독 해제
+await unsub();
+```
+
+##### 전형 예제 — 브로드캐스트 전송
+
+```typescript
+import { Intent } from "@simplysm/capacitor-plugin-intent";
+
+await Intent.send({
+  action: "com.symbol.datawedge.api.ACTION",
+  extras: {
+    "com.symbol.datawedge.api.SOFT_SCAN_TRIGGER": "TOGGLE_SCANNING",
+  },
+});
+```
+
+##### 전형 예제 — startActivityForResult
+
+```typescript
+import { Intent } from "@simplysm/capacitor-plugin-intent";
+
+const result = await Intent.startActivityForResult({
+  action: "com.example.PAY",
+  extras: { amount: 1000 },
+});
+if (result.resultCode === -1) {
+  // RESULT_OK — result.data?.extras에서 결과 데이터 추출
+}
+```
+
+#### 🚫 Anti-patterns
+
+##### `subscribe()` 콜백에서 초기 resolve를 처리
+
+```typescript
+// ❌ subscribe가 반환하는 초기 콜백을 처리하려 함
+const unsub = await Intent.subscribe(["action"], (result) => {
+  processData(result.extras!); // 초기 호출 시 extras가 undefined
+});
+
+// ✅ Intent 파사드가 action == null인 초기 resolve를 이미 필터링한다.
+//    콜백은 실제 브로드캐스트만 수신하므로 안전하게 처리 가능.
+const unsub = await Intent.subscribe(["action"], (result) => {
+  if (result.extras != null) {
+    processData(result.extras);
+  }
+});
+```
+
+**근거**: Capacitor 플러그인 레벨에서 `subscribe()`는 `{ id }`만 포함된 초기 resolve 콜백을 한 번 호출한다. `Intent` 파사드가 `result.action != null` 조건으로 이를 필터링하지만, extras 접근 시에는 방어적으로 null 체크하는 것이 안전하다.
+
+---
+
+### `IntentResult`
+
+브로드캐스트 또는 인텐트 결과 데이터 인터페이스.
+
+```typescript
+export interface IntentResult {
+  action?: string;
+  extras?: Record<string, unknown>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `action` | `string \| undefined` | 브로드캐스트 액션 |
+| `extras` | `Record<string, unknown> \| undefined` | 추가 데이터 |
+
+---
+
+### `StartActivityForResultOptions`
+
+`startActivityForResult` 호출 시 전달하는 옵션 인터페이스. 모든 필드가 optional이다.
+
+```typescript
+export interface StartActivityForResultOptions {
+  action?: string;
+  uri?: string;
+  extras?: Record<string, unknown>;
+  type?: string;
+  packageName?: string;
+  className?: string;
+  flags?: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `action` | `string \| undefined` | Intent 액션 |
+| `uri` | `string \| undefined` | Intent 데이터 URI |
+| `extras` | `Record<string, unknown> \| undefined` | 추가 데이터 |
+| `type` | `string \| undefined` | MIME type |
+| `packageName` | `string \| undefined` | 특정 앱 지정 |
+| `className` | `string \| undefined` | 특정 Activity 지정 |
+| `flags` | `number \| undefined` | Intent flags |
+
+---
+
+### `StartActivityForResultResult`
+
+`startActivityForResult` 호출의 반환 결과 인터페이스.
+
+```typescript
+export interface StartActivityForResultResult {
+  resultCode: number;
+  data?: {
+    action?: string;
+    uri?: string;
+    extras?: Record<string, unknown>;
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `resultCode` | `number` | 결과 코드. `-1`: RESULT_OK, `0`: RESULT_CANCELED |
+| `data` | `object \| undefined` | 결과 데이터 |
+| `data.action` | `string \| undefined` | 결과 인텐트 액션 |
+| `data.uri` | `string \| undefined` | 결과 인텐트 데이터 URI |
+| `data.extras` | `Record<string, unknown> \| undefined` | 결과 인텐트 추가 데이터 |
+
+---
+
+### `IntentPlugin`
+
+Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `Intent` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
+
+```typescript
+export interface IntentPlugin {
+  subscribe(
+    options: { filters: string[] },
+    callback: (result: IntentResult) => void,
+  ): Promise<{ id: string }>;
+  unsubscribe(options: { id: string }): Promise<void>;
+  unsubscribeAll(): Promise<void>;
+  send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>;
+  getLaunchIntent(): Promise<IntentResult>;
+  addListener(
+    eventName: "newIntent",
+    listenerFunc: (data: IntentResult) => void,
+  ): Promise<PluginListenerHandle>;
+  removeAllListeners(): Promise<void>;
+  startActivityForResult(
+    options: StartActivityForResultOptions,
+  ): Promise<StartActivityForResultResult>;
+}
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 파일 시스템 접근 → [`@simplysm/capacitor-plugin-file-system`](../capacitor-plugin-file-system/README.md)
+- APK 설치 → [`@simplysm/capacitor-plugin-auto-update`](../capacitor-plugin-auto-update/README.md)
+- USB 저장 장치 접근 → [`@simplysm/capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md)

package/claude/references/sd-simplysm-v14/capacitor-plugin-usb-storage/README.md

@@ -0,0 +1,251 @@
+# @simplysm/capacitor-plugin-usb-storage
+
+> Capacitor USB 저장소 플러그인. Android에서 libaums 라이브러리를 통해 USB Mass Storage 장치를 열거하고 파일을 읽는다. 브라우저에서는 IndexedDB 기반 가상 USB 저장소로 에뮬레이션한다. `@capacitor/core ^7` peerDependency.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-usb-storage
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| USB 장치 열거 및 권한 요청 | 이 문서의 `UsbStorage` 섹션 |
+| USB 장치에서 파일 읽기 | 이 문서의 `UsbStorage.readFile` |
+| 브라우저에서 가상 USB 테스트 | 이 문서의 `Browser-Only Testing API` 섹션 |
+
+## API Overview
+
+### `UsbStorage`
+
+USB 저장 장치 접근 정적 파사드 클래스. 모든 장치 접근 메서드는 `UsbDeviceFilter`(`vendorId` + `productId`)로 대상 장치를 식별한다.
+
+#### When to use
+
+- ✅ Android에서 USB Mass Storage 장치의 파일을 읽을 때
+- ✅ 연결된 USB 장치를 열거하고 권한을 관리할 때
+- ❌ 일반 파일 시스템 접근 → [`@simplysm/capacitor-plugin-file-system`](../capacitor-plugin-file-system/README.md)
+- ❌ USB 장치에 파일 쓰기 → 현재 지원하지 않는다 (읽기 전용)
+
+#### Signature
+
+```typescript
+export abstract class UsbStorage {
+  static async getDevices(): Promise<UsbDeviceInfo[]>;
+  static async requestPermissions(filter: UsbDeviceFilter): Promise<boolean>;
+  static async checkPermissions(filter: UsbDeviceFilter): Promise<boolean>;
+  static async readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>;
+  static async readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>;
+}
+```
+
+#### Members
+
+| Member | Kind | Return | Description |
+|--------|------|--------|-------------|
+| `getDevices` | static method | `Promise<UsbDeviceInfo[]>` | 연결된 USB Mass Storage 장치 목록 조회 |
+| `requestPermissions` | static method | `Promise<boolean>` | USB 장치 접근 권한 요청. 승인 여부 반환 |
+| `checkPermissions` | static method | `Promise<boolean>` | USB 장치 접근 권한 보유 여부 확인 |
+| `readdir` | static method | `Promise<UsbFileInfo[]>` | USB 저장 장치의 디렉토리 내용 읽기 |
+| `readFile` | static method | `Promise<Bytes \| undefined>` | USB 저장 장치에서 파일 읽기. 파일이 없으면 `undefined`. 최대 100MB |
+
+`Bytes`는 `@simplysm/core-common`의 타입이다 (`Uint8Array` 별칭).
+
+#### Usage
+
+##### 최소 예제
+
+```typescript
+import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
+
+const devices = await UsbStorage.getDevices();
+if (devices.length > 0) {
+  const { vendorId, productId } = devices[0];
+  const files = await UsbStorage.readdir({ vendorId, productId }, "/");
+}
+```
+
+##### 전형 예제 — 권한 확인 후 파일 읽기
+
+```typescript
+import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
+import type { UsbDeviceFilter } from "@simplysm/capacitor-plugin-usb-storage";
+
+const devices = await UsbStorage.getDevices();
+if (devices.length === 0) {
+  throw new Error("USB 장치가 연결되어 있지 않습니다.");
+}
+
+const filter: UsbDeviceFilter = {
+  vendorId: devices[0].vendorId,
+  productId: devices[0].productId,
+};
+
+const granted = await UsbStorage.checkPermissions(filter);
+if (!granted) {
+  const accepted = await UsbStorage.requestPermissions(filter);
+  if (!accepted) {
+    throw new Error("USB 장치 접근 권한이 거부되었습니다.");
+  }
+}
+
+const data = await UsbStorage.readFile(filter, "/updates/config.json");
+if (data != null) {
+  const text = new TextDecoder().decode(data);
+}
+```
+
+#### 🚫 Anti-patterns
+
+##### `readFile()` 반환값을 null 체크 없이 사용
+
+```typescript
+// ❌ 파일이 없으면 undefined이므로 decode 실패
+const data = await UsbStorage.readFile(filter, "/file.txt");
+const text = new TextDecoder().decode(data); // TypeError if undefined
+
+// ✅ null 체크 후 사용
+const data = await UsbStorage.readFile(filter, "/file.txt");
+if (data != null) {
+  const text = new TextDecoder().decode(data);
+}
+```
+
+**근거**: USB 장치에서 파일이 없거나 읽기 실패 시 `undefined`를 반환한다. throw하지 않으므로 반드시 null 체크가 필요하다.
+
+---
+
+### `UsbDeviceInfo`
+
+연결된 USB 장치 정보 인터페이스.
+
+```typescript
+export interface UsbDeviceInfo {
+  deviceName: string;
+  manufacturerName: string;
+  productName: string;
+  vendorId: number;
+  productId: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `deviceName` | `string` | 장치 이름 |
+| `manufacturerName` | `string` | 제조사 이름 |
+| `productName` | `string` | 제품 이름 |
+| `vendorId` | `number` | USB Vendor ID |
+| `productId` | `number` | USB Product ID |
+
+---
+
+### `UsbDeviceFilter`
+
+USB 장치를 식별하기 위한 필터 인터페이스. 모든 장치 접근 메서드의 첫 번째 파라미터로 사용된다.
+
+```typescript
+export interface UsbDeviceFilter {
+  vendorId: number;
+  productId: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `vendorId` | `number` | USB Vendor ID |
+| `productId` | `number` | USB Product ID |
+
+---
+
+### `UsbFileInfo`
+
+USB 저장소 내 파일 또는 디렉토리 정보 인터페이스.
+
+```typescript
+export interface UsbFileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 파일 또는 디렉토리 이름 |
+| `isDirectory` | `boolean` | 디렉토리 여부 |
+
+---
+
+### `UsbStoragePlugin`
+
+Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `UsbStorage` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
+
+```typescript
+export interface UsbStoragePlugin {
+  getDevices(): Promise<{ devices: UsbDeviceInfo[] }>;
+  requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
+  checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>;
+  readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>;
+  readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>;
+}
+```
+
+---
+
+## Browser-Only Testing API (`UsbStorageWeb`)
+
+브라우저 환경에서 테스트 및 개발 목적으로 사용하는 API. `UsbStorage` 정적 파사드로는 접근할 수 없으며, `UsbStorageWeb` 인스턴스를 직접 사용할 때만 호출 가능하다. `UsbStorageWeb`은 패키지 공개 API(`index.ts`)에서 export되지 않으므로 소스 경로를 직접 참조해야 한다.
+
+### `addVirtualDevice(device)`
+
+가상 USB 장치를 IndexedDB에 등록한다.
+
+```typescript
+async addVirtualDevice(device: {
+  vendorId: number;
+  productId: number;
+  deviceName: string;
+  manufacturerName: string;
+  productName: string;
+}): Promise<void>
+```
+
+### `addVirtualFile(filter, filePath, data)`
+
+가상 USB 장치에 파일을 추가한다. 부모 디렉토리가 없으면 자동 생성된다.
+
+```typescript
+async addVirtualFile(filter: UsbDeviceFilter, filePath: string, data: Uint8Array): Promise<void>
+```
+
+### `addVirtualDirectory(filter, dirPath)`
+
+가상 USB 장치에 디렉토리를 추가한다.
+
+```typescript
+async addVirtualDirectory(filter: UsbDeviceFilter, dirPath: string): Promise<void>
+```
+
+### 테스트 설정 예시
+
+```typescript
+import { UsbStorageWeb } from "@simplysm/capacitor-plugin-usb-storage/src/web/UsbStorageWeb";
+
+const web = new UsbStorageWeb();
+await web.addVirtualDevice({
+  vendorId: 1234,
+  productId: 5678,
+  deviceName: "Test Device",
+  manufacturerName: "Test Manufacturer",
+  productName: "Test Product",
+});
+
+const fileData = new TextEncoder().encode("Hello, USB!");
+await web.addVirtualFile({ vendorId: 1234, productId: 5678 }, "/data/config.json", fileData);
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 일반 파일 시스템 접근 → [`@simplysm/capacitor-plugin-file-system`](../capacitor-plugin-file-system/README.md)
+- USB 장치에 파일 쓰기 → 현재 미지원. 읽기 전용 접근만 제공한다.

package/claude/references/sd-simplysm-v14/core-browser/README.md

@@ -0,0 +1,52 @@
+# @simplysm/core-browser
+
+> 브라우저 전용 유틸리티 패키지. DOM 프로토타입 확장(Element/HTMLElement), 파일 다운로드/업로드, HTTP 바이너리 fetch, IndexedDB 추상화를 제공한다.
+> 런타임: 브라우저 전용 (DOM API 필수). `@simplysm/core-common`에 의존한다.
+
+## Installation
+
+```bash
+npm install @simplysm/core-browser
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| DOM 요소 검색/탐색 (findAll, findFirst 등) | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) |
+| 요소 위치 계산, 스크롤 조정, 리페인트 | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) |
+| 여러 요소의 경계(bounds) 비동기 조회 | [get-bounds.md](./extensions/get-bounds.md) |
+| copy/paste 이벤트 핸들러 구현 | [copy-paste.md](./extensions/copy-paste.md) |
+| Blob을 파일로 다운로드 | [download-blob.md](./utils/download-blob.md) |
+| URL에서 바이너리 데이터 다운로드 | [fetch-url-bytes.md](./utils/fetch-url-bytes.md) |
+| 프로그래밍 방식으로 파일 선택 대화상자 열기 | [open-file-dialog.md](./utils/open-file-dialog.md) |
+| IndexedDB CRUD 작업 | [indexed-db-store.md](./utils/indexed-db-store.md) |
+| IndexedDB 기반 가상 파일시스템 | [indexed-db-virtual-fs.md](./utils/indexed-db-virtual-fs.md) |
+
+## API Overview
+
+### Extensions
+
+사이드 이펙트 모듈로, `@simplysm/core-browser`를 임포트하면 자동으로 `Element`와 `HTMLElement` 프로토타입에 메서드가 추가된다.
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`Element/HTMLElement Prototype Extensions`](./extensions/element-prototype-extensions.md) | prototype extension | DOM 요소 검색, 탭 이동, 가시성 확인, 위치 계산, 스크롤 조정이 필요할 때 |
+| [`getBounds`](./extensions/get-bounds.md) | function | IntersectionObserver로 여러 요소의 경계 정보를 비동기 조회할 때 |
+| [`copyElement` / `pasteToElement`](./extensions/copy-paste.md) | function | copy/paste 이벤트 핸들러에서 input/textarea 값을 클립보드와 동기화할 때 |
+
+### Utils
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`downloadBlob`](./utils/download-blob.md) | function | 메모리의 Blob을 사용자 파일로 다운로드할 때 |
+| [`fetchUrlBytes`](./utils/fetch-url-bytes.md) | function | URL에서 바이너리 데이터를 Uint8Array로 가져올 때 (진행 콜백 필요) |
+| [`openFileDialog`](./utils/open-file-dialog.md) | function | `<input type="file">`없이 프로그래밍 방식으로 파일 선택할 때 |
+| [`IndexedDbStore`](./utils/indexed-db-store.md) | class | IndexedDB에 Promise 기반 CRUD가 필요할 때 |
+| [`IndexedDbVirtualFs`](./utils/indexed-db-virtual-fs.md) | class | IndexedDB 위에 경로 기반 파일시스템 추상화가 필요할 때 |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- Node.js 환경 → `@simplysm/core-node`
+- 플랫폼 중립 유틸리티 (DateTime, UUID 등) → `@simplysm/core-common`
+- Angular 컴포넌트/디렉티브 → `@simplysm/angular`

package/claude/references/sd-simplysm-v14/core-browser/extensions/copy-paste.md

@@ -0,0 +1,59 @@
+# `copyElement` / `pasteToElement`
+
+클립보드 이벤트 핸들러에서 input/textarea 값을 클립보드와 동기화하는 함수 쌍.
+
+## When to use
+
+- ✅ `copy`/`paste` 이벤트 핸들러에서 커스텀 클립보드 동작이 필요할 때
+- ❌ 임의 시점에 클립보드에 접근 → `navigator.clipboard` API 직접 사용
+
+## Signature
+
+```typescript
+export function copyElement(event: ClipboardEvent): void
+export function pasteToElement(event: ClipboardEvent): void
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `event` | `ClipboardEvent` | copy 또는 paste 이벤트 객체 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { copyElement, pasteToElement } from "@simplysm/core-browser";
+
+document.addEventListener("copy", copyElement);
+document.addEventListener("paste", pasteToElement);
+```
+
+## 동작 상세
+
+### `copyElement`
+
+이벤트 타겟 요소 내의 첫 번째 `input` 또는 `textarea`를 찾아 그 `value`를 `clipboardData.setData("text/plain", ...)`로 설정하고 `event.preventDefault()`를 호출한다. 해당 요소가 없으면 아무 동작도 하지 않는다.
+
+### `pasteToElement`
+
+이벤트 타겟 요소 내의 첫 번째 `input` 또는 `textarea`를 찾아 값 전체를 클립보드 텍스트(`text/plain`)로 교체한다. 교체 후 `input` 이벤트를 dispatch한다. 커서 위치나 선택 영역은 고려하지 않으며, 값 전체가 대체된다.
+
+## 🚫 Anti-patterns
+
+### 커서 위치를 유지하면서 붙여넣기
+
+```typescript
+// ❌ pasteToElement는 전체 값을 대체함 — 커서 위치 보존 불가
+document.addEventListener("paste", pasteToElement);
+
+// ✅ 커서 위치 기반 삽입이 필요하면 직접 구현
+document.addEventListener("paste", (e) => {
+  const text = e.clipboardData?.getData("text/plain");
+  // selectionStart/selectionEnd를 사용한 직접 삽입 로직
+});
+```
+
+**근거**: `pasteToElement`는 `firstInputEl.value = contentText`로 전체 교체한다. 부분 삽입이 필요한 경우에는 적합하지 않다.