@simplysm/sd-claude 14.0.91 → 14.0.93

package/claude/references/sd-simplysm14/apis/capacitor-plugin-file-system/README.md

@@ -1,30 +1,32 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor 네이티브 파일 시스템 접근 플러그인. Android 는 OS 파일 시스템(Android 11+ 는 `MANAGE_EXTERNAL_STORAGE`, 10- 는 `READ/WRITE_EXTERNAL_STORAGE` 권한), 웹은 IndexedDB 기반 가상 파일 시스템으로 동일 API 를 에뮬레이션한다. 권한 확인/요청, 디렉토리 읽기·생성, 파일 읽기·쓰기·삭제, 저장소 경로·파일 URI 조회를 모두 `FileSystem` 정적 메서드로 제공한다.
+Capacitor 네이티브 파일 시스템 접근 플러그인. Android 에서는 OS 파일 시스템(11+ `MANAGE_EXTERNAL_STORAGE`, 10- `READ/WRITE_EXTERNAL_STORAGE` 권한)에, 웹에서는 IndexedDB 기반 가상 파일 시스템 에뮬레이션에 동일 API 로 접근한다. 진입점은 `FileSystem` 정적 클래스이며, 입출력 형태는 `StorageType`·`FileInfo`·`FileSystemPlugin` 타입으로 기술된다.
 
 ## 사용 트리거 인덱스
 
-- **FileSystem** — 앱에서 단말 파일을 읽고 쓰거나 디렉토리·권한을 다룰 때의 진입점. 모든 메서드가 `static async` 이며 인스턴스화 불필요(abstract class). 권한·경로·읽기/쓰기·삭제 전반.
-- **StorageType** — `getStoragePath` 인자. 어느 저장소(외부/앱 전용/캐시 등) 의 기준 경로를 얻을지 고를 때.
-- **FileInfo** — `readdir` 결과 항목 타입. 디렉토리 나열 결과를 순회·필터할 때.
-- **FileSystemPlugin** — 저수준 Capacitor 플러그인 인터페이스(옵션 객체 기반 원형). 보통 직접 쓰지 않고 `FileSystem` 래퍼를 쓰며, 커스텀 네이티브/web 구현이나 옵션·반환 타입 참조가 필요할 때만 사용.
+- **FileSystem** — 앱에서 단말 파일을 읽고 쓰거나 디렉토리·권한·저장소 경로·파일 URI 를 다룰 때의 진입점. 모든 메서드가 `static async` 이며 `new` 없이 `FileSystem.메서드()` 로 호출(abstract class).
+- **StorageType** — `getStoragePath` 인자. 외부/앱 전용/캐시 등 어느 표준 저장소의 기준 경로를 얻을지 고를 때.
+- **FileInfo** — `readdir` 결과 항목 1건의 타입(이름 + 디렉토리 여부). 디렉토리 나열 결과를 순회·분기할 때.
+- **FileSystemPlugin** — 저수준 Capacitor 플러그인 계약 인터페이스(옵션 객체 기반 원형). 보통 직접 쓰지 않고 `FileSystem` 래퍼를 쓰며, 커스텀 web 구현이나 옵션·반환 타입 참조가 필요할 때만 사용.
 
 ## FileSystem
 
-모든 파일 작업의 진입점. 추상 클래스의 정적 메서드 모음이라 `new` 없이 `FileSystem.메서드()` 로 호출한다. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 으로 얻은 네이티브 구현(웹은 `FileSystemWeb`)에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환한다.
+모든 파일 작업의 진입점. 추상 클래스의 정적 메서드 모음이라 인스턴스화 없이 호출한다. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 로 얻은 네이티브 구현(웹은 `FileSystemWeb`)에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환한다. 모든 메서드는 Promise 반환.
 
-- `static checkPermissions(): Promise<boolean>` — 파일 접근 권한 보유 여부 확인. true = 권한 있음, false = 없음. 웹은 항상 true. 읽기/쓰기 전 게이트로 호출. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
-- `static requestPermissions(): Promise<void>` — 권한 요청. Android 11+ 는 `MANAGE_EXTERNAL_STORAGE` 설정 화면으로 이동, Android 10- 는 권한 대화상자 표시. 웹은 무동작. `checkPermissions` 가 false 일 때 호출.
-- `static readdir(dirPath: string): Promise<FileInfo[]>` — 디렉토리 내 항목 나열. `dirPath` = 나열할 디렉토리 경로. 디렉토리가 없으면 throw. 폴더 내용을 훑을 때. 각 항목은 `FileInfo`(이름·디렉토리 여부).
-- `static getStoragePath(type: StorageType): Promise<string>` — 표준 저장소 위치의 기준 경로 문자열 조회. `type` = 어느 저장소인지(아래 StorageType). 경로를 하드코딩하지 말고 이 메서드로 베이스 경로를 얻어 join. 웹은 `/webfs/<type>` 가상 경로를 반환하며 해당 경로를 자동 생성.
-- `static getUri(filePath: string): Promise<string>` — 파일을 외부에 넘길 수 있는 URI 조회. `filePath` = 대상 파일 경로. Android 는 FileProvider content:// URI(다른 앱 공유·뷰어 인텐트용), 웹은 `URL.createObjectURL` Blob URL 반환. 웹의 Blob URL 은 사용 후 반드시 `URL.revokeObjectURL(uri)` 로 해제(미해제 시 메모리 누수). 파일이 없으면 throw.
-- `static writeFile(filePath: string, data: string | Bytes): Promise<void>` — 파일 쓰기(부모 디렉토리 자동 생성). `filePath` = 대상 경로. `data` = 문자열이면 utf8 인코딩으로, `Bytes`(Uint8Array)면 base64 로 변환해 바이너리 저장(`bytes.toBase64`, cross-realm 안전). 텍스트면 string, 바이너리면 Bytes 를 넘김.
-- `static readFile(filePath: string): Promise<Bytes>` / `static readFile(filePath: string, encoding: "utf8"): Promise<string>` — 파일 읽기 오버로드. `encoding` 생략 시 base64 로 읽어 `Bytes`(`bytes.fromBase64`) 반환(바이너리용), `"utf8"` 지정 시 텍스트 `string` 반환. 반환 타입이 오버로드로 갈리므로 바이너리는 인자 없이, 텍스트는 `"utf8"` 명시. 파일이 없으면 throw.
-- `static remove(targetPath: string): Promise<void>` — 파일/디렉토리 재귀 삭제. `targetPath` = 삭제 대상 경로(디렉토리면 하위 전체 삭제). 실패 시 throw. 정리·덮어쓰기 전 제거 시.
-- `static mkdir(targetPath: string): Promise<void>` — 디렉토리 재귀 생성. `targetPath` = 생성할 디렉토리 경로(중간 상위 경로까지 모두 생성, 이미 있으면 무동작). 쓰기 전 폴더 보장 시. (`writeFile` 은 부모를 자동 생성하므로 빈 디렉토리만 필요할 때 사용)
-- `static exists(targetPath: string): Promise<boolean>` — 경로 존재 여부 확인. true = 파일·디렉토리 존재, false = 없음. 읽기/삭제 전 분기 조건.
+- `static checkPermissions(): Promise<boolean>` — 파일 접근 권한 보유 여부. `true` = 권한 있음, `false` = 없음. 웹은 항상 `true`. 읽기/쓰기 전 게이트로 호출. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
+- `static requestPermissions(): Promise<void>` — 권한 요청. Android 11+ 는 설정 화면으로 이동, Android 10- 는 권한 대화상자 표시. 웹은 무동작. `checkPermissions()` 가 `false` 일 때 호출.
+- `static readdir(dirPath: string): Promise<FileInfo[]>` — `dirPath` 디렉토리의 직접 하위 항목을 나열. 디렉토리가 없으면 throw. 각 항목은 `FileInfo`(이름·디렉토리 여부). 폴더 내용을 훑을 때.
+- `static getStoragePath(type: StorageType): Promise<string>` — `type` 에 해당하는 표준 저장소 위치의 기준 경로 문자열. 경로를 하드코딩하지 말고 이 값으로 베이스를 얻어 join. 웹은 `/webfs/<type>` 가상 경로를 자동 생성 후 반환.
+- `static getUri(filePath: string): Promise<string>` — 파일을 외부에 넘길 수 있는 URI. Android 는 FileProvider content:// URI(타 앱 공유·뷰어 인텐트용), 웹은 `URL.createObjectURL` Blob URL. 웹의 Blob URL 은 사용 후 반드시 `URL.revokeObjectURL(uri)` 로 해제(미해제 시 메모리 누수). 파일이 없으면 throw.
+- `static writeFile(filePath: string, data: string | Bytes): Promise<void>` — 파일 쓰기(상위 디렉토리 자동 생성). `data` 가 `string` 이면 utf8 로, `Bytes`(Uint8Array)이면 base64 로 변환해 바이너리 저장(`bytes.toBase64`, cross-realm 안전). 텍스트면 문자열, 바이너리면 `Bytes` 를 넘김.
+- `static readFile(filePath: string): Promise<Bytes>` / `static readFile(filePath: string, encoding: "utf8"): Promise<string>` — 파일 읽기(오버로드). 반환 타입이 인자로 갈리므로 바이너리는 인자 없이, 텍스트는 `"utf8"` 명시. 파일이 없으면 throw.
+  - `encoding` 생략 — base64 로 읽어 `Bytes`(`bytes.fromBase64`) 반환. 이미지·바이너리 파일용.
+  - `encoding: "utf8"` — utf8 텍스트 `string` 반환. 텍스트 파일을 문자열로 바로 다룰 때.
+- `static remove(targetPath: string): Promise<void>` — 파일/디렉토리 재귀 삭제(디렉토리면 하위 전체). 실패 시 throw. 정리·덮어쓰기 전 제거 시.
+- `static mkdir(targetPath: string): Promise<void>` — 디렉토리 재귀 생성(중간 상위 경로까지, 이미 있으면 무동작). `writeFile` 은 부모를 자동 생성하므로 빈 디렉토리만 보장하면 될 때 사용.
+- `static exists(targetPath: string): Promise<boolean>` — 경로 존재 여부. `true` = 파일·디렉토리 존재, `false` = 없음. 읽기/삭제 전 분기 조건.
 
-`data` 의 `Bytes` 는 `@simplysm/core-common` 의 바이트 배열 타입(Uint8Array 계열). 텍스트는 문자열로 그대로 전달, 바이너리는 `Bytes` 로 전달하면 내부에서 base64 왕복 처리한다.
+`data` 의 `Bytes` 와 `readFile` 반환 `Bytes` 는 `@simplysm/core-common` 의 바이트 배열 타입(Uint8Array 계열). 바이너리는 내부에서 base64 왕복 처리한다.
 
 사용 예:
 
@@ -76,11 +78,11 @@ interface FileInfo {
 ```
 
 - `name: string` — 항목 이름(경로가 아닌 파일/디렉토리명). 표시·필터·경로 결합 시.
-- `isDirectory: boolean` — 디렉토리 여부. true = 하위 디렉토리(재귀 탐색 대상), false = 파일. 파일만 처리할지 폴더로 내려갈지 분기할 때.
+- `isDirectory: boolean` — 디렉토리 여부. `true` = 하위 디렉토리(재귀 탐색 대상), `false` = 파일. 파일만 처리할지 폴더로 내려갈지 분기할 때.
 
 ## FileSystemPlugin
 
-저수준 Capacitor 플러그인 인터페이스. `FileSystem` 정적 메서드가 내부에서 위임하는 원형으로, 메서드가 옵션 객체(`{ path }`, `{ type }`, `{ path, data, encoding }`)를 받고 결과도 래핑 객체(`{ granted }`, `{ files }`, `{ path }`, `{ uri }`, `{ data }`, `{ exists }`)로 반환한다. 보통 직접 호출하지 않으며, 커스텀 web 구현(`FileSystemPlugin` 구현)을 작성하거나 옵션/반환 타입을 참조해야 할 때만 사용한다.
+저수준 Capacitor 플러그인 계약 인터페이스. `FileSystem` 정적 메서드가 내부에서 위임하는 원형으로, 메서드가 옵션 객체(`{ path }`, `{ type }`, `{ path, data, encoding }`)를 받고 결과도 래핑 객체(`{ granted }`, `{ files }`, `{ path }`, `{ uri }`, `{ data }`, `{ exists }`)로 반환한다. 보통 직접 호출하지 않으며, 커스텀 web 구현(`FileSystemPlugin` 구현)을 작성하거나 옵션·반환 타입을 참조해야 할 때만 사용한다.
 
 - `checkPermissions(): Promise<{ granted: boolean }>` — 권한 보유 여부를 `granted` 로 반환.
 - `requestPermissions(): Promise<void>` — 권한 요청.

package/claude/references/sd-simplysm14/apis/capacitor-plugin-intent/README.md

@@ -1,44 +1,49 @@
 # @simplysm/capacitor-plugin-intent
 
-Android 인텐트(Intent) 송수신 Capacitor 플러그인. 브로드캐스트 수신/전송, 실행 인텐트 조회, newIntent 이벤트 리스닝, `startActivityForResult` 외부 Activity 실행·결과 수신을 다룸. 산업용 디바이스(바코드 스캐너·PDA 등, 예: Zebra DataWedge) 연동에 사용. 웹 환경(`IntentWeb`)에서는 실제 동작 없이 경고만 로깅하고 무해한 기본값을 반환하므로 실제 인텐트 처리는 Android 네이티브에서만 일어남.
+Android 인텐트 송수신 Capacitor 플러그인. 정적 클래스 `Intent` 로 브로드캐스트 구독/전송·실행 인텐트 조회·newIntent 리스닝·startActivityForResult 외부 Activity 실행을 수행한다. 바코드 스캐너·PDA(예: Zebra DataWedge) 등 산업용 디바이스 연동 시 사용. 웹 환경(`IntentWeb` 스텁)에서는 실제 동작 없이 경고 로그만 남기고 무해한 기본값을 반환하므로 실제 인텐트 처리는 Android 네이티브에서만 일어난다.
 
 ## 사용 트리거 인덱스
 
-- **Intent** — 인텐트 작업의 정적 진입점(추상 클래스). 브로드캐스트 구독/전송, 실행 인텐트 조회, newIntent 리스너 등록, 외부 Activity 실행을 할 때. 아래 인라인 섹션 참조.
-- **IntentResult / StartActivityForResultOptions / StartActivityForResultResult** — `Intent` 메서드의 입출력 타입. 콜백 결과·실행 옵션·반환값을 타입으로 다룰 때. 아래 인라인 섹션 참조.
-- **IntentPlugin** — `registerPlugin` 에 쓰이는 Capacitor 네이티브 플러그인 계약. 보통 직접 호출하지 않고 `Intent` 정적 메서드를 거치며, 웹 스텁·네이티브 구현의 저수준 계약 확인용. 아래 인라인 섹션 참조.
+- **Intent** — 인텐트 작업의 정적 진입점(추상 클래스). 브로드캐스트 수신기 등록/해제(`subscribe`/`unsubscribeAll`), 브로드캐스트 전송(`send`), 앱 실행 인텐트 조회(`getLaunchIntent`), 실행 중 새 인텐트 리스닝(`addListener`/`removeAllListeners`), 외부 Activity 실행 후 결과 수신(`startActivityForResult`) 이 필요할 때. 아래 인라인 섹션 참조.
+- **결과·옵션 타입** (`IntentResult`, `StartActivityForResultOptions`, `StartActivityForResultResult`) — `Intent` 메서드의 콜백 인자·반환·실행 옵션을 타입으로 다룰 때. 아래 인라인 섹션 참조.
+- **IntentPlugin** — `registerPlugin` 에 쓰이는 Capacitor 네이티브 플러그인 저수준 계약. 보통 직접 호출하지 않고 `Intent` 정적 메서드를 거치며, 네이티브 구현·웹 스텁의 계약 확인용. 아래 인라인 섹션 참조.
 
 ## Intent (정적 클래스)
 
-`abstract class Intent` — 정적 메서드만 가진 진입점. 인스턴스화하지 않고 `Intent.xxx()` 형태로 호출하며 모든 메서드는 비동기(`Promise`). 내부적으로 `registerPlugin<IntentPlugin>("Intent")` 로 얻은 플러그인(웹은 `IntentWeb`)을 래핑.
+`abstract class Intent` — 정적 메서드만 가진 진입점. 인스턴스화하지 않고 `Intent.xxx()` 형태로 호출하며 모든 메서드는 비동기(`Promise`). 내부적으로 `registerPlugin<IntentPlugin>("Intent")` 로 얻은 플러그인(웹은 `IntentWeb`)을 래핑한다.
 
-- `Intent.subscribe(filters: string[], callback: (result: IntentResult) => void): Promise<() => Promise<void>>` — 브로드캐스트 수신기 등록.
+- `Intent.subscribe(filters: string[], callback: (result: IntentResult) => void): Promise<() => Promise<void>>` — 브로드캐스트 수신기를 등록하고, 호출하면 해당 구독만 해제하는 함수를 resolve.
   - `filters: string[]` — 수신할 인텐트 액션 문자열 배열(예: `"com.symbol.datawedge.api.RESULT_ACTION"`). 이 액션들로 들어오는 브로드캐스트만 콜백으로 전달. 스캐너 결과 액션 등 수신 대상 액션을 등록할 때 지정.
-  - `callback: (result: IntentResult) => void` — 매칭 브로드캐스트 도착 시마다 호출. 등록 직후 플러그인이 보내는 `{ id }` 만 담긴 초기 resolve(`result.action == null`)는 내부에서 걸러져 호출되지 않음(실제 수신 시점에만 호출).
-  - 반환: 구독 해제 함수 `() => Promise<void>`. 호출 시 내부 `id` 로 해당 수신기만 해제. 화면 진입 시 등록하고 이탈 시 반환 함수로 해제.
-- `Intent.unsubscribeAll(): Promise<void>` — 등록된 모든 브로드캐스트 수신기를 한 번에 해제. 개별 해제 함수를 보관하지 않았거나 화면 정리 시 전체를 일괄 정리할 때.
-- `Intent.send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>` — 브로드캐스트 전송.
+  - `callback: (result: IntentResult) => void` — 매칭 브로드캐스트 도착 시마다 호출. 등록 직후 플러그인이 보내는 `{ id }` 만 담긴 초기 resolve(`result.action == null`)는 내부에서 걸러져 호출되지 않으며, `action` 이 채워진 실제 수신 시점에만 호출.
+  - 반환: 구독 해제 함수 `() => Promise<void>`. `await` 한 결과가 이 함수이며 호출(다시 `await`) 시 내부 `id` 로 해당 수신기만 해제. 화면 진입 시 등록하고 이탈 시 반환 함수로 해제하는 용도.
+- `Intent.unsubscribeAll(): Promise<void>` — 등록된 모든 브로드캐스트 수신기를 한 번에 해제. 개별 해제 함수를 보관하지 않았거나 화면 정리 시 전체를 일괄로 끊을 때.
+- `Intent.send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>` — 브로드캐스트 전송. 스캐너 트리거 토글 등 디바이스 제어 명령 송신에 사용.
   - `action: string` — 전송할 인텐트 액션 문자열(필수). 디바이스 API 가 정의한 명령 액션을 지정.
   - `extras?: Record<string, unknown>` — 함께 보낼 추가 키-값 데이터(선택). 명령 파라미터(예: 스캐너 트리거 토글 값)를 담을 때.
-- `Intent.getLaunchIntent(): Promise<IntentResult>` — 앱을 실행시킨 인텐트 조회. 외부 인텐트로 앱이 기동됐는지·그 `extras` 를 앱 시작 시점에 읽을 때. 웹 스텁은 항상 빈 객체 `{}` 반환.
-- `Intent.addListener(eventName: "newIntent", callback: (result: IntentResult) => void): Promise<PluginListenerHandle>` — 앱 실행 중 새로 들어오는 인텐트 리스너 등록.
+- `Intent.getLaunchIntent(): Promise<IntentResult>` — 앱을 실행시킨 인텐트(action·extras)를 조회. 외부 인텐트로 앱이 기동됐는지·그 `extras` 를 앱 시작 시점에 읽을 때. 웹 스텁은 항상 빈 객체 `{}` 반환.
+- `Intent.addListener(eventName: "newIntent", callback: (result: IntentResult) => void): Promise<PluginListenerHandle>` — 앱이 이미 실행 중인 상태에서 새로 도착하는 인텐트(`onNewIntent`)를 리스닝.
   - `eventName: "newIntent"` — 리스닝 대상 이벤트(현재 이 리터럴 하나만 지원). 이미 떠 있는 앱에 인텐트가 재전달되는 singleTop 등 상황에서 발생.
-  - `callback: (result: IntentResult) => void` — 새 인텐트 수신 시 호출. 들어온 인텐트의 `action`·`extras` 를 받음.
+  - `callback: (result: IntentResult) => void` — 새 인텐트 수신 시 호출. `subscribe` 와 달리 액션 필터 없이 들어오는 새 인텐트의 `action`·`extras` 를 받음.
   - 반환: `PluginListenerHandle`(@capacitor/core). `handle.remove()` 로 이 리스너만 개별 해제.
-- `Intent.removeAllListeners(): Promise<void>` — `addListener` 로 등록한 모든 이벤트 리스너를 일괄 제거. subscribe(브로드캐스트 수신기)와는 별개 채널이므로 둘 다 쓰면 각각 정리해야 함.
-- `Intent.startActivityForResult(options: StartActivityForResultOptions): Promise<StartActivityForResultResult>` — 외부 Activity 를 실행하고 결과를 `await` 로 직접 수신. 결제·서명 등 외부 앱에 1회성 작업을 위임하고 응답을 되받아야 할 때. 반환 `resultCode` 로 성공 판정(Android 규약상 `-1` = RESULT_OK, `0` = RESULT_CANCELED). 옵션·결과 필드는 아래 "입출력 타입" 참조.
+- `Intent.removeAllListeners(): Promise<void>` — `addListener` 로 등록한 모든 이벤트 리스너를 일괄 제거. `subscribe`(브로드캐스트 수신기)와는 별개 채널이므로 둘 다 쓰면 각각 정리해야 함.
+- `Intent.startActivityForResult(options: StartActivityForResultOptions): Promise<StartActivityForResultResult>` — 외부 Activity 를 실행하고 그 결과 코드·데이터를 `await` 로 직접 수신. 결제·서명 등 외부 앱에 1회성 작업을 위임하고 응답을 되받아야 할 때. 반환 `resultCode` 로 성공 판정(Android 규약상 `-1` = RESULT_OK, `0` = RESULT_CANCELED). 옵션·결과 필드는 아래 "결과·옵션 타입" 참조.
+
+`subscribe`/`unsubscribeAll` 은 구독 핸들로 끊거나 일괄로 끊는 두 경로를 제공하므로, 화면별로는 `subscribe` 의 반환 함수를, 전역 정리에는 `unsubscribeAll` 을 쓴다. `addListener`/`removeAllListeners` 는 newIntent 이벤트용 동일 패턴이며 브로드캐스트 수신기와 별개 채널이다.
 
 사용 예:
 
 ```ts
+// 바코드 스캐너 결과 브로드캐스트 구독
 const unsub = await Intent.subscribe(
   ["com.symbol.datawedge.api.RESULT_ACTION"],
   (result) => console.log(result.action, result.extras),
 );
+// 스캐너 트리거 토글 전송
 await Intent.send({
   action: "com.symbol.datawedge.api.ACTION",
   extras: { "com.symbol.datawedge.api.SOFT_SCAN_TRIGGER": "TOGGLE_SCANNING" },
 });
+// 외부 Activity 실행 후 결과 수신
 const res = await Intent.startActivityForResult({ action: "com.example.PAY", extras: { amount: 1000 } });
 if (res.resultCode === -1) { /* RESULT_OK */ }
 await unsub(); // 개별 해제
@@ -46,7 +51,7 @@ await unsub(); // 개별 해제
 
 주의: 웹 플랫폼(`IntentWeb`)에서는 `subscribe`·`send`·`startActivityForResult` 가 실제 동작 없이 경고 로그(`createLogger("capacitor:intent")` → `"웹 환경에서는 지원하지 않습니다."`)만 남긴다. 이때 `subscribe` 는 `{ id: "web-stub" }`(콜백 미호출), `getLaunchIntent` 는 `{}`(경고 없음), `startActivityForResult` 는 `{ resultCode: 0 }`(항상 CANCELED 로 보임)을 반환하고, `unsubscribe`·`unsubscribeAll` 은 무동작. 웹·하이브리드 공용 코드에서 호출해도 예외는 나지 않으나 인텐트 동작은 Android 에서만 발생함을 전제로 작성할 것.
 
-## 입출력 타입
+## 결과·옵션 타입
 
 `Intent` 메서드의 결과·옵션을 타입으로 다룰 때 참조하는 인터페이스. "값 없음"은 그대로 `undefined` 로 전달되므로 호출부에서 optional 로 다룰 것.
 
@@ -60,7 +65,7 @@ await unsub(); // 개별 해제
   - `type?: string` — MIME 타입. 데이터 형식으로 처리 대상 앱을 좁힐 때.
   - `packageName?: string` — 실행할 특정 앱 패키지명. 명시적 인텐트화(특정 앱으로만 실행)할 때.
   - `className?: string` — 실행할 특정 Activity 클래스명. `packageName` 과 함께 컴포넌트를 직접 지정할 때.
-  - `flags?: number` — Android Intent flags 비트값. 실행 모드(새 태스크 시작 등) 제어가 필요할 때.
+  - `flags?: number` — Android Intent flags 비트값(`Intent.FLAG_*`). 실행 모드(새 태스크 시작 등) 제어가 필요할 때.
 - `StartActivityForResultResult` — `startActivityForResult` 반환.
   - `resultCode: number` — Activity 결과 코드(필수). Android 규약상 `-1` = RESULT_OK, `0` = RESULT_CANCELED. 성공/취소 분기 판단에 사용(웹 스텁은 항상 `0`).
   - `data?: { action?: string; uri?: string; extras?: Record<string, unknown> }` — 결과 인텐트 데이터(선택, 결과 없으면 부재). `action` = 결과 인텐트 액션, `uri` = 결과 data URI, `extras` = 결과 추가 데이터. 결과 본문은 `data?.extras` 형태로 접근.
@@ -70,7 +75,7 @@ await unsub(); // 개별 해제
 `interface IntentPlugin` — `registerPlugin<IntentPlugin>("Intent")` 에 쓰이는 Capacitor 네이티브 플러그인 계약. 웹 구현(`IntentWeb`)과 Android 네이티브가 이를 구현. 일반 사용 코드는 `Intent` 정적 메서드를 쓰고 이 인터페이스를 직접 호출하지 않으며, 네이티브 구현·웹 스텁이 충족해야 할 저수준 계약을 확인할 때만 참조.
 
 - `subscribe(options: { filters: string[] }, callback: (result: IntentResult) => void): Promise<{ id: string }>` — 수신기 등록 후 해제용 `id` 반환. `Intent.subscribe` 가 이 `id` 를 클로저로 보관해 반환 함수에서 `unsubscribe` 에 넘김.
-- `unsubscribe(options: { id: string }): Promise<void>` — 주어진 `id` 의 수신기만 해제.
+- `unsubscribe(options: { id: string }): Promise<void>` — 주어진 `id` 의 수신기만 해제. 단일 구독 해제는 `IntentPlugin` 에만 있고 `Intent` 클래스에서는 `subscribe` 가 돌려주는 해제 함수로 대체됨.
 - `unsubscribeAll(): Promise<void>` — 모든 수신기 해제.
 - `send(options: { action: string; extras?: Record<string, unknown> }): Promise<void>` — 브로드캐스트 전송.
 - `getLaunchIntent(): Promise<IntentResult>` — 실행 인텐트 조회.

package/claude/references/sd-simplysm14/apis/capacitor-plugin-usb-storage/README.md

@@ -1,21 +1,26 @@
 # @simplysm/capacitor-plugin-usb-storage
 
-Capacitor 플러그인. 연결된 USB Mass Storage 장치를 열거하고 권한을 얻은 뒤 디렉토리/파일을 읽는다. Android 는 libaums 네이티브 구현, 브라우저는 IndexedDB 기반 가상 USB 저장소로 에뮬레이션된다. entry 가 노출하는 심볼은 정적 클래스 `UsbStorage` 와 입출력 타입 4종.
+연결된 USB Mass Storage 장치를 열거하고, 장치별 접근 권한을 확인·요청한 뒤 디렉토리·파일을 읽는 Capacitor 플러그인. Android 는 libaums 라이브러리로 USB Mass Storage 에 접근하고, 웹은 IndexedDB 기반 가상 USB 저장소(`capacitor_usb_virtual_storage` DB)로 동일 API 를 에뮬레이션한다. 모든 호출은 `vendorId`/`productId` 조합(`UsbDeviceFilter`)으로 대상 장치를 지정하며, `UsbStorage` 정적 메서드가 진입점이다.
 
 ## 사용 트리거 인덱스
 
-- **UsbStorage** — USB 저장 장치 접근의 진입점. "장치 목록 조회 → 권한 확인/요청 → readdir/readFile" 흐름을 정적 메서드로 호출할 때.
-- **UsbDeviceInfo / UsbDeviceFilter / UsbFileInfo / UsbStoragePlugin** — 위 메서드의 입출력 타입. 장치 식별(vendorId/productId), 반환 항목(`name`/`isDirectory`) 형태를 다룰 때 참조.
+- **UsbStorage** — 앱에서 USB 저장 장치를 다룰 때의 진입점. 장치 목록 조회·권한 확인/요청·디렉토리 나열·파일 읽기 전반. 모든 메서드가 `static async` 이며 인스턴스화 불필요(abstract class).
+- **UsbDeviceFilter** — `requestPermissions`/`checkPermissions`/`readdir`/`readFile` 의 대상 장치 지정 인자. `getDevices` 로 얻은 장치 중 하나를 vendorId/productId 로 가리킬 때.
+- **UsbDeviceInfo** — `getDevices` 결과 항목 타입. 연결된 장치를 표시·선택하거나 거기서 filter 를 만들 때.
+- **UsbFileInfo** — `readdir` 결과 항목 타입. 디렉토리 나열 결과를 순회·필터할 때.
+- **UsbStoragePlugin** — 저수준 Capacitor 플러그인 인터페이스(옵션 객체 기반 원형). 보통 직접 쓰지 않고 `UsbStorage` 래퍼를 쓰며, 커스텀 네이티브/web 구현이나 옵션·반환 타입 참조가 필요할 때만 사용.
 
 ## UsbStorage
 
-`abstract class` 이며 모든 멤버가 `static` — 인스턴스화하지 않고 `UsbStorage.메서드()` 로 호출한다. 내부적으로 `registerPlugin<UsbStoragePlugin>("UsbStorage")` 로 얻은 네이티브(Android)/웹 구현에 위임하고, 래퍼 객체(`{ devices }`·`{ granted }`·`{ files }`·`{ data }`)에서 값을 꺼내 평탄화해 반환한다. 대상 장치는 항상 `UsbDeviceFilter`(= `{ vendorId, productId }`) 로 지정하며 readdir/readFile 도 매 호출마다 filter 를 받는다(상태 없음).
+모든 USB 저장 작업의 진입점. 추상 클래스의 정적 메서드 모음이라 `new` 없이 `UsbStorage.메서드()` 로 호출한다. 내부적으로 `registerPlugin<UsbStoragePlugin>("UsbStorage")` 로 얻은 네이티브 구현(웹은 `UsbStorageWeb`)에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환한다. 대상 장치는 항상 `UsbDeviceFilter`(`{ vendorId, productId }`) 로 지정하며 readdir/readFile 도 매 호출마다 filter 를 받는다(상태 없음).
 
-- `static getDevices(): Promise<UsbDeviceInfo[]>` — 현재 연결된 USB 장치 목록 조회. 권한과 무관하게 열거되며, 반환 항목의 `vendorId`/`productId` 를 추려 이후 호출의 filter 로 사용. 흐름의 첫 단계.
-- `static requestPermissions(filter: UsbDeviceFilter): Promise<boolean>` — 지정 장치 접근 권한을 사용자에게 요청(다이얼로그). 반환 true=승인, false=거부(이때 읽기 중단). 권한이 없을 때 읽기 직전 호출. 브라우저 웹 구현은 항상 true 를 반환.
-- `static checkPermissions(filter: UsbDeviceFilter): Promise<boolean>` — 다이얼로그 없이 현재 권한 보유 여부만 확인. true=이미 보유(requestPermissions 생략 가능), false=미보유(요청 필요). 권한이 이미 있을 때 요청을 건너뛰려는 분기 기준. 브라우저 웹 구현은 항상 true 를 반환.
-- `static readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>` — 지정 장치의 `dirPath`(읽을 디렉토리 경로, 루트는 `"/"`) 바로 아래 항목 목록 조회. 각 항목은 `name`+`isDirectory` 로 파일/폴더 구분. 트리를 순회하려면 `isDirectory === true` 인 항목을 다시 readdir. 웹 구현은 장치가 없거나 대상이 디렉토리가 아니면 빈 배열.
-- `static readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>` — 지정 장치의 `filePath`(읽을 파일 경로) 내용을 `Bytes`(`@simplysm/core-common`) 로 읽음. 파일이 없거나 네이티브가 데이터 없음(`null`)을 주면 `undefined` 반환 — "빈 파일" 과 "없음" 을 구분하려면 이 `undefined` 를 그대로 검사(`""`·기본값 치환 금지). 내부에서 base64 응답을 `bytes.fromBase64` 로 복원.
+- `static getDevices(): Promise<UsbDeviceInfo[]>` — 현재 연결된 USB 장치 목록 조회. 빈 배열이면 연결된 장치 없음. 권한과 무관하게 열거되며, 반환 항목의 `vendorId`/`productId` 를 추려 이후 호출의 filter 로 사용. 목록 UI 를 채우거나 흐름의 첫 단계에서 호출. 플러그인의 `{ devices }` 를 배열로 풀어 반환.
+- `static checkPermissions(filter: UsbDeviceFilter): Promise<boolean>` — 다이얼로그 없이 지정 장치 접근 권한 보유 여부만 확인. true = 이미 보유(requestPermissions 생략 가능), false = 미보유(요청 필요). 웹은 항상 true. `readdir`/`readFile` 전 게이트로 호출. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
+- `static requestPermissions(filter: UsbDeviceFilter): Promise<boolean>` — 지정 장치 접근 권한을 사용자에게 요청(다이얼로그). true = 승인, false = 거부(이때 읽기 중단). 웹은 항상 true. `checkPermissions` 가 false 일 때 호출. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
+- `static readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>` — 지정 장치의 디렉토리 항목 나열. `filter` = 대상 장치, `dirPath` = 나열할 디렉토리 경로(루트는 `"/"`). 각 항목은 `UsbFileInfo`(이름·디렉토리 여부)로, 트리를 순회하려면 `isDirectory === true` 인 항목을 다시 readdir. 폴더 내용을 훑을 때. 플러그인의 `{ files }` 를 배열로 풀어 반환.
+- `static readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>` — 지정 장치의 파일 읽기. `filter` = 대상 장치, `filePath` = 읽을 파일 경로. 플러그인이 base64 문자열로 준 데이터를 `bytes.fromBase64` 로 `Bytes`(Uint8Array 계열)로 디코드해 반환. 파일이 없거나 데이터가 `null` 이면 `undefined`(결측 그대로 전파 — `""`·기본값 치환 금지). 읽은 바이너리를 가공·저장할 때.
+
+반환 `Bytes` 는 `@simplysm/core-common` 의 바이트 배열 타입. 플러그인 레벨에서는 base64 문자열로 주고받고, `UsbStorage.readFile` 가 base64 ↔ `Bytes` 변환을 담당한다.
 
 사용 예:
 
@@ -32,31 +37,66 @@ if (!(await UsbStorage.checkPermissions(filter))) {
 
 for (const entry of await UsbStorage.readdir(filter, "/")) {
   if (entry.isDirectory) continue; // 폴더면 하위 readdir 로 순회
-  const data = await UsbStorage.readFile(filter, `/${entry.name}`);
+  const data = await UsbStorage.readFile(filter, `/${entry.name}`); // Bytes | undefined
   if (data === undefined) continue; // 파일 없음/데이터 없음
   // data: Bytes 사용
 }
 ```
 
-## 입출력 타입
-
-`UsbStoragePlugin` 은 Capacitor 가 `registerPlugin<UsbStoragePlugin>("UsbStorage")` 로 등록하는 네이티브 측 계약이며, 위 `UsbStorage` 정적 메서드가 이를 1:1 로 감싸 쓰기 쉬운 형태(배열·boolean·Bytes)로 변환한다. 보통 직접 호출하지 않고 타입 참조용으로만 본다.
-
-- `UsbDeviceInfo` — `getDevices()` 가 돌려주는 장치 정보 1건.
-  - `deviceName: string` — OS 가 부여한 장치 시스템 이름. 화면 표시·로그용.
-  - `manufacturerName: string` — 제조사 이름. 사용자에게 장치를 식별시키거나 동일 제품명을 구분할 때.
-  - `productName: string` — 제품 이름. 사용자에게 어떤 장치인지 보여줄 때.
-  - `vendorId: number` — USB 벤더 ID. 이후 filter 의 `vendorId` 로 그대로 사용.
-  - `productId: number` — USB 제품 ID. `vendorId` 와 조합해 장치를 유일하게 지정, 이후 filter 의 `productId` 로 그대로 사용.
-- `UsbDeviceFilter` — 접근 대상 장치를 지정하는 키. 권한·읽기 메서드 모두 이 형태를 받음. 보통 `UsbDeviceInfo` 에서 두 ID 만 추려 만듦.
-  - `vendorId: number` — 대상 장치 벤더 ID. `UsbDeviceInfo.vendorId` 를 그대로 넘김.
-  - `productId: number` — 대상 장치 제품 ID. `UsbDeviceInfo.productId` 를 그대로 넘김.
-- `UsbFileInfo` — `readdir()` 가 돌려주는 디렉토리 항목 1건.
-  - `name: string` — 파일/폴더 이름(경로가 아닌 단일 세그먼트). readFile/하위 readdir 경로를 만들 때 부모 경로에 이어붙임.
-  - `isDirectory: boolean` — 디렉토리 여부. true 면 폴더(다시 readdir 대상), false 면 파일(readFile 대상). 트리 순회·파일 필터링의 분기 기준.
-- `UsbStoragePlugin` — Capacitor `registerPlugin` 대상 인터페이스. `UsbStorage` 가 평탄화하기 전의 원형 시그니처로, 메서드는 옵션 객체 입력 / 래퍼 객체 출력을 가짐.
-  - `getDevices(): Promise<{ devices: UsbDeviceInfo[] }>` — 장치 목록을 `devices` 키로 반환.
-  - `requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>` — 권한 요청 결과를 `granted` 로 반환.
-  - `checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>` — 권한 보유 여부를 `granted` 로 반환.
-  - `readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>` — filter 에 `path`(대상 디렉토리 경로)를 합친 입력으로 항목을 `files` 로 반환.
-  - `readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>` — filter 에 `path`(대상 파일 경로)를 합친 입력으로 파일을 base64 문자열 `data` 로 반환. 데이터 없으면 `null`(상위 `UsbStorage.readFile` 가 `undefined` 로 변환).
+## UsbDeviceFilter
+
+권한 메서드와 `readdir`/`readFile` 가 대상 장치를 가리키는 데 쓰는 식별 인자. 보통 `getDevices` 결과 항목의 `vendorId`/`productId` 를 그대로 옮겨 만든다.
+
+```ts
+interface UsbDeviceFilter {
+  vendorId: number;
+  productId: number;
+}
+```
+
+- `vendorId: number` — 대상 USB 장치 벤더 ID(제조사 식별 코드). `UsbDeviceInfo.vendorId` 를 그대로 넘김. 같은 제조사여도 모델 구분은 `productId` 로.
+- `productId: number` — 대상 USB 장치 제품 ID(모델 식별 코드). `UsbDeviceInfo.productId` 를 그대로 넘김. `vendorId` 와 조합해 하나의 장치를 특정(웹 구현은 `${vendorId}:${productId}` 를 장치 키로 사용).
+
+## UsbDeviceInfo
+
+`getDevices` 가 반환하는 연결 장치 1건. 표시·선택용 메타데이터에 더해 `UsbDeviceFilter` 를 만들 두 ID 를 포함한다.
+
+```ts
+interface UsbDeviceInfo {
+  deviceName: string;
+  manufacturerName: string;
+  productName: string;
+  vendorId: number;
+  productId: number;
+}
+```
+
+- `deviceName: string` — OS 가 부여한 장치 시스템 이름(식별 문자열). 디버깅·로그·표시용.
+- `manufacturerName: string` — 제조사 표시명. 사람이 읽는 장치 라벨을 만들거나 동일 제품명을 구분할 때.
+- `productName: string` — 제품 표시명. 목록 UI 의 장치 항목 라벨에 사용.
+- `vendorId: number` — 벤더 ID. 이 값을 `UsbDeviceFilter.vendorId` 로 옮겨 권한·읽기 호출에 사용.
+- `productId: number` — 제품 ID. 이 값을 `UsbDeviceFilter.productId` 로 옮겨 권한·읽기 호출에 사용.
+
+## UsbFileInfo
+
+`readdir` 가 반환하는 디렉토리 항목 1건.
+
+```ts
+interface UsbFileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
+- `name: string` — 항목 이름(경로가 아닌 단일 세그먼트의 파일/디렉토리명). readFile·하위 readdir 경로를 만들 때 부모 경로에 이어붙임.
+- `isDirectory: boolean` — 디렉토리 여부. true = 하위 디렉토리(다시 readdir 대상), false = 파일(readFile 대상). 트리 순회·파일 필터링의 분기 기준.
+
+## UsbStoragePlugin
+
+저수준 Capacitor 플러그인 인터페이스. `UsbStorage` 정적 메서드가 내부에서 위임하는 원형으로, 메서드가 옵션 객체(`UsbDeviceFilter`, 또는 거기에 `path` 를 더한 형태)를 받고 결과도 래핑 객체(`{ devices }`·`{ granted }`·`{ files }`·`{ data }`)로 반환한다. 보통 직접 호출하지 않으며, 커스텀 web 구현(`UsbStoragePlugin` 구현)을 작성하거나 옵션/반환 타입을 참조해야 할 때만 사용한다.
+
+- `getDevices(): Promise<{ devices: UsbDeviceInfo[] }>` — 연결 장치 목록을 `devices` 로 반환.
+- `requestPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>` — `options` 장치의 권한 요청 결과를 `granted` 로 반환(true=승인).
+- `checkPermissions(options: UsbDeviceFilter): Promise<{ granted: boolean }>` — `options` 장치의 권한 보유 여부를 `granted` 로 반환(true=보유).
+- `readdir(options: UsbDeviceFilter & { path: string }): Promise<{ files: UsbFileInfo[] }>` — filter 에 `path`(나열할 디렉토리 경로)를 합친 입력으로 항목 목록을 `files` 로 반환.
+- `readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>` — filter 에 `path`(읽을 파일 경로)를 합친 입력으로 파일을 base64 문자열 `data` 로 반환. 파일이 없거나 데이터 없음이면 `data` 가 `null`(래퍼 `UsbStorage.readFile` 이 이를 `undefined` 로 변환).

package/claude/references/sd-simplysm14/apis/core-browser/README.md

@@ -1,18 +1,18 @@
 # @simplysm/core-browser
 
-브라우저 전용 유틸리티 묶음. DOM 요소 탐색·위치 계산·가시성 판정 확장, IndexedDB 영속화 및 그 위의 가상 파일시스템, 파일 다운로드·선택 헬퍼를 제공.
+브라우저 전용 유틸리티 — DOM 요소 탐색·위치 계산·가시성 확장, IndexedDB 영속화 및 가상 파일시스템, Blob 다운로드·URL 바이너리 수신·파일 선택 대화상자.
 
-> 패키지의 어떤 심볼이든 import 하면 `index.ts` 가 `import "./extensions/element-ext"`·`"./extensions/html-element-ext"` 를 실행해 `Element`/`HTMLElement` 프로토타입 확장이 사이드 이펙트로 자동 등록됨. 별도 초기화 없이 `el.findAll(...)` 식으로 호출 가능.
+이 패키지의 심볼을 하나라도 import 하면 `index.ts` 가 `element-ext`/`html-element-ext` 를 사이드 이펙트로 실행해 `Element`/`HTMLElement` 프로토타입 확장 메서드가 전역에서 자동 활성화된다(별도 초기화 불필요).
 
 ## 사용 트리거 인덱스
 
-- **DOM 요소 확장·헬퍼** — DOM 조회(`findAll`/`findFirst`), 조상/탭 이동 가능 요소 탐색, offset·가시성 판정, 부모 기준 상대 좌표 계산, 가림 보정 스크롤, 강제 리페인트, 클립보드 복사/붙여넣기 핸들러, 다중 요소 경계 측정이 필요할 때. 자세히: [dom-element.md](./dom-element.md)
-- **IndexedDB 영속화** (`IndexedDbStore`, `IndexedDbVirtualFs`) — 브라우저 IndexedDB 에 KV 영구 저장하거나, 그 위에 경로 키 기반 가상 파일트리(파일/디렉터리)를 올릴 때. 자세히: [indexed-db.md](./indexed-db.md)
-- **downloadBlob / fetchUrlBytes / openFileDialog** — 생성한 Blob 을 파일로 저장하거나, 진행률을 보며 URL 바이너리를 받거나, 파일 선택 대화상자를 코드로 열 때. (아래 인라인 섹션)
+- **DOM 요소 확장** — DOM 조회(findAll/findFirst)·조상/자식 순회·탭 이동 대상 탐색·offset/가시성 판정·부모 기준 상대 좌표 계산·가림 보정 스크롤·강제 리페인트·클립보드 복사/붙여넣기 핸들러·다중 요소 경계 측정이 필요할 때. 자세히: [dom-element.md](./dom-element.md)
+- **IndexedDB 영속화** — 브라우저 IndexedDB 에 키-값을 영구 저장(IndexedDbStore)하거나, 그 위에 경로 키 기반 가상 파일트리(IndexedDbVirtualFs)를 올릴 때. 자세히: [indexed-db.md](./indexed-db.md)
+- **파일 입출력** — 메모리 Blob 을 파일로 내려받거나(downloadBlob), URL 에서 진행률과 함께 바이너리를 받거나(fetchUrlBytes), 파일 선택 대화상자를 코드로 열 때(openFileDialog). 아래 인라인 섹션 참조.
 
-## 파일·다운로드 유틸
+## 파일 입출력
 
-생성한 데이터를 파일로 내보내거나, 외부 바이너리를 받거나, 사용자에게 파일을 고르게 할 때 쓰는 단발성 함수들.
+데이터를 파일로 내보내거나, 외부 바이너리를 받거나, 사용자에게 파일을 고르게 하는 단발성 함수 묶음.
 
 ### downloadBlob
 
@@ -20,10 +20,10 @@
 function downloadBlob(blob: Blob, fileName: string): void;
 ```
 
-Blob 을 object URL 로 만들어 동적 `a[download]` 클릭으로 저장하고, object URL 은 1초 뒤 revoke. 클릭 직후 함수가 반환됨(다운로드 완료를 기다리지 않음). 화면 다운로드 버튼 핸들러에서 즉시 저장할 때.
+Blob 을 object URL 로 만들어 동적 `a[download]` 클릭으로 저장하고, object URL 은 1초 뒤 revoke 한다. 클릭 직후 반환되며 다운로드 완료를 기다리지 않는다. 다운로드 버튼 핸들러에서 즉시 저장할 때.
 
-- blob: Blob — 저장할 데이터. 엑셀·이미지·텍스트 등 메모리에서 만든 Blob 을 그대로 전달.
-- fileName: string — 저장 파일명. `sanitize-filename` 으로 OS 금지 문자·예약어를 제거한 뒤 추가로 `[`·`]` 도 제거하며, 결과가 빈 문자열이면 `"download"` 로 대체. 확장자 포함, 사용자 입력 파일명을 그대로 넣어도 안전.
+- `blob: Blob` — 저장할 데이터. 엑셀·이미지·텍스트 등 메모리에서 만든 Blob 을 그대로 전달.
+- `fileName: string` — 저장 파일명. `sanitize-filename` 으로 OS 금지 문자·예약어를 제거한 뒤 추가로 `[`·`]` 도 제거하며, 결과가 빈 문자열이면 `"download"` 로 대체. 확장자 포함, 사용자 입력 파일명을 그대로 넣어도 안전.
 
 ```ts
 downloadBlob(new Blob([buf], { type: "application/pdf" }), "보고서[2026].pdf");
@@ -39,12 +39,12 @@ function fetchUrlBytes(
 ): Promise<Uint8Array>;
 ```
 
-URL 바이너리를 스트림 reader 로 다운로드하며 진행률을 보고. 큰 파일을 진행 바와 함께 받을 때.
+URL 바이너리를 스트림 reader 로 다운로드하며 진행률을 보고한다. 큰 파일을 진행 바와 함께 받을 때.
 
-- url: string — 다운로드 대상 URL. `response.ok` 가 아니면 `Error("다운로드 실패: <status> <statusText>")`, 본문 reader 가 없으면 `Error("응답 본문을 읽을 수 없습니다")` throw.
-- options.onProgress: (progress: DownloadProgress) => void — 청크 수신마다 호출되는 진행 콜백. `Content-Length` 헤더가 있는 경로에서만 호출됨(헤더가 없으면 청크를 모아 `bytes.concat` 으로 마지막에 한 번 병합 → chunked encoding 이라 중간 보고 없음). 진행 바 갱신이 필요할 때만 전달.
-- DownloadProgress.receivedLength: number — 지금까지 받은 누적 바이트 수.
-- DownloadProgress.contentLength: number — 전체 바이트 수(`Content-Length` 헤더 값, 없으면 0). 헤더가 있으면 그 크기로 버퍼를 사전 할당하고, 수신량이 헤더 값을 초과·미달하면 무결성 위반으로 Error throw.
+- `url: string` — 다운로드 대상 URL. `response.ok` 가 아니면 `Error("다운로드 실패: <status> <statusText>")`, 본문 reader 가 없으면 `Error("응답 본문을 읽을 수 없습니다")` throw.
+- `options.onProgress?: (progress: DownloadProgress) => void` — 청크 수신마다 호출되는 진행 콜백. `Content-Length` 헤더가 있는 경로에서만 호출됨(헤더가 없으면 청크를 모아 `bytes.concat` 으로 마지막에 한 번 병합 — chunked encoding 이라 중간 보고 없음). 진행 바 갱신이 필요할 때만 전달.
+- `DownloadProgress.receivedLength: number` — 지금까지 받은 누적 바이트 수.
+- `DownloadProgress.contentLength: number` — 전체 바이트 수(`Content-Length` 헤더 값, 없으면 0). 헤더가 있으면 그 크기로 버퍼를 사전 할당하고, 수신량이 헤더 값을 초과·미달하면 무결성 위반으로 Error throw.
 
 ```ts
 const data = await fetchUrlBytes("/api/file", {
@@ -58,10 +58,10 @@ const data = await fetchUrlBytes("/api/file", {
 function openFileDialog(options?: { accept?: string; multiple?: boolean }): Promise<File[] | undefined>;
 ```
 
-동적 `input[type=file]` 을 만들어 클릭, 파일 선택 대화상자를 표시. 업로드 버튼 핸들러에서 호출.
+동적 `input[type=file]` 을 만들어 클릭해 파일 선택 대화상자를 표시한다. 업로드 버튼 핸들러에서 호출.
 
-- options.accept: string — 허용 MIME/확장자 필터(input `accept` 에 그대로 전달, 예: `".png,.jpg"`, `"image/*"`). 미지정 시 제한 없음.
-- options.multiple: boolean — 다중 선택 허용. true 면 여러 파일 선택 가능, 기본 `false`(단일). 여러 파일을 한 번에 받을 화면이면 true.
+- `options.accept?: string` — 허용 MIME/확장자 필터(input `accept` 에 그대로 전달, 예: `".png,.jpg"`, `"image/*"`). 미지정 시 제한 없음.
+- `options.multiple?: boolean` — 다중 선택 허용. true 면 여러 파일 선택 가능, 기본 `false`(단일). 여러 파일을 한 번에 받을 화면이면 true.
 - 반환: 선택 파일이 있으면 `File[]`, 사용자가 취소하거나(`cancel` 이벤트) 0개 선택이면 `undefined`. 결측을 빈 배열로 뭉개지 않으므로 `== null` 로 취소를 구분.
 
 ```ts

package/claude/references/sd-simplysm14/apis/core-browser/dom-element.md

@@ -1,19 +1,19 @@
-# @simplysm/core-browser — DOM 요소 확장·헬퍼
+# @simplysm/core-browser — DOM 요소 확장
 
-DOM 요소를 다룰 때 함께 읽히는 묶음. `Element.prototype`/`HTMLElement.prototype` 에 등록되는 확장 메서드와, 이벤트 핸들러·다중 요소용 정적 함수(`copyElement`/`pasteToElement`/`getBounds`)로 구성. 패키지를 import 하면 프로토타입 메서드가 자동 등록되므로 별도 초기화 불필요.
+DOM 요소를 다룰 때 함께 읽히는 묶음. `Element.prototype`/`HTMLElement.prototype` 에 등록되는 확장 메서드와, 이벤트 핸들러·다중 요소용 정적 함수(`copyElement`/`pasteToElement`/`getBounds`)로 구성. 패키지를 import 하면 프로토타입 메서드가 자동 등록되므로 별도 초기화는 필요 없다.
 
 ## Element 확장 메서드
 
 `Element.prototype` 에 등록. import 만으로 활성화.
 
-- findAll<TEl>(selector: string): TEl[] — 선택자 일치 하위 요소를 배열로 반환. 선택자를 trim 한 결과가 빈 문자열이면 `[]`. `querySelectorAll` 결과를 NodeList 대신 배열로 받고 빈 선택자 예외를 회피할 때.
-- findFirst<TEl>(selector: string): TEl | undefined — 첫 일치 하위 요소 또는 `undefined`. 빈 선택자도 `undefined`, 미일치도 `undefined`. `querySelector` 의 `null` 을 `undefined` 로 정규화한 형태.
-- prependChild<TEl>(child: TEl): TEl — 자식을 첫 번째 위치(`insertBefore(child, firstElementChild)`)에 삽입하고 그 요소 반환. 맨 앞에 끼울 때.
-- getParents(): Element[] — 모든 조상 요소를 가까운 것부터 먼 순서로 배열 반환. 조상 체인 순회·특정 조상 포함 판정에.
-- findTabbableParent(): HTMLElement | undefined — `tabbable` 라이브러리 기준 첫 탭 이동 가능 조상. 없으면 `undefined`. 포커스 위임 대상을 위로 탐색할 때.
-- findFirstTabbableChild(): HTMLElement | undefined — TreeWalker 로 순회한 첫 탭 이동 가능 하위 요소. 없으면 `undefined`. 컨테이너 진입 시 자동 포커스 대상을 찾을 때.
-- isOffsetElement(): boolean — `getComputedStyle().position` 이 relative/absolute/fixed/sticky 중 하나면 true, 아니면 false. offset parent(절대배치 기준) 역할 여부 판정에.
-- isVisible(): boolean — `getClientRects().length > 0` 이고 `visibility !== "hidden"` 이고 `opacity !== "0"` 를 모두 만족하면 true. 화면 표시 여부 판정에(display:none 은 clientRects 가 비어 false).
+- `findAll<TEl>(selector: string): TEl[]` — 선택자 일치 하위 요소를 배열로 반환. 선택자를 trim 한 결과가 빈 문자열이면 `[]`. `querySelectorAll` 결과를 NodeList 대신 배열로 받고 빈 선택자 예외를 회피할 때.
+- `findFirst<TEl>(selector: string): TEl | undefined` — 첫 일치 하위 요소 또는 `undefined`. 빈 선택자도 `undefined`, 미일치도 `undefined`. `querySelector` 의 `null` 을 `undefined` 로 정규화한 형태.
+- `prependChild<TEl>(child: TEl): TEl` — 자식을 첫 번째 위치(`insertBefore(child, firstElementChild)`)에 삽입하고 그 요소 반환. 맨 앞에 끼워 넣을 때.
+- `getParents(): Element[]` — 모든 조상 요소를 가까운 것부터 먼 순서로 배열 반환. 조상 체인 순회·특정 조상 포함 판정에.
+- `findTabbableParent(): HTMLElement | undefined` — `tabbable` 라이브러리 기준 첫 탭 이동 가능 조상. 없으면 `undefined`. 포커스 위임 대상을 위로 탐색할 때.
+- `findFirstTabbableChild(): HTMLElement | undefined` — TreeWalker 로 순회한 첫 탭 이동 가능 하위 요소. 없으면 `undefined`. 컨테이너 진입 시 자동 포커스 대상을 찾을 때.
+- `isOffsetElement(): boolean` — `getComputedStyle().position` 이 relative/absolute/fixed/sticky 중 하나면 true, 아니면 false. 절대배치 기준(offset parent) 역할 여부 판정에.
+- `isVisible(): boolean` — `getClientRects().length > 0` 이고 `visibility !== "hidden"` 이고 `opacity !== "0"` 를 모두 만족하면 true. 화면 표시 여부 판정에(display:none 은 clientRects 가 비어 false).
 
 ```ts
 import "@simplysm/core-browser";
@@ -25,12 +25,12 @@ const first = containerEl.findFirstTabbableChild();
 
 `HTMLElement.prototype` 에 등록. 위와 동일하게 import 만으로 활성화.
 
-- repaint(): void — `offsetHeight` 접근으로 강제 동기 레이아웃(reflow)을 유발해 즉시 리페인트. 스타일 변경 직후 즉각 반영을 강제할 때.
-- getRelativeOffset(parent: HTMLElement | string): { top: number; left: number } — 부모 기준 CSS `top`/`left` 좌표 계산. 뷰포트 위치(getBoundingClientRect)·부모 내부 스크롤(scrollTop/Left)·중간 요소 border 두께·CSS transform 까지 반영해, 드롭다운/팝업 위치 지정에 바로 쓸 수 있는 좌표 반환. 부모를 못 찾으면(`HTMLElement` 아님) `ArgumentError` throw.
-  - parent: HTMLElement | string — 기준 부모. 문자열이면 `this.closest(parent)` 로 조상 탐색, 요소면 직접 사용(예: `document.body`, `".container"`).
-- scrollIntoViewIfNeeded(target, offset?): void — 대상이 스크롤 영역의 상단/좌측 경계를 벗어났을 때만 그쪽으로 스크롤해 보이게 함. 하단/우측 방향은 처리하지 않고 브라우저 기본 포커스 스크롤에 위임. 고정 헤더/컬럼이 있는 테이블의 포커스 처리에.
-  - target: { top: number; left: number } — 컨테이너 내 대상 위치(offsetTop/offsetLeft 기준).
-  - offset: { top: number; left: number } — 가려지면 안 되는 영역 크기(고정 헤더 높이·고정 컬럼 너비). 기본 `{ top: 0, left: 0 }`.
+- `repaint(): void` — `offsetHeight` 접근으로 강제 동기 레이아웃(reflow)을 유발해 즉시 리페인트. 스타일 변경 직후 즉각 반영을 강제할 때.
+- `getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }` — 부모 기준 CSS `top`/`left` 좌표 계산. 뷰포트 위치(getBoundingClientRect)·부모 내부 스크롤(scrollTop/Left)·중간 요소 border 두께·CSS transform 까지 반영해, 드롭다운/팝업 위치 지정에 바로 쓸 수 있는 좌표를 반환. 부모를 못 찾으면(`HTMLElement` 아님) `ArgumentError` throw.
+  - `parent: HTMLElement | string` — 기준 부모. 문자열이면 `this.closest(parent)` 로 조상 탐색, 요소면 직접 사용(예: `document.body`, `".container"`).
+- `scrollIntoViewIfNeeded(target, offset?): void` — 대상이 스크롤 영역의 상단/좌측 경계를 벗어났을 때만 그쪽으로 스크롤해 보이게 함. 하단/우측 방향은 처리하지 않고 브라우저 기본 포커스 스크롤에 위임. 고정 헤더/컬럼이 있는 테이블의 포커스 처리에.
+  - `target: { top: number; left: number }` — 컨테이너 내 대상 위치(offsetTop/offsetLeft 기준).
+  - `offset?: { top: number; left: number }` — 가려지면 안 되는 영역 크기(고정 헤더 높이·고정 컬럼 너비). 기본 `{ top: 0, left: 0 }`.
 
 ```ts
 const { top, left } = popupEl.getRelativeOffset(".container");
@@ -41,19 +41,19 @@ scrollEl.scrollIntoViewIfNeeded({ top: cellTop, left: cellLeft }, { top: headerH
 
 이벤트 핸들러로 붙이거나 다중 요소를 한 번에 처리하는 함수. 프로토타입 확장이 아니라 named export 이므로 직접 import.
 
-- copyElement(event: ClipboardEvent): void — copy 이벤트 핸들러용. 이벤트 타겟 내 첫 `input/textarea` 의 `value` 를 클립보드 `text/plain` 으로 기록하고 `preventDefault`. clipboardData 가 없거나 타겟이 Element 가 아니거나 input 이 없으면 무동작.
-  - event: ClipboardEvent — copy 이벤트 객체. `el.addEventListener("copy", copyElement)` 로 등록.
-- pasteToElement(event: ClipboardEvent): void — paste 이벤트 핸들러용. 타겟 내 첫 `input/textarea` 의 전체 `value` 를 클립보드 텍스트로 교체하고 `input` 이벤트 dispatch(`bubbles: true`) 후 `preventDefault`. 커서 위치·선택 영역은 무시하고 전체를 치환.
-  - event: ClipboardEvent — paste 이벤트 객체. `el.addEventListener("paste", pasteToElement)` 로 등록.
-- getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]> — `IntersectionObserver` 로 여러 요소의 뷰포트 기준 경계를 한 번에 측정. 중복은 제거하고 입력 순서대로 정렬해 반환. 빈 배열이면 즉시 `[]`. 모든 요소 관측 완료 시 resolve, 제한시간 초과 시 `TimeoutError` throw(어느 경우든 finally 에서 observer disconnect).
-  - els: Element[] — 측정 대상. 중복은 제거되고 결과는 입력 순서로 정렬됨.
-  - timeout: number — 제한시간(ms). 기본 `5000`. 초과 시 `TimeoutError`.
-- ElementBounds (반환 항목 타입):
-  - target: Element — 측정된 요소.
-  - top: number — 뷰포트 기준 상단 위치(boundingClientRect.top).
-  - left: number — 뷰포트 기준 좌측 위치(boundingClientRect.left).
-  - width: number — 요소 너비(boundingClientRect.width).
-  - height: number — 요소 높이(boundingClientRect.height).
+- `copyElement(event: ClipboardEvent): void` — copy 이벤트 핸들러용. 이벤트 타겟 내 첫 `input/textarea` 의 `value` 를 클립보드 `text/plain` 으로 기록하고 `preventDefault`. clipboardData 가 없거나 타겟이 Element 가 아니거나 input 이 없으면 무동작.
+  - `event: ClipboardEvent` — copy 이벤트 객체. `el.addEventListener("copy", copyElement)` 로 등록.
+- `pasteToElement(event: ClipboardEvent): void` — paste 이벤트 핸들러용. 타겟 내 첫 `input/textarea` 의 전체 `value` 를 클립보드 텍스트로 교체하고 `input` 이벤트 dispatch(`bubbles: true`) 후 `preventDefault`. 커서 위치·선택 영역은 무시하고 전체를 치환.
+  - `event: ClipboardEvent` — paste 이벤트 객체. `el.addEventListener("paste", pasteToElement)` 로 등록.
+- `getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>` — `IntersectionObserver` 로 여러 요소의 뷰포트 기준 경계를 한 번에 측정. 중복은 제거하고 입력 순서대로 정렬해 반환. 빈 배열이면 즉시 `[]`. 모든 요소 관측 완료 시 resolve, 제한시간 초과 시 `TimeoutError` throw(어느 경우든 finally 에서 observer disconnect).
+  - `els: Element[]` — 측정 대상. 중복은 제거되고 결과는 입력 순서로 정렬됨.
+  - `timeout?: number` — 제한시간(ms). 기본 `5000`. 초과 시 `TimeoutError`.
+- `ElementBounds` (반환 항목 타입):
+  - `target: Element` — 측정된 요소.
+  - `top: number` — 뷰포트 기준 상단 위치(boundingClientRect.top).
+  - `left: number` — 뷰포트 기준 좌측 위치(boundingClientRect.left).
+  - `width: number` — 요소 너비(boundingClientRect.width).
+  - `height: number` — 요소 높이(boundingClientRect.height).
 
 ```ts
 inputEl.addEventListener("copy", copyElement);