@simplysm/sd-claude 14.0.88 → 14.0.90

package/claude/references/sd-simplysm14/apis/angular/sheet.md

@@ -1,78 +1,88 @@
 # @simplysm/angular — 시트 (sd-sheet)
 
-선택·다중정렬·트리확장·컬럼 고정/숨김/리사이즈·페이지네이션·셀편집·설정 영속화를 갖춘 데이터 그리드. 컬럼은 `<sd-sheet-column>` 디렉티브 + `<ng-template [cell]>` 셀 템플릿으로 선언. 선택/정렬/확장은 selection-managers 컴포저블을 내부 사용.
-
-## SdSheet
-
-`<sd-sheet>` — 데이터 그리드. 제네릭 `<TItem>`.
-
-inputs:
-- `key = input<string>()` — 설정 영속화 키. 지정 시 설정 버튼·컬럼폭/순서/고정/숨김을 `SdSystemConfigProvider` 에 저장.
-- `items = input<TItem[]>([])` — 표시 데이터.
-- `trackByFn = input<(item, index) => unknown>` — 행 키 추출. 기본 `(item) => item`. 선택키·정렬 추적 기준.
-- `selectMode: "single"|"multi"` — 선택 모드. 미지정 시 선택 비활성. multi 면 헤더 전체선택 체크박스.
-- `autoSelect: "click"|"focus"` — 자동 선택 트리거. `"click"` = 행/셀 클릭 시 선택, `"focus"` = 셀 포커스 시 선택. 키보드 위주 화면이면 `"focus"`.
-- `getItemSelectableFn?: (item) => boolean | string` — 행 선택 가능 여부. `string` 반환 시 비활성 + 그 문자열을 툴팁 사유로 표시.
-- `getChildrenFn?: (item, index) => TItem[] | undefined` — 트리 자식. 지정 시 확장 토글 컬럼 노출.
-- `useAutoSort = input(false)` — 클라이언트 정렬. true 면 `sorts` 변경 시 시트가 직접 `items` 정렬. 서버측 정렬/페이징이면 false 로 두고 외부에서 재조회.
-- `visiblePageCount = input(10)`/`totalPageCount = input(0)`/`itemsPerPage = input(0)` — 페이지네이션. `totalPageCount>0` 면 서버 페이징, `itemsPerPage>0` 면 클라이언트 페이징.
-- `focusMode: "row"|"cell"` — 키보드 포커스 단위. `"row"` = 행 강조만, `"cell"` = 셀 단위 포커스/편집. 기본 `"cell"`.
-- `inset = input(false)` — 테두리 없는 삽입형.
-- `contentStyle` — 스크롤 컨테이너 인라인 스타일.
-- `getItemCellClassFn?: (item, colKey) => string` / `getItemCellStyleFn?: (item, colKey) => string | undefined` — 셀별 동적 클래스/스타일.
-- `hideConfigBar = input(false)` — 상단 설정/페이지 바 숨김.
-- `columnControlsInput = input<readonly SdSheetColumn[]>([])` — 투영 외 추가 컬럼 컨트롤(예: CRUD 목록이 삭제 컬럼 주입).
-
-outputs:
-- `itemKeydown = output<SdSheetItemKeydownEventParam<TItem>>()` — 행에서 키 입력(`{ item, event }`).
-- `cellKeydown = output<SdSheetCellKeydownEventParam<TItem>>()` — 셀에서 키 입력(`{ item, key, event }`, key=컬럼키).
-
-models(양방향):
-- `selectedKeys = model<unknown[]>([])` — 선택 행 키 배열.
-- `expandedItems = model<TItem[]>([])` — 펼친 트리 항목.
-- `sorts = model<SortingDef[]>([])` — 정렬 정의(`{ key, desc }[]`). 헤더 클릭으로 토글(Shift=다중).
-- `currentPage = model(0)` — 현재 페이지(0-base).
-
-## SdSheetColumn
-
-`<sd-sheet-column>` 디렉티브 — 컬럼 정의. 제네릭 `<T>`.
-
-- `key = input.required<string>()` — 컬럼 식별키(설정 저장·정렬·이벤트 기준).
-- `header: string | string[]` — 헤더 텍스트. 배열이면 다단(그룹) 헤더.
-- `headerStyle`/`tooltip` — 헤더 스타일·툴팁.
-- `width` — 컬럼 폭(CSS 값).
-- `fixed = input(false)` — 좌측 고정.
-- `hidden = input(false)` — 숨김.
-- `collapse = input(false)` — 접힘.
-- `disableSorting = input(false)` — 정렬 비활성.
-- `disableResizing = input(false)` — 폭 조절 비활성.
-- `ordering = input(0)` — 컬럼 정렬 순서.
-- 셀 본문은 `<ng-template [cell]="items()" let-item="item" let-edit="edit">`, 헤더 커스텀은 `#headerTpl`, 합계행은 `#summaryTpl`.
-
-`SdSheetCellContext<T>` (셀 템플릿 컨텍스트): `$implicit`/`item`(행 데이터), `index`(행 인덱스), `depth`(트리 깊이), `edit`(현재 셀 편집모드 여부).
-
-## SdSheetColumnCellTemplate
-
-`<ng-template [cell]>` 디렉티브 — 셀 본문 템플릿 마커. `cell = input.required<T[]>()` 로 타입 추론용 items 를 받아 `SdSheetCellContext<T>` 컨텍스트 타입 가드 제공.
-
-## SdSheetConfigModal
-
-`<sd-sheet-config-modal>` — 시트 설정(컬럼 표시/순서/고정/폭) 편집 모달. `sd-sheet` 의 설정 버튼이 내부적으로 띄움. 직접 사용은 드묾.
-
-## 타입
-
-- `SdSheetColumnDef` — 해석된 컬럼 정의(`key`/`header`/`width`/`fixed`/`hidden`/`collapse`/`disableSorting`/`disableResizing`/`ordering`/`headerStyle`/`tooltip`).
-- `SdSheetHeaderDef` — 헤더 셀 메타(`text`/`colspan`/`rowspan`/`isLastRow`/`fixed`/`colDef`/`colIndex`).
-- `SdSheetConfig` — 영속화 형태. `columnRecord: Record<키, { width?; hidden?; fixed?; ordering? }>`.
-- `SdSheetItemKeydownEventParam<T>` — `{ item, event }`.
-- `SdSheetCellKeydownEventParam<T>` — `{ item, key, event }`.
-- `SortingDef`(re-export) — `{ key: string; desc: boolean }`.
-
+다건 목록·편집 표(그리드). 컬럼 디렉티브 + 셀 템플릿으로 구성하며, 선택·정렬·페이지·트리펼침·셀 편집·컬럼 고정/리사이즈/설정저장을 내장. `sd-crud-list` 는 이 시트를 감싼 표준 골격(crud.md). 셀 본문·정렬·폭 규약은 client-component.md "시트 컬럼·셀 표준" 을 따름.
+
+## SdSheet<TItem> (`sd-sheet`)
+
+### 입력
+
+- `key: string` — 시트 설정(컬럼 폭/숨김/고정/순서) 저장 키. 지정하면 설정 버튼 + `SdSystemConfigProvider` 영속·복원. 없으면 설정 비활성.
+- `items: TItem[]` — 표시할 행 데이터.
+- `trackByFn: (item, index) => unknown` — 행 추적/선택 키 함수(기본 item 자체). 선택은 이 반환값을 키로 사용.
+- `selectMode: "single"|"multi"` — 선택 모드. 미지정이면 선택 비활성. single 은 행 화살표, multi 는 체크박스(전체선택 헤더).
+- `autoSelect: "click"|"focus"` — 자동 선택 트리거. `"click"` = 행/셀 클릭 시 선택, `"focus"` = 셀 포커스 이동만으로 선택. 키보드 위주 화면이면 `"focus"`.
+- `getItemSelectableFn: (item) => boolean | string` — 행 선택 가능 여부. `false`/문자열(사유) 면 선택 불가(문자열은 툴팁으로 표시).
+- `getChildrenFn: (item, index) => TItem[] | undefined` — 트리 자식 함수. 지정 시 펼침 기능 활성(들여쓰기 + 토글).
+- `useAutoSort: boolean` — 클라이언트 정렬. true 면 `sorts` 변경 시 시트가 직접 `items` 정렬. 서버 페이징/정렬이면 false(외부에서 재조회). `sd-crud-list` 는 `totalPageCount===0` 일 때만 true.
+- `totalPageCount: number` — 서버 페이징 총 페이지 수. >0 이면 서버 페이징 모드(시트는 slice 안 함).
+- `itemsPerPage: number` — 클라이언트 페이징 페이지당 행 수. >0 이면 시트가 직접 slice. `totalPageCount` 와 택일.
+- `visiblePageCount: number` — 페이지네이터 표시 번호 개수(기본 10).
+- `focusMode: "row"|"cell"` — 키보드 포커스 단위. `"cell"`(기본) = 셀 단위 이동·셀 포커스 표시, `"row"` = 행 단위(셀 표시 없음). 셀 편집/복사 화면이면 `"cell"`.
+- `inset: boolean` — 테두리·radius 제거(컨테이너 내장).
+- `contentStyle: string` — 스크롤 컨테이너 인라인 스타일.
+- `getItemCellClassFn: (item, colKey) => string` / `getItemCellStyleFn: (item, colKey) => string | undefined` — 셀별 클래스/스타일(삭제행 취소선 등).
+- `hideConfigBar: boolean` — 상단 설정/페이지 바 숨김.
+- `columnControlsInput: readonly SdSheetColumn[]` — 템플릿 외부에서 컬럼 디렉티브를 주입(투영 컬럼과 합쳐짐). `sd-crud-list` 가 투영 컬럼을 시트로 전달할 때 사용.
+
+### 출력·모델
+
+- `selectedKeys: model<unknown[]>` — 선택된 행 키 배열(`trackByFn` 반환값). single 도 배열(길이 0/1).
+- `expandedItems: model<TItem[]>` — 펼쳐진 트리 항목.
+- `sorts: model<SortingDef[]>` — 정렬 상태(`{ key; desc }[]`). 헤더 클릭으로 토글(Shift=다중). `useAutoSort` 면 직접 정렬, 아니면 외부 재조회 트리거.
+- `currentPage: model<number>` — 현재 페이지(0-based).
+- `itemKeydown: output<SdSheetItemKeydownEventParam<TItem>>` — 행에서 키 입력(`{ item; event }`).
+- `cellKeydown: output<SdSheetCellKeydownEventParam<TItem>>` — 셀에서 키 입력(`{ item; key; event }`. key=컬럼 key).
+
+### 컬럼·셀
+
+#### SdSheetColumn<T> (`sd-sheet-column`)
+
+컬럼 정의 디렉티브. `<sd-sheet>`(또는 `sd-crud-list`) 직속 자식으로 둠.
+
+- `key: input.required<string>` — 컬럼 식별 키(설정 저장·셀 키).
+- `header: string | string[]` — 헤더 텍스트(배열이면 다단 헤더로 그룹).
+- `headerStyle: string` — 헤더 셀 스타일.
+- `tooltip: string` — 헤더 도움말(? 표시).
+- `width: string` — 컬럼 폭(미지정=자동). px 지정은 명시 지시 시만(client-component.md).
+- `fixed: boolean` — 좌측 고정 컬럼.
+- `hidden: boolean` — 숨김.
+- `collapse: boolean` — 접힘 컬럼.
+- `disableSorting: boolean` — 헤더 클릭 정렬 비활성.
+- `disableResizing: boolean` — 폭 드래그 리사이즈 비활성.
+- `ordering: number` — 컬럼 정렬 순서.
+- 템플릿: `<ng-template [cell]="items()" let-item="item">`(필수, 셀 본문), `#headerTpl`(헤더 커스텀), `#summaryTpl`(요약 행).
+- `SdSheetCellContext<T> = { $implicit; item: T; index: number; depth: number; edit: boolean }` — 셀 컨텍스트. `let-edit="edit"` 로 편집 모드 여부.
+
+#### SdSheetColumnCellTemplate<T> (`ng-template[cell]`)
+
+셀 본문 템플릿 디렉티브. `cell: input.required<T[]>` 는 타입 추론용 더미(실제 데이터는 시트 `items`). `let-item`/`let-index`/`let-depth`/`let-edit` 컨텍스트 제공.
+
+사용:
 ```html
-<sd-sheet [items]="rows()" [(selectedKeys)]="sel" [selectMode]="'multi'"
-          [(sorts)]="sorts" [useAutoSort]="true" key="order-sheet">
-  <sd-sheet-column key="name" header="이름" [fixed]="true">
-    <ng-template [cell]="rows()" let-item="item">{{ item.name }}</ng-template>
+<sd-sheet [items]="items()" [(selectedKeys)]="selectedKeys" selectMode="single" [trackByFn]="trackByFn">
+  <sd-sheet-column [key]="'name'" [header]="'이름'">
+    <ng-template [cell]="items()" let-item="item">
+      <div class="p-xs-sm">{{ item.name }}</div>
+    </ng-template>
   </sd-sheet-column>
 </sd-sheet>
 ```
+
+#### SdSheetConfigModal (`sd-sheet-config-modal`)
+
+컬럼 폭/순서/고정/숨김을 사용자가 조정하는 설정 모달(`SdModalContentDef<SdSheetConfig | undefined>`). `key` 있는 시트의 설정 버튼이 자동으로 띄움 → 직접 호출 불필요.
+
+- `sheetKey: input.required<string>` / `controls: input.required<readonly SdSheetColumn[]>` / `config: input.required<SdSheetConfig | undefined>` — 대상 시트 키·컬럼들·현재 설정.
+- `close: output<SdSheetConfig | undefined>` — 변경된 설정(취소 시 undefined).
+
+### 타입 (data/sheet/types)
+
+- `SdSheetColumnDef` — 내부 계산된 컬럼 정의(`key/header/headerStyle/tooltip/width/fixed/hidden/collapse/disableSorting/disableResizing/ordering`).
+- `SdSheetHeaderDef` — 헤더 셀 렌더 정의(`text/colspan/rowspan/isLastRow/fixed/colDef/colIndex`).
+- `SdSheetConfig = { columnRecord: Record<string, { width?; hidden?; fixed?; ordering? }> }` — 영속되는 시트 설정.
+- `SdSheetItemKeydownEventParam<T> = { item: T; event: KeyboardEvent }`.
+- `SdSheetCellKeydownEventParam<T> = { item: T; key: string; event: KeyboardEvent }`.
+
+### 요약 행
+
+컬럼 중 하나라도 `#summaryTpl` 을 가지면 헤더 하단에 요약 행이 고정 렌더(warning 배경). 집계 값은 시트가 계산하지 않으므로 화면에서 `computed` 로 만들어 넣음(client-component.md).

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

@@ -1,69 +1,70 @@
 # @simplysm/capacitor-plugin-auto-update
 
-Android 앱(Capacitor)에서 APK 설치 및 자동 업데이트를 수행하는 플러그인. APK 설치 인텐트 실행·설치 권한 관리·서버/외부저장소 기반 최신 버전 감지 후 다운로드·설치 흐름을 제공. 모든 공개 심볼은 `static` 멤버만 가진 abstract 클래스이거나 타입이므로 인스턴스 생성 없이 클래스명으로 직접 호출.
+Capacitor 앱(Android)에서 APK 설치 인텐트를 실행하고, 서버 또는 외부 저장소의 최신 APK 를 받아 자동 업데이트하는 플러그인. 공개 심볼은 모두 `static` 멤버만 가진 abstract 클래스이거나 타입이라 인스턴스 없이 클래스명으로 직접 호출. 비-Android(웹) 환경에서는 `ApkInstallerWeb` 폴백으로 설치는 no-op, 권한은 항상 통과로 동작.
 
 ## 사용 트리거 인덱스
 
-- **AutoUpdate** — 앱 시작 시 최신 버전을 감지해 APK 를 받아 설치하는 전체 자동 업데이트 흐름을 돌릴 때. 서버 조회 방식(`run`)과 외부 저장소 디렉토리 방식(`runByExternalStorage`).
-- **ApkInstaller** — 자동 업데이트 흐름을 직접 구성할 때 쓰는 저수준 API. 설치 권한 확인·요청, APK 설치 인텐트 실행, 현재 앱 버전 조회.
-- **ApkInstallerPlugin / VersionInfo** — Capacitor 네이티브 브리지 인터페이스 타입과 버전 정보 형태. 플러그인을 직접 등록·구현하거나 반환 타입을 참조할 때.
+- **AutoUpdate** — 앱 부팅 시 "최신 확인 → 권한 → 다운로드 → 설치 → 앱 멈춤" 까지 한 번에 돌리는 자동 업데이트 오케스트레이터. 서버 기반(`run`) 또는 외부 저장소 기반(`runByExternalStorage`). 부트스트랩에서 1회 호출.
+- **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(파일경로)` 결과). 내부에서 `{ uri: apkUri }` 로 래핑해 플러그인에 전달. 웹에서는 미지원 alert 후 반환.
+- getVersionInfo() → VersionInfo — 현재 설치된 앱 버전 조회. 서버/외부 버전과 비교할 현재 버전 기준값. 웹 구현은 `versionName` 을 빌드 시 주입된 `env("__VER__")`(없으면 `"0.0.0"`), `versionCode` 를 `"0"` 으로 응답.
 
-```ts
+```typescript
 const { granted, manifest } = await ApkInstaller.checkPermissions();
+if (!manifest) throw new Error("앱을 재설치해야 합니다.");
 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 +73,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,28 +1,32 @@
 # @simplysm/capacitor-plugin-file-system
 
-Capacitor 기반 네이티브 파일 시스템 접근 플러그인. Android 는 외부/앱 저장소 직접 접근(11+ 는 `MANAGE_EXTERNAL_STORAGE`, 10- 는 `READ/WRITE_EXTERNAL_STORAGE` 권한), Browser 는 IndexedDB 기반 에뮬레이션으로 동작.
+Capacitor 네이티브 파일 시스템 접근 플러그인. Android 는 OS 파일 시스템(Android 11+ 는 `MANAGE_EXTERNAL_STORAGE`, 10- 는 `READ/WRITE_EXTERNAL_STORAGE` 권한), 웹은 IndexedDB 기반 가상 파일 시스템으로 동일 API 를 에뮬레이션한다. 권한 확인/요청, 디렉토리 읽기·생성, 파일 읽기·쓰기·삭제, 저장소 경로·파일 URI 조회를 모두 `FileSystem` 정적 메서드로 제공한다.
 
 ## 사용 트리거 인덱스
 
-- **FileSystem** — 파일 읽기/쓰기, 디렉토리 조회/생성, 삭제, 권한 확인/요청, 저장소 경로 조회가 필요할 때 쓰는 정적(static) 진입점 클래스(주 사용처).
-- **StorageType** — `FileSystem.getStoragePath` 인자로 넘기는 저장소 위치 유형 리터럴을 고를 때.
-- **FileInfo** — `FileSystem.readdir` 가 반환하는 항목 정보(이름 + 디렉토리 여부). 디렉토리 순회 시.
-- **FileSystemPlugin** — Capacitor 네이티브 브릿지 원형 인터페이스 타입. 보통 `FileSystem` 가 래핑하므로 직접 호출 불필요. 커스텀 web 구현 작성이나 타입 참조 시에만.
+- **FileSystem** — 앱에서 단말 파일을 읽고 쓰거나 디렉토리·권한을 다룰 때의 진입점. 모든 메서드가 `static async` 이며 인스턴스화 불필요(abstract class). 권한·경로·읽기/쓰기·삭제 전반.
+- **StorageType** — `getStoragePath` 인자. 어느 저장소(외부/앱 전용/캐시 등) 의 기준 경로를 얻을지 고를 때.
+- **FileInfo** — `readdir` 결과 항목 타입. 디렉토리 나열 결과를 순회·필터할 때.
+- **FileSystemPlugin** — 저수준 Capacitor 플러그인 인터페이스(옵션 객체 기반 원형). 보통 직접 쓰지 않고 `FileSystem` 래퍼를 쓰며, 커스텀 네이티브/web 구현이나 옵션·반환 타입 참조가 필요할 때만 사용.
 
-## FileSystem (static 클래스)
+## FileSystem
 
-모든 메서드 `static async`. 인스턴스 생성 없이 `FileSystem.xxx()` 호출. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 으로 얻은 네이티브/web 구현에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환.
+모든 파일 작업의 진입점. 추상 클래스의 정적 메서드 모음이라 `new` 없이 `FileSystem.메서드()` 로 호출한다. 내부적으로 `registerPlugin<FileSystemPlugin>("FileSystem")` 으로 얻은 네이티브 구현(웹은 `FileSystemWeb`)에 위임하고, 플러그인의 `{ ... }` 래퍼 결과를 평탄화해 반환한다.
 
-- `checkPermissions(): Promise<boolean>` — 파일 접근 권한 보유 여부. true 면 권한 있음. 읽기/쓰기 전 사전 확인용. 플러그인의 `{ granted }` 를 boolean 으로 풀어 반환.
-- `requestPermissions(): Promise<void>` — 권한 요청. Android 11+ 는 설정 화면으로 이동, Android 10- 는 권한 대화상자 표시. `checkPermissions()` 가 false 일 때 호출.
-- `readdir(dirPath: string): Promise<FileInfo[]>` — 디렉토리 하위 항목 목록 조회. `dirPath` = 조회할 디렉토리 경로. 각 항목은 `FileInfo`(이름·디렉토리 여부).
-- `getStoragePath(type: StorageType): Promise<string>` — 지정 유형 저장소의 절대 경로 조회. 경로를 직접 조립하지 말고 이 메서드로 베이스 경로를 얻어 join. `type` 풀이는 아래 StorageType 참조.
-- `getUri(filePath: string): Promise<string>` — 파일을 FileProvider 기반 content URI 로 변환. 다른 앱(공유·열기 인텐트)에 파일을 넘길 때. `filePath` = 대상 파일 경로.
-- `writeFile(filePath: string, data: string | Bytes): Promise<void>` — 파일 쓰기. `data` 가 `string` 이면 utf8 인코딩으로, `Bytes`(Uint8Array)면 base64 로 인코딩해(`bytes.toBase64`, cross-realm 안전) 저장. 텍스트면 string, 바이너리면 Bytes 를 넘김.
-- `readFile(filePath: string): Promise<Bytes>` / `readFile(filePath: string, encoding: "utf8"): Promise<string>` — 파일 읽기 오버로드. `encoding` 생략 시 base64 로 읽어 `Bytes`(`bytes.fromBase64`) 반환(바이너리용), `"utf8"` 지정 시 텍스트 `string` 반환. 반환 타입이 오버로드로 갈리므로 바이너리는 인자 없이, 텍스트는 `"utf8"` 명시.
-- `remove(targetPath: string): Promise<void>` — 파일 또는 디렉토리 삭제(재귀). `targetPath` = 삭제 대상 경로. 디렉토리면 하위까지 모두 제거.
-- `mkdir(targetPath: string): Promise<void>` — 디렉토리 생성(재귀). `targetPath` = 생성할 경로. 중간 상위 디렉토리가 없으면 함께 생성.
-- `exists(targetPath: string): Promise<boolean>` — 경로 존재 여부 확인. true 면 존재. 쓰기 전 충돌 확인이나 읽기 전 가드용.
+- `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 = 없음. 읽기/삭제 전 분기 조건.
+
+`data` 의 `Bytes` 는 `@simplysm/core-common` 의 바이트 배열 타입(Uint8Array 계열). 텍스트는 문자열로 그대로 전달, 바이너리는 `Bytes` 로 전달하면 내부에서 base64 왕복 처리한다.
+
+사용 예:
 
 ```ts
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
@@ -35,32 +39,56 @@ await FileSystem.writeFile(`${base}/notes/memo.txt`, "hello"); // utf8
 const text = await FileSystem.readFile(`${base}/notes/memo.txt`, "utf8"); // string
 const raw = await FileSystem.readFile(`${base}/notes/memo.txt`); // Bytes
 for (const f of await FileSystem.readdir(`${base}/notes`)) {
-  console.log(f.name, f.isDirectory);
+  if (!f.isDirectory) console.log(f.name);
+}
+const uri = await FileSystem.getUri(`${base}/notes/memo.txt`); // 웹: 사용 후 URL.revokeObjectURL(uri)
+```
+
+## StorageType
+
+`getStoragePath(type)` 가 받는 저장소 유형 리터럴. 직접 경로를 만들지 말고 이 유형으로 플랫폼 표준 위치를 얻는다.
+
+```ts
+type StorageType =
+  | "external" | "externalFiles" | "externalCache" | "externalMedia"
+  | "appData" | "appFiles" | "appCache";
+```
+
+- `"external"` — 외부 저장소 루트(`Environment.getExternalStorageDirectory`). 사용자/타 앱과 공유되는 공용 영역 전체에 접근할 때. `MANAGE_EXTERNAL_STORAGE` 권한 필요.
+- `"externalFiles"` — 앱 전용 외부 파일 디렉토리. 앱이 소유하는 외부 영속 파일(앱 제거 시 함께 삭제)을 둘 때.
+- `"externalCache"` — 앱 전용 외부 캐시 디렉토리. 공간 부족 시 OS 가 회수할 수 있는 외부 임시 캐시를 둘 때.
+- `"externalMedia"` — 앱 전용 외부 미디어 디렉토리. 이미지·동영상 등 미디어 산출물을 외부 미디어 영역에 둘 때.
+- `"appData"` — 앱 데이터 디렉토리(내부 저장소). 앱 비공개 데이터 루트가 필요할 때.
+- `"appFiles"` — 앱 파일 디렉토리(내부 저장소). 앱 비공개 영속 파일을 둘 때.
+- `"appCache"` — 앱 캐시 디렉토리(내부 저장소). 재생성 가능한 내부 임시 캐시를 둘 때.
+
+웹에서는 각 유형이 `/webfs/<type>` 가상 경로로 매핑되며 호출 시 해당 디렉토리를 자동 생성한다.
+
+## FileInfo
+
+`readdir` 가 반환하는 디렉토리 항목 1건.
+
+```ts
+interface FileInfo {
+  name: string;
+  isDirectory: boolean;
 }
 ```
 
-## StorageType / FileInfo / FileSystemPlugin
-
-- `StorageType` — `getStoragePath(type)` 의 저장소 위치 선택 유니온. 값별 디렉토리 매핑:
-  - `"external"` — 외부 저장소 루트(`Environment.getExternalStorageDirectory`). 사용자에게 노출되는 공용 영역 전체 접근 시. MANAGE_EXTERNAL_STORAGE 권한 필요.
-  - `"externalFiles"` — 앱 전용 외부 파일 디렉토리. 앱이 소유하는 외부 영속 파일용(앱 제거 시 함께 삭제).
-  - `"externalCache"` — 앱 전용 외부 캐시 디렉토리. 시스템이 공간 부족 시 회수할 수 있는 임시 캐시용.
-  - `"externalMedia"` — 앱 전용 외부 미디어 디렉토리. 이미지·동영상 등 미디어 산출물용.
-  - `"appData"` — 앱 데이터 디렉토리(내부 저장소). 앱 비공개 데이터용.
-  - `"appFiles"` — 앱 파일 디렉토리(내부 저장소). 앱 비공개 영속 파일용.
-  - `"appCache"` — 앱 캐시 디렉토리(내부 저장소). 앱 비공개 임시 캐시용.
-- `FileInfo` — `readdir` 결과 배열의 각 항목.
-  - `name: string` — 항목(파일·디렉토리) 이름.
-  - `isDirectory: boolean` — 디렉토리 여부. true 면 디렉토리, false 면 파일. 재귀 순회 시 분기 기준.
-- `FileSystemPlugin` — `registerPlugin` 에 넘기는 네이티브 브릿지 인터페이스. 메서드는 `FileSystem` 정적 메서드의 저수준 원형으로, 옵션 객체를 받고 래핑 전 결과를 `{ ... }` 로 반환:
-  - `checkPermissions(): Promise<{ granted: boolean }>` — 권한 보유 여부를 `granted` 로 반환.
-  - `requestPermissions(): Promise<void>` — 권한 요청.
-  - `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` 로 반환.
-  - `remove(options: { path: string }): Promise<void>` — `path` 파일/디렉토리 재귀 삭제.
-  - `mkdir(options: { path: string }): Promise<void>` — `path` 디렉토리 재귀 생성.
-  - `exists(options: { path: string }): Promise<{ exists: boolean }>` — `path` 존재 여부를 `exists` 로 반환.
-  - 직접 호출 대신 `FileSystem` 사용 권장. 커스텀 web 구현 작성 시 이 인터페이스를 구현.
+- `name: string` — 항목 이름(경로가 아닌 파일/디렉토리명). 표시·필터·경로 결합 시.
+- `isDirectory: boolean` — 디렉토리 여부. true = 하위 디렉토리(재귀 탐색 대상), false = 파일. 파일만 처리할지 폴더로 내려갈지 분기할 때.
+
+## FileSystemPlugin
+
+저수준 Capacitor 플러그인 인터페이스. `FileSystem` 정적 메서드가 내부에서 위임하는 원형으로, 메서드가 옵션 객체(`{ path }`, `{ type }`, `{ path, data, encoding }`)를 받고 결과도 래핑 객체(`{ granted }`, `{ files }`, `{ path }`, `{ uri }`, `{ data }`, `{ exists }`)로 반환한다. 보통 직접 호출하지 않으며, 커스텀 web 구현(`FileSystemPlugin` 구현)을 작성하거나 옵션/반환 타입을 참조해야 할 때만 사용한다.
+
+- `checkPermissions(): Promise<{ granted: boolean }>` — 권한 보유 여부를 `granted` 로 반환.
+- `requestPermissions(): Promise<void>` — 권한 요청.
+- `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` 파일의 외부 전달용 `uri` 반환.
+- `writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>` — `path` 에 `data`(문자열) 기록. `encoding` = 입력 데이터 해석 방식. `"utf8"` = 텍스트 그대로, `"base64"` = base64 문자열을 바이너리로 디코드해 기록. 래퍼 `FileSystem.writeFile` 이 문자열은 `"utf8"`, `Bytes` 는 `"base64"` 로 자동 지정.
+- `readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>` — `path` 읽어 `data`(문자열) 반환. `encoding` = 반환 문자열 형식. `"utf8"` = 텍스트, `"base64"` = 바이너리를 base64 문자열로 인코딩. 플러그인 레벨에서 바이너리는 항상 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,32 @@
 # @simplysm/capacitor-plugin-intent
 
-Android 인텐트 송수신 Capacitor 플러그인. 브로드캐스트 구독/전송, 실행 인텐트 조회, `startActivityForResult` 외부 Activity 실행을 제공하며 바코드 스캐너·PDA 등 산업용 디바이스 연동에 사용. 웹 환경은 미지원 스텁(경고 로그 후 빈/스텁 결과)으로 동작.
+Android 인텐트(Intent) 송수신 Capacitor 플러그인. 브로드캐스트 수신/전송, 실행 인텐트 조회, newIntent 이벤트 리스닝, `startActivityForResult` 외부 Activity 실행·결과 수신을 다룸. 산업용 디바이스(바코드 스캐너·PDA 등, 예: Zebra DataWedge) 연동에 사용. 웹 환경(`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: 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>` — 브로드캐스트 전송.
+  - `action: string` — 전송할 인텐트 액션 문자열(필수). 디바이스 API 가 정의한 명령 액션을 지정.
+  - `extras?: Record<string, unknown>` — 함께 보낼 추가 키-값 데이터(선택). 명령 파라미터(예: 스캐너 트리거 토글 값)를 담을 때.
+- `Intent.getLaunchIntent(): Promise<IntentResult>` — 앱을 실행시킨 인텐트 조회. 외부 인텐트로 앱이 기동됐는지·그 `extras` 를 앱 시작 시점에 읽을 때. 웹 스텁은 항상 빈 객체 `{}` 반환.
+- `Intent.addListener(eventName: "newIntent", callback: (result: IntentResult) => void): Promise<PluginListenerHandle>` — 앱 실행 중 새로 들어오는 인텐트 리스너 등록.
+  - `eventName: "newIntent"` — 리스닝 대상 이벤트(현재 이 리터럴 하나만 지원). 이미 떠 있는 앱에 인텐트가 재전달되는 singleTop 등 상황에서 발생.
+  - `callback: (result: IntentResult) => void` — 새 인텐트 수신 시 호출. 들어온 인텐트의 `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). 옵션·결과 필드는 아래 "입출력 타입" 참조.
 
 사용 예:
 
@@ -36,36 +44,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` 은 무동작. 웹·하이브리드 공용 코드에서 호출해도 예외는 나지 않으나 인텐트 동작은 Android 에서만 발생함을 전제로 작성할 것.
 
 ## 입출력 타입
 
-`Intent` 메서드의 결과·옵션을 타입 처리할 때 참조하는 인터페이스들.
+`Intent` 메서드의 결과·옵션을 타입으로 다룰 때 참조하는 인터페이스. "값 없음"은 그대로 `undefined` 로 전달되므로 호출부에서 optional 로 다룰 것.
 
-- `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` 반환.
-  - `data?: { action?: string; uri?: string; extras?: Record<string, unknown> }` — 결과 인텐트 데이터. `action` = 결과 인텐트 액션, `uri` = 결과 data URI, `extras` = 결과 추가 데이터. 취소 등으로 데이터가 없으면 부재.
+  - `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` 형태로 접근.
 
 ## 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 실행 및 결과 수신.