@simplysm/sd-claude 14.0.53 → 14.0.55

package/claude/references/sd-simplysm-v14/angular/ui-overlay/sd-dropdown.md

@@ -1,5 +1,7 @@
 # `SdDropdown`
 
+> **읽어야 하는 상황**: 클릭이나 키보드로 드롭다운 팝업을 열어 추가 콘텐츠를 표시할 때.
+
 드롭다운 트리거 컴포넌트. 클릭 또는 키보드로 `SdDropdownPopup`을 열고 닫는다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-overlay/sd-modal.md

@@ -1,5 +1,7 @@
 # `SdModal`
 
+> **읽어야 하는 상황**: 모달 래퍼 컴포넌트의 내부 구조를 이해할 때. 모달 생성은 [`SdModalProvider`](../providers/sd-modal-provider.md) 참조.
+
 모달 래퍼 컴포넌트. `SdModalProvider.showAsync()`에 의해 프로그래밍 방식으로 생성된다. 직접 템플릿에 배치하지 않는다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-overlay/sd-prompt-modal.md

@@ -1,5 +1,7 @@
 # `SdPromptModal`
 
+> **읽어야 하는 상황**: 사용자로부터 텍스트를 입력받는 대화상자가 필요할 때. 확인/취소만 필요하면 [`SdConfirmModal`](./sd-confirm-modal.md) 참조.
+
 범용 프롬프트 입력 모달. `SdModalContentDef<string>`을 구현한다.
 메시지를 표시하고 텍스트 입력 후 확인/취소한다. 확인 시 입력값 반환, 취소 시 `undefined` 반환.
 

package/claude/references/sd-simplysm-v14/angular/ui-overlay/sd-toast.md

@@ -1,5 +1,7 @@
 # `SdToast`
 
+> **읽어야 하는 상황**: 토스트 개별 항목 컴포넌트의 내부 구조를 이해할 때. 토스트 표시는 [`SdToastProvider`](../providers/sd-toast-provider.md) 참조.
+
 토스트 개별 항목 컴포넌트. `SdToastProvider`에 의해 프로그래밍 방식으로 생성된다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-barcode.md

@@ -1,5 +1,7 @@
 # `SdBarcode`
 
+> **읽어야 하는 상황**: 바코드를 생성하여 표시할 때.
+
 바코드 생성 컴포넌트. bwip-js 라이브러리를 사용하여 SVG 바코드를 렌더링한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-calendar.md

@@ -1,5 +1,7 @@
 # `SdCalendar`
 
+> **읽어야 하는 상황**: 캘린더에 항목을 날짜별로 배치할 때.
+
 월별 달력 컴포넌트. `items`를 날짜 기준으로 분류하여 각 날짜 셀에 표시한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-echarts.md

@@ -1,5 +1,7 @@
 # `SdEcharts`
 
+> **읽어야 하는 상황**: ECharts 차트를 표시할 때.
+
 Apache ECharts 차트 래퍼 컴포넌트. 호스트 요소의 크기 변경을 감지하여 자동으로 차트를 리사이즈한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-label.md

@@ -1,5 +1,7 @@
 # `SdLabel`
 
+> **읽어야 하는 상황**: 테마 색상 라벨을 표시할 때.
+
 인라인 라벨 컴포넌트. 테마 색상 또는 커스텀 배경색을 적용한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-note.md

@@ -1,5 +1,7 @@
 # `SdNote`
 
+> **읽어야 하는 상황**: 노트/알림 메시지 박스를 표시할 때.
+
 알림 메시지 블록 컴포넌트. 배경 색상으로 중요도를 표현한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/ui-visual/sd-progress.md

@@ -1,5 +1,7 @@
 # `SdProgress`
 
+> **읽어야 하는 상황**: 진행률 바를 표시할 때.
+
 진행률 바 컴포넌트. `value`(0~1 범위)에 따라 바 너비를 계산하고 퍼센트를 표시한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/utils/inject-routing-signals.md

@@ -1,5 +1,7 @@
 # 라우팅 Signal 함수들
 
+> **읽어야 하는 상황**: 현재 페이지 코드, 뷰 타입, 뷰 타이틀 등 라우팅 상태를 signal로 조회할 때.
+
 라우터 상태를 signal로 반환하는 inject 함수 모음. 생성자/필드 이니셜라이저에서 호출한다.
 
 ## `injectCurrentPageCodeSignal`
@@ -46,10 +48,6 @@ protected readonly viewTitle = injectViewTitleSignal();
 </sd-topbar>
 ```
 
-**실사용 예:**
-- [crud-list.md §3 최소 뼈대](../recipes/crud-list.md#3-최소-뼈대-조회-전용-page) — topbar 제목
-- [crud-detail.md §3 최소 뼈대](../recipes/crud-detail.md#3-최소-뼈대-읽기-전용-상세-폼) — topbar 제목
-
 ## `injectViewTypeSignal`
 
 현재 뷰의 타입 signal. 모달/페이지/컨트롤 중 하나를 반환한다.
@@ -86,14 +84,7 @@ private readonly _autoViewType = injectViewTypeSignal();
 protected readonly viewType = computed(() => this.override() ?? this._autoViewType());
 ```
 
-> 이 오버라이드는 추상화 복원을 부추기므로 **기본은 자동 판정으로 쓰기**를 권장한다. 상세: [page-modal-container.md §5 뷰 타입 결정](../recipes/page-modal-container.md#5-뷰-타입-결정)
-
-**실사용 예:**
-- [crud-list.md §3 최소 뼈대](../recipes/crud-list.md#3-최소-뼈대-조회-전용-page) — 뷰 타입 기반 topbar 조건부 렌더
-- [crud-list.md §8 확장 D: 선택 모달 전환](../recipes/crud-list.md#8-확장-d-선택-모달-전환) — modal 뷰 분기
-- [crud-detail.md §7 확장 C: modal 뷰](../recipes/crud-detail.md#7-확장-c-modal-뷰) — modal 뷰 분기
-- [crud-detail.md §8 확장 D: control 뷰](../recipes/crud-detail.md#8-확장-d-control-뷰) — control 뷰 분기
-- [page-modal-container.md §5 뷰 타입 결정](../recipes/page-modal-container.md#5-뷰-타입-결정) — 판정 규칙 + 수동 오버라이드
+> 이 오버라이드는 추상화 복원을 부추기므로 **기본은 자동 판정으로 쓰기**를 권장한다.
 
 ## `injectPermsSignal`
 
@@ -128,10 +119,6 @@ protected readonly canEdit = computed(() => this.perms().includes("edit"));
 }
 ```
 
-**실사용 예:**
-- [crud-list.md §3 최소 뼈대](../recipes/crud-list.md#3-최소-뼈대-조회-전용-page) — 권한 기반 조건부 렌더
-- [crud-detail.md §3 최소 뼈대](../recipes/crud-detail.md#3-최소-뼈대-읽기-전용-상세-폼) — 권한 기반 조건부 렌더
-
 ## `getMenuRouterLinkOption`
 
 메뉴에서 라우터 링크 옵션을 추출한다.

package/claude/references/sd-simplysm-v14/angular/utils/inject-sd-system-config-resource.md

@@ -1,5 +1,7 @@
 # `injectSdSystemConfigResource`
 
+> **읽어야 하는 상황**: 컴포넌트별 시스템 설정을 resource 패턴으로 읽고 쓸 때.
+
 컴포넌트 태그명 기반 키로 시스템 설정을 읽고 쓰는 resource 래퍼. 생성자에서 호출한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/utils/mark.md

@@ -1,5 +1,7 @@
 # `mark`
 
+> **읽어야 하는 상황**: WritableSignal 내부를 mutation한 후 consumer에게 변경을 알릴 때.
+
 WritableSignal의 변경 알림을 수동으로 트리거한다. 배열/객체의 내부 변경(mutation) 후 consumer에게 변경을 알릴 때 사용. shallow copy로 새 참조를 생성하여 signal을 업데이트한다.
 
 ```typescript
@@ -36,8 +38,3 @@ mark(filter);  // filter signal이 {...filter()} 로 갱신됨
 - Chrome 61 호환성(`Proxy` 폴리필 불가)으로 signal 자동 notify가 불가하여 명시적 `mark` 호출이 필요
 - `mark`는 **UI에 변경을 반영**하기 위한 것이지, 데이터 변경 자체를 감지하는 메커니즘이 아니다
 
-**실사용 예:**
-- [crud-list.md §5 확장 A: inline 편집/저장](../recipes/crud-list.md#5-확장-a-inline-편집저장) — items 배열 mutation 후 mark
-- [crud-list.md §6 확장 B: 선택 기능](../recipes/crud-list.md#6-확장-b-선택-기능--선택-삭제복구) — selectedItems 변경 후 mark
-- [crud-detail.md §5 확장 A: 편집/저장](../recipes/crud-detail.md#5-확장-a-편집저장) — data 객체 mutation 후 mark
-- [crud-detail.md §10 확장 F: 복합 상세](../recipes/crud-detail.md#10-확장-f-복합-상세-내부-sd-sheet) — 하위 컬렉션 mutation 후 mark

package/claude/references/sd-simplysm-v14/angular/utils/selection-managers.md

@@ -1,5 +1,7 @@
 # Selection Managers
 
+> **읽어야 하는 상황**: 선택(single/multi), 정렬, 트리 확장/축소 관리가 필요할 때.
+
 선택/정렬/트리 확장을 관리하는 composable 함수 모음. `inject()` 없이 Signal 입력만으로 동작한다.
 
 ## `useSelectionManager`
@@ -9,7 +11,7 @@
 ```typescript
 function useSelectionManager<T>(options: {
   displayItems: Signal<T[]>;
-  selectedItems: WritableSignal<T[]>;
+  selectedKeys: WritableSignal<unknown[]>;
   selectMode: Signal<"single" | "multi" | undefined>;
   getItemSelectableFn: Signal<((item: T) => boolean | string) | undefined>;
   trackByFn: Signal<(item: T, index: number) => unknown>;

package/claude/references/sd-simplysm-v14/angular/utils/set-safe-style.md

@@ -1,5 +1,7 @@
 # `setSafeStyle`
 
+> **읽어야 하는 상황**: Renderer2로 여러 CSS 스타일을 안전하게 일괄 적용할 때.
+
 Renderer2를 사용하여 여러 CSS 스타일을 일괄 적용한다.
 
 ```typescript

package/claude/references/sd-simplysm-v14/angular/utils/setup-functions.md

@@ -1,5 +1,7 @@
 # Setup Functions
 
+> **읽어야 하는 상황**: 컴포넌트에 배경 테마, 리플, reveal 애니메이션, 유효성 표시, model 가드, canDeactivate 등의 부수효과를 설치할 때.
+
 생성자에서 호출하는 설정 함수들. `inject()`, `effect()`, `DestroyRef.onDestroy()`를 사용하여 수명주기를 관리한다.
 
 ## `setupBgTheme`
@@ -87,7 +89,3 @@ setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges
 - **페이지 뷰**: `_checkIgnoreChanges()` → confirm 결과로 제어
 - **control 뷰**: setupCanDeactivate 내부에서 아무 동작 하지 않음 (라우트도 모달도 아님)
 
-**실사용 예:**
-- [crud-list.md §5 확장 A: inline 편집/저장](../recipes/crud-list.md#5-확장-a-inline-편집저장) — 기본 패턴
-- [crud-detail.md §5 확장 A: 편집/저장](../recipes/crud-detail.md#5-확장-a-편집저장) — 기본 패턴
-- [crud-detail.md §7 확장 C: modal 뷰](../recipes/crud-detail.md#7-확장-c-modal-뷰) — 뷰 타입별 분기 패턴

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

@@ -1,6 +1,6 @@
 # @simplysm/capacitor-plugin-auto-update
 
-> Android APK 자동 업데이트 플러그인. 서버 버전 비교 후 APK 다운로드·설치를 처리하며, 외부 저장소(USB 등)에서도 업데이트할 수 있다. Capacitor 7 기반이며 `@capacitor/core`가 peerDependency다.
+> Android APK 자동 업데이트 플러그인. Capacitor 7 기반이며 `@capacitor/core`가 peerDependency다. 서버 버전 비교 후 APK 다운로드·설치를 처리하며, 외부 저장소(USB 등)에서도 업데이트할 수 있다.
 
 ## Installation
 
@@ -10,29 +10,27 @@ npm install @simplysm/capacitor-plugin-auto-update
 
 피어 의존성으로 `@capacitor/core ^7`이 필요하다. Android 네이티브 플러그인이 포함되어 있으므로 `npx cap sync` 후 사용한다.
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 서버에서 최신 APK 자동 업데이트 | [auto-update.md](./auto-update/auto-update.md) |
-| 외부 저장소(USB)에서 APK 업데이트 | [auto-update.md](./auto-update/auto-update.md) |
-| APK 설치 권한 관리 및 직접 설치 | [apk-installer.md](./apk-installer/apk-installer.md) |
+### 앱 업데이트
 
-## API Overview
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 앱 부트스트랩 시 서버에서 최신 APK를 자동 다운로드·설치 | [auto-update.md](./auto-update/auto-update.md) |
+| 네트워크 없이 외부 저장소(USB)에서 APK 업데이트 | [auto-update.md](./auto-update/auto-update.md) |
 
-### APK 설치
+### APK 설치 직접 제어
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ApkInstaller`](./apk-installer/apk-installer.md) | abstract class | `AutoUpdate` 없이 APK 설치 권한·설치를 직접 제어할 때 |
-
-### 자동 업데이트
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`AutoUpdate`](./auto-update/auto-update.md) | abstract class | 앱 부트스트랩 시 서버 또는 외부 저장소에서 최신 버전을 확인하고 APK를 설치할 때 |
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| `AutoUpdate` 없이 APK 설치 권한·설치를 직접 제어 | [apk-installer.md](./apk-installer/apk-installer.md) |
+| 현재 설치된 앱의 버전 정보 조회 | [apk-installer.md](./apk-installer/apk-installer.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - iOS 앱 업데이트 → App Store 메커니즘을 사용한다. 이 플러그인은 Android APK 전용이다.
 - 웹 앱 업데이트 → 서버 배포로 처리한다. 브라우저 폴백은 알림만 표시하고 실제 설치를 수행하지 않는다.
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/_api-index.md

@@ -0,0 +1,18 @@
+# API Index — @simplysm/capacitor-plugin-auto-update
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## APK 설치
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ApkInstaller` | abstract class | [apk-installer.md](./apk-installer/apk-installer.md) | `AutoUpdate` 없이 APK 설치 권한·설치를 직접 제어할 때 |
+| `ApkInstallerPlugin` | interface | [apk-installer.md](./apk-installer/apk-installer.md) | Capacitor 네이티브 플러그인 인터페이스. 타입 참조 목적. `ApkInstaller` 파사드를 통해 접근한다 |
+| `VersionInfo` | interface | [apk-installer.md](./apk-installer/apk-installer.md) | `ApkInstaller.getVersionInfo()` 반환 타입 |
+
+## 자동 업데이트
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `AutoUpdate` | abstract class | [auto-update.md](./auto-update/auto-update.md) | 앱 부트스트랩 시 서버 또는 외부 저장소에서 최신 버전을 확인하고 APK를 설치할 때 |

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/apk-installer/apk-installer.md

@@ -1,6 +1,6 @@
 # `ApkInstaller`
 
-APK 설치 플러그인 정적 파사드 클래스. Android에서 APK 설치 권한 확인·요청, APK 설치 인텐트 실행, 앱 버전 정보 조회를 제공한다.
+> **읽어야 하는 상황**: `AutoUpdate` 없이 APK 설치 권한 확인·요청, APK 설치, 앱 버전 정보 조회를 직접 제어할 때. 서버/외부 저장소 기반 자동 업데이트는 [`AutoUpdate`](../auto-update/auto-update.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/auto-update/auto-update.md

@@ -1,6 +1,6 @@
 # `AutoUpdate`
 
-자동 업데이트 오케스트레이터. 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치한다. 모든 메서드가 `static`이며 인스턴스화하지 않는다.
+> **읽어야 하는 상황**: 앱 부트스트랩 시 서버에서 최신 APK를 자동 다운로드·설치하거나, 네트워크 없이 외부 저장소(USB)에서 APK를 업데이트할 때. APK 설치만 직접 제어하려면 [`ApkInstaller`](../apk-installer/apk-installer.md) 참조.
 
 ## When to use
 

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

@@ -8,27 +8,30 @@
 npm install @simplysm/capacitor-plugin-file-system
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 파일 읽기/쓰기/삭제 | 이 문서의 `FileSystem` 섹션 |
-| 저장소 경로 조회 | 이 문서의 `StorageType` 섹션 |
+### 파일 시스템 조작
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 파일 읽기/쓰기/삭제/디렉토리 조작 | 이 문서의 `FileSystem` 섹션 |
+| 저장소 유형별 경로를 얻어야 할 때 | 이 문서의 `StorageType` 섹션 |
+| USB Mass Storage 장치 접근 | [`capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md) |
 | APK 자동 업데이트에서 파일 저장 | [`capacitor-plugin-auto-update`](../capacitor-plugin-auto-update/README.md) |
 
-## API Overview
+---
 
-### `FileSystem`
+## `FileSystem`
 
-파일 시스템 접근 파사드 클래스. 모든 API는 정적 메서드로 제공된다.
+> **읽어야 하는 상황**: Android 앱에서 파일 읽기/쓰기/삭제, 디렉토리 탐색, FileProvider URI 조회가 필요할 때. USB 저장 장치 접근은 [`@simplysm/capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md) 참조.
 
-#### When to use
+### When to use
 
 - ✅ Android 앱에서 파일 읽기/쓰기/삭제, 디렉토리 탐색이 필요할 때
 - ✅ `content://` URI(FileProvider)를 얻어 다른 앱에 파일을 전달할 때
 - ❌ USB 저장 장치 접근 → [`@simplysm/capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md)
 
-#### Signature
+### Signature
 
 ```typescript
 export abstract class FileSystem {
@@ -46,7 +49,7 @@ export abstract class FileSystem {
 }
 ```
 
-#### Members
+### Members
 
 | Member | Kind | Signature | Description |
 |--------|------|-----------|-------------|
@@ -61,23 +64,12 @@ export abstract class FileSystem {
 | `mkdir` | static method | `(targetPath: string) => Promise<void>` | 디렉토리 재귀 생성. 이미 존재하면 무동작 |
 | `exists` | static method | `(targetPath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인 |
 
-#### Usage
-
-##### 최소 예제
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-const appFilesPath = await FileSystem.getStoragePath("appFiles");
-await FileSystem.writeFile(appFilesPath + "/hello.txt", "Hello!");
-const content = await FileSystem.readFile(appFilesPath + "/hello.txt", "utf8");
-```
-
-##### 전형 예제 — 권한 확인 후 파일 읽기
+### Usage
 
 ```typescript
 import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
 
+// 권한 확인 후 파일 읽기/쓰기
 const hasPermission = await FileSystem.checkPermissions();
 if (!hasPermission) {
   await FileSystem.requestPermissions();
@@ -85,31 +77,16 @@ if (!hasPermission) {
 }
 
 const appFilesPath = await FileSystem.getStoragePath("appFiles");
-const exists = await FileSystem.exists(appFilesPath + "/config.json");
-if (exists) {
-  const content = await FileSystem.readFile(appFilesPath + "/config.json", "utf8");
-}
-```
-
-##### 전형 예제 — Bytes 데이터 쓰기/읽기
-
-```typescript
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-const appCachePath = await FileSystem.getStoragePath("appCache");
-const data = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header 예시
-await FileSystem.writeFile(appCachePath + "/image.png", data);
-
-// Bytes(Uint8Array)로 반환
-const readData = await FileSystem.readFile(appCachePath + "/image.png");
+await FileSystem.writeFile(appFilesPath + "/hello.txt", "Hello!");
+const content = await FileSystem.readFile(appFilesPath + "/hello.txt", "utf8");
 ```
 
-#### 🚫 Anti-patterns
+### Anti-patterns
 
-##### 웹에서 `getUri()` 반환값을 해제하지 않음
+#### 웹에서 `getUri()` 반환값을 해제하지 않음
 
 ```typescript
-// ❌ Blob URL 미해제 → 메모리 누수
+// ❌ Blob URL 미해제 - 메모리 누수
 const uri = await FileSystem.getUri(filePath);
 img.src = uri;
 
@@ -125,9 +102,11 @@ img.onload = () => {
 
 ---
 
+## Related Types
+
 ### `StorageType`
 
-저장소 유형을 나타내는 union type.
+저장소 유형을 나타내는 union type. `FileSystem.getStoragePath()`의 파라미터로 사용한다.
 
 ```typescript
 export type StorageType =

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

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

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

@@ -0,0 +1,37 @@
+# API Index — @simplysm/core-browser
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Extensions
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `Element.findAll` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 선택자로 하위 요소를 모두 검색할 때 |
+| `Element.findFirst` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 선택자로 첫 번째 하위 요소를 검색할 때 |
+| `Element.prependChild` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 요소를 첫 번째 자식으로 삽입할 때 |
+| `Element.getParents` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 모든 부모 요소를 배열로 조회할 때 |
+| `Element.findTabbableParent` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 탭 이동 가능한 부모 요소를 찾을 때 |
+| `Element.findFirstTabbableChild` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 탭 이동 가능한 첫 번째 자식 요소를 찾을 때 |
+| `Element.isOffsetElement` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 요소가 offset parent인지 확인할 때 |
+| `Element.isVisible` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 요소가 화면에 보이는지 확인할 때 |
+| `HTMLElement.repaint` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 강제 리페인트가 필요할 때 |
+| `HTMLElement.getRelativeOffset` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 부모 기준 상대 위치를 계산할 때 |
+| `HTMLElement.scrollIntoViewIfNeeded` | prototype method | [element-prototype-extensions.md](./extensions/element-prototype-extensions.md) | 고정 헤더/컬럼에 가려진 요소를 스크롤할 때 |
+| `getBounds` | function | [get-bounds.md](./extensions/get-bounds.md) | 여러 요소의 경계 정보를 비동기 조회할 때 |
+| `ElementBounds` | interface | [get-bounds.md](./extensions/get-bounds.md) | `getBounds` 반환 타입 |
+| `copyElement` | function | [copy-paste.md](./extensions/copy-paste.md) | copy 이벤트 핸들러에서 input 값을 클립보드에 복사할 때 |
+| `pasteToElement` | function | [copy-paste.md](./extensions/copy-paste.md) | paste 이벤트 핸들러에서 클립보드 내용을 input에 붙여넣을 때 |
+
+## Utils
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `downloadBlob` | function | [download-blob.md](./utils/download-blob.md) | Blob을 파일로 다운로드할 때 |
+| `fetchUrlBytes` | function | [fetch-url-bytes.md](./utils/fetch-url-bytes.md) | URL에서 바이너리 데이터를 Uint8Array로 다운로드할 때 |
+| `DownloadProgress` | interface | [fetch-url-bytes.md](./utils/fetch-url-bytes.md) | `fetchUrlBytes` 진행 콜백 파라미터 타입 |
+| `openFileDialog` | function | [open-file-dialog.md](./utils/open-file-dialog.md) | 프로그래밍 방식으로 파일 선택 대화상자를 열 때 |
+| `IndexedDbStore` | class | [indexed-db-store.md](./utils/indexed-db-store.md) | IndexedDB에 Promise 기반 CRUD가 필요할 때 |
+| `StoreConfig` | interface | [indexed-db-store.md](./utils/indexed-db-store.md) | `IndexedDbStore` 생성자 스토어 설정 타입 |
+| `IndexedDbVirtualFs` | class | [indexed-db-virtual-fs.md](./utils/indexed-db-virtual-fs.md) | IndexedDB 위에 경로 기반 파일시스템이 필요할 때 |
+| `VirtualFsEntry` | interface | [indexed-db-virtual-fs.md](./utils/indexed-db-virtual-fs.md) | 가상 파일시스템 엔트리 타입 |

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

@@ -1,6 +1,6 @@
 # `copyElement` / `pasteToElement`
 
-클립보드 이벤트 핸들러에서 input/textarea 값을 클립보드와 동기화하는 함수 쌍.
+> **읽어야 하는 상황**: `copy`/`paste` 이벤트 핸들러에서 input/textarea 값을 클립보드와 동기화할 때. 임의 시점에 클립보드에 접근하려면 `navigator.clipboard` API를 직접 사용.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/extensions/element-prototype-extensions.md

@@ -1,5 +1,7 @@
 # Element / HTMLElement Prototype Extensions
 
+> **읽어야 하는 상황**: DOM 요소 검색/탐색, 탭 이동 가능 요소 찾기, 가시성/위치 확인, 강제 리페인트, 스크롤 조정이 필요할 때. 여러 요소의 경계 정보를 비동기로 조회하려면 [`getBounds`](./get-bounds.md), copy/paste 이벤트 핸들러는 [`copyElement`/`pasteToElement`](./copy-paste.md) 참조.
+
 패키지를 임포트하면 사이드 이펙트로 `Element`와 `HTMLElement` 프로토타입에 메서드가 추가된다. 별도 등록 없이 `import "@simplysm/core-browser"` 또는 개별 모듈 임포트로 활성화된다.
 
 ## When to use

package/claude/references/sd-simplysm-v14/core-browser/extensions/get-bounds.md

@@ -1,6 +1,6 @@
 # `getBounds`
 
-IntersectionObserver를 사용하여 여러 요소의 경계 정보를 비동기로 조회하는 함수. 뷰포트 기준 위치·크기가 필요할 때 사용한다.
+> **읽어야 하는 상황**: IntersectionObserver를 사용하여 여러 요소의 뷰포트 기준 위치·크기를 비동기로 조회할 때. 단일 요소의 즉시 측정은 `getBoundingClientRect()`로 충분하고, 요소 가시성만 확인하려면 [`element.isVisible()`](./element-prototype-extensions.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/utils/download-blob.md

@@ -1,6 +1,6 @@
 # `downloadBlob`
 
-메모리의 Blob을 사용자 파일로 다운로드하는 함수. `<a>` 태그 클릭 방식으로 동작한다.
+> **읽어야 하는 상황**: 메모리에서 생성한 데이터(엑셀, CSV, 바이너리 등)를 사용자 파일로 다운로드할 때. URL에서 파일을 먼저 가져와야 하면 [`fetchUrlBytes`](./fetch-url-bytes.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/utils/fetch-url-bytes.md

@@ -1,6 +1,6 @@
 # `fetchUrlBytes`
 
-URL에서 바이너리 데이터를 `Uint8Array`로 다운로드하는 함수. 진행 콜백을 지원한다.
+> **읽어야 하는 상황**: URL에서 바이너리 파일(이미지, WASM, 압축 파일 등)을 메모리로 가져오거나 다운로드 진행률을 표시할 때. 텍스트/JSON 응답은 표준 `fetch()` API를 직접 사용.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/utils/indexed-db-store.md

@@ -1,6 +1,6 @@
 # `IndexedDbStore`
 
-IndexedDB를 Promise 기반으로 래핑한 저수준 CRUD 클래스. 생성자에서 DB 이름, 버전, 스토어 설정을 받아 자기 완결적으로 동작한다.
+> **읽어야 하는 상황**: 브라우저에서 IndexedDB에 Promise 기반 CRUD가 필요할 때. 경로 기반 파일시스템 추상화가 필요하면 [`IndexedDbVirtualFs`](./indexed-db-virtual-fs.md) 참조.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/utils/indexed-db-virtual-fs.md

@@ -1,6 +1,6 @@
 # `IndexedDbVirtualFs`
 
-`IndexedDbStore` 위에 경로 기반 가상 파일시스템을 구현하는 클래스. 키는 `/path/to/file` 형태의 문자열이다.
+> **읽어야 하는 상황**: 브라우저에서 파일/디렉토리 계층 구조를 IndexedDB에 저장해야 할 때. 단순 키-값 저장은 [`IndexedDbStore`](./indexed-db-store.md)로 충분.
 
 ## When to use
 

package/claude/references/sd-simplysm-v14/core-browser/utils/open-file-dialog.md

@@ -1,6 +1,6 @@
 # `openFileDialog`
 
-프로그래밍 방식으로 파일 선택 대화상자를 여는 함수. `<input type="file">`을 DOM에 추가하지 않고 사용할 수 있다.
+> **읽어야 하는 상황**: `<input type="file">` 없이 프로그래밍 방식으로 파일 선택 대화상자를 열어야 할 때. 드래그 앤 드롭 파일 업로드는 `dragover`/`drop` 이벤트를 직접 처리.
 
 ## When to use