@simplysm/sd-claude 14.0.41 → 14.0.43

package/claude/references/sd-simplysm14/angular/docs/utils.md

@@ -265,7 +265,7 @@ function setupModelHook<T, S extends WritableSignal<T>>(
 function setupCanDeactivate(fn: () => boolean): void
 ```
 
-모달 내부이면 `SdActivatedModalProvider.canDeactiveFn`에 설정, 라우트 내부이면 `routeConfig.canDeactivate`에 추가.
+모달 내부이면 `SdActivatedModalProvider.canDeactivateFn`에 설정, 라우트 내부이면 `routeConfig.canDeactivate`에 추가.
 
 ### `setupCumulateSelectedKeys`
 

package/claude/references/sd-simplysm14/angular/usage.md

@@ -2,6 +2,8 @@
 
 Angular 21 기반 UI 컴포넌트 라이브러리. Zoneless, signal-based, standalone 컴포넌트로 구성된다.
 
+> **NOTE:** 이 문서는 `@simplysm/angular` 라이브러리의 사용법만 다룬다. Angular 프레임워크 자체의 사용법(컴포넌트 작성, DI, 라우팅, signal 등)은 `angular-cli` MCP를 활용한다.
+
 ## Installation
 
 ```bash
@@ -49,7 +51,6 @@ npm install @simplysm/angular
 
 | API | Type | Description |
 |-----|------|-------------|
-| `AppStructureItem` | type | 앱 구조 항목 (그룹 또는 리프) |
 | `SdMenu` | interface | 메뉴 트리 노드 |
 | `SdFlatMenu` | interface | 플랫 메뉴 항목 |
 | `SdPermission` | interface | 권한 트리 노드 |
@@ -82,6 +83,11 @@ npm install @simplysm/angular
 | `SdItemOfTemplate` | directive | `ng-template[itemOf]` 항목 반복 템플릿 타입 가드 |
 | `SdItemOfTemplateContext` | interface | itemOf 템플릿 컨텍스트 (`$implicit`, `item`, `index`, `depth`) |
 | `SdRouterLink` | directive | `[sdRouterLink]` 라우터 네비게이션 (Ctrl+클릭 새 창) |
+| `SdCommandDirective` | directive | `[sdSaveCommand]`, `[sdRefreshCommand]`, `[sdInsertCommand]` 키보드 단축키 output 이벤트 디렉티브 |
+| `SdResizeDirective` | directive | `[sdResize]` ResizeObserver 기반 resize output 이벤트 디렉티브 |
+| `SdResizeEvent` | interface | resize 이벤트 데이터 (`heightChanged`, `widthChanged`, `target`, `contentRect`) |
+| `SdIntersectionDirective` | directive | `[sdIntersection]` IntersectionObserver 기반 intersection output 이벤트 디렉티브 |
+| `SdIntersectionEvent` | interface | intersection 이벤트 데이터 (`entry`) |
 
 -> See [docs/directives.md](./docs/directives.md) for details.
 
@@ -89,14 +95,7 @@ npm install @simplysm/angular
 
 | API | Type | Description |
 |-----|------|-------------|
-| `SdSaveCommandEventPlugin` | class | `(sdSaveCommand)` Ctrl+S 이벤트 플러그인 |
-| `SdRefreshCommandEventPlugin` | class | `(sdRefreshCommand)` Ctrl+Alt+L 이벤트 플러그인 |
-| `SdInsertCommandEventPlugin` | class | `(sdInsertCommand)` Ctrl+Insert 이벤트 플러그인 |
-| `SdResizeEventPlugin` | class | `(sdResize)` ResizeObserver 이벤트 플러그인 |
-| `SdResizeEvent` | interface | resize 이벤트 데이터 |
-| `SdIntersectionEventPlugin` | class | `(sdIntersection)` IntersectionObserver 이벤트 플러그인 |
-| `SdIntersectionEvent` | interface | intersection 이벤트 데이터 |
-| `SdOptionEventPlugin` | class | `.capture`, `.passive`, `.once` 이벤트 옵션 플러그인 |
+| `SdOptionEventPlugin` | class | `.capture`, `.passive`, `.once` 이벤트 옵션 플러그인 (`provideSdAngular`에서 자동 등록) |
 | `SdGlobalErrorHandlerPlugin` | class | 글로벌 에러 핸들러 (PromiseRejection, ErrorEvent 등) |
 
 -> See [docs/plugins.md](./docs/plugins.md) for details.
@@ -161,7 +160,7 @@ npm install @simplysm/angular
 | `SdBaseContainer` | component | 페이지/모달/뷰 공통 레이아웃 컨테이너 |
 | `SdAddressSearchModal` | component | Daum Postcode 주소 검색 모달 |
 | `Address` | interface | 주소 검색 결과 |
-| `SdPermissionTable` | component | 권한 매트릭스 테이블 |
+| `SdPermissionTable` | component | 권한 매트릭스 테이블 (items, value) |
 | `SdDataSheetBase` | class | 데이터 시트 CRUD 추상 클래스 |
 | `SdDataSheet` | component | 데이터 시트 presentation 컴포넌트 |
 | `SdDataSheetColumn` | directive | 데이터 시트 컬럼 (edit 추가) |
@@ -171,7 +170,7 @@ npm install @simplysm/angular
 | `SdDataSelectButton` | component | 선택 버튼 presentation 컴포넌트 |
 | `SdSharedDataSelect` | component | 공유 데이터 드롭다운 선택 |
 | `SdSharedDataSelectButton` | component | 공유 데이터 모달 선택 버튼 |
-| `SdSharedDataSelectList` | component | 공유 데이터 목록형 선택 |
+| `SdSharedDataSelectList` | component | 공유 데이터 목록형 선택 (selectedItem model) |
 | `matchesSearchText` | function | 공백 구분 AND 조건 텍스트 검색 매칭 |
 | `getOrmDataEditToastErrorMessage` | function | ORM 편집 에러 메시지 변환 (FK 위반 등 DB 에러를 한국어 메시지로) |
 
@@ -195,7 +194,7 @@ npm install @simplysm/angular
 | `SdDockContainer` | component | 도킹 레이아웃 컨테이너 |
 | `SdDock` | component | 도킹 영역 (top/bottom/left/right) |
 | `SdGap` | component | 간격 (gap) 컴포넌트 |
-| `SdKanbanBoard` | component | 칸반 보드 (드래그앤드롭) |
+| `SdKanbanBoard` | component | 칸반 보드 (드래그앤드롭, selectedValues) |
 | `SdKanbanBoardDropInfo` | interface | 칸반 보드 드롭 이벤트 정보 |
 | `SdKanbanDragRef` | interface | 칸반 드래그 참조 인터페이스 |
 | `SdKanbanDropTarget` | interface | 칸반 드롭 타겟 인터페이스 |
@@ -224,7 +223,7 @@ npm install @simplysm/angular
 | `SdCheckboxGroup` | component | 체크박스 그룹 |
 | `SdCheckboxGroupItem` | component | 체크박스 그룹 항목 |
 | `SdTiptapEditor` | component | TipTap 리치 텍스트 에디터 |
-| `SdSelect` | component | 드롭다운 선택 (single/multi/multi-with-header) |
+| `SdSelect` | component | 드롭다운 선택 (single/multi) |
 | `SdSelectItem` | component | 드롭다운 선택 항목 |
 | `SdSelectButton` | component | 버튼 스타일 선택 |
 | `SdForm` | component | 폼 래퍼 (submit 이벤트, busy 관리) |
@@ -261,8 +260,10 @@ npm install @simplysm/angular
 |-----|------|-------------|
 | `SdList` | component | 리스트 |
 | `SdListItem` | component | 리스트 항목 |
-| `SdSheet` | component | 스프레드시트 (정렬, 고정, 리사이즈) |
-| `SdSheetColumn` | directive | 시트 컬럼 정의 |
+| `SdSheet` | component | 스프레드시트 (정렬, 고정, 리사이즈). `key`로 설정 저장 |
+| `SdSheetColumn` | directive | 시트 컬럼 정의 (헤더, 너비, 고정, 정렬 등) |
+| `SdSheetColumnCellTemplate` | directive | 시트 컬럼 셀 내용 정의 (`ng-template[cell]`), `SdSheetCellContext` 타입 가드 제공 |
+| `SdSheetCellContext` | interface | 시트 셀 템플릿 컨텍스트 (`$implicit`, `item`, `index`, `depth`, `edit`) |
 | `SdSheetConfigModal` | component | 시트 설정 모달 |
 | `SdSheetColumnDef` | interface | 시트 컬럼 정의 데이터 |
 | `SdSheetConfig` | interface | 시트 설정 데이터 |

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

@@ -66,7 +66,7 @@ export interface ApkInstallerPlugin {
 
 ## `ApkInstaller`
 
-APK 설치 플러그인 정적 파사드 클래스. Android에서는 네이티브 플러그인을 실행하고, 브라우저 환경에서는 `ApkInstallerWeb`으로 폴백한다(설치 시 알림 표시, 권한은 항상 `true` 반환).
+APK 설치 플러그인 정적 파사드 클래스. Android에서는 네이티브 플러그인을 실행하고, 브라우저 환경에서는 `ApkInstallerWeb`으로 폴백한다. 브라우저 폴백: `install()`은 `alert()` 표시 후 반환, `checkPermissions()`는 항상 `{ granted: true, manifest: true }` 반환, `requestPermissions()`는 무동작, `getVersionInfo()`는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환.
 
 ```typescript
 export abstract class ApkInstaller {

package/claude/references/sd-simplysm14/capacitor-plugin-file-system/docs/file-operations.md

@@ -0,0 +1,154 @@
+# File Operations
+
+## `FileSystem.readdir`
+
+디렉토리의 파일과 폴더 목록을 조회합니다.
+
+```typescript
+static async readdir(dirPath: string): Promise<FileInfo[]>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dirPath` | string | 조회할 디렉토리의 절대 경로 |
+
+**Return**: 디렉토리 내 파일/폴더 목록 (각 항목은 name과 isDirectory 포함)
+
+**Throws**: 디렉토리가 존재하지 않거나 허용되지 않는 경로일 경우 Error
+
+```typescript
+const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+for (const file of files) {
+  console.log(`${file.name} ${file.isDirectory ? "[DIR]" : ""}`);
+}
+```
+
+## `FileSystem.writeFile`
+
+파일을 작성합니다. 문자열 또는 Bytes(Uint8Array) 데이터를 지원합니다.
+
+```typescript
+static async writeFile(filePath: string, data: string | Bytes): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 쓸 파일의 절대 경로 |
+| `data` | string \| Bytes | 파일 내용 (문자열 또는 Uint8Array) |
+
+**Behavior**:
+- 문자열인 경우: UTF-8 인코딩으로 저장 (encoding: "utf8")
+- Bytes인 경우: Base64 인코딩으로 저장 (encoding: "base64")
+- 상위 디렉토리가 없으면 자동 생성 (웹 환경에서만)
+
+**Throws**: 쓰기 권한 없을 경우 Error
+
+```typescript
+// 문자열 쓰기
+await FileSystem.writeFile("/storage/emulated/0/Documents/notes.txt", "Hello, World!");
+
+// Bytes 쓰기 (예: PNG 이미지)
+const pngData = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+await FileSystem.writeFile("/storage/emulated/0/Pictures/image.png", pngData);
+```
+
+## `FileSystem.readFile`
+
+파일을 읽습니다. 기본적으로 Bytes를 반환하며, encoding 파라미터로 문자열 반환을 지정할 수 있습니다.
+
+```typescript
+static async readFile(filePath: string): Promise<Bytes>;
+static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 읽을 파일의 절대 경로 |
+| `encoding` | "utf8" (optional) | "utf8"일 경우 string 반환, 생략 시 Bytes 반환 |
+
+**Return**:
+- encoding 생략: `Promise<Bytes>` (Uint8Array)
+- encoding="utf8": `Promise<string>`
+
+**Throws**: 파일이 없거나 읽기 권한이 없을 경우 Error
+
+```typescript
+// Bytes로 읽기 (기본)
+const imageData = await FileSystem.readFile("/storage/emulated/0/Pictures/photo.jpg");
+console.log(imageData instanceof Uint8Array); // true
+
+// 문자열로 읽기
+const config = await FileSystem.readFile("/storage/emulated/0/Documents/config.json", "utf8");
+const obj = JSON.parse(config);
+```
+
+## `FileSystem.remove`
+
+파일 또는 디렉토리를 삭제합니다. 디렉토리인 경우 재귀적으로 삭제됩니다.
+
+```typescript
+static async remove(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 삭제할 파일/디렉토리의 절대 경로 |
+
+**Behavior**:
+- 파일: 즉시 삭제
+- 디렉토리: 하위의 모든 파일/폴더 포함하여 재귀 삭제
+- 웹 환경: 경로 프리픽스로 모든 관련 항목 삭제
+
+**Throws**: 대상이 존재하지 않거나 권한 없을 경우 Error
+
+```typescript
+// 파일 삭제
+await FileSystem.remove("/storage/emulated/0/Documents/temp.txt");
+
+// 디렉토리 재귀 삭제
+await FileSystem.remove("/storage/emulated/0/Documents/old_backup");
+```
+
+## `FileSystem.mkdir`
+
+디렉토리를 생성합니다. 상위 경로가 없는 경우 자동으로 생성됩니다 (재귀 생성).
+
+```typescript
+static async mkdir(targetPath: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 생성할 디렉토리의 절대 경로 |
+
+**Behavior**:
+- 중간 경로가 없어도 자동 생성
+- 이미 존재하면 아무 동작 없음
+
+**Throws**: 권한 없을 경우 Error
+
+```typescript
+// 중간 경로 자동 생성
+await FileSystem.mkdir("/storage/emulated/0/Documents/projects/2025/Q1");
+```
+
+## `FileSystem.exists`
+
+파일 또는 디렉토리의 존재 여부를 확인합니다.
+
+```typescript
+static async exists(targetPath: string): Promise<boolean>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetPath` | string | 확인할 파일/디렉토리의 절대 경로 |
+
+**Return**: true (존재), false (존재하지 않음)
+
+```typescript
+const exists = await FileSystem.exists("/storage/emulated/0/Documents/config.json");
+if (!exists) {
+  await FileSystem.writeFile("/storage/emulated/0/Documents/config.json", "{}");
+}
+```

package/claude/references/sd-simplysm14/capacitor-plugin-file-system/docs/permissions.md

@@ -0,0 +1,84 @@
+# Permissions
+
+## `FileSystem.checkPermissions`
+
+파일 시스템 접근 권한 여부를 확인합니다.
+
+```typescript
+static async checkPermissions(): Promise<boolean>
+```
+
+**Return**: true (권한 허용), false (권한 거부)
+
+**플랫폼별 동작**:
+- **Android**: 현재 권한 상태 확인 (MANAGE_EXTERNAL_STORAGE 또는 READ/WRITE_EXTERNAL_STORAGE)
+- **Web**: 항상 true (권한 개념 없음)
+
+```typescript
+const hasPermission = await FileSystem.checkPermissions();
+if (hasPermission) {
+  // 파일 접근 가능
+  const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+} else {
+  // 권한 요청 필요
+  await FileSystem.requestPermissions();
+}
+```
+
+## `FileSystem.requestPermissions`
+
+파일 시스템 접근 권한을 요청합니다.
+
+```typescript
+static async requestPermissions(): Promise<void>
+```
+
+**플랫폼별 동작**:
+- **Android 11+ (API 30+)**:
+  - `MANAGE_EXTERNAL_STORAGE` 권한 요청
+  - 설정 화면으로 이동하여 사용자가 수동으로 허용
+  - 권한 대화상자가 표시되지 않음
+- **Android 10 이하 (API 29-)**:
+  - `READ_EXTERNAL_STORAGE` + `WRITE_EXTERNAL_STORAGE` 요청
+  - 표준 권한 대화상자 표시
+- **Web**: 아무 동작 없음
+
+```typescript
+async function ensureFileSystemAccess() {
+  const hasPermission = await FileSystem.checkPermissions();
+  
+  if (!hasPermission) {
+    try {
+      await FileSystem.requestPermissions();
+      console.log("Permission granted");
+    } catch (error) {
+      console.error("Permission request failed:", error);
+    }
+  }
+}
+
+// 앱 시작 시 권한 확인
+await ensureFileSystemAccess();
+
+// 외부 저장소 접근
+const externalPath = await FileSystem.getStoragePath("external");
+const files = await FileSystem.readdir(externalPath);
+```
+
+## 권한 관련 주의사항
+
+### Android 11+ (Scoped Storage)
+
+- `MANAGE_EXTERNAL_STORAGE` 권한은 특수 권한이며, 일반 권한 대화상자로 요청할 수 없습니다.
+- 권한 요청 시 설정 앱으로 이동하므로 사용자가 직접 허용/거부를 선택해야 합니다.
+- AndroidManifest.xml에 `android.permission.MANAGE_EXTERNAL_STORAGE`를 선언해야 합니다.
+
+### Android 10 이하
+
+- `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE` 권한이 필요합니다.
+- 이 권한들은 위험한(Dangerous) 권한으로 분류되어 런타임 권한 요청이 필요합니다.
+
+### 웹 환경
+
+- 권한 개념이 없으며, IndexedDB 기반 가상 파일 시스템을 사용합니다.
+- 사용자는 브라우저 저장소 한도에만 제한됩니다.

package/claude/references/sd-simplysm14/capacitor-plugin-file-system/docs/storage-paths.md

@@ -0,0 +1,107 @@
+# Storage & Paths
+
+## `FileSystem.getStoragePath`
+
+저장소 유형별로 기기의 실제 경로(Android) 또는 가상 경로(웹)를 반환합니다.
+
+```typescript
+static async getStoragePath(type: StorageType): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | StorageType | 저장소 유형 |
+
+**Return**: 절대 경로 문자열
+
+**StorageType 종류**:
+
+| Type | Android Path | Web Path | 설명 |
+|------|--------------|----------|------|
+| `external` | `Environment.getExternalStorageDirectory()` | `/webfs/external` | 외부 저장소 루트 (공유 저장소) |
+| `externalFiles` | `getExternalFilesDir(null)` | `/webfs/externalFiles` | 앱 전용 외부 파일 디렉토리 |
+| `externalCache` | `externalCacheDir` | `/webfs/externalCache` | 앱 전용 외부 캐시 디렉토리 |
+| `externalMedia` | `externalMediaDirs[0]` | `/webfs/externalMedia` | 앱 전용 외부 미디어 디렉토리 |
+| `appData` | `applicationInfo.dataDir` | `/webfs/appData` | 앱 데이터 디렉토리 (내부) |
+| `appFiles` | `filesDir` | `/webfs/appFiles` | 앱 파일 디렉토리 (내부) |
+| `appCache` | `cacheDir` | `/webfs/appCache` | 앱 캐시 디렉토리 (내부) |
+
+```typescript
+// 앱 캐시 디렉토리에 임시 파일 작성
+const cachePath = await FileSystem.getStoragePath("appCache");
+await FileSystem.writeFile(cachePath + "/temp.dat", "temporary data");
+
+// 외부 파일 디렉토리에 문서 저장
+const filesPath = await FileSystem.getStoragePath("externalFiles");
+await FileSystem.mkdir(filesPath + "/documents");
+await FileSystem.writeFile(filesPath + "/documents/report.pdf", pdfBytes);
+```
+
+## `FileSystem.getUri`
+
+파일의 URI를 조회합니다. 주로 Blob URL(웹) 또는 FileProvider URI(Android)로 반환됩니다.
+
+```typescript
+static async getUri(filePath: string): Promise<string>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | string | 파일의 절대 경로 |
+
+**Return**: URI 문자열
+- Android: `content://` scheme의 FileProvider URI
+- Web: `blob://` scheme의 Blob URL
+
+**Web 환경 주의사항**:
+반환된 Blob URL은 사용 후 반드시 `URL.revokeObjectURL(uri)`로 해제해야 합니다. 해제하지 않으면 메모리 누수가 발생할 수 있습니다.
+
+```typescript
+// 웹 환경: Blob URL 사용 후 해제
+const imagePath = await FileSystem.getStoragePath("appFiles");
+const imageFile = imagePath + "/photo.jpg";
+
+const uri = await FileSystem.getUri(imageFile);
+
+const img = document.createElement("img");
+img.src = uri;
+img.onload = () => {
+  URL.revokeObjectURL(uri); // 메모리 해제
+};
+
+// Android 환경: FileProvider URI를 다른 앱과 공유
+const documentPath = await FileSystem.getStoragePath("externalFiles");
+const documentFile = documentPath + "/report.pdf";
+const contentUri = await FileSystem.getUri(documentFile);
+
+// contentUri를 Intent의 data로 사용하여 다른 앱 실행
+const intent = new Intent(Intent.ACTION_VIEW);
+intent.setDataAndType(Uri.parse(contentUri), "application/pdf");
+startActivity(intent);
+```
+
+## `StorageType`
+
+저장소 유형을 나타내는 union type입니다.
+
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```
+
+**사용 가이드**:
+- **내부 저장소 (앱 전용)**:
+  - `appData`: 앱 상태 데이터 (자동 백업 대상)
+  - `appFiles`: 일반 파일 저장
+  - `appCache`: 임시 캐시 (시스템이 필요 시 삭제 가능)
+- **외부 저장소 (공유 또는 앱 전용)**:
+  - `external`: 전체 외부 저장소 (권한 필요)
+  - `externalFiles`: 앱 전용 외부 파일 (권한 필요)
+  - `externalCache`: 앱 전용 외부 캐시 (권한 필요)
+  - `externalMedia`: 앱 전용 외부 미디어 (권한 필요)

package/claude/references/sd-simplysm14/capacitor-plugin-file-system/docs/types.md

@@ -0,0 +1,83 @@
+# Types
+
+## `FileInfo`
+
+파일 또는 디렉토리의 정보를 나타내는 인터페이스입니다.
+
+```typescript
+interface FileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | 파일 또는 디렉토리의 이름 (경로 제외, 확장자 포함) |
+| `isDirectory` | boolean | true일 경우 디렉토리, false일 경우 파일 |
+
+```typescript
+// 디렉토리 읽기 결과
+const files = await FileSystem.readdir("/storage/emulated/0/Documents");
+
+// FileInfo 배열 처리
+for (const file of files) {
+  if (file.isDirectory) {
+    console.log(`📁 ${file.name} (directory)`);
+  } else {
+    console.log(`📄 ${file.name} (file)`);
+  }
+}
+```
+
+## `FileSystemPlugin`
+
+Capacitor 플러그인 인터페이스입니다. 일반적으로 `FileSystem` 파사드를 통해 간접적으로 사용됩니다.
+
+```typescript
+interface FileSystemPlugin {
+  checkPermissions(): Promise<{ granted: boolean }>;
+  requestPermissions(): Promise<void>;
+  readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
+  getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
+  getUri(options: { path: string }): Promise<{ uri: string }>;
+  writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
+  readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
+  remove(options: { path: string }): Promise<void>;
+  mkdir(options: { path: string }): Promise<void>;
+  exists(options: { path: string }): Promise<{ exists: boolean }>;
+}
+```
+
+**참고**: 이 인터페이스는 내부 플러그인 구현용이며, 외부 사용자는 `FileSystem` 파사드의 정적 메서드를 사용합니다.
+
+## `Bytes`
+
+이 패키지에서는 `@simplysm/core-common`의 `Bytes` 타입(Uint8Array의 별칭)을 사용합니다.
+
+```typescript
+import type { Bytes } from "@simplysm/core-common";
+import { bytes } from "@simplysm/core-common";
+
+// Bytes = Uint8Array
+const data: Bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+
+// Base64 변환 유틸리티
+const base64Str = bytes.toBase64(data);      // Bytes → Base64 문자열
+const bytesData = bytes.fromBase64(base64Str); // Base64 문자열 → Bytes
+```
+
+## `StorageType`
+
+저장소 유형 union type입니다. 자세한 설명은 [storage-paths.md](./storage-paths.md)를 참조하세요.
+
+```typescript
+type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```