@simplysm/sd-claude 14.0.88 → 14.0.89

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

@@ -1,69 +1,69 @@
 # @simplysm/capacitor-plugin-auto-update
 
-Android 앱(Capacitor)에서 APK 설치 및 자동 업데이트를 수행하는 플러그인. APK 설치 인텐트 실행·설치 권한 관리·서버/외부저장소 기반 최신 버전 감지 후 다운로드·설치 흐름을 제공. 모든 공개 심볼은 `static` 멤버만 가진 abstract 클래스이거나 타입이므로 인스턴스 생성 없이 클래스명으로 직접 호출.
+Capacitor 앱(Android)에서 APK 설치 인텐트를 실행하고, 서버 또는 외부 저장소의 최신 APK 를 받아 자동 업데이트하는 플러그인. 공개 심볼은 모두 `static` 멤버만 가진 abstract 클래스이거나 타입이라 인스턴스 없이 클래스명으로 직접 호출.
 
 ## 사용 트리거 인덱스
 
-- **AutoUpdate** — 앱 시작 시 최신 버전을 감지해 APK 를 받아 설치하는 전체 자동 업데이트 흐름을 돌릴 때. 서버 조회 방식(`run`)과 외부 저장소 디렉토리 방식(`runByExternalStorage`).
-- **ApkInstaller** — 자동 업데이트 흐름을 직접 구성할 때 쓰는 저수준 API. 설치 권한 확인·요청, APK 설치 인텐트 실행, 현재 앱 버전 조회.
-- **ApkInstallerPlugin / VersionInfo** — Capacitor 네이티브 브리지 인터페이스 타입과 버전 정보 형태. 플러그인을 직접 등록·구현하거나 반환 타입을 참조할 때.
+- **AutoUpdate** — 앱 부팅 시 "최신 확인 → 권한 → 다운로드 → 설치 → 앱 멈춤" 까지 한 번에 돌리는 자동 업데이트 오케스트레이터. 서버 기반(`run`) 또는 외부 저장소 기반(`runByExternalStorage`).
+- **ApkInstaller** — APK 설치/권한/버전 조회를 직접 호출하는 저수준 정적 클래스. 자동 업데이트 흐름을 직접 짜거나 단건 설치·권한 처리만 필요할 때.
+- **ApkInstallerPlugin / VersionInfo** — Capacitor 네이티브 브리지 인터페이스 및 버전 정보 타입. 직접 호출보다는 `ApkInstaller` 가 감싸므로 반환 타입 참조·웹 구현체 작성 시 참조용.
 
 ## AutoUpdate
 
-`abstract class AutoUpdate` — 정적 메서드만 가진 고수준 오케스트레이터. 두 진입점 모두 내부에서 Android 여부 확인 → 설치 권한 확인/요청 → 버전 비교 → 다운로드/설치 → 무한 freeze 까지 일괄 처리. 도중 발생한 모든 예외를 잡아 `log` 로 표시한 뒤 `_freezeApp()`(영원히 resolve 되지 않는 무한 대기)으로 진입함. Android 가 아니면(`navigator.userAgent` 에 "android" 없음) `"Android만 지원됩니다."` throw. 버전 비교는 `semver.gt` 로 대상 버전이 현재보다 클 때만 진행.
+`abstract class AutoUpdate` — 정적 메서드만 가진 고수준 오케스트레이터. 두 진입점 모두 내부에서 Android 여부 확인 → 설치 권한 확인/요청 → 버전 비교 → 다운로드/설치 → 무한 freeze 순으로 일괄 처리. 진행 단계는 `log` 콜백으로 HTML 문자열을 흘려보내고, 도중 발생한 모든 예외를 잡아 `log` 로 에러 메시지를 표시한 뒤 영원히 resolve 되지 않는 무한 대기로 진입해 구버전 실행을 막는다. Android 가 아니면(`navigator.userAgent` 에 "android" 없음) `"Android만 지원됩니다."` 로 throw 되어 catch 에서 표시됨.
 
-```ts
+```typescript
 static run(opt: { log: (messageHtml: string) => void; serviceClient: ServiceClient }): Promise<void>
 static runByExternalStorage(opt: { log: (messageHtml: string) => void; dirPath: string }): Promise<void>
 ```
 
-- `run` — 서버 `AutoUpdate` 서비스에서 최신 버전을 조회해 업데이트. 서버 연동 배포일 때 사용.
-  - `log: (messageHtml: string) => void` — 진행/오류 상태를 HTML 문자열로 전달받는 콜백. "최신 버전 확인 중...", "권한 확인 중...", 다운로드 진행률 `(NN.NN%)`, 권한 활성화/재시도 버튼 HTML, 오류 메시지 등이 인자로 들어옴. 화면에 그대로 innerHTML 로 렌더하는 용도.
-  - `serviceClient: ServiceClient` — `@simplysm/service-client` 의 서비스 클라이언트. 내부에서 `getService<AutoUpdateService>("AutoUpdate").getLastVersion("android")` 로 최신 버전·다운로드 경로를 조회하고, `serviceClient.hostUrl + downloadPath` 로 `fetchUrlBytes` 다운로드. 받은 바이트는 `appCache` 저장소의 `latest.apk` 로 써서 설치. 서버 버전 정보 없으면 무동작 반환.
-- `runByExternalStorage` — 외부 저장소의 지정 디렉토리에서 APK 파일들을 스캔해 업데이트. 서버 없이 외부 저장소로 사이드로딩 배포할 때 사용.
-  - `log: (messageHtml: string) => void` — `run` 과 동일한 진행/오류 상태 콜백.
-  - `dirPath: string` — 외부 저장소(`FileSystem.getStoragePath("external")`) 기준 상대 디렉토리 경로. 이 폴더의 비-디렉토리 항목 중 확장자가 `.apk` 이고 파일명(확장자 제외)이 `[0-9.]` 로만 이뤄진 것을 버전으로 보고 `semver.maxSatisfying(..., "*")` 로 최신을 선정. 파일 없거나 유효 semver 없으면 반환. 설치 파일은 `<dirPath>/<version>.apk`.
+- log: (messageHtml: string) => void — 진행/오류 상태를 HTML 문자열로 받는 콜백. "최신 버전 확인 중...", "권한 확인 중...", 다운로드 진행률 `(NN.NN%)`, 권한 활성화·재시도 버튼 HTML, 오류 메시지 등이 인자로 들어옴. 부팅 스플래시 등에 그대로 innerHTML 로 렌더하는 용도이며 매 단계마다 여러 번 호출됨. 버튼 등 인터랙티브 HTML 이 포함되므로 텍스트가 아닌 HTML 로 렌더해야 재시도/다운로드가 동작.
+- serviceClient: ServiceClient (`run` 전용) — `@simplysm/service-client` 의 서비스 클라이언트. 내부에서 `getService<AutoUpdateService>("AutoUpdate").getLastVersion("android")` 로 최신 버전·다운로드 경로를 조회하고, `serviceClient.hostUrl + downloadPath` 로 `fetchUrlBytes` 다운로드. 서버가 버전 정보를 안 주면(`undefined`) 무동작 반환(업데이트 없음). 서버 연동 배포일 때 사용.
+- dirPath: string (`runByExternalStorage` 전용) — 외부 저장소(`FileSystem.getStoragePath("external")`) 기준 상대 디렉토리 경로. 이 폴더의 비-디렉토리 항목 중 확장자가 `.apk` 이고 파일명(확장자 제외)이 `^[0-9.]*$` 인 것을 버전으로 보고 `semver.maxSatisfying(..., "*")` 로 최신을 선정. 서버 없이 USB/SD 등으로 사이드로딩 배포할 때 사용.
 
-```ts
+동작 차이: `run` 은 다운로드한 바이트를 `appCache` 저장소의 `latest.apk` 로 써서 설치하고, `runByExternalStorage` 는 외부 저장소의 `<dirPath>/<version>.apk` 를 직접 설치 대상으로 삼는다. 두 경로 모두 현재 버전(`ApkInstaller.getVersionInfo().versionName`)과 비교해 `semver.gt(최신, 현재)` 가 아니면(이미 최신·동일·낮음) 반환하고, 어느 한쪽이라도 유효한 semver 가 아니면 업데이트 확인을 건너뛴다.
+
+```typescript
 // 앱 부트스트랩에서
 await AutoUpdate.run({ log: (h) => (statusEl.innerHTML = h), serviceClient });
+// 또는 오프라인 배포 폴더 기준
 await AutoUpdate.runByExternalStorage({ log: (h) => (statusEl.innerHTML = h), dirPath: "myapp-apks" });
 ```
 
-주의: 업데이트가 없으면 그냥 반환하지만, 업데이트를 진행하거나 오류가 나면 `_freezeApp()` 으로 영원히 resolve 되지 않음 — 호출 후속 코드에 의존하지 말 것. 권한 미승인 시 설정 화면으로 보낸 뒤 최대 5분(1초 간격 폴링) 동안 권한 부여를 대기. APK manifest 에 `REQUEST_INSTALL_PACKAGES` 가 없거나(`manifest:false`) 권한 확인 자체가 실패하면 "APK 파일을 다시 다운로드하여 설치해야 합니다(코드)" 안내(다운로드 링크 버튼 포함)와 함께 throw.
+주의: 업데이트가 없으면 그냥 반환하지만, 설치를 진행하거나 오류가 나면 무한 대기로 들어가 영원히 resolve 되지 않으므로 호출 후속 코드에 의존하지 말 것 — 후속 코드는 "업데이트 없음" 경로에서만 실행된다. 권한 미승인 시 설정 화면으로 보낸 뒤 최대 5분(1초 간격 300회) 동안 권한 부여를 폴링. APK manifest 에 `REQUEST_INSTALL_PACKAGES` 가 없거나(`manifest:false`) 권한 확인 자체가 실패하면 "APK 파일을 다시 다운로드하여 설치해야 합니다(코드)." 안내(코드 1·2, 다운로드 링크 버튼 포함)와 함께 throw.
 
 ## ApkInstaller
 
-`abstract class ApkInstaller` — 정적 메서드만 가진 저수준 설치 래퍼. Android 는 네이티브 인텐트/권한을 다루고, 브라우저(web)는 `ApkInstallerWeb` 가 대체 구현(설치 시 알림 표시 후 정상 반환, 권한은 항상 `granted:true`/`manifest:true`). `AutoUpdate` 가 내부적으로 사용하며, 자동 업데이트 UX 를 직접 구성할 때 사용.
+`abstract class ApkInstaller` — APK 설치 관련 네이티브 호출을 감싼 저수준 정적 클래스. Android 는 실제 인텐트/권한을 다루고, 브라우저(web)는 `ApkInstallerWeb` 가 대체 구현(설치 시 미지원 alert 후 정상 반환, 권한은 항상 `granted:true`/`manifest:true`). `AutoUpdate` 가 내부에서 쓰며, 자동 업데이트 UX 를 직접 구성하거나 권한·설치만 단독으로 다룰 때 직접 호출.
 
-```ts
+```typescript
 static checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>
 static requestPermissions(): Promise<void>
 static install(apkUri: string): Promise<void>
 static getVersionInfo(): Promise<VersionInfo>
 ```
 
-- `checkPermissions()` — 설치 권한 상태 조회. 설치 시도 전 사전 점검에 사용.
-  - `granted: boolean` — `REQUEST_INSTALL_PACKAGES` 설치 권한이 사용자에게 승인되었는지. false 면 `requestPermissions` 로 유도해야 함.
-  - `manifest: boolean` — 해당 권한이 앱 manifest 에 선언되어 있는지. false 면 권한 요청 자체가 불가하므로 APK 재설치가 필요한 상황.
-- `requestPermissions()` — 권한 미승인 시 호출. 시스템 설정 화면으로 이동시키며 즉시 부여되진 않으므로 이후 `checkPermissions` 폴링이 필요.
-- `install(apkUri)` — APK 설치 인텐트 실행.
-  - `apkUri: string` — `content://` 형태의 FileProvider URI. 로컬 파일 경로가 아니라 `@simplysm/capacitor-plugin-file-system` 의 `FileSystem.getUri(filePath)` 로 변환한 content URI 를 넘겨야 함.
-- `getVersionInfo()` — 현재 설치된 앱의 버전 정보(`VersionInfo`) 조회. 서버/외부 버전과 비교할 현재 버전 기준값. (web 구현은 `env("__VER__") ?? "0.0.0"` / `versionCode "0"` 반환.)
+- checkPermissions() → { granted, manifest } — 설치 권한 상태 조회. granted: boolean = `REQUEST_INSTALL_PACKAGES` 권한이 사용자에게 승인되었는지(false 면 `requestPermissions` 로 유도), manifest: boolean = 해당 권한이 앱 manifest 에 선언되어 있는지(false 면 권한 요청 자체가 불가 → APK 재설치 필요). 설치 전 사전 점검·재시도 폴링에 사용. 웹에서는 둘 다 true.
+- requestPermissions() → void — 설치 권한 요청. Android 에서는 시스템 설정 화면으로 이동시키며 즉시 부여되지 않으므로 이후 `checkPermissions` 폴링으로 승인 여부를 확인해야 함. 웹에서는 동작 없음.
+- install(apkUri: string) → void — APK 설치 인텐트 실행. apkUri 는 로컬 경로가 아니라 `content://` FileProvider URI (보통 `@simplysm/capacitor-plugin-file-system` 의 `FileSystem.getUri(파일경로)` 결과). 웹에서는 미지원 alert 후 반환.
+- getVersionInfo() → VersionInfo — 현재 설치된 앱 버전 조회. 서버/외부 버전과 비교할 현재 버전 기준값. 웹 구현은 `versionName` 을 빌드 시 주입된 `env("__VER__")`(없으면 `"0.0.0"`), `versionCode` 를 `"0"` 으로 응답.
 
-```ts
+```typescript
 const { granted, manifest } = await ApkInstaller.checkPermissions();
 if (!granted) await ApkInstaller.requestPermissions();
-const uri = await FileSystem.getUri(apkFilePath);
-await ApkInstaller.install(uri);
+await ApkInstaller.install(await FileSystem.getUri(apkFilePath));
 ```
 
 ## ApkInstallerPlugin / VersionInfo
 
-Capacitor 네이티브 브리지 타입. `ApkInstaller` 의 정적 메서드는 `registerPlugin("ApkInstaller")` 로 등록된 이 인터페이스 구현체(네이티브 또는 `ApkInstallerWeb`)에 위임함. 일반적으로 직접 쓰지 않고 `ApkInstaller` 를 통해 접근하며, 타입 참조·웹 구현체 작성 시에만 사용.
+Capacitor `registerPlugin("ApkInstaller")` 로 등록되는 네이티브 브리지 인터페이스와 버전 정보 타입. `ApkInstaller` 의 정적 메서드가 이 인터페이스 구현체(네이티브 또는 `ApkInstallerWeb`)에 위임하므로, 직접 구현·호출할 일은 드물고 주로 `getVersionInfo` 반환 형태 참조·웹 구현체 작성 시에만 본다.
+
+```typescript
+interface VersionInfo {
+  versionName: string;
+  versionCode: string;
+}
 
-```ts
-interface VersionInfo { versionName: string; versionCode: string; }
 interface ApkInstallerPlugin {
   install(options: { uri: string }): Promise<void>;
   checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
@@ -72,9 +72,7 @@ interface ApkInstallerPlugin {
 }
 ```
 
-- `VersionInfo.versionName: string` — 사람이 읽는 표시 버전(semver, 예 `"1.2.3"`). `AutoUpdate` 의 버전 비교(`semver.gt`)는 이 값을 semver 로 사용.
-- `VersionInfo.versionCode: string` — Android 빌드 버전 코드의 문자열 표현. 표시·식별용.
-- `ApkInstallerPlugin.install(options: { uri: string })` — content URI APK 설치. `uri` 는 `content://` FileProvider URI.
-- `ApkInstallerPlugin.checkPermissions()` — 설치 권한 승인 여부(`granted`)와 manifest 선언 여부(`manifest`) 조회.
-- `ApkInstallerPlugin.requestPermissions()` — 설치 권한 요청(설정 화면 이동).
-- `ApkInstallerPlugin.getVersionInfo()` — 현재 앱 버전 정보(`VersionInfo`) 조회.
+- VersionInfo.versionName: string — 사람이 읽는 표시 버전(semver, 예 `"1.2.3"`). `AutoUpdate` 의 버전 비교(`semver.gt`/`semver.valid`)는 이 값을 semver 로 사용.
+- VersionInfo.versionCode: string — Android 빌드 버전 코드의 문자열 표현. 웹 구현에서는 `"0"` 고정. 현재 업데이트 판정 로직은 `versionName` 만 사용하며 이 값은 표시·식별용.
+- ApkInstallerPlugin.install(options: { uri: string }) — content URI APK 설치. `ApkInstaller.install(apkUri)` 가 `{ uri: apkUri }` 형태로 래핑해 전달하며 uri 는 `content://` FileProvider URI.
+- ApkInstallerPlugin.checkPermissions / requestPermissions / getVersionInfo — 각각 `ApkInstaller` 의 동명 정적 메서드가 그대로 위임하는 원본 브리지 메서드(권한 조회 / 권한 요청 / 현재 버전 조회).

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

@@ -1,17 +1,17 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor 기반 네이티브 파일 시스템 접근 플러그인. Android 는 외부/앱 저장소 직접 접근(11+ 는 `MANAGE_EXTERNAL_STORAGE`, 10- 는 `READ/WRITE_EXTERNAL_STORAGE` 권한), Browser 는 IndexedDB 기반 에뮬레이션으로 동작.
+Capacitor 기반 파일 시스템 접근 플러그인. 네이티브(Android)에서 외부/앱 저장소를 직접 다루고(Android 11+ 는 `MANAGE_EXTERNAL_STORAGE`, 10- 는 `READ/WRITE_EXTERNAL_STORAGE` 권한), 브라우저에서는 IndexedDB 기반 에뮬레이션으로 동일 API 를 제공.
 
 ## 사용 트리거 인덱스
 
-- **FileSystem** — 파일 읽기/쓰기, 디렉토리 조회/생성, 삭제, 권한 확인/요청, 저장소 경로 조회가 필요할 때 쓰는 정적(static) 진입점 클래스(주 사용처).
-- **StorageType** — `FileSystem.getStoragePath` 인자로 넘기는 저장소 위치 유형 리터럴을 고를 때.
+- **FileSystem** — 파일 읽기/쓰기, 디렉토리 조회/생성, 삭제, 존재 확인, 권한 확인/요청, 저장소 경로/URI 조회가 필요할 때 쓰는 static 진입점 클래스(주 사용처).
+- **StorageType** — `FileSystem.getStoragePath` 인자로 넘길 저장소 위치 유형 리터럴을 고를 때.
 - **FileInfo** — `FileSystem.readdir` 가 반환하는 항목 정보(이름 + 디렉토리 여부). 디렉토리 순회 시.
-- **FileSystemPlugin** — Capacitor 네이티브 브릿지 원형 인터페이스 타입. 보통 `FileSystem` 가 래핑하므로 직접 호출 불필요. 커스텀 web 구현 작성이나 타입 참조 시에만.
+- **FileSystemPlugin** — Capacitor 네이티브 브릿지 원형 인터페이스 타입. 보통 `FileSystem` 가 래핑하므로 직접 호출 불필요. 커스텀 web 구현 작성·타입 참조 시에만.
 
 ## FileSystem (static 클래스)
 
-모든 메서드 `static async`. 인스턴스 생성 없이 `FileSystem.xxx()` 호출. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 으로 얻은 네이티브/web 구현에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환.
+`abstract class`, 모든 멤버 `static async`. 인스턴스 생성 없이 `FileSystem.xxx()` 호출. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 으로 얻은 네이티브/web 구현에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환.
 
 - `checkPermissions(): Promise<boolean>` — 파일 접근 권한 보유 여부. true 면 권한 있음. 읽기/쓰기 전 사전 확인용. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
 - `requestPermissions(): Promise<void>` — 권한 요청. Android 11+ 는 설정 화면으로 이동, Android 10- 는 권한 대화상자 표시. `checkPermissions()` 가 false 일 때 호출.
@@ -58,8 +58,8 @@ for (const f of await FileSystem.readdir(`${base}/notes`)) {
   - `readdir(options: { path: string }): Promise<{ files: FileInfo[] }>` — `path` 디렉토리 항목 목록을 `files` 로 반환.
   - `getStoragePath(options: { type: StorageType }): Promise<{ path: string }>` — `type` 저장소의 실제 경로를 `path` 로 반환.
   - `getUri(options: { path: string }): Promise<{ uri: string }>` — `path` 파일의 FileProvider URI 를 `uri` 로 반환.
-  - `writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>` — `data`(문자열)를 `encoding`(`"utf8"`=텍스트, `"base64"`=바이너리 디코드, 생략 시 구현 기본)으로 `path` 에 기록.
-  - `readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>` — `path` 내용을 `encoding`(`"utf8"`=텍스트, `"base64"`=바이너리 인코딩 문자열)으로 읽어 `data` 로 반환.
+  - `writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>` — `data`(문자열)를 `encoding`(`"utf8"`=텍스트 그대로, `"base64"`=base64 문자열을 바이너리로 디코드해 기록, 생략 시 구현 기본)으로 `path` 에 기록.
+  - `readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>` — `path` 내용을 `encoding`(`"utf8"`=텍스트, `"base64"`=바이너리를 base64 문자열로 인코딩)으로 읽어 `data` 로 반환. 플러그인 레벨에서 바이너리는 항상 base64 문자열로 주고받음(`FileSystem` 가 `Bytes` ↔ base64 변환 담당).
   - `remove(options: { path: string }): Promise<void>` — `path` 파일/디렉토리 재귀 삭제.
   - `mkdir(options: { path: string }): Promise<void>` — `path` 디렉토리 재귀 생성.
   - `exists(options: { path: string }): Promise<{ exists: boolean }>` — `path` 존재 여부를 `exists` 로 반환.

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

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

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

@@ -1,67 +1,62 @@
 # @simplysm/capacitor-plugin-usb-storage
 
-USB Mass Storage 장치를 읽는 Capacitor 플러그인. Android 는 libaums 로 실제 USB 저장소에 접근하고, 브라우저(web)는 IndexedDB 기반 가상 USB 저장소로 에뮬레이션함. 외부 노출 심볼은 정적 클래스 `UsbStorage`, 타입 정의 3종, 네이티브 인터페이스 `UsbStoragePlugin`.
+Capacitor 플러그인. 연결된 USB Mass Storage 장치를 열거하고 권한을 얻은 뒤 디렉토리/파일을 읽음. Android 는 libaums 네이티브 구현, 브라우저는 IndexedDB 기반 가상 USB 저장소로 에뮬레이션됨. export 심볼은 정적 클래스 `UsbStorage` 와 타입 4종.
 
 ## 사용 트리거 인덱스
 
-- **UsbStorage** — USB 장치 목록 조회·권한 요청/확인·디렉토리/파일 읽기를 할 때 쓰는 정적 진입점. 모든 동작이 `vendorId`/`productId` 로 대상 장치를 지정.
-- **UsbDeviceFilter / UsbDeviceInfo / UsbFileInfo** — 위 메서드의 인자·반환 타입. 장치 식별·열거·항목 분기 시 함께 참조.
-- **UsbStoragePlugin** — `UsbStorage` 가 내부적으로 감싸는 Capacitor 네이티브 인터페이스. 보통 직접 호출하지 않음.
+- **UsbStorage** — USB 장치 접근의 진입점. 장치 목록 조회 → 권한 요청/확인 → readdir/readFile 흐름을 정적 메서드로 제공.
+- **UsbDeviceInfo / UsbDeviceFilter / UsbFileInfo / UsbStoragePlugin** — 위 메서드의 입출력 타입. 장치 식별(vendorId/productId)·반환 항목 형태를 다룰 때 참조.
 
-## UsbStorage (정적 클래스)
+## UsbStorage
 
-모든 메서드 정적, 인스턴스화 불필요. 장치 지정은 항상 `UsbDeviceFilter`(vendorId+productId).
+`abstract class` 이며 모든 멤버가 `static`. 인스턴스화하지 않고 `UsbStorage.메서드()` 로 호출. 내부적으로 `registerPlugin("UsbStorage")` 로 얻은 네이티브/웹 구현에 위임하고 래퍼 객체(`{ devices }` 등)에서 값을 꺼내 평탄화해 반환. 장치 지정은 항상 `UsbDeviceFilter`(= `{ vendorId, productId }`) — readdir/readFile 도 매 호출마다 대상 장치를 filter 로 받음.
 
-`static getDevices(): Promise<UsbDeviceInfo[]>`
-- 현재 연결된 USB 장치 목록을 반환. 권한 요청 전 장치의 `vendorId`/`productId` 를 알아내는 용도.
-
-`static requestPermissions(filter: UsbDeviceFilter): Promise<boolean>`
-- `filter` 장치의 접근 권한을 OS 에 요청. 반환 `true`=승인, `false`=거부. web 구현은 항상 `true`. readdir/readFile 전 권한 확보용.
-
-`static checkPermissions(filter: UsbDeviceFilter): Promise<boolean>`
-- 권한 요청 다이얼로그 없이 현재 보유 권한만 확인. `true`=이미 보유, `false`=미보유(이때 `requestPermissions` 필요). web 구현은 항상 `true`.
-
-`static readdir(filter: UsbDeviceFilter, dirPath: string): Promise<UsbFileInfo[]>`
-- `filter` 장치의 `dirPath` 디렉토리 하위 항목 목록을 반환. `dirPath`=읽을 디렉토리 경로(루트는 `"/"`).
-
-`static readFile(filter: UsbDeviceFilter, filePath: string): Promise<Bytes | undefined>`
-- `filter` 장치의 `filePath` 파일 내용을 `Bytes`(`@simplysm/core-common`)로 반환. `filePath`=읽을 파일 경로. 네이티브가 데이터 없음(null)을 주면 `undefined` 반환 — 결측을 빈 Bytes 로 치환하지 않고 그대로 전파. 내부적으로 base64 → `bytes.fromBase64` 변환.
+- `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`) 로 읽음. 파일이 없거나 네이티브가 데이터 없음을 주면 `undefined` 반환 — "빈 파일" 과 "없음" 을 구분하려면 이 `undefined` 를 그대로 검사(기본값으로 치환 금지). 내부에서 base64 응답을 `bytes.fromBase64` 로 복원.
 
 사용 예:
 
 ```ts
-const devices = await UsbStorage.getDevices();
-const filter = { vendorId: devices[0].vendorId, productId: devices[0].productId };
+import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
+
+const [device] = await UsbStorage.getDevices();
+if (!device) return;
+const filter = { vendorId: device.vendorId, productId: device.productId };
+
 if (!(await UsbStorage.checkPermissions(filter))) {
   if (!(await UsbStorage.requestPermissions(filter))) return; // 거부 시 중단
 }
-const files = await UsbStorage.readdir(filter, "/");
-const data = await UsbStorage.readFile(filter, "/data.bin"); // Bytes | undefined
-```
 
-## 타입 정의
-
-`interface UsbDeviceFilter` — 권한·읽기 메서드의 장치 식별 키
-- `vendorId: number` — 대상 USB 장치의 벤더 ID. 장치 특정 키의 일부.
-- `productId: number` — 대상 USB 장치의 제품 ID. `vendorId` 와 조합해 장치를 유일하게 지정.
-
-`interface UsbDeviceInfo` — `getDevices` 반환 배열 요소
-- `deviceName: string` — OS 가 보고하는 장치 시스템 이름.
-- `manufacturerName: string` — 제조사 이름.
-- `productName: string` — 제품 이름.
-- `vendorId: number` — 벤더 ID. 그대로 `UsbDeviceFilter.vendorId` 구성에 사용.
-- `productId: number` — 제품 ID. 그대로 `UsbDeviceFilter.productId` 구성에 사용.
-
-`interface UsbFileInfo` — `readdir` 반환 배열 요소
-- `name: string` — 항목(파일/폴더) 이름.
-- `isDirectory: boolean` — `true`=디렉토리(하위 readdir 가능), `false`=파일(readFile 대상). 재귀 탐색·파일 필터링 분기에 사용.
-
-## UsbStoragePlugin (네이티브 인터페이스)
-
-`registerPlugin<UsbStoragePlugin>("UsbStorage")` 로 등록되는 Capacitor 인터페이스. `UsbStorage` 정적 메서드가 이를 감싸며 `{ ... }` 래퍼 객체에서 값을 꺼내므로 보통 직접 호출 불필요. 직접 다뤄야 할 때만 참조.
+const entries = await UsbStorage.readdir(filter, "/");
+for (const e of entries.filter((x) => !x.isDirectory)) {
+  const data = await UsbStorage.readFile(filter, `/${e.name}`);
+  if (data === undefined) continue; // 파일 없음/데이터 없음
+  // data: Bytes 사용
+}
+```
 
-- `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[] }>` — `path` 디렉토리 항목을 `files` 로 반환. `options` 는 필터에 `path`(대상 경로)를 합친 형태.
-- `readFile(options: UsbDeviceFilter & { path: string }): Promise<{ data: string | null }>` — `path` 파일을 base64 문자열 `data` 로 반환. 데이터 없으면 `null`(상위 `UsbStorage.readFile` 가 `undefined` 로 변환).
+## 입출력 타입
+
+`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` 로 변환).

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

@@ -1,83 +1,70 @@
 # @simplysm/core-browser
 
-브라우저 전용 유틸리티. DOM `Element`/`HTMLElement` 프로토타입 확장(import 시 사이드 이펙트로 등록)과 클립보드·다운로드·파일선택·fetch·IndexedDB 헬퍼를 제공.
+브라우저 전용 유틸리티. `Element`/`HTMLElement` 프로토타입 확장(사이드 이펙트)과 파일 다운로드·업로드, IndexedDB 래퍼를 제공.
+
+> 패키지의 어떤 심볼이든 import 하면 `index.ts` 가 `import "./extensions/..."` 를 실행해 프로토타입 확장이 자동 등록됨(`element-ext`, `html-element-ext` 의 사이드 이펙트). 별도 초기화 호출 없이 `el.findAll(...)` 식으로 사용 가능.
 
 ## 사용 트리거 인덱스
 
-- **Element 확장 메서드** — DOM 요소 탐색·삽입·가시성/탭이동 판정을 프로토타입 메서드로 호출할 때. 패키지를 import 하면 자동 등록됨. (아래 인라인)
-- **HTMLElement 확장 메서드** — 리페인트 강제, 부모 기준 상대 좌표 계산, offset 가림 보정 스크롤이 필요할 때. (아래 인라인)
-- **clipboard / bounds 정적 함수** (`copyElement`, `pasteToElement`, `getBounds`) — copy/paste 이벤트 핸들러를 붙이거나 여러 요소의 화면 경계를 한 번에 측정할 때. (아래 인라인)
-- **다운로드·파일선택·fetch** (`downloadBlob`, `openFileDialog`, `fetchUrlBytes`) — Blob 저장, 파일 선택 다이얼로그, 진행률 포함 바이너리 다운로드가 필요할 때. (아래 인라인)
-- **IndexedDB 저장소/가상 파일시스템** (`IndexedDbStore`, `IndexedDbVirtualFs`) — 브라우저 IndexedDB 에 KV 저장하거나 경로 기반 가상 파일트리를 다룰 때. 자세히: [indexed-db.md](./indexed-db.md)
+- **DOM 요소 확장** — DOM 조회(`findAll`/`findFirst`), 부모/탭이동 가능 요소 탐색, 가시성·offset 판정, 부모 기준 상대 좌표 계산, 가림 보정 스크롤, 강제 리페인트, 클립보드 복사/붙여넣기 핸들러, 다중 요소 경계 측정이 필요할 때. 자세히: [dom-element.md](./dom-element.md)
+- **IndexedDB 저장소/가상 파일시스템** (`IndexedDbStore`, `IndexedDbVirtualFs`) — 브라우저 IndexedDB 에 KV 영구 저장하거나, 그 위에 경로 키 기반 가상 파일트리를 올릴 때. 자세히: [indexed-db.md](./indexed-db.md)
+- **파일 다운로드/업로드** (`downloadBlob`, `fetchUrlBytes`/`DownloadProgress`, `openFileDialog`) — Blob 을 파일로 내려받거나, URL 바이너리를 진행률과 함께 받거나, 파일 선택 대화상자를 코드에서 띄울 때. (아래 인라인 섹션)
 
-## Element 확장 메서드
+## 파일 다운로드/업로드
 
-`import "@simplysm/core-browser"`(또는 패키지 내 어떤 심볼이든 import) 시 `index.ts` 가 `import "./extensions/..."` 로 `Element.prototype` 에 등록함. 별도 초기화 호출 불필요.
+브라우저에서 파일을 내려받거나, URL 에서 바이너리를 받거나, 사용자가 파일을 고르게 할 때 쓰는 독립 함수 묶음.
 
-- `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` 기준 첫 탭 이동 가능 조상. 포커스 위임 대상을 위로 탐색할 때.
-- `findFirstTabbableChild(): HTMLElement | undefined` — TreeWalker 로 순회한 첫 탭 이동 가능 하위 요소. 컨테이너 진입 시 자동 포커스 대상 찾을 때.
-- `isOffsetElement(): boolean` — `position` 이 relative/absolute/fixed/sticky 중 하나면 true. offset parent(절대배치 기준) 역할 여부 판정에.
-- `isVisible(): boolean` — `getClientRects().length > 0` + `visibility !== "hidden"` + `opacity !== "0"` 를 모두 만족하면 true. 화면 표시 여부 판정에(display:none 은 clientRects 가 비어 false).
+### downloadBlob
 
 ```ts
-import "@simplysm/core-browser";
-const rows = containerEl.findAll<HTMLElement>("tr");
-const first = containerEl.findFirstTabbableChild();
+function downloadBlob(blob: Blob, fileName: string): void;
 ```
 
-## HTMLElement 확장 메서드
-
-`HTMLElement.prototype` 에 등록되는 메서드. 위와 동일하게 import 만으로 활성화.
+Blob 을 objectURL 로 만들어 동적 `a[download]` 클릭으로 저장. objectURL 은 1초 뒤 revoke. 화면 다운로드 버튼 핸들러에서 즉시 저장할 때.
 
-- `repaint(): void` — `offsetHeight` 접근으로 강제 동기 레이아웃(reflow)을 유발해 즉시 리페인트. 스타일 변경 직후 반영을 강제할 때.
-- `getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }` — 부모 기준 CSS top/left 좌표 계산. 뷰포트 위치·부모 스크롤·중간 요소 border·CSS transform 까지 반영. 드롭다운/팝업 위치 지정에. 부모를 못 찾으면 `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 }`.
+- `blob: Blob` — 저장할 데이터.
+- `fileName: string` — 저장 파일명. `sanitize-filename` 으로 OS 금지 문자·예약어를 제거한 뒤 추가로 `[`·`]` 도 제거하며, 결과가 빈 문자열이면 `"download"` 로 대체. 사용자 입력 파일명을 그대로 넣어도 안전.
 
 ```ts
-const { top, left } = popupEl.getRelativeOffset(".container");
-scrollEl.scrollIntoViewIfNeeded({ top: cellTop, left: cellLeft }, { top: headerH, left: fixedW });
+downloadBlob(new Blob([buf], { type: "application/pdf" }), "보고서[2026].pdf");
 ```
 
-## clipboard / bounds 정적 함수
-
-- `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 후 `preventDefault`. 커서 위치·선택 영역은 무시(전체 치환).
-  - event: `ClipboardEvent` — paste 이벤트 객체.
-- `getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>` — `IntersectionObserver` 로 여러 요소의 뷰포트 기준 경계를 한 번에 측정. 중복 제거 후 입력 순서대로 정렬해 반환. 빈 배열이면 즉시 `[]`. 모든 요소 관측 완료 시 resolve, 제한시간 초과 시 `TimeoutError` throw.
-  - els: `Element[]` — 측정 대상. 중복은 제거되고 입력 순서로 정렬됨.
-  - timeout: `number` — 제한시간(ms). 기본 `5000`. 초과 시 `TimeoutError`.
-- `ElementBounds`(반환 타입) — `target: Element`(측정 요소), `top`/`left`(뷰포트 기준 위치), `width`/`height`(요소 크기). 모두 `boundingClientRect` 값.
+### fetchUrlBytes / DownloadProgress
 
 ```ts
-inputEl.addEventListener("copy", copyElement);
-const bounds = await getBounds([elA, elB], 3000);
+interface DownloadProgress { receivedLength: number; contentLength: number }
+function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>;
 ```
 
-## 다운로드·파일선택·fetch
+URL 바이너리를 스트림 reader 로 다운로드. 큰 파일을 진행률과 함께 받을 때.
 
-- `downloadBlob(blob: Blob, fileName: string): void` — Blob 을 objectURL 로 만들어 동적 `a[download]` 클릭으로 저장. objectURL 은 1초 뒤 revoke. fileName 은 `sanitize-filename` 으로 금지문자·예약어 제거 후 `[`,`]` 도 제거하며, 결과가 비면 `"download"` 로 대체.
-  - blob: `Blob` — 저장할 데이터.
-  - fileName: `string` — 저장 파일명. 파일시스템 금지 문자·예약어는 자동 정리됨.
-- `openFileDialog(options?): Promise<File[] | undefined>` — 동적 `input[type=file]` 을 클릭해 파일 선택 다이얼로그 표시. 선택하면 `File[]`, 취소(cancel 이벤트)하거나 빈 선택이면 `undefined`.
-  - options.accept: `string` — 허용 MIME/확장자 필터(input `accept`). 미지정 시 제한 없음. 예: `".png,.jpg"`.
-  - options.multiple: `boolean` — 다중 선택 허용. 기본 `false`. 여러 파일 받을 때 `true`.
-- `fetchUrlBytes(url, options?): Promise<Uint8Array>` — URL 바이너리를 스트림으로 다운로드. `response.ok` 아니거나 본문 없으면 Error throw. Content-Length 가 있으면 그 크기로 사전 할당하며 수신량이 그보다 초과/미달이면 Error, 없으면 청크를 모아 `bytes.concat` 으로 병합(chunked encoding).
-  - url: `string` — 다운로드 대상 URL.
-  - options.onProgress: `(progress: DownloadProgress) => void` — 청크 수신마다 호출(Content-Length 가 있는 경로에서만).
-- `DownloadProgress`(콜백 인자 타입) — `receivedLength`(누적 수신 바이트), `contentLength`(전체 바이트, Content-Length).
+- `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
-downloadBlob(new Blob([buf]), "보고서.xlsx");
-const files = await openFileDialog({ accept: ".csv", multiple: true });
 const data = await fetchUrlBytes("/api/file", {
   onProgress: (p) => setPct(p.receivedLength / p.contentLength),
 });
 ```
+
+### openFileDialog
+
+```ts
+function openFileDialog(options?: { accept?: string; multiple?: boolean }): Promise<File[] | undefined>;
+```
+
+동적 `input[type=file]` 을 만들어 클릭, 파일 선택 대화상자를 표시. 업로드 버튼 핸들러에서 호출.
+
+- `options.accept: string` — 허용 MIME/확장자 필터(input `accept` 에 그대로 전달). 미지정 시 제한 없음. 특정 형식만 받을 때(예: `".png,.jpg"`, `"image/*"`).
+- `options.multiple: boolean` — 다중 선택 허용. true 면 여러 파일 선택 가능, 기본 `false`(단일). 여러 파일 업로드 화면이면 true.
+- 반환: 선택 파일이 있으면 `File[]`, 사용자가 취소하거나(`cancel` 이벤트) 0개 선택이면 `undefined`. 결측을 빈 배열로 뭉개지 않으므로 `== null` 로 취소를 구분.
+
+```ts
+const files = await openFileDialog({ accept: ".csv", multiple: true });
+if (files == null) return; // 취소
+```