@simplysm/sd-claude 14.0.41 → 14.0.43

package/claude/references/sd-simplysm14/core-node/usage.md

@@ -10,154 +10,250 @@ npm install @simplysm/core-node
 
 ## API Overview
 
-### Utilities (fsx)
+### File System (fsx)
 
-파일 시스템 유틸리티. `import { fsx } from "@simplysm/core-node"` 형태로 사용한다.
+파일 시스템 작업을 위한 유틸리티 네임스페이스. 모든 함수는 동기/비동기 쌍으로 제공된다.
 
 | API | Type | Description |
 |-----|------|-------------|
-| `fsx.exists` | function | 파일/디렉토리 존재 여부 확인 (비동기) |
-| `fsx.existsSync` | function | 파일/디렉토리 존재 여부 확인 (동기) |
-| `fsx.mkdir` | function | 디렉토리 재귀 생성 (비동기) |
-| `fsx.mkdirSync` | function | 디렉토리 재귀 생성 (동기) |
-| `fsx.rm` | function | 파일/디렉토리 삭제, 최대 6회 재시도 (비동기) |
-| `fsx.rmSync` | function | 파일/디렉토리 삭제, 재시도 없음 (동기) |
-| `fsx.copy` | function | 파일/디렉토리 복사, filter 옵션 지원 (비동기) |
-| `fsx.copySync` | function | 파일/디렉토리 복사, filter 옵션 지원 (동기) |
-| `fsx.read` | function | 파일을 UTF-8 문자열로 읽기 (비동기) |
-| `fsx.readSync` | function | 파일을 UTF-8 문자열로 읽기 (동기) |
-| `fsx.readBytes` | function | 파일을 Uint8Array로 읽기 (비동기) |
-| `fsx.readBytesSync` | function | 파일을 Uint8Array로 읽기 (동기) |
-| `fsx.readJson` | function | JSON 파일 읽기 (비동기) |
-| `fsx.readJsonSync` | function | JSON 파일 읽기 (동기) |
-| `fsx.write` | function | 파일 쓰기, 상위 디렉토리 자동 생성 (비동기) |
-| `fsx.writeSync` | function | 파일 쓰기, 상위 디렉토리 자동 생성 (동기) |
-| `fsx.writeJson` | function | JSON 파일 쓰기 (비동기) |
-| `fsx.writeJsonSync` | function | JSON 파일 쓰기 (동기) |
-| `fsx.readdir` | function | 디렉토리 내용 읽기 (비동기) |
-| `fsx.readdirSync` | function | 디렉토리 내용 읽기 (동기) |
-| `fsx.stat` | function | 파일 정보 조회, 심볼릭 링크 따라감 (비동기) |
-| `fsx.statSync` | function | 파일 정보 조회, 심볼릭 링크 따라감 (동기) |
-| `fsx.lstat` | function | 파일 정보 조회, 심볼릭 링크 따라가지 않음 (비동기) |
-| `fsx.lstatSync` | function | 파일 정보 조회, 심볼릭 링크 따라가지 않음 (동기) |
-| `fsx.glob` | function | glob 패턴으로 파일 검색, 절대 경로 반환 (비동기) |
-| `fsx.globSync` | function | glob 패턴으로 파일 검색, 절대 경로 반환 (동기) |
-| `fsx.clearEmptyDirectory` | function | 빈 디렉토리 재귀 삭제 (비동기) |
-| `fsx.findAllParentChildPaths` | function | 부모 디렉토리 순회하며 glob 매칭 경로 수집 (비동기) |
-| `fsx.findAllParentChildPathsSync` | function | 부모 디렉토리 순회하며 glob 매칭 경로 수집 (동기) |
-
-→ See [docs/utilities-fsx.md](./docs/utilities-fsx.md) for details.
-
-### Utilities (cpx)
-
-자식 프로세스 실행 유틸리티. `import { cpx } from "@simplysm/core-node"` 형태로 사용한다.
+| `exists` | function | 파일 또는 디렉토리가 존재하는지 확인 (비동기) |
+| `existsSync` | function | 파일 또는 디렉토리가 존재하는지 확인 (동기) |
+| `mkdir` | function | 디렉토리를 생성 (재귀적, 비동기) |
+| `mkdirSync` | function | 디렉토리를 생성 (재귀적, 동기) |
+| `rm` | function | 파일/디렉토리 삭제, 파일 잠금 시 최대 6회 재시도 (비동기) |
+| `rmSync` | function | 파일/디렉토리 삭제 (동기, 재시도 없음) |
+| `copy` | function | 파일/디렉토리 복사, 필터 옵션 지원 (비동기) |
+| `copySync` | function | 파일/디렉토리 복사, 필터 옵션 지원 (동기) |
+| `read` | function | 파일을 UTF-8 문자열로 읽음 (비동기) |
+| `readSync` | function | 파일을 UTF-8 문자열로 읽음 (동기) |
+| `readBytes` | function | 파일을 Uint8Array로 읽음 (비동기) |
+| `readBytesSync` | function | 파일을 Uint8Array로 읽음 (동기) |
+| `readJson` | function | JSON 파일 읽음 (비동기) |
+| `readJsonSync` | function | JSON 파일 읽음 (동기) |
+| `write` | function | 파일에 데이터 쓰기, 상위 디렉토리 자동 생성 (비동기) |
+| `writeSync` | function | 파일에 데이터 쓰기, 상위 디렉토리 자동 생성 (동기) |
+| `writeJson` | function | JSON 파일에 데이터 쓰기 (비동기) |
+| `writeJsonSync` | function | JSON 파일에 데이터 쓰기 (동기) |
+| `readdir` | function | 디렉토리 내용 읽기 (비동기) |
+| `readdirSync` | function | 디렉토리 내용 읽기 (동기) |
+| `stat` | function | 파일/디렉토리 정보 조회, 심볼릭 링크 따라감 (비동기) |
+| `statSync` | function | 파일/디렉토리 정보 조회, 심볼릭 링크 따라감 (동기) |
+| `lstat` | function | 파일/디렉토리 정보 조회, 심볼릭 링크 따라가지 않음 (비동기) |
+| `lstatSync` | function | 파일/디렉토리 정보 조회, 심볼릭 링크 따라가지 않음 (동기) |
+| `glob` | function | Glob 패턴으로 파일 검색 (비동기) |
+| `globSync` | function | Glob 패턴으로 파일 검색 (동기) |
+| `clearEmptyDirectory` | function | 빈 디렉토리 재귀적 삭제 |
+| `findAllParentChildPathsSync` | function | 부모 디렉토리에서 특정 파일 검색 (동기) |
+| `findAllParentChildPaths` | function | 부모 디렉토리에서 특정 파일 검색 (비동기) |
+
+→ See [docs/file-system.md](./docs/file-system.md) for details.
+
+### Child Process (cpx)
+
+자식 프로세스 실행 및 인코딩 감지.
 
 | API | Type | Description |
 |-----|------|-------------|
-| `cpx.spawn` | function | 비동기 자식 프로세스 실행, SpawnProcess 반환 |
-| `cpx.spawnSync` | function | 동기 자식 프로세스 실행, SpawnResult 반환 |
-| `cpx.SpawnProcess` | class | spawn()의 반환 타입. PromiseLike + kill() 지원 |
-| `cpx.SpawnResult` | interface | 프로세스 실행 결과 (stdout, stderr, exitCode) |
-| `cpx.getSystemEncoding` | function | 시스템 인코딩 감지 (Windows: chcp, Linux: LANG 환경변수) |
-| `cpx.codePageToEncoding` | function | Windows 코드 페이지 번호를 인코딩 이름으로 변환 |
-| `cpx.resetEncodingCache` | function | 캐시된 시스템 인코딩 초기화 |
-| `cpx.decodeBytes` | function | Uint8Array를 시스템 인코딩으로 디코딩 |
-| `cpx.resolveStdioPipe` | function | stdio 옵션에서 stdout/stderr pipe 여부 추출 |
+| `spawn` | function | 자식 프로세스 실행, Promise 기반, 실시간 제어 가능 |
+| `spawnSync` | function | 자식 프로세스 동기 실행 |
+| `getSystemEncoding` | function | 시스템 기본 인코딩 감지 |
+| `codePageToEncoding` | function | Windows 코드 페이지를 인코딩명으로 변환 |
+| `decodeBytes` | function | Uint8Array를 문자열로 디코딩 |
+| `resolveStdioPipe` | function | stdio 옵션에서 pipe 여부 판단 |
+| `resetEncodingCache` | function | 인코딩 캐시 초기화 |
+| `SpawnProcess` | class | spawn() 반환 타입, PromiseLike 구현 |
+| `SpawnResult` | interface | spawn/spawnSync 결과 타입 |
 
-→ See [docs/utilities-cpx.md](./docs/utilities-cpx.md) for details.
+→ See [docs/child-process.md](./docs/child-process.md) for details.
 
-### Utilities (pathx)
+### Path (pathx)
 
-경로 유틸리티. `import { pathx } from "@simplysm/core-node"` 형태로 사용한다.
+경로 처리 및 PosixPath 브랜드 타입.
 
 | API | Type | Description |
 |-----|------|-------------|
-| `pathx.PosixPath` | type | POSIX 슬래시 경로임을 타입 수준에서 보장하는 브랜드 타입 |
-| `pathx.posix` | function | 백슬래시를 슬래시로 변환하여 PosixPath 반환 |
-| `pathx.posixResolve` | function | 절대 경로 resolve 후 POSIX 스타일로 변환 |
-| `pathx.changeFileDirectory` | function | 파일 경로의 디렉토리 부분을 변경 |
-| `pathx.basenameWithoutExt` | function | 확장자를 제외한 파일명 반환 |
-| `pathx.isChildPath` | function | childPath가 parentPath의 하위 경로인지 확인 |
-| `pathx.filterByTargets` | function | 대상 경로 목록으로 파일 목록 필터링 |
+| `posix` | function | 경로를 POSIX 스타일(슬래시)로 변환 |
+| `posixResolve` | function | 경로를 절대 경로로 resolve한 후 POSIX 스타일로 변환 |
+| `changeFileDirectory` | function | 파일의 디렉토리를 변경 |
+| `basenameWithoutExt` | function | 확장자를 제외한 파일명 반환 |
+| `isChildPath` | function | 자식 경로 여부 확인 |
+| `filterByTargets` | function | 대상 경로 목록에 기반한 파일 필터링 |
+| `PosixPath` | type | POSIX 스타일 경로 브랜드 타입 |
 
-→ See [docs/utilities-pathx.md](./docs/utilities-pathx.md) for details.
+→ See [docs/path.md](./docs/path.md) for details.
 
-### Features
+### File Watching (FsWatcher)
+
+Chokidar 기반 파일 시스템 감시 클래스.
 
 | API | Type | Description |
 |-----|------|-------------|
-| `FsWatcher` | class | Chokidar 기반 파일 시스템 감시 래퍼. 이벤트 병합, EPERM 자동 복구 |
-| `FsWatcherEvent` | type | 파일 변경 이벤트 타입 (`"add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir"`) |
+| `FsWatcher` | class | 파일 시스템 감시, 이벤트 병합, 자동 복구 |
+| `FsWatcherEvent` | type | 감시 이벤트 타입: "add" \| "addDir" \| "change" \| "unlink" \| "unlinkDir" |
 | `FsWatcherChangeInfo` | interface | 파일 변경 정보 (event + path) |
-| `PrettyReporter` | class | 터미널 출력용 consola reporter (아이콘, 색상, 에러 스택 포맷팅) |
-| `createFileReporter` | function | 파일 기반 consola reporter 생성 (JSON 라인, 날짜별 로테이션, 크기 제한) |
-| `FileReporterOptions` | interface | createFileReporter 옵션 (maxSize, maxDays) |
-| `withMaxLevel` | function | consola reporter를 지정된 로그 레벨 이하로 제한하는 래퍼 |
-| `setupConsola` | function | 환경에 따라 consola reporter를 자동 구성 |
-| `SetupConsolaOptions` | interface | setupConsola 옵션 (cli 모드 여부) |
 
-→ See [docs/features.md](./docs/features.md) for details.
+→ See [docs/file-watching.md](./docs/file-watching.md) for details.
+
+### Logging (consola)
+
+Consola 로깅 설정 및 reporter.
+
+| API | Type | Description |
+|-----|------|-------------|
+| `setupConsola` | function | 환경별 자동 consola 구성 |
+| `withMaxLevel` | function | 로그 레벨 상한선을 설정한 reporter 래퍼 |
+| `PrettyReporter` | class | 터미널 출력용 consola reporter |
+| `createFileReporter` | function | 파일 기반 consola reporter 생성 |
+
+→ See [docs/logging.md](./docs/logging.md) for details.
+
+### Worker Threads
 
-### Worker
+타입 안전한 Worker thread 래퍼.
 
 | API | Type | Description |
 |-----|------|-------------|
-| `Worker` | const (object) | 타입 안전한 Worker Proxy 생성 팩토리 (`Worker.create()`) |
-| `createWorker` | function | Worker thread 측에서 메서드와 이벤트를 등록하는 팩토리 |
-| `WorkerModule` | interface | createWorker가 반환하는 워커 모듈의 타입 구조 |
-| `PromisifyMethods` | type | 메서드 반환값을 Promise로 감싸는 매핑 타입 |
-| `WorkerProxy` | type | Worker.create()가 반환하는 프록시 타입 (메서드 + on/off + terminate) |
-| `WorkerRequest` | interface | 내부 워커 요청 메시지 |
-| `WorkerResponse` | type | 내부 워커 응답 메시지 (discriminated union: return \| error \| event \| log) |
+| `Worker` | class | Worker thread 프록시 생성 및 메서드 호출 |
+| `createWorker` | function | 워커 측에서 호출하는 워커 모듈 생성 함수 |
+| `WorkerModule` | interface | 워커 모듈의 타입 구조 |
+| `WorkerProxy` | type | Worker.create() 반환 프록시 타입 |
+| `WorkerRequest` | interface | 워커 요청 메시지 타입 |
+| `WorkerResponse` | type | 워커 응답 메시지 타입 |
+| `PromisifyMethods` | type | 메서드를 Promise 버전으로 변환하는 매핑 타입 |
 
-→ See [docs/worker.md](./docs/worker.md) for details.
+→ See [docs/worker-threads.md](./docs/worker-threads.md) for details.
 
 ## Usage Examples
 
-### 파일 시스템 조작
+### File System Operations
 
 ```typescript
 import { fsx } from "@simplysm/core-node";
 
+// 파일 존재 확인
+const exists = await fsx.exists("/path/to/file.txt");
+
 // 파일 읽기/쓰기
-await fsx.write("/path/to/file.txt", "content");
-const text = await fsx.read("/path/to/file.txt");
+const content = await fsx.read("/path/to/file.txt");
+await fsx.write("/path/to/new-file.txt", "Hello, World!");
+
+// JSON 파일 읽기/쓰기
+const data = await fsx.readJson<{ name: string }>("/path/to/config.json");
+await fsx.writeJson("/path/to/config.json", { name: "test" });
 
-// JSON 읽기/쓰기
-await fsx.writeJson("/path/to/config.json", { key: "value" }, { space: 2 });
-const config = await fsx.readJson<{ key: string }>("/path/to/config.json");
+// 파일 복사 (필터 적용)
+await fsx.copy("/src/dir", "/dst/dir", (filePath) => {
+  return !filePath.includes("node_modules");
+});
 
-// glob 검색
-const tsFiles = await fsx.glob("/project/src/**/*.ts");
+// Glob 검색
+const tsFiles = await fsx.glob("src/**/*.ts");
 ```
 
-### 자식 프로세스 실행
+### Child Process Execution
 
 ```typescript
 import { cpx } from "@simplysm/core-node";
 
-const result = await cpx.spawn("git", ["status"], { cwd: "/project" });
-// result: { stdout: string, stderr: string, exitCode: number }
+// 기본 실행
+const result = await cpx.spawn("npm", ["list"], { cwd: "/project" });
+console.log(result.stdout);
+
+// 실시간 출력
+await cpx.spawn("npm", ["run", "build"], { stdio: "inherit" });
+
+// 오류 무시
+const result = await cpx.spawn("cmd", ["nonexistent"], { reject: false });
+// result.exitCode가 0이 아니어도 throw되지 않음
+
+// 동기 실행
+const syncResult = cpx.spawnSync("node", ["--version"]);
+console.log(syncResult.stdout);
+```
+
+### Path Utilities
+
+```typescript
+import { pathx } from "@simplysm/core-node";
+
+// POSIX 경로 변환
+const posixPath = pathx.posix("C:\\Users\\test");
+console.log(posixPath); // "C:/Users/test"
+
+// 절대 경로 resolve + POSIX
+const absPath = pathx.posixResolve("./relative", "path");
 
-// 실행 중 종료 가능
-const proc = cpx.spawn("long-running-cmd", []);
-proc.kill();
+// 자식 경로 확인
+const isChild = pathx.isChildPath("/a/b/c", "/a/b"); // true
+
+// 경로 필터링
+const filtered = pathx.filterByTargets(
+  ["/proj/src/a.ts", "/proj/tests/b.ts"],
+  ["src"],
+  "/proj"
+);
+// ["/proj/src/a.ts"]
+```
+
+### File Watching
+
+```typescript
+import { FsWatcher } from "@simplysm/core-node";
+
+const watcher = await FsWatcher.watch(["src/**/*.ts"]);
+
+watcher.onChange({ delay: 300 }, (changes) => {
+  for (const { event, path } of changes) {
+    console.log(`${event}: ${path}`);
+  }
+});
+
+// 파일 감시 종료
+await watcher.close();
 ```
 
-### Worker thread
+### Logging Setup
 
 ```typescript
-// worker.ts
+import { setupConsola } from "@simplysm/core-node";
+
+// 환경별 자동 구성
+setupConsola();
+
+// CLI 모드 (프로덕션에서도 file + pretty reporter 사용)
+setupConsola({ cli: true });
+```
+
+### Worker Threads
+
+```typescript
+// worker.ts (워커 파일)
 import { createWorker } from "@simplysm/core-node";
 
-const methods = { add: (a: number, b: number) => a + b };
-export default createWorker(methods);
+interface MyEvents {
+  progress: number;
+}
+
+const methods = {
+  add: (a: number, b: number) => a + b,
+  multiply: (a: number, b: number) => a * b,
+};
 
-// main.ts
+const sender = createWorker<typeof methods, MyEvents>(methods);
+export default sender;
+
+// main.ts (메인 파일)
 import { Worker } from "@simplysm/core-node";
 import type * as MyWorker from "./worker";
 
 const worker = Worker.create<typeof MyWorker>("./worker.ts");
-const result = await worker.add(10, 20); // 30
+
+const sum = await worker.add(10, 20); // 30
+const product = await worker.multiply(5, 6); // 30
+
+worker.on("progress", (value) => {
+  console.log(`Progress: ${value}%`);
+});
+
 await worker.terminate();
 ```

package/claude/references/sd-simplysm14/excel/docs/core-classes.md

@@ -63,7 +63,7 @@ ZIP 리더와 내부 캐시를 정리한다. 이미 닫힌 워크북에 대해
 
 ## `ExcelWorksheet`
 
-Excel 워크시트를 나타내는 클래스. 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입 기능을 제공한다.
+Excel 워크시트를 나타내는 클래스. 셀 접근, 행/열 복사, 데이터 테이블 처리, 이미지 삽입, 뷰 설정 기능을 제공한다.
 
 ```typescript
 export class ExcelWorksheet {
@@ -90,7 +90,11 @@ export class ExcelWorksheet {
   async getCells(): Promise<ExcelCell[][]>;
 
   // Data
-  async getDataTable(opt?: { ... }): Promise<Record<string, ExcelValueType>[]>;
+  async getDataTable(opt?: {
+    headerRowIndex?: number;
+    checkEndColIndex?: number;
+    usableHeaderNameFn?: (headerName: string) => boolean;
+  }): Promise<Record<string, ExcelValueType>[]>;
   async setDataMatrix(matrix: ExcelValueType[][]): Promise<void>;
   async setRecords(records: Record<string, ExcelValueType>[]): Promise<void>;
 
@@ -99,7 +103,12 @@ export class ExcelWorksheet {
   async freezeAt(point: { r?: number; c?: number }): Promise<void>;
 
   // Image
-  async addImage(opts: { ... }): Promise<void>;
+  async addImage(opts: {
+    bytes: Bytes;
+    ext: string;
+    from: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+    to?: { r: number; c: number; rOff?: number | string; cOff?: number | string };
+  }): Promise<void>;
 }
 ```
 
@@ -193,6 +202,10 @@ export class ExcelWorksheet {
 | `srcR` | `number` | 복사할 원본 행 인덱스 (0 기반) |
 | `targetR` | `number` | 삽입할 대상 행 인덱스 (0 기반) |
 
+**병합 셀 처리:**
+- 삽입 지점을 관통하는 다중행 병합은 자동으로 1행 확장됨
+- 원본 행의 단일행 병합만 대상 행에 복사됨
+
 ### Range Methods
 
 #### `getRange()`
@@ -207,25 +220,27 @@ export class ExcelWorksheet {
 
 #### `getDataTable(opt?)`
 
-워크시트 데이터를 테이블(레코드 배열)로 반환한다. 첫 번째 행(또는 `headerRowIndex`)을 헤더로 사용한다.
+워크시트 데이터를 테이블(레코드 배열)로 반환한다. 지정된 헤더 행(기본값: 첫 번째 행)을 기준으로 이하의 데이터를 읽는다.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `opt.headerRowIndex` | `number \| undefined` | 헤더 행 인덱스 (기본값: 첫 번째 행) |
-| `opt.checkEndColIndex` | `number \| undefined` | 데이터 끝을 판단할 열 인덱스. 이 열이 비어있으면 데이터가 끝난 것으로 판단한다 |
-| `opt.usableHeaderNameFn` | `(headerName: string) => boolean \| undefined` | 사용 가능한 헤더를 필터링하는 함수 |
+| `opt.headerRowIndex` | `number \| undefined` | 헤더 행 인덱스 (기본값: 데이터 범위의 시작 행) |
+| `opt.checkEndColIndex` | `number \| undefined` | 데이터 끝을 판단할 열 인덱스. 이 열이 비어있는 행을 만나면 데이터가 끝난 것으로 판단한다 |
+| `opt.usableHeaderNameFn` | `(headerName: string) => boolean \| undefined` | 사용 가능한 헤더를 필터링하는 함수. 반환값이 `false`인 헤더는 제외된다 |
+
+**반환값:** `Record<string, ExcelValueType>[]` - 헤더를 키로 하는 레코드 배열
 
 #### `setDataMatrix(matrix)`
 
-2차원 배열 데이터를 워크시트에 쓴다.
+2차원 배열 데이터를 워크시트에 쓴다. (0, 0) 위치부터 시작하여 데이터를 기록한다.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `matrix` | `ExcelValueType[][]` | 2차원 배열 데이터 (행 우선, 인덱스 0이 첫 번째 행) |
+| `matrix` | `ExcelValueType[][]` | 2차원 배열 데이터 (행 우선, `matrix[0]`이 첫 번째 행) |
 
 #### `setRecords(records)`
 
-레코드 배열을 워크시트에 쓴다. 첫 번째 행에 헤더가 자동 생성되고, 이후 행에 데이터가 기록된다.
+레코드 배열을 워크시트에 쓴다. 첫 번째 행(r=0)에 헤더가 자동 생성되고, 이후 행(r=1...)에 데이터가 기록된다. 모든 레코드의 필드를 수집하여 헤더로 사용한다.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -254,14 +269,18 @@ export class ExcelWorksheet {
 
 #### `addImage(opts)`
 
-워크시트에 이미지를 삽입한다.
+워크시트에 이미지를 삽입한다. 같은 시트의 첫 이미지 호출 시 `drawing1.xml` 생성, 이후 이미지는 동일 drawing에 추가된다.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `opts.bytes` | `Bytes` | 이미지 바이너리 데이터 |
-| `opts.ext` | `string` | 이미지 확장자 (png, jpg 등) |
-| `opts.from` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string }` | 이미지 시작 위치 (0 기반 행/열 인덱스, rOff/cOff는 EMU 오프셋) |
-| `opts.to` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string } \| undefined` | 이미지 끝 위치 (생략 시 from 위치에서 1행x1열 크기) |
+| `opts.ext` | `string` | 이미지 확장자 (예: `"png"`, `"jpg"`, `"gif"`) |
+| `opts.from` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string }` | 이미지 시작 위치. `r`/`c`는 0 기반 행/열 인덱스, `rOff`/`cOff`는 선택적 EMU 오프셋 |
+| `opts.to` | `{ r: number; c: number; rOff?: number \| string; cOff?: number \| string } \| undefined` | 이미지 끝 위치. 생략 시 기본값은 `{ r: from.r + 1, c: from.c + 1 }`이다 |
+
+**이미지 파일 관리:**
+- 이미지는 `xl/media/image1.ext`, `xl/media/image2.ext` 등으로 자동 관리됨
+- 기존 파일명과 중복되지 않도록 인덱스 자동 증가
 
 ---
 

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

@@ -1,6 +1,6 @@
 # @simplysm/excel
 
-심플리즘 패키지 - xlsx 파일 읽기/쓰기 라이브러리. DOM-independent (neutral) 환경에서 동작한다.
+Excel 워크북(xlsx) 읽기/쓰기 라이브러리. DOM 의존성이 없어 Node.js와 브라우저 양쪽에서 동작하는 neutral 패키지다. Lazy Loading 아키텍처로 대용량 파일도 메모리 효율적으로 처리한다.
 
 ## Installation
 
@@ -14,65 +14,50 @@ npm install @simplysm/excel
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ExcelWorkbook` | class | Excel 워크북 처리 클래스. ZIP 리소스를 관리하며, 워크시트 생성/조회/내보내기를 제공한다 |
-| `ExcelWorksheet` | class | Excel 워크시트. 셀/행/열 접근, 복사, 데이터 테이블, 이미지 삽입 기능을 제공한다 |
-| `ExcelCell` | class | Excel 셀. 값 읽기/쓰기, 수식, 스타일, 셀 병합 기능을 제공한다 |
-| `ExcelRow` | class | Excel 행. 셀 접근 기능을 제공한다 |
-| `ExcelCol` | class | Excel 열. 셀 접근 및 열 너비 설정 기능을 제공한다 |
+| `ExcelWorkbook` | class | Excel 워크북 진입점. 워크시트 생성/조회, 바이트 내보내기, ZIP 리소스 관리 |
+| `ExcelWorksheet` | class | 워크시트. 셀/행/열 접근, 행/셀 복사, 데이터 테이블 읽기, 이미지 삽입, 시트명 변경 |
+| `ExcelCell` | class | 개별 셀. 값/수식 읽기/쓰기, 스타일 설정, 셀 병합 |
+| `ExcelRow` | class | 워크시트 행. 셀 접근, 행 전체 셀 조회 |
+| `ExcelCol` | class | 워크시트 열. 셀 접근, 열 너비 설정 |
 
--> See [docs/core-classes.md](./docs/core-classes.md) for details.
+→ See [docs/core-classes.md](./docs/core-classes.md) for details.
 
 ### Wrapper
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ExcelWrapper` | class | Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기 래퍼 |
+| `ExcelWrapper` | class | Zod 스키마 기반 타입 안전한 Excel 읽기/쓰기. 헤더 자동 생성, 유효성 검사, 필수 필드 강조 |
 
--> See [docs/wrapper.md](./docs/wrapper.md) for details.
+→ See [docs/wrapper.md](./docs/wrapper.md) for details.
 
 ### Utilities
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ExcelUtils` | class | 셀 주소 변환, 날짜/숫자 변환, 숫자 형식 처리 정적 메서드 모음 |
+| `ExcelUtils` | class | 셀 주소 변환 (좌표↔문자열), 날짜↔숫자 변환, 숫자 형식 매핑 (정적 메서드) |
 
--> See [docs/utilities.md](./docs/utilities.md) for details.
+→ See [docs/utilities.md](./docs/utilities.md) for details.
 
 ### Types
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ExcelValueType` | type | 셀 값 타입 (`number \| string \| DateOnly \| DateTime \| Time \| boolean \| undefined`) |
-| `ExcelNumberFormat` | type | 숫자 형식 이름 (`"number" \| "string" \| "DateOnly" \| "DateTime" \| "Time"`) |
-| `ExcelCellType` | type | Excel 셀 타입 (`"s" \| "b" \| "str" \| "n" \| "inlineStr" \| "e"`) |
+| `ExcelValueType` | type | 셀 값 타입: number, string, DateOnly, DateTime, Time, boolean, undefined |
+| `ExcelNumberFormat` | type | 숫자 형식 이름: "number", "string", "DateOnly", "DateTime", "Time" |
+| `ExcelCellType` | type | 셀 타입: "s"(공유문자열), "b"(boolean), "str"(수식문자열), "n"(숫자), "inlineStr", "e"(에러) |
 | `ExcelAddressPoint` | interface | 셀 좌표 (0 기반 r, c) |
-| `ExcelAddressRangePoint` | interface | 셀 범위 좌표 (s, e) |
+| `ExcelAddressRangePoint` | interface | 셀 범위 좌표 (시작점 s, 끝점 e) |
 | `ExcelStyleOptions` | interface | 셀 스타일 옵션 (배경색, 테두리, 정렬, 숫자 형식) |
-| `ExcelBorderPosition` | type | 테두리 위치 (`"left" \| "right" \| "top" \| "bottom"`) |
-| `ExcelHorizontalAlign` | type | 가로 정렬 (`"center" \| "left" \| "right"`) |
-| `ExcelVerticalAlign` | type | 세로 정렬 (`"center" \| "top" \| "bottom"`) |
+| `ExcelBorderPosition` | type | 테두리 위치: "left", "right", "top", "bottom" |
+| `ExcelHorizontalAlign` | type | 가로 정렬: "left", "center", "right" |
+| `ExcelVerticalAlign` | type | 세로 정렬: "top", "center", "bottom" |
 | `ExcelXml` | interface | XML 처리 클래스가 구현하는 인터페이스 (내부용) |
-| `ExcelXmlContentTypeData` | interface | `[Content_Types].xml` 데이터 구조 (내부용) |
-| `ExcelXmlRelationshipData` | interface | `*.rels` 데이터 구조 (내부용) |
-| `ExcelRelationshipData` | interface | 개별 Relationship 엔트리 데이터 (내부용) |
-| `ExcelXmlWorkbookData` | interface | `workbook.xml` 데이터 구조 (내부용) |
-| `ExcelXmlWorksheetData` | interface | `worksheet*.xml` 데이터 구조 (내부용) |
-| `ExcelRowData` | interface | 행 XML 데이터 (내부용) |
-| `ExcelCellData` | interface | 셀 XML 데이터 (내부용) |
-| `ExcelXmlDrawingData` | interface | `drawing*.xml` 데이터 구조 (내부용) |
-| `ExcelXmlSharedStringData` | interface | `sharedStrings.xml` 데이터 구조 (내부용) |
-| `ExcelXmlSharedStringDataSi` | type | SharedString 개별 항목 union 타입 (내부용) |
-| `ExcelXmlSharedStringDataText` | type | SharedString 텍스트 데이터 (내부용) |
-| `ExcelXmlStyleData` | interface | `styles.xml` 데이터 구조 (내부용) |
-| `ExcelXmlStyleDataXf` | interface | 셀 서식(xf) 데이터 (내부용) |
-| `ExcelXmlStyleDataFill` | interface | 채우기 스타일 데이터 (내부용) |
-| `ExcelXmlStyleDataBorder` | interface | 테두리 스타일 데이터 (내부용) |
-
--> See [docs/types.md](./docs/types.md) for details.
+
+→ See [docs/types.md](./docs/types.md) for details.
 
 ## Usage Examples
 
-### 워크북 생성 및 셀 값 쓰기
+### 새 Excel 파일 생성 및 저장
 
 ```typescript
 import { ExcelWorkbook } from "@simplysm/excel";
@@ -80,32 +65,44 @@ import { ExcelWorkbook } from "@simplysm/excel";
 const wb = new ExcelWorkbook();
 try {
   const ws = await wb.addWorksheet("Sheet1");
+  
+  // 헤더 행
   await ws.cell(0, 0).setValue("이름");
   await ws.cell(0, 1).setValue("나이");
-  await ws.cell(1, 0).setValue("홍길동");
+  
+  // 데이터 행
+  await ws.cell(1, 0).setValue("김철수");
   await ws.cell(1, 1).setValue(30);
+  
   const bytes = await wb.toBytes();
+  // 파일 저장 또는 전송
 } finally {
   await wb.close();
 }
 ```
 
-### 기존 파일 읽기
+### 기존 Excel 파일 읽기
 
 ```typescript
 import { ExcelWorkbook } from "@simplysm/excel";
 
-const wb = new ExcelWorkbook(fileBytes);
+const bytes = /* 파일 바이트 배열 */;
+const wb = new ExcelWorkbook(bytes);
 try {
+  // 시트명 또는 인덱스(0 기반)로 조회
   const ws = await wb.getWorksheet(0);
+  
+  // 개별 셀 읽기
   const value = await ws.cell(0, 0).getValue();
-  const dataTable = await ws.getDataTable();
+  
+  // 전체 데이터 테이블 읽기 (첫 행이 헤더)
+  const table = await ws.getDataTable();
 } finally {
   await wb.close();
 }
 ```
 
-### Zod 스키마 기반 래퍼 사용
+### Zod 스키마 기반 타입 안전한 작업
 
 ```typescript
 import { ExcelWrapper } from "@simplysm/excel";
@@ -119,14 +116,19 @@ const schema = z.object({
 
 const wrapper = new ExcelWrapper(schema);
 
-// 쓰기
-const wb = await wrapper.write("Sheet1", records);
+// 레코드 배열을 Excel로 쓰기
+const records = [
+  { name: "김철수", age: 30, email: "kim@example.com" },
+  { name: "이영희", age: 28 },
+];
+const wb = await wrapper.write("사람", records);
 try {
   const bytes = await wb.toBytes();
 } finally {
   await wb.close();
 }
 
-// 읽기
-const records = await wrapper.read(fileBytes, "Sheet1");
+// Excel 파일을 레코드 배열로 읽기 (유효성 검사 포함)
+const bytes = /* 파일 바이트 배열 */;
+const data = await wrapper.read(bytes, "사람");
 ```