@simplysm/sd-claude 14.0.50 → 14.0.52

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

@@ -0,0 +1,137 @@
+# Element / HTMLElement Prototype Extensions
+
+패키지를 임포트하면 사이드 이펙트로 `Element`와 `HTMLElement` 프로토타입에 메서드가 추가된다. 별도 등록 없이 `import "@simplysm/core-browser"` 또는 개별 모듈 임포트로 활성화된다.
+
+## When to use
+
+- ✅ DOM 요소 검색/탐색이 필요할 때 (`findAll`, `findFirst`, `getParents`)
+- ✅ 탭 이동 가능한 요소를 찾을 때 (`findTabbableParent`, `findFirstTabbableChild`)
+- ✅ 요소 가시성/위치 확인이 필요할 때 (`isVisible`, `isOffsetElement`, `getRelativeOffset`)
+- ✅ 강제 리페인트나 스크롤 조정이 필요할 때 (`repaint`, `scrollIntoViewIfNeeded`)
+- ❌ 여러 요소의 경계 정보를 비동기로 조회 → [`getBounds`](./get-bounds.md)
+- ❌ Node.js 환경 → DOM API가 없으므로 사용 불가
+
+## Element Prototype Methods
+
+```typescript
+// 선택자와 일치하는 모든 하위 요소 검색. 빈 선택자 → 빈 배열.
+element.findAll<TEl extends Element = Element>(selector: string): TEl[]
+
+// 선택자와 일치하는 첫 번째 요소. 빈 선택자 → undefined.
+element.findFirst<TEl extends Element = Element>(selector: string): TEl | undefined
+
+// 요소를 첫 번째 자식으로 삽입. 삽입된 자식 요소를 반환.
+element.prependChild<TEl extends Element>(child: TEl): TEl
+
+// 모든 부모 요소 배열 (가장 가까운 것부터 먼 것 순서)
+element.getParents(): Element[]
+
+// 첫 번째 탭 이동 가능한 부모 요소 (tabbable 라이브러리 사용). 없으면 undefined.
+element.findTabbableParent(): HTMLElement | undefined
+
+// 첫 번째 탭 이동 가능한 자식 요소 (TreeWalker + tabbable 사용). 없으면 undefined.
+element.findFirstTabbableChild(): HTMLElement | undefined
+
+// position이 relative/absolute/fixed/sticky인지 확인
+element.isOffsetElement(): boolean
+
+// 화면에 보이는지 확인 (clientRects 존재 + visibility !== "hidden" + opacity !== "0")
+element.isVisible(): boolean
+```
+
+## HTMLElement Prototype Methods
+
+```typescript
+// 강제 리페인트. offsetHeight 접근으로 동기 reflow를 트리거한다.
+htmlElement.repaint(): void
+
+// 부모 요소 기준 상대 위치 계산. CSS top/left 속성에 바로 사용 가능한 좌표 반환.
+// parent: HTMLElement 인스턴스 또는 CSS 선택자 문자열 (closest()로 탐색)
+// border 두께, CSS transform 변환을 모두 포함하여 계산한다.
+// 부모를 찾을 수 없으면 ArgumentError를 던진다.
+htmlElement.getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }
+
+// offset 영역(고정 헤더/컬럼)에 가려진 경우 대상이 보이도록 스크롤 조정.
+// target: 컨테이너 내 대상 위치 (offsetTop, offsetLeft)
+// offset: 가려지면 안 되는 영역 크기 (기본값 { top: 0, left: 0 })
+// 상단/좌측 방향만 처리. 하단/우측은 브라우저 기본 포커스 스크롤에 의존.
+htmlElement.scrollIntoViewIfNeeded(
+  target: { top: number; left: number },
+  offset?: { top: number; left: number }
+): void
+```
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import "@simplysm/core-browser";
+
+const container = document.querySelector(".container")!;
+const buttons = container.findAll<HTMLButtonElement>("button");
+const firstInput = container.findFirst<HTMLInputElement>("input[type=text]");
+```
+
+### 전형 예제 — 포커스 이동 가능한 요소 탐색
+
+```typescript
+import "@simplysm/core-browser";
+
+// 현재 요소에서 가장 가까운 탭 이동 가능한 부모로 포커스 이동
+function focusNearestTabbableParent(el: Element): void {
+  const tabbable = el.findTabbableParent();
+  if (tabbable != null) {
+    tabbable.focus();
+  }
+}
+
+// 컨테이너 내 첫 번째 탭 이동 가능한 자식으로 포커스
+function focusFirstChild(container: Element): void {
+  const child = container.findFirstTabbableChild();
+  if (child != null) {
+    child.focus();
+  }
+}
+```
+
+### 전형 예제 — 드롭다운 위치 계산
+
+```typescript
+import "@simplysm/core-browser";
+
+function positionDropdown(trigger: HTMLElement, dropdown: HTMLElement): void {
+  // position: relative/absolute 부모를 찾아 상대 좌표 계산
+  const offset = trigger.getRelativeOffset(dropdown.offsetParent as HTMLElement);
+  dropdown.style.top = `${offset.top + trigger.offsetHeight}px`;
+  dropdown.style.left = `${offset.left}px`;
+}
+```
+
+## 🚫 Anti-patterns
+
+### 빈 선택자로 findAll/findFirst 호출
+
+```typescript
+// ❌ 빈 문자열은 빈 배열/undefined를 반환하므로 의미 없는 호출
+const els = container.findAll("");
+
+// ✅ 빈 선택자 가능성이 있으면 호출 전에 검사
+if (selector !== "") {
+  const els = container.findAll(selector);
+}
+```
+
+**근거**: 내부에서 `trim()` 후 빈 문자열이면 즉시 빈 결과를 반환한다. 에러는 나지 않지만 불필요한 호출이다.
+
+### getRelativeOffset에 존재하지 않는 선택자 전달
+
+```typescript
+// ❌ 선택자가 일치하지 않으면 ArgumentError 발생
+element.getRelativeOffset(".nonexistent-class");
+
+// ✅ 확실한 부모 요소를 직접 전달
+element.getRelativeOffset(parentElement);
+```
+
+**근거**: 문자열을 전달하면 `closest()`로 탐색하므로, 일치하는 부모가 없으면 `ArgumentError`가 발생한다.

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

@@ -0,0 +1,84 @@
+# `getBounds`
+
+IntersectionObserver를 사용하여 여러 요소의 경계 정보를 비동기로 조회하는 함수. 뷰포트 기준 위치·크기가 필요할 때 사용한다.
+
+## When to use
+
+- ✅ 여러 요소의 뷰포트 기준 위치/크기를 한 번에 조회할 때
+- ✅ `getBoundingClientRect()`가 정확하지 않은 타이밍(예: 레이아웃 직후)에 안정적인 측정이 필요할 때
+- ❌ 단일 요소의 즉시 측정 → `getBoundingClientRect()`로 충분
+- ❌ 요소 가시성만 확인 → `element.isVisible()` 프로토타입 확장 사용
+
+## Signature
+
+```typescript
+export async function getBounds(
+  els: Element[],
+  timeout?: number, // 기본값: 5000 (ms)
+): Promise<ElementBounds[]>
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `els` | `Element[]` | 측정 대상 요소 배열. 중복은 자동 제거. 빈 배열이면 빈 결과 반환 |
+| `timeout` | `number` | 타임아웃 밀리초. 기본값 5000. 시간 내에 모든 요소의 측정이 완료되지 않으면 `TimeoutError` 발생 |
+
+## Returns
+
+`Promise<ElementBounds[]>` — 입력 순서대로 정렬된 경계 정보 배열.
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { getBounds } from "@simplysm/core-browser";
+
+const elements = document.querySelectorAll(".card");
+const bounds = await getBounds([...elements]);
+// bounds[0].top, bounds[0].left, bounds[0].width, bounds[0].height
+```
+
+### 전형 예제 — 타임아웃 처리
+
+```typescript
+import { getBounds } from "@simplysm/core-browser";
+import { TimeoutError } from "@simplysm/core-common";
+
+try {
+  const bounds = await getBounds(targetElements, 3000); // 3초 타임아웃
+  for (const b of bounds) {
+    // b.target: 원본 요소 참조
+    // b.top, b.left: 뷰포트 기준 좌표
+    // b.width, b.height: 요소 크기
+  }
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    // 요소가 DOM에서 제거되었거나 display:none인 경우 IntersectionObserver가 응답하지 않을 수 있음
+  }
+}
+```
+
+## Related Types
+
+### `ElementBounds`
+
+```typescript
+export interface ElementBounds {
+  target: Element;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `Element` | 측정 대상 요소 |
+| `top` | `number` | 뷰포트 기준 상단 위치 |
+| `left` | `number` | 뷰포트 기준 좌측 위치 |
+| `width` | `number` | 요소 너비 |
+| `height` | `number` | 요소 높이 |

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

@@ -0,0 +1,59 @@
+# `downloadBlob`
+
+메모리의 Blob을 사용자 파일로 다운로드하는 함수. `<a>` 태그 클릭 방식으로 동작한다.
+
+## When to use
+
+- ✅ 메모리에서 생성한 데이터(엑셀, CSV, 바이너리 등)를 파일로 다운로드할 때
+- ❌ URL에서 파일 다운로드 → [`fetchUrlBytes`](./fetch-url-bytes.md)로 먼저 가져온 후 사용하거나, `<a href>` 직접 사용
+
+## Signature
+
+```typescript
+export function downloadBlob(blob: Blob, fileName: string): void
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `blob` | `Blob` | 다운로드할 Blob 객체 |
+| `fileName` | `string` | 저장할 파일명. 파일시스템 금지 문자(`/ \ : * ? " < > \|`), 제어문자, Windows 예약어(CON, PRN 등)는 `sanitize-filename`으로 자동 제거. 제거 후 빈 문자열이면 `"download"`로 대체 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { downloadBlob } from "@simplysm/core-browser";
+
+const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+const blob = new Blob([data], { type: "application/octet-stream" });
+downloadBlob(blob, "output.bin");
+```
+
+### 전형 예제 — JSON 데이터 다운로드
+
+```typescript
+import { downloadBlob } from "@simplysm/core-browser";
+
+const jsonStr = JSON.stringify(exportData, null, 2);
+const blob = new Blob([jsonStr], { type: "application/json" });
+downloadBlob(blob, "export-data.json");
+```
+
+## 🚫 Anti-patterns
+
+### Object URL 수동 해제
+
+```typescript
+// ❌ downloadBlob은 내부에서 1초 후 자동으로 URL.revokeObjectURL을 호출함
+const url = URL.createObjectURL(blob);
+downloadBlob(blob, "file.txt");
+URL.revokeObjectURL(url); // 불필요한 중복 해제
+
+// ✅ downloadBlob만 호출하면 됨
+downloadBlob(blob, "file.txt");
+```
+
+**근거**: 내부에서 `setTimeout(() => URL.revokeObjectURL(url), 1000)`으로 자동 정리한다.

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

@@ -0,0 +1,91 @@
+# `fetchUrlBytes`
+
+URL에서 바이너리 데이터를 `Uint8Array`로 다운로드하는 함수. 진행 콜백을 지원한다.
+
+## When to use
+
+- ✅ URL에서 바이너리 파일을 메모리로 가져올 때 (이미지, WASM, 압축 파일 등)
+- ✅ 다운로드 진행률 표시가 필요할 때
+- ❌ 텍스트/JSON 응답 → 표준 `fetch()` API 직접 사용
+- ❌ 다운로드한 데이터를 바로 파일로 저장 → 이 함수로 가져온 후 [`downloadBlob`](./download-blob.md) 사용
+
+## Signature
+
+```typescript
+export async function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | 다운로드 대상 URL |
+| `options.onProgress` | `(progress: DownloadProgress) => void` | 진행 콜백. `Content-Length` 헤더가 있는 경우에만 호출됨 |
+
+## Returns
+
+`Promise<Uint8Array>` — 다운로드된 바이너리 데이터.
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { fetchUrlBytes } from "@simplysm/core-browser";
+
+const data = await fetchUrlBytes("/api/files/report.pdf");
+```
+
+### 전형 예제 — 진행률 표시
+
+```typescript
+import { fetchUrlBytes } from "@simplysm/core-browser";
+
+const data = await fetchUrlBytes("/api/files/large-file.zip", {
+  onProgress: (progress) => {
+    const percent = Math.round((progress.receivedLength / progress.contentLength) * 100);
+    updateProgressBar(percent);
+  },
+});
+```
+
+## 🚫 Anti-patterns
+
+### Content-Length 없는 응답에서 진행률 의존
+
+```typescript
+// ❌ chunked encoding 응답은 Content-Length가 0이므로 onProgress가 호출되지 않음
+const data = await fetchUrlBytes("/api/stream", {
+  onProgress: (p) => {
+    // contentLength가 0이면 이 콜백은 호출되지 않음
+    showProgress(p.receivedLength / p.contentLength);
+  },
+});
+```
+
+**근거**: `Content-Length` 헤더가 없거나 0이면 청크 수집 모드로 전환되며, 이 경우 `onProgress`가 호출되지 않는다.
+
+## 에러 처리
+
+- HTTP 응답이 실패하면 (`response.ok === false`) `Error` 발생: `"다운로드 실패: {status} {statusText}"`
+- 응답 본문을 읽을 수 없으면 `Error` 발생: `"응답 본문을 읽을 수 없습니다"`
+- 수신 데이터가 `Content-Length`를 초과하거나 부족하면 `Error` 발생
+
+## Related Types
+
+### `DownloadProgress`
+
+```typescript
+export interface DownloadProgress {
+  receivedLength: number;
+  contentLength: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `receivedLength` | `number` | 현재까지 수신한 바이트 수 |
+| `contentLength` | `number` | 전체 콘텐츠 길이 (Content-Length 헤더 값) |

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

@@ -0,0 +1,131 @@
+# `IndexedDbStore`
+
+IndexedDB를 Promise 기반으로 래핑한 저수준 CRUD 클래스. 생성자에서 DB 이름, 버전, 스토어 설정을 받아 자기 완결적으로 동작한다.
+
+## When to use
+
+- ✅ 브라우저에서 구조화된 데이터를 영속 저장할 때 (캐시, 오프라인 데이터 등)
+- ✅ IndexedDB의 콜백 기반 API를 Promise로 사용하고 싶을 때
+- ❌ 경로 기반 파일시스템 추상화가 필요 → [`IndexedDbVirtualFs`](./indexed-db-virtual-fs.md)
+- ❌ 서버 측 데이터 저장 → `@simplysm/orm-node`
+
+## Signature
+
+```typescript
+export class IndexedDbStore {
+  constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[])
+
+  open(): Promise<IDBDatabase>
+  withStore<TResult>(
+    storeName: string,
+    mode: IDBTransactionMode,
+    fn: (store: IDBObjectStore) => Promise<TResult>,
+  ): Promise<TResult>
+  get<TValue>(storeName: string, key: IDBValidKey): Promise<TValue | undefined>
+  put(storeName: string, value: unknown): Promise<void>
+  delete(storeName: string, key: IDBValidKey): Promise<void>
+  getAll<TItem>(storeName: string): Promise<TItem[]>
+  close(): void
+}
+```
+
+## Members
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `constructor` | method | DB 이름, 버전, 스토어 설정으로 인스턴스 생성. `open()` 시 설정에 없는 스토어는 자동 생성 |
+| `open` | method | DB 연결. 중복 호출에 안전 (이미 열려 있으면 기존 인스턴스 반환). 다른 연결에 의해 차단되면 에러 |
+| `withStore` | method | 트랜잭션을 열고 `fn`을 실행. fn이 에러를 던지면 트랜잭션을 abort |
+| `get` | method | 키로 단일 항목 조회. 없으면 `undefined` |
+| `put` | method | 항목 추가/갱신. value에 keyPath에 해당하는 필드가 포함되어야 함 |
+| `delete` | method | 키로 항목 삭제 |
+| `getAll` | method | 스토어의 모든 항목 조회 |
+| `close` | method | DB 연결 닫기. 내부 상태 초기화 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { IndexedDbStore } from "@simplysm/core-browser";
+
+const store = new IndexedDbStore("myDb", 1, [{ name: "items", keyPath: "id" }]);
+
+await store.put("items", { id: "key1", value: "hello" });
+const item = await store.get<{ id: string; value: string }>("items", "key1");
+store.close();
+```
+
+### 전형 예제 — 커스텀 트랜잭션
+
+```typescript
+import { IndexedDbStore } from "@simplysm/core-browser";
+
+const store = new IndexedDbStore("appDb", 2, [
+  { name: "users", keyPath: "uid" },
+  { name: "settings", keyPath: "key" },
+]);
+
+// withStore로 저수준 트랜잭션 제어
+const count = await store.withStore("users", "readonly", async (objectStore) => {
+  return new Promise<number>((resolve, reject) => {
+    const req = objectStore.count();
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+});
+
+// 전체 항목 조회
+const allUsers = await store.getAll<{ uid: string; name: string }>("users");
+
+store.close();
+```
+
+## 🚫 Anti-patterns
+
+### close() 호출 누락
+
+```typescript
+// ❌ 연결을 닫지 않으면 다른 탭에서 DB 버전 업그레이드 시 차단됨
+const store = new IndexedDbStore("db", 1, configs);
+await store.put("items", data);
+// close() 없이 방치
+
+// ✅ 사용 후 반드시 close()
+const store = new IndexedDbStore("db", 1, configs);
+try {
+  await store.put("items", data);
+} finally {
+  store.close();
+}
+```
+
+**근거**: IndexedDB는 `versionchange` 이벤트 시 열린 연결을 닫아야 다른 탭에서 스키마 업그레이드가 가능하다. 내부에서 `onversionchange` 핸들러가 자동으로 닫기는 하지만, 명시적 정리가 권장된다.
+
+### keyPath 누락된 값으로 put
+
+```typescript
+// ❌ StoreConfig에 keyPath: "id"로 설정했는데 id 필드가 없음
+await store.put("items", { name: "test" }); // IndexedDB DataError
+
+// ✅ keyPath에 해당하는 필드를 반드시 포함
+await store.put("items", { id: "1", name: "test" });
+```
+
+**근거**: IndexedDB는 keyPath에 해당하는 필드가 없으면 `DataError`를 발생시킨다.
+
+## Related Types
+
+### `StoreConfig`
+
+```typescript
+export interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | object store 이름 |
+| `keyPath` | `string` | 기본 키 경로 |

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

@@ -0,0 +1,121 @@
+# `IndexedDbVirtualFs`
+
+`IndexedDbStore` 위에 경로 기반 가상 파일시스템을 구현하는 클래스. 키는 `/path/to/file` 형태의 문자열이다.
+
+## When to use
+
+- ✅ 브라우저에서 파일/디렉토리 계층 구조를 IndexedDB에 저장할 때
+- ✅ 오프라인 캐시나 가상 파일시스템이 필요할 때
+- ❌ 단순 키-값 저장 → [`IndexedDbStore`](./indexed-db-store.md)로 충분
+- ❌ 실제 파일시스템 접근 → File System Access API 또는 서버 측 처리
+
+## Signature
+
+```typescript
+export class IndexedDbVirtualFs {
+  constructor(db: IndexedDbStore, storeName: string, keyField: string)
+
+  getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>
+  putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>
+  deleteByPrefix(keyPrefix: string): Promise<boolean>
+  listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>
+  ensureDir(fullKeyBuilder: (path: string) => string, dirPath: string): Promise<void>
+}
+```
+
+## Members
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `constructor` | method | `IndexedDbStore` 인스턴스, 스토어 이름, 키 필드명을 주입받음 |
+| `getEntry` | method | 경로에 해당하는 엔트리 조회. 없으면 `undefined` |
+| `putEntry` | method | 엔트리 추가/갱신. `kind`는 `"file"` 또는 `"dir"`. 파일이면 `dataBase64`에 Base64 데이터 전달 |
+| `deleteByPrefix` | method | 접두사와 일치하는 모든 엔트리 삭제. 삭제된 항목이 있으면 `true` 반환 |
+| `listChildren` | method | 접두사 바로 아래 자식 목록 반환. 직접 자식만 (재귀적이지 않음) |
+| `ensureDir` | method | 경로의 모든 중간 디렉토리를 재귀적으로 생성. 이미 있으면 건너뜀 |
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { IndexedDbStore, IndexedDbVirtualFs } from "@simplysm/core-browser";
+
+const store = new IndexedDbStore("fsDb", 1, [{ name: "files", keyPath: "path" }]);
+const fs = new IndexedDbVirtualFs(store, "files", "path");
+
+await fs.putEntry("/readme.txt", "file", btoa("Hello"));
+const entry = await fs.getEntry("/readme.txt");
+// entry?.kind === "file", entry?.dataBase64 === "SGVsbG8="
+
+store.close();
+```
+
+### 전형 예제 — 디렉토리 구조 관리
+
+```typescript
+import { IndexedDbStore, IndexedDbVirtualFs } from "@simplysm/core-browser";
+
+const store = new IndexedDbStore("appFs", 1, [{ name: "vfs", keyPath: "fullPath" }]);
+const fs = new IndexedDbVirtualFs(store, "vfs", "fullPath");
+
+// 중간 디렉토리 자동 생성 (/, /docs 모두 생성됨)
+// fullKeyBuilder는 키를 가공하는 함수 (접두사 추가 등)
+await fs.ensureDir((p) => p, "/docs/reports");
+
+// 파일 저장
+await fs.putEntry("/docs/reports/q1.pdf", "file", base64Data);
+
+// 자식 목록 조회 (직접 자식만)
+const children = await fs.listChildren("/docs/");
+// [{ name: "reports", isDirectory: true }]
+
+// 접두사로 일괄 삭제
+const deleted = await fs.deleteByPrefix("/docs/reports");
+// deleted === true
+
+store.close();
+```
+
+## 🚫 Anti-patterns
+
+### ensureDir 없이 중간 경로의 파일 저장
+
+```typescript
+// ❌ /docs 디렉토리 엔트리가 없으면 listChildren("/")에서 /docs가 나타나지 않을 수 있음
+await fs.putEntry("/docs/file.txt", "file", data);
+
+// ✅ 중간 디렉토리를 먼저 생성
+await fs.ensureDir((p) => p, "/docs");
+await fs.putEntry("/docs/file.txt", "file", data);
+```
+
+**근거**: `putEntry`는 해당 경로의 엔트리만 저장하고 부모 디렉토리를 자동 생성하지 않는다. `listChildren`이 정확한 결과를 반환하려면 중간 디렉토리 엔트리가 존재해야 한다.
+
+### prefix에 후행 슬래시 누락
+
+```typescript
+// ❌ "/docs"로 listChildren하면 "/docsExtra" 같은 형제도 포함될 수 있음
+const children = await fs.listChildren("/docs");
+
+// ✅ 후행 슬래시를 포함하여 정확한 디렉토리 자식만 조회
+const children = await fs.listChildren("/docs/");
+```
+
+**근거**: `listChildren`은 `key.startsWith(prefix)` 후 첫 번째 `/` 세그먼트를 기준으로 자식을 추출한다. 후행 슬래시가 없으면 접두사가 같은 다른 경로가 포함될 수 있다.
+
+## Related Types
+
+### `VirtualFsEntry`
+
+```typescript
+export interface VirtualFsEntry {
+  kind: "file" | "dir";
+  dataBase64?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `kind` | `"file" \| "dir"` | 엔트리 종류 |
+| `dataBase64` | `string \| undefined` | 파일 데이터 (Base64 인코딩). 디렉토리인 경우 `undefined` |

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

@@ -0,0 +1,60 @@
+# `openFileDialog`
+
+프로그래밍 방식으로 파일 선택 대화상자를 여는 함수. `<input type="file">`을 DOM에 추가하지 않고 사용할 수 있다.
+
+## When to use
+
+- ✅ 버튼 클릭 등 사용자 인터랙션에서 파일 선택이 필요할 때
+- ✅ Angular 컴포넌트에서 `<input type="file">` 없이 파일 선택할 때
+- ❌ 드래그 앤 드롭 파일 업로드 → `dragover`/`drop` 이벤트 직접 처리
+
+## Signature
+
+```typescript
+export function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `options.accept` | `string` | 파일 형식 필터 (예: `".xlsx,.csv"`, `"image/*"`) |
+| `options.multiple` | `boolean` | 다중 선택 허용 여부. 기본값 `false` |
+
+## Returns
+
+`Promise<File[] | undefined>` — 파일 선택 시 `File[]`, 취소 시 `undefined`.
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { openFileDialog } from "@simplysm/core-browser";
+
+const files = await openFileDialog();
+if (files != null) {
+  // 파일 처리
+}
+```
+
+### 전형 예제 — 이미지 다중 선택
+
+```typescript
+import { openFileDialog } from "@simplysm/core-browser";
+
+const images = await openFileDialog({
+  accept: "image/*",
+  multiple: true,
+});
+
+if (images != null) {
+  for (const file of images) {
+    const arrayBuffer = await file.arrayBuffer();
+    // 이미지 처리
+  }
+}
+```