@simplysm/sd-claude 14.0.89 → 14.0.90

package/claude/references/sd-simplysm14/apis/core-node/worker.md

@@ -1,17 +1,18 @@
 # @simplysm/core-node — worker
 
-`worker_threads` 를 타입 안전하게 쓰기 위한 래퍼. 워커 파일에서 `createWorker(methods)` 로 메서드 묶음을 export 하고, 메인에서 `Worker.create<typeof import("./worker")>(path)` 로 프록시를 만들어 `await worker.method(...)` 처럼 호출. 메시지 직렬화는 `@simplysm/core-common` 의 `transfer`(Date/특수타입·transferList 지원)를 사용한다. 개발(.ts)·프로덕션(.js) 양쪽을 자동 분기한다.
+`worker_threads` 를 타입 안전하게 쓰기 위한 래퍼 (`packages/core-node/src/worker/*`). 워커 파일에서 `createWorker(methods)` 로 메서드 묶음을 만들어 `export default` 하고, 메인에서 `Worker.create<typeof import("./worker")>(path)` 로 프록시를 만들어 `await worker.method(...)` 처럼 호출. 메시지 직렬화는 `@simplysm/core-common` 의 `transfer`(Date 등 특수타입·transferList 지원)를 사용한다. 개발(`.ts`)·프로덕션(`.js`) 양쪽을 자동 분기한다.
 
 ## createWorker (워커 스레드 측)
 
 - `createWorker<TMethods, TEvents>(methods): { send; __methods; __events }` — 워커 스레드 진입 파일에서 호출하고 그 반환을 `export default`. `parentPort` 가 없으면(워커 컨텍스트 아님) `SdError` throw. 메서드 호출 메시지를 수신해 실행 후 결과/에러를 응답하고, 워커의 `process.stdout.write` 를 가로채 메인으로 로그를 전달한다.
-  - `methods: TMethods` (`Record<string, (...args) => unknown>`) — 워커가 제공할 메서드 맵. 동기/비동기 모두 가능(await 됨). 알 수 없는 메서드 호출 시 `SdError("알 수 없는 메서드: ...")` 응답.
-  - 제네릭 `TEvents extends Record<string, unknown>` — 워커가 보낼 이벤트명→데이터 타입 맵(메인의 `on` 타입 추론에 사용).
-  - 반환 `send<K extends keyof TEvents & string>(event, data?)` — 워커→메인 이벤트 전송. 진행률 등 메서드 반환과 별개 통지에 사용.
-  - 반환 `__methods`/`__events` — 타입 추론용 마커(런타임에 `Worker.create` 가 직접 쓰진 않음, 타입에서만 참조).
+  - `methods: TMethods` (`Record<string, (...args: any[]) => unknown>`) — 워커가 제공할 메서드 맵. 동기/비동기 모두 가능(내부에서 await). 알 수 없는 메서드 호출 시 `SdError("알 수 없는 메서드: ...")` 로 응답.
+  - 제네릭 `TEvents extends Record<string, unknown>`(기본 `Record<string, never>`) — 워커가 보낼 이벤트명→데이터 타입 맵(메인의 `on` 타입 추론에 사용).
+  - 반환 `send<K extends keyof TEvents & string>(event, data?): void` — 워커→메인 이벤트 전송. 진행률 등 메서드 반환과 별개의 통지에 사용.
+  - 반환 `__methods` / `__events` — 타입 추론용 마커. 런타임 값이 아니라 `Worker.create<typeof import(...)>` 의 타입에서만 참조됨.
 
 ```ts
-// worker.ts
+// worker.ts (워커 스레드 진입)
+import { createWorker } from "@simplysm/core-node";
 interface MyEvents { progress: number; }
 const methods = {
   calc: (x: number) => { sender.send("progress", 50); return x * 2; },
@@ -25,10 +26,10 @@ export default sender;
 - `Worker.create<TModule extends WorkerModule>(filePath, opt?): WorkerProxy<TModule>` — 워커 스레드를 띄우고 메서드 프록시를 반환. 메서드 호출은 메시지로 전달되어 결과가 Promise 로 resolve/reject 된다. 워커 stdout/stderr 는 메인 프로세스로 파이프되며, 워커 비정상 종료(exit code≠0)·error 시 대기 중인 모든 호출이 reject 된다. 로거 태그 `sd-worker`.
   - `filePath: string` — 워커 파일 경로. `file://` URL 또는 절대 경로. 확장자가 `.ts` 면 dev 모드로 `lib/worker-dev-proxy.js`(tsx 로 TS 동적 로드)를 통해 실행, `.js` 면 직접 실행.
   - `opt?: Omit<WorkerRawOptions, "stdout" | "stderr">` — worker_threads 옵션(stdout/stderr 는 내부 고정이라 제외). `env` 는 `process.env` 와 병합 전달, `argv` 는 dev 모드에서 워커 경로 뒤에 이어 붙음.
-  - 반환 `WorkerProxy<TModule>` — 아래.
 
 ```ts
-// main.ts
+// main.ts (메인 측)
+import { Worker } from "@simplysm/core-node";
 const worker = Worker.create<typeof import("./worker")>("./worker.ts");
 worker.on("progress", (p) => console.log(p));
 const result = await worker.calc(10); // 20
@@ -39,14 +40,15 @@ await worker.terminate();
 
 `Worker.create` 반환 프록시. 워커 메서드 + 예약 메서드 3종을 제공.
 
-- 메서드 프록시: `TModule["default"]["__methods"]` 의 각 메서드가 `(...args) => Promise<Awaited<R>>` 로 노출(`PromisifyMethods`). 동기 메서드도 항상 Promise(postMessage 기반).
+- 메서드 프록시: `TModule["default"]["__methods"]` 의 각 메서드가 `(...args) => Promise<Awaited<R>>` 로 노출(`PromisifyMethods`). 동기 메서드도 postMessage 기반이라 항상 Promise.
 - `on<TEventName>(event, listener): void` — 워커 `send` 이벤트 구독. `event`/`listener` 타입은 `TEvents` 에서 추론.
 - `off<TEventName>(event, listener): void` — 이벤트 구독 해제.
 - `terminate(): Promise<void>` — 워커 종료. 대기 중 호출은 "워커가 종료되었습니다" 로 reject 후 스레드 종료.
 
 ## 타입
 
-- `interface WorkerModule { default: { __methods: Record<string, (...args) => unknown>; __events: Record<string, unknown> } }` — `Worker.create` 의 제네릭 제약. `typeof import("./worker")` 가 이 구조를 만족(=`createWorker` 반환을 default export).
-- `type PromisifyMethods<TMethods>` — 각 메서드 반환을 `Promise<Awaited<R>>` 로 바꾸는 매핑 타입.
+- `interface WorkerModule { default: { __methods: Record<string, (...args: any[]) => unknown>; __events: Record<string, unknown> } }` — `Worker.create` 의 제네릭 제약. `typeof import("./worker")` 가 이 구조를 만족(=`createWorker` 반환을 default export).
+- `type PromisifyMethods<TMethods>` — 각 메서드 반환을 `Promise<Awaited<R>>` 로 바꾸는 매핑 타입. 함수가 아닌 멤버는 `never`.
 - `type WorkerProxy<TModule>` — 위 프록시 타입.
-- `interface WorkerRequest { id; method; params }` / `type WorkerResponse` — 내부 메시지 프로토콜 타입(`return`/`error`/`event`/`log`). 직접 다룰 일은 거의 없음.
+- `interface WorkerRequest { id: string; method: string; params: unknown[] }` — 내부 요청 메시지.
+- `type WorkerResponse` — 내부 응답 메시지 union: `return`(결과) / `error`(Error) / `event`(워커 send) / `log`(stdout 전달). 직접 다룰 일은 거의 없음.

package/claude/references/sd-simplysm14/apis/excel/README.md

@@ -1,43 +1,43 @@
 # @simplysm/excel
 
-OOXML(.xlsx) 워크북을 ZIP 단위 lazy-load 로 읽고 쓰는 라이브러리. 대용량 파일에서도 접근한 셀에 필요한 XML 파트(SharedStrings/Styles 등)만 그때그때 로드한다(모든 셀 메서드가 `async` 인 이유). `ExcelWorkbook` 진입점에서 시트 추가·셀 값/수식·스타일·조건부 서식·이미지·행 복사를 다루며, Zod 스키마 기반 `ExcelWrapper` 로 레코드 배열 ↔ 엑셀 변환도 지원한다.
+OOXML(.xlsx) 워크북을 ZIP 단위 lazy-load 로 읽고 쓰는 순수 TypeScript 라이브러리. 대용량 파일에서도 접근한 셀에 필요한 XML 파트(SharedStrings/Styles 등)만 그때그때 로드하므로 모든 셀 메서드가 `async` 다. `ExcelWorkbook` 진입점에서 시트 추가·셀 값/수식·스타일·조건부 서식·이미지·행 복사·뷰 설정을 다루며, Zod 스키마 기반 `ExcelWrapper` 로 레코드 배열 ↔ 엑셀 변환도 지원한다. 외부 의존은 `@simplysm/core-common`(DateOnly/DateTime/Time/Bytes), `zod`, `mime` 뿐.
 
 ## 사용 트리거 인덱스
 
-- **ExcelWorkbook / ExcelWorksheet** — .xlsx 파일을 열거나 새로 만들고 시트를 다루며 바이트/Blob 로 내보낼 때. 시트 단위 데이터 테이블·매트릭스·행 복사·이미지·뷰(zoom/freeze/탭색) 처리 포함. 자세히: [workbook-worksheet.md](./workbook-worksheet.md)
+- **ExcelWorkbook / ExcelWorksheet** — .xlsx 를 열거나 새로 만들고 시트를 추가/조회하며 바이트·Blob 로 내보낼 때. 시트 단위 데이터 테이블·매트릭스·레코드 쓰기·행 복사/삽입·이미지·뷰(zoom/freeze/탭색) 처리 포함. 자세히: [workbook-worksheet.md](./workbook-worksheet.md)
 - **ExcelCell / ExcelRow / ExcelCol** — 개별 셀의 값·수식·병합·스타일을 읽고 쓰거나 행/열 단위로 셀을 순회하고 열 너비를 줄 때. 자세히: [cell.md](./cell.md)
 - **셀 스타일 (ExcelStyleOptions / ExcelFont)** — 셀(`cell.setStyle`) 또는 워크북 default(`wb.setDefaultStyle`)의 배경·테두리·정렬·숫자형식·폰트를 지정할 때. 자세히: [style.md](./style.md)
 - **조건부 서식 (ExcelConditionalRule / ExcelConditionalRuleStyle)** — 셀/범위에 값 비교·텍스트 매칭·수식 기반 native CF 규칙을 추가할 때. 자세히: [conditional-format.md](./conditional-format.md)
 - **ExcelWrapper** — Zod 스키마로 헤더 매핑·타입 변환·유효성 검사를 자동화해 레코드 배열 ↔ 엑셀을 변환할 때. 자세히: [wrapper.md](./wrapper.md)
 - **ExcelUtils** — 셀 주소(A1 ↔ 좌표) 변환, 엑셀 날짜 시리얼 ↔ 타임스탬프 변환, 숫자형식 코드/ID/이름 상호 변환이 필요할 때. 자세히: [utils.md](./utils.md)
-- **값/주소/형식 타입** — 셀 값 유니온·숫자형식 프리셋·셀 타입·주소 좌표·정렬/테두리 enum 을 시그니처에서 참조할 때. 아래 인라인 섹션 참조.
+- **값/주소/형식 타입** — 셀 값 유니온·숫자형식 프리셋·셀 타입·주소 좌표·정렬/테두리/밑줄 enum 을 시그니처에서 참조할 때. 아래 인라인 섹션 참조.
 - **OOXML XML-shape 타입** — `ExcelXml*` / `Excel*Data` 류. 라이브러리 내부 XML 파서/직렬화기가 쓰는 OOXML 노드 구조 타입. 아래 인라인 섹션 참조.
 
 ## 값/주소/형식 타입
 
-`./types` 가 노출하는 사용자 대면 타입. 셀 값을 다루거나 메서드 시그니처를 해석할 때 참조.
+`./types` 가 노출하는 사용자 대면 값/형식 타입. 셀 값을 다루거나 메서드 시그니처를 해석할 때 참조.
 
-- `ExcelValueType` = `number | string | DateOnly | DateTime | Time | boolean | undefined` — 셀이 가질 수 있는 값 유니온. `getValue()` 반환·`setValue()` 인자 타입. `undefined` = "값 없음"(읽기 시 빈 셀, 쓰기 시 셀 삭제)이므로 결측을 끝까지 보존. `DateOnly`/`DateTime`/`Time` 은 `@simplysm/core-common` 타입.
-- `ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋 이름. `"number"` = 일반 수치, `"string"` = 텍스트 형식, 나머지는 날짜/시간 시리얼 해석/표시에 사용. `ExcelStyleOptions.numberFormat` 와 `ExcelUtils` 변환의 공용 단위.
-- `ExcelCellType` = `"s" | "b" | "str" | "n" | "inlineStr" | "e"` — OOXML 셀 `t` 속성. `"s"` = SharedString 인덱스 참조, `"b"` = boolean(`"1"`/`"0"`), `"str"` = 수식 결과 문자열, `"n"` = 숫자, `"inlineStr"` = 인라인 서식 텍스트, `"e"` = 에러(읽기 시 throw). 보통 직접 다루지 않고 `getValue`/`setValue` 가 자동 매핑.
-- `ExcelAddressPoint` = `{ r: number; c: number }` — 0 기반 행(`r`)·열(`c`) 좌표. 셀 단일 위치 단위.
-- `ExcelAddressRangePoint` = `{ s: ExcelAddressPoint; e: ExcelAddressPoint }` — 범위 좌표. `s` = 시작(좌상단), `e` = 끝(우하단). `getRange()` 반환 타입.
-- `ExcelBorderPosition` = `"left" | "right" | "top" | "bottom"` — 테두리 적용 변. `ExcelStyleOptions.border` 배열 원소.
-- `ExcelHorizontalAlign` = `"center" | "left" | "right"` — 가로 정렬 값.
-- `ExcelVerticalAlign` = `"center" | "top" | "bottom"` — 세로 정렬 값.
-- `ExcelFontUnderline` = `"single" | "double" | "singleAccounting" | "doubleAccounting"` — 밑줄 종류. OOXML `<u val="...">` 의 val 에 그대로 매핑.
+- `ExcelValueType` = `number | string | DateOnly | DateTime | Time | boolean | undefined` — 셀이 가질 수 있는 값 유니온. `getValue()` 반환·`setValue()` 인자 타입. `undefined` = "값 없음"(읽기 시 빈 셀, 쓰기 시 셀 삭제)이므로 결측을 끝까지 보존. `DateOnly`/`DateTime`/`Time` 은 `@simplysm/core-common` 타입이며 셀에 시리얼 숫자 + 날짜 numFmt 로 저장된다.
+- `ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋 이름. `"number"` = 일반 수치, `"string"` = 텍스트 형식, `"DateOnly"`/`"DateTime"`/`"Time"` = 날짜/시간 시리얼 해석·표시. `ExcelStyleOptions.numberFormat` 와 `ExcelUtils` 변환의 공용 단위. 날짜 형식 화면이면 셀 값으로 직접 `DateOnly`/`Time` 을 넣어 자동 numFmt 를 받는 편이 단순.
+- `ExcelCellType` = `"s" | "b" | "str" | "n" | "inlineStr" | "e"` — OOXML 셀 `t` 속성. `"s"` = SharedString 인덱스 참조, `"b"` = boolean(`"1"`/`"0"`), `"str"` = 수식 결과 문자열, `"n"` = 숫자, `"inlineStr"` = 인라인 서식 텍스트, `"e"` = 에러(읽기 시 throw). 보통 직접 다루지 않고 `getValue`/`setValue` 가 자동 매핑하므로, 외부 생성 파일의 셀 타입 분기를 직접 검사할 때만 참조.
+- `ExcelAddressPoint` = `{ r: number; c: number }` — 0 기반 행(`r`)·열(`c`) 좌표. 셀 단일 위치 단위. `cell(r, c)` 인덱스와 동일 0 기반.
+- `ExcelAddressRangePoint` = `{ s: ExcelAddressPoint; e: ExcelAddressPoint }` — 범위 좌표. `s` = 시작(좌상단), `e` = 끝(우하단, inclusive). `getRange()` 반환 타입이며 시트 순회 루프 경계로 쓴다.
+- `ExcelBorderPosition` = `"left" | "right" | "top" | "bottom"` — 테두리 적용 변. `ExcelStyleOptions.border` 배열 원소. 4변 전부면 4개를 배열에 모두 넣음.
+- `ExcelHorizontalAlign` = `"center" | "left" | "right"` — 가로 정렬 값. 미지정 시 셀 기본(엑셀 자동).
+- `ExcelVerticalAlign` = `"center" | "top" | "bottom"` — 세로 정렬 값. 미지정 시 셀 기본.
+- `ExcelFontUnderline` = `"single" | "double" | "singleAccounting" | "doubleAccounting"` — 밑줄 종류. OOXML `<u val="...">` 의 val 에 그대로 매핑. 회계용 밑줄이 필요할 때 `*Accounting`.
 
 ## OOXML XML-shape 타입
 
-`./types` 가 함께 export 하는 다음 인터페이스·타입은 라이브러리 내부 XML 파서/직렬화기가 OOXML 파트의 파싱 결과(`xml2js` 스타일의 `$`=속성, 자식 배열 래핑)를 표현하는 데이터 모델이다. 일반 사용 흐름(값/스타일/시트 API)에서는 직접 다루지 않으며, OOXML 노드를 직접 조작·검증할 때만 참조한다.
+`./types` 가 함께 export 하는 다음 인터페이스·타입은 라이브러리 내부 XML 파서/직렬화기가 OOXML 파트의 파싱 결과(`xml2js` 스타일의 `$`=속성, 자식은 단일 원소 배열로 래핑)를 표현하는 데이터 모델이다. 일반 사용 흐름(값/스타일/시트 API)에서는 직접 다루지 않으며, OOXML 노드를 직접 조작·검증할 때만 참조한다. 풀이는 각 타입이 표현하는 파트 1줄로 한정.
 
-- `ExcelXmlContentTypeData` — `[Content_Types].xml` 의 `Types`(Default/Override 파트 등록) 구조.
-- `ExcelXmlRelationshipData` / `ExcelRelationshipData` — `*.rels` 의 `Relationships` 및 개별 `Relationship`(Id/Target/Type) 구조.
+- `ExcelXmlContentTypeData` — `[Content_Types].xml` 의 `Types`(Default 확장자 매핑·Override 파트 등록) 구조.
+- `ExcelXmlRelationshipData` / `ExcelRelationshipData` — `*.rels` 의 `Relationships` 컨테이너 및 개별 `Relationship`(Id/Target/Type) 구조.
 - `ExcelXmlWorkbookData` — `xl/workbook.xml` 의 `workbook`(bookViews/sheets 등) 구조.
-- `ExcelXmlWorksheetData` — `xl/worksheets/sheetN.xml` 의 `worksheet`(sheetPr/dimension/sheetViews/cols/sheetData/mergeCells/conditionalFormatting/drawing 등) 구조.
-- `ExcelXmlConditionalFormattingData` / `ExcelXmlCfRuleData` — `<conditionalFormatting>` 블록과 `<cfRule>`(type/operator/priority/dxfId/formula) 구조. `ExcelXmlCfRuleData["$"]["type"|"operator"]` 는 규칙 spec 빌드 시 내부적으로 참조된다.
-- `ExcelRowData` / `ExcelCellData` — `<row r="..">` 과 `<c r=".." s=".." t="..">`(v=값, f=수식, is=인라인 문자열) 구조.
-- `ExcelXmlDrawingData` — `xl/drawings/drawingN.xml` 의 `wsDr`(twoCellAnchor/pic/blipFill/spPr 등 이미지 앵커) 구조.
-- `ExcelXmlSharedStringData` / `ExcelXmlSharedStringDataSi` / `ExcelXmlSharedStringDataText` — `xl/sharedStrings.xml` 의 `sst` 와 `si` 항목(단순 `t` 또는 서식 run `r[]`), 텍스트 노드(`space="preserve"` 보존) 구조.
+- `ExcelXmlWorksheetData` — `xl/worksheets/sheetN.xml` 의 `worksheet`(sheetPr 탭색/dimension/sheetViews 뷰·틀고정/cols 열너비/sheetData 행·셀/mergeCells/conditionalFormatting/drawing) 구조.
+- `ExcelXmlConditionalFormattingData` / `ExcelXmlCfRuleData` — `<conditionalFormatting sqref="...">` 블록과 `<cfRule>`(type/operator/priority/dxfId/text/formula) 구조. `ExcelXmlCfRuleData["$"]["type"|"operator"]` 인덱스 타입은 규칙 spec 빌드 시 내부에서 참조된다.
+- `ExcelRowData` / `ExcelCellData` — `<row r="..">` 과 `<c r=".." s="스타일ID" t="타입">`(v=값, f=수식, is=인라인 문자열) 구조.
+- `ExcelXmlDrawingData` — `xl/drawings/drawingN.xml` 의 `wsDr`(twoCellAnchor from/to 앵커, pic/blipFill/spPr 이미지 노드) 구조.
+- `ExcelXmlSharedStringData` / `ExcelXmlSharedStringDataSi` / `ExcelXmlSharedStringDataText` — `xl/sharedStrings.xml` 의 `sst` 와 `si` 항목(단순 `t` 또는 서식 run `r[]` 유니온), 텍스트 노드(`space="preserve"` 공백 보존) 구조.
 - `ExcelXmlStyleData` 및 하위(`...Font` / `...Fill` / `...Border` / `...Xf` / `...Dxf`) — `xl/styles.xml` 의 `styleSheet`(numFmts/fonts/fills/borders/cellXfs/dxfs) 와 각 자원 노드 구조.
-- `ExcelXml` = `{ readonly data: unknown; cleanup(): void }` — 모든 XML 파트 래퍼가 따르는 공통 인터페이스. `data` = 파싱된 노드 트리, `cleanup()` = 직렬화 전 마무리 정리. 외부에서 구현할 일은 거의 없다.
+- `ExcelXml` = `{ readonly data: unknown; cleanup(): void }` — 모든 XML 파트 래퍼 클래스가 따르는 공통 인터페이스. `data` = 파싱된 노드 트리, `cleanup()` = 직렬화 직전 빈 노드 정리 등 마무리. 외부에서 구현할 일은 거의 없다.

package/claude/references/sd-simplysm14/apis/excel/cell.md

@@ -1,54 +1,62 @@
 # @simplysm/excel — ExcelCell / ExcelRow / ExcelCol
 
-개별 셀의 값·수식·병합·스타일을 읽고 쓰거나, 행/열 단위로 셀을 순회할 때 함께 읽는 묶음. 모든 셀 I/O 가 `async` 인 이유는 셀 타입별로 필요한 XML 파트(SharedStrings/Styles)만 lazy-load 하기 때문이다. 인스턴스는 `ws.cell(r,c)` / `ws.row(r)` / `ws.col(c)` 로 얻으며 좌표는 모두 0 기반.
+개별 셀의 값·수식·병합·스타일을 읽고 쓰거나, 행/열 단위로 셀을 순회하고 열 너비를 줄 때 함께 읽는 묶음. 셀 객체는 `ws.cell(r,c)` / `ws.row(r)` / `ws.col(c)` 로 얻으며(모두 0 기반, 동기 반환·인스턴스 캐시), 실제 I/O 는 셀의 `async` 메서드에서 일어난다.
 
 ## ExcelCell
 
-```typescript
-readonly addr: ExcelAddressPoint   // { r, c } 0 기반
-```
+`ws.cell(r, c)` 또는 `row.cell(c)` / `col.cell(r)` 로 얻는다.
+
+- `readonly addr: ExcelAddressPoint` — 이 셀의 0 기반 좌표 `{ r, c }`. 병합·복사 인자로 재사용.
 
-### 값/수식
+값/수식:
 
-- `setValue(val: ExcelValueType): Promise<void>` — 셀 값 설정. `val` 타입별 분기: string → SharedString 으로 등록, boolean → `"1"/"0"`, number → 숫자 셀, `DateOnly`/`DateTime`/`Time` → Excel 날짜 시리얼 + 해당 numFmt 스타일 자동 적용, `undefined`/`null` → 셀 삭제. 그 외 타입은 throw.
-- `getValue(): Promise<ExcelValueType>` — 셀 값 반환. 빈 셀이면 `undefined`. 셀 타입·numFmt 를 보고 string/boolean/number/`DateOnly`/`DateTime`/`Time` 로 복원. 셀 타입이 `"e"`(에러)면 throw.
-- `setFormula(val: string | undefined): Promise<void>` — 수식 설정. `undefined` 면 셀 삭제. 설정 시 셀 타입은 `str` 로.
-- `getFormula(): Promise<string | undefined>` — 셀 수식 반환(없으면 `undefined`).
+- `getValue(): Promise<ExcelValueType>` — 셀 값을 타입 추론해 반환. SharedString→string, `b`→boolean, 숫자형 numFmt→number, 날짜/시간 numFmt→`DateOnly`/`DateTime`/`Time`, 빈 셀→`undefined`. 셀 타입이 `e`(에러)이거나 시리얼 파싱 실패면 throw. 날짜 판별은 셀 스타일의 numFmtCode/numFmtId 를 본다.
+- `setValue(val: ExcelValueType): Promise<void>` — 값 쓰기. `string`→SharedString 등록 후 `s` 타입, `boolean`→`b` 타입(`"1"`/`"0"`), `number`→숫자, `DateOnly`/`DateTime`/`Time`→시리얼 숫자 + 해당 날짜 numFmt 자동 부여, `undefined`/`null`→셀 삭제. 그 외 타입은 throw. 날짜형 화면이면 문자열 변환 없이 날짜 객체를 그대로 넘겨 자동 서식을 받는 게 단순.
+- `getFormula(): Promise<string | undefined>` — 셀 수식 문자열 반환(없으면 `undefined`).
+- `setFormula(val: string | undefined): Promise<void>` — 수식 설정. 셀 타입을 `str` 로 두고 캐시 값(v)은 비운다. `undefined` 면 셀 삭제. 수식 문자열은 `=` 없이 본문만(예: `"SUM(A1:A3)"`).
 
-### 병합
+병합:
 
-- `merge(r, c): Promise<void>` — 현재 셀을 시작점으로 끝 좌표 `(r, c)`(0 기반)까지 병합. 예: A1 에서 `merge(2, 2)` → A1:C3.
+- `merge(r: number, c: number): Promise<void>` — 현재 셀(좌상단)부터 끝 좌표 `(r, c)`(0 기반, inclusive)까지 병합. 예: `ws.cell(0,0).merge(2,2)` → A1:C3(3×3) 병합.
 
-### 스타일
+스타일:
 
-- `setStyle(opts: ExcelStyleOptions): Promise<void>` — 배경·테두리·정렬·숫자형식·폰트 적용. 기존 스타일이 있으면 clone 후 병합. 자세히: [style.md](./style.md).
-- `getStyleId(): Promise<string | undefined>` — 셀의 스타일 ID(없으면 `undefined`).
-- `setStyleId(styleId: string | undefined): Promise<void>` — 스타일 ID 를 직접 지정/해제. 이미 만들어진 스타일을 재사용할 때.
+- `getStyleId(): Promise<string | undefined>` — 셀의 styles.xml cellXfs 인덱스 ID 반환.
+- `setStyleId(styleId: string | undefined): Promise<void>` — 셀 스타일 ID 직접 지정(다른 셀과 동일 스타일 공유 시). `undefined` 면 스타일 해제.
+- `setStyle(opts: ExcelStyleOptions): Promise<void>` — 배경·테두리·정렬·숫자형식·폰트 적용. 기존 셀 스타일이 있으면 clone 후 지정 필드만 병합한다(부분 갱신). 옵션 풀이는 [style.md](./style.md).
 
-### 사용 예
+값 읽기/쓰기 예:
 
 ```typescript
-await ws.cell(0, 0).setValue("이름");
-await ws.cell(1, 0).setValue(new DateOnly(2026, 6, 1)); // 날짜 numFmt 자동
-await ws.cell(0, 0).merge(0, 2);                        // A1:C1 병합
-const v = await ws.cell(1, 0).getValue();               // DateOnly 인스턴스
+await ws.cell(0, 0).setValue("코드");
+await ws.cell(1, 0).setValue(new DateOnly(2026, 6, 3)); // 날짜 numFmt 자동
+await ws.cell(1, 1).setFormula("SUM(C2:C10)");
+const v = await ws.cell(1, 0).getValue(); // DateOnly 로 복원
 ```
 
 ## ExcelRow
 
-```typescript
-cell(c: number): ExcelCell           // 이 행의 c열 셀(0 기반)
-getCells(): Promise<ExcelCell[]>     // 데이터 범위 폭만큼 셀 배열(인덱스=열)
-```
+`ws.row(r)` 로 얻는다.
 
-- `getCells` 는 시트 데이터 범위의 시작~끝 열까지 셀을 채우며, 배열 인덱스가 열 번호와 일치(앞쪽 빈 열은 sparse).
+- `cell(c: number): ExcelCell` — 이 행의 0 기반 열 `c` 셀 반환.
+- `getCells(): Promise<ExcelCell[]>` — 이 행에서 시트 range 의 열 범위에 해당하는 셀들을 배열로 반환(인덱스 = 열 번호, 앞쪽 빈 열은 비어 있음).
 
 ## ExcelCol
 
+`ws.col(c)` 로 얻는다.
+
+- `cell(r: number): ExcelCell` — 이 열의 0 기반 행 `r` 셀 반환.
+- `getCells(): Promise<ExcelCell[]>` — 이 열에서 시트 range 의 행 범위에 해당하는 셀들을 배열로 반환(인덱스 = 행 번호).
+- `setWidth(size: number): Promise<void>` — 열 너비 설정(엑셀 문자 너비 단위). 열 1개 단위로 cols 정의를 갱신.
+
+열 너비 예:
+
 ```typescript
-cell(r: number): ExcelCell           // 이 열의 r행 셀(0 기반)
-getCells(): Promise<ExcelCell[]>     // 데이터 범위 높이만큼 셀 배열(인덱스=행)
-setWidth(size: number): Promise<void> // 열 너비 설정
+await ws.col(0).setWidth(20);
 ```
 
-- `setWidth` 의 `size` — Excel 열 너비 단위(문자 폭 기준). 컬럼 폭을 데이터에 맞게 넓힐 때.
+## 주의사항
+
+- 행/열/셀 인덱스는 모두 0 기반(엑셀 화면의 1행/A열 = 인덱스 0).
+- `getCells()` 가 반환하는 배열은 range 시작 인덱스부터 채워지므로 앞쪽 인덱스가 비어 있을 수 있다. `for..of` 보다 `range` 경계로 직접 순회하는 편이 안전.
+- `setStyle` 은 누적 병합(기존 스타일 위에 지정 필드만 덮어씀)이고, `setStyleId(undefined)` 는 스타일 전체 해제다. 둘을 혼동하지 말 것.

package/claude/references/sd-simplysm14/apis/excel/conditional-format.md

@@ -1,25 +1,33 @@
 # @simplysm/excel — 조건부 서식
 
-셀/범위에 값 비교·텍스트 매칭·수식 기반의 native CF(Excel 조건부 서식) 규칙을 추가할 때 함께 읽는 묶음. `ws.addConditionalFormat` 에 `ExcelConditionalRule[]` 을 넘기며, 각 규칙은 `ExcelConditionalRuleStyle` 강조 스타일을 가진다.
+셀/범위에 값 비교·텍스트 매칭·수식 기반의 엑셀 native 조건부 서식(CF)을 추가할 때 참조. `ws.addConditionalFormat({ ref, rules })` 한 메서드로 적용하며, 규칙은 `ExcelConditionalRule` 유니온으로 표현한다. 정적 셀 스타일과의 합성은 엑셀 native CF 오버레이에 위임된다(라이브러리가 직접 색을 칠하지 않음).
 
-## ws.addConditionalFormat
+## addConditionalFormat
 
 ```typescript
-addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>
+ws.addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>
 ```
 
-- `opts.ref: string` — 단일 셀(`"A1"`) 또는 범위(`"A1:B10"`) Excel 주소. 규칙 수식은 범위의 좌상단 셀 기준으로 생성된다.
-- `opts.rules: ExcelConditionalRule[]` — 적용할 규칙 배열. 배열 순서가 priority(앞이 우선)이며, 호출 간에는 시트 전역 카운터로 이어붙는다. 빈 배열이면 no-op.
-- 같은 시트에 여러 번 호출하면 호출마다 `<conditionalFormatting>` 블록이 누적된다. 정적 셀 스타일과의 합성은 Excel native CF 오버레이에 위임.
+- `opts.ref: string` — 적용 대상. 단일 셀(`"A1"`) 또는 범위(`"A1:B10"`) 엑셀 주소. text 류 규칙의 비교 기준 셀은 ref 의 좌상단 셀.
+- `opts.rules: ExcelConditionalRule[]` — 적용 규칙 배열. 배열 순서가 priority(앞이 우선)이며, 같은 시트에 여러 번 호출하면 호출마다 `<conditionalFormatting>` 블록이 누적되고 priority 는 시트 전역 카운터로 이어붙는다. 빈 배열이면 no-op.
 
 ## ExcelConditionalRule
 
-4개 변형의 유니온. 모든 변형이 `style: ExcelConditionalRuleStyle` 를 가진다.
+값 비교(단일):
 
-- `{ type: "cellIs"; op: "<" | ">" | "<=" | ">=" | "=" | "<>"; value: number | string; style }` — 단일 값 비교. `op` = 비교 연산자, `value` = 비교 대상(숫자는 raw formula, 문자열은 따옴표 리터럴 formula 로 emit).
-- `{ type: "cellIs"; op: "between" | "notBetween"; value: [number, number] | [string, string]; style }` — 구간 비교. `value` = `[a, b]` 튜플(양 끝 inclusive). `"between"` = 구간 안, `"notBetween"` = 구간 밖.
-- `{ type: "text"; op: "contains" | "notContains" | "beginsWith" | "endsWith"; value: string; style }` — 텍스트 매칭. `value` = 비교 문자열. `"contains"`/`"notContains"` = 포함/미포함, `"beginsWith"`/`"endsWith"` = 시작/끝 일치. SEARCH 기반 대소문자 무시 고정.
-- `{ type: "expression"; formula: string; style }` — 임의 수식 규칙. `formula` = Excel 수식 문자열(true 면 강조). 프리셋으로 표현 못하는 조건일 때.
+- `{ type: "cellIs"; op: "<" | ">" | "<=" | ">=" | "=" | "<>"; value: number | string; style }` — 셀 값과 `value` 의 단일 비교. `op` = 비교 연산자(`"<>"` = 같지 않음). `value: number` 는 raw formula(`4999`), `value: string` 은 따옴표 리터럴(`"OK"`)로 emit. 수치 임계·특정 텍스트 일치 강조에.
+
+값 비교(구간):
+
+- `{ type: "cellIs"; op: "between" | "notBetween"; value: [number, number] | [string, string]; style }` — 두 값 사이 구간 비교(양 끝 inclusive). `op` = 구간 안/밖. `value` = `[a, b]` 튜플.
+
+텍스트 매칭:
+
+- `{ type: "text"; op: "contains" | "notContains" | "beginsWith" | "endsWith"; value: string; style }` — 문자열 매칭. `op` = 포함/미포함/시작/끝. 내부적으로 SEARCH 기반(대소문자 무시) formula 로 변환되며 비교 기준은 ref 좌상단 셀. 부분 문자열·접두/접미 강조에.
+
+수식:
+
+- `{ type: "expression"; formula: string; style }` — 임의 엑셀 수식 기반. `formula` 가 TRUE 인 셀에 style 적용. `=` 없이 본문만(예 `"$B2>$C2"`). 다른 셀 참조·복합 조건 등 위 프리셋으로 안 되는 규칙에.
 
 ## ExcelConditionalRuleStyle
 
@@ -31,11 +39,11 @@ interface ExcelConditionalRuleStyle {
 }
 ```
 
-- `background?: string` — 강조 배경색. ARGB 8자리(예: `"00FFFF00"`).
-- `fontColor?: string` — 강조 글자색. ARGB 8자리.
-- `fontWeight?: "bold" | "normal"` — 글자 굵기. `"bold"` = 굵게, `"normal"` = base 가 bold 라도 강제 normal.
+- `background?: string` — 강조 배경색(ARGB 8자리, 예 `"00FFFF00"`). 미지정 시 base 셀 배경 유지.
+- `fontColor?: string` — 강조 글자색(ARGB 8자리). 미지정 시 base 글자색 유지.
+- `fontWeight?: "bold" | "normal"` — 글자 굵기. `"bold"` = 굵게, `"normal"` = base 가 bold 라도 강제 보통. 미지정 시 base 유지.
 
-미지정 필드는 base 셀 스타일을 그대로 두고, 지정 필드만 OOXML dxf 로 emit 되어 native CF 오버레이로 합성된다.
+지정한 필드만 OOXML dxf 로 emit 되어 native CF 오버레이로 합성된다(미지정 필드는 base 그대로).
 
 ## 사용 예
 
@@ -49,3 +57,9 @@ await ws.addConditionalFormat({
   ],
 });
 ```
+
+## 주의사항
+
+- `rules` 배열 순서 = priority(앞이 우선). 겹치는 조건은 앞 규칙이 이긴다.
+- 여러 번 호출하면 블록이 누적되고 priority 카운터가 시트 전역으로 이어진다 — 한 범위의 규칙은 한 번의 호출에 모아 넣는 편이 우선순위 예측에 유리.
+- `value: string` 과 `expression.formula` 의 따옴표/이스케이프는 라이브러리가 처리하므로 원문 그대로 전달.

package/claude/references/sd-simplysm14/apis/excel/style.md

@@ -1,6 +1,6 @@
 # @simplysm/excel — 셀 스타일
 
-셀(`cell.setStyle`) 또는 워크북 default(`wb.setDefaultStyle`)의 배경·테두리·정렬·숫자형식·폰트를 지정할 때 함께 읽는 묶음. 두 API 모두 `ExcelStyleOptions` 를 받으며 `font` 는 `ExcelFont` 를 공유한다.
+셀(`cell.setStyle(opts)`)이나 워크북 default(`wb.setDefaultStyle(opts)`)에 배경·테두리·정렬·숫자형식·폰트를 줄 때 참조. 두 호출 모두 동일한 `ExcelStyleOptions` 를 받는다. 미지정 필드는 emit 하지 않아 엑셀 기본값으로 표시되며, `cell.setStyle` 은 기존 셀 스타일을 clone 후 지정 필드만 병합(부분 갱신)한다.
 
 ## ExcelStyleOptions
 
@@ -16,13 +16,13 @@ interface ExcelStyleOptions {
 }
 ```
 
-- `background?: string` — 배경색. ARGB 8자리 16진수(예: `"00FF0000"` = 빨강). 셀 채우기 색이 필요할 때.
-- `border?: ExcelBorderPosition[]` — 테두리를 그릴 변 배열. 원소 = `"left" | "right" | "top" | "bottom"`. 4변 모두면 `["left","right","top","bottom"]`.
-- `horizontalAlign?: "center" | "left" | "right"` — 가로 정렬.
-- `verticalAlign?: "center" | "top" | "bottom"` — 세로 정렬.
-- `numberFormat?: "number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋. `"number"` = 일반 수치, `"string"` = 텍스트 형식, 나머지는 날짜/시간 표시 형식. 표준 형식 적용 시 사용.
-- `numberFormatCode?: string` — 커스텀 Excel formatCode(예: `"0.000000"`, `"#,##0.00"`, `"0.00%"`). `numberFormat` 과 동시 지정 시 **이 필드가 우선**. 프리셋에 없는 세밀한 형식이 필요할 때.
-- `font?: ExcelFont` — 폰트 묶음(아래). 미지정 속성은 워크북 default 폰트로 표시.
+- `background?: string` — 배경 채움색. ARGB 8자리 16진수(앞 2자리 알파, 예 `"00FF0000"` = 빨강). 셀 강조·헤더색에 사용.
+- `border?: ExcelBorderPosition[]` — 테두리를 그릴 변 배열. 원소는 `"left" | "right" | "top" | "bottom"`. 4변 전부면 4개를 모두 넣음(`["left","right","top","bottom"]`). 빈 배열·미지정은 테두리 없음.
+- `horizontalAlign?: "center" | "left" | "right"` — 가로 정렬. `"center"` = 가운데, `"left"`/`"right"` = 좌/우. 미지정 시 셀 기본(엑셀 자동).
+- `verticalAlign?: "center" | "top" | "bottom"` — 세로 정렬. `"center"` = 가운데, `"top"`/`"bottom"` = 위/아래. 행 높이가 큰 셀에서 의미.
+- `numberFormat?: "number" | "string" | "DateOnly" | "DateTime" | "Time"` — 숫자형식 프리셋. `"number"` = 일반 수치(numFmtId 0), `"string"` = 텍스트(49), `"DateOnly"`(14)/`"DateTime"`(22)/`"Time"`(18) = 날짜/시간 표시. 표준 형식이면 이걸로 충분.
+- `numberFormatCode?: string` — 커스텀 엑셀 formatCode(예 `"0.000000"`, `"#,##0.00"`, `"0.00%"`). `numberFormat` 과 동시 지정 시 이 필드가 우선. 천단위·소수 자릿수·퍼센트 등 세밀한 표시가 필요할 때.
+- `font?: ExcelFont` — 폰트 묶음(아래). 일부 속성만 줘도 되며, 미지정 속성은 워크북 default 폰트로 표시.
 
 ## ExcelFont
 
@@ -39,29 +39,35 @@ interface ExcelFont {
 ```
 
 - `size?: number` — 폰트 크기(pt).
-- `family?: string` — 폰트명(예: `"맑은 고딕"`, `"Calibri"`).
-- `bold?: boolean` — 굵게. `true` 면 굵게.
-- `italic?: boolean` — 기울임. `true` 면 이탤릭.
-- `underline?: "single" | "double" | "singleAccounting" | "doubleAccounting"` — 밑줄 종류. OOXML `<u val="...">` val 에 그대로 매핑.
-- `color?: string` — 글자색. ARGB 8자리(예: `"00FF0000"`).
-- `strike?: boolean` — 취소선. `true` 면 가운데줄.
+- `family?: string` — 폰트명(예 `"맑은 고딕"`, `"Calibri"`). 한글 문서면 보통 `"맑은 고딕"`.
+- `bold?: boolean` — 굵게. `true` = 볼드, 미지정/`false` = 보통.
+- `italic?: boolean` — 기울임. `true` = 이탤릭.
+- `underline?: "single" | "double" | "singleAccounting" | "doubleAccounting"` — 밑줄 종류. `<u val="...">` 의 val 로 그대로 emit. 회계용이면 `*Accounting`.
+- `color?: string` — 글자색. ARGB 8자리(예 `"00FF0000"`).
+- `strike?: boolean` — 취소선. `true` = 취소선 표시.
 
-미지정 폰트 속성은 OOXML `<font>` 자식으로 emit 되지 않고 Excel 기본값으로 표시된다.
-
-## cell.setStyle vs wb.setDefaultStyle
-
-- `cell.setStyle(opts)` — 해당 셀에만 스타일 적용. 기존 셀 스타일이 있으면 clone 후 옵션을 병합.
-- `wb.setDefaultStyle(opts)` — `xl/styles.xml` 의 `fonts[0]`/`fills[0]`/`borders[0]`(OOXML default 슬롯) 자체를 덮어써, fontId/fillId/borderId 를 명시하지 않은 모든 셀에 전역 적용. `horizontalAlign`/`verticalAlign`/`numberFormat`/`numberFormatCode` 는 0번 슬롯 개념이 없어 `cellXfs[0]` 에 박힌다. 옵션이 없는 자원은 0번 슬롯이 빈 슬롯으로 reset 되며, 미호출 시 원본이 보존된다.
-
-### 사용 예
+## 사용 예
 
 ```typescript
-await wb.setDefaultStyle({ font: { family: "맑은 고딕", size: 10 }, horizontalAlign: "center" });
-
+// 셀 단위
 await ws.cell(0, 0).setStyle({
-  background: "00FFFF00",
+  background: "00FFFF00",          // 노랑 헤더
   border: ["left", "right", "top", "bottom"],
-  font: { bold: true, color: "00FF0000" },
-  numberFormatCode: "#,##0",
+  horizontalAlign: "center",
+  verticalAlign: "center",
+  font: { family: "맑은 고딕", bold: true },
 });
+
+// 커스텀 숫자 형식
+await ws.cell(1, 2).setStyle({ numberFormatCode: "#,##0.00" });
+
+// 워크북 전역 default
+await wb.setDefaultStyle({ font: { family: "맑은 고딕", size: 10 } });
 ```
+
+## 주의사항
+
+- `setDefaultStyle` 은 styles.xml 의 0번 자원 슬롯(font/fill/border)을 덮어쓴다 — fontId/fillId/borderId 를 명시하지 않은 모든 셀이 영향을 받는다. 옵션에 없는 자원은 0번 슬롯이 빈 슬롯으로 reset 되므로, default 로 줄 항목은 한 번에 모아 호출.
+- `numberFormat` 과 `numberFormatCode` 동시 지정 시 `numberFormatCode` 우선.
+- 색상은 모두 ARGB 8자리(알파 포함). RGB 6자리만 주면 의도와 다르게 해석될 수 있다.
+- 날짜/시간 셀은 값으로 `DateOnly`/`DateTime`/`Time` 을 넣으면 numFmt 가 자동 부여되므로 보통 `numberFormat` 을 따로 줄 필요가 없다.

package/claude/references/sd-simplysm14/apis/excel/utils.md

@@ -1,35 +1,45 @@
 # @simplysm/excel — ExcelUtils
 
-셀 주소(A1 표기) ↔ 좌표 변환, Excel 날짜 시리얼 ↔ 타임스탬프 변환, 숫자형식 코드/ID/이름 상호 변환이 필요할 때 읽는다. 모든 메서드는 `static` 이라 인스턴스 없이 `ExcelUtils.xxx()` 로 호출.
+셀 주소(A1 ↔ 좌표) 변환, 엑셀 날짜 시리얼 ↔ JS 타임스탬프 변환, 숫자형식 코드/ID/이름 상호 변환이 필요할 때 쓰는 static 유틸 클래스. 모든 메서드가 정적이므로 인스턴스 생성 없이 `ExcelUtils.xxx(...)` 로 호출. 일반 셀 API 가 내부적으로 쓰지만, 외부에서 주소 문자열 ↔ 좌표를 직접 다룰 때 유용하다.
 
 ## 주소 변환
 
-- `stringifyAddr(point: ExcelAddressPoint): string` — 0 기반 좌표 `{r,c}` → `"A1"`. 로그·범위 ref 조립에 사용.
-- `stringifyRowAddr(r: number): string` — 행 인덱스 → 행 문자열(0 → `"1"`).
-- `stringifyColAddr(c: number): string` — 열 인덱스 → 열 문자(0 → `"A"`, 26 → `"AA"`). 0~16383 범위 밖이면 throw.
-- `parseRowAddr(addr: string): number` — 주소 문자열에서 0 기반 행 인덱스(`"A3"` → 2). 파싱 실패 시 throw.
-- `parseColAddr(addr: string): number` — 주소 문자열에서 0 기반 열 인덱스(`"B3"` → 1).
-- `parseCellAddr(addr: string): ExcelAddressPoint` — 셀 주소 → 좌표(`"B3"` → `{r:2,c:1}`).
-- `parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint` — 범위 주소 → 좌표 범위(`"A1:C3"` → `{s:{r:0,c:0}, e:{r:2,c:2}}`). `:` 없으면 단일 셀을 `s===e` 로.
-- `stringifyRangeAddr(point: ExcelAddressRangePoint): string` — 좌표 범위 → 문자열(`"A1:C3"`). `s===e` 면 단일 셀 문자열만 반환.
+좌표는 `ExcelAddressPoint`(`{ r, c }`, 0 기반), 범위는 `ExcelAddressRangePoint`(`{ s, e }`).
 
-## 날짜 변환
+- `stringifyAddr(point: ExcelAddressPoint): string` — 좌표를 `"A1"` 형식 문자열로. 예 `{r:0,c:0}` → `"A1"`.
+- `stringifyRowAddr(r: number): string` — 0 기반 행 인덱스를 행 주소 문자열로(예 `0` → `"1"`).
+- `stringifyColAddr(c: number): string` — 0 기반 열 인덱스를 열 문자로(예 `0` → `"A"`, `26` → `"AA"`). 범위 0~16383 밖이면 throw.
+- `parseRowAddr(addr: string): number` — 셀 주소에서 0 기반 행 인덱스 추출(예 `"A3"` → `2`). 행 숫자 파싱 실패 시 throw.
+- `parseColAddr(addr: string): number` — 셀 주소에서 0 기반 열 인덱스 추출(예 `"B3"` → `1`).
+- `parseCellAddr(addr: string): ExcelAddressPoint` — 주소를 좌표로(예 `"B3"` → `{r:2,c:1}`).
+- `parseRangeAddr(rangeAddr: string): ExcelAddressRangePoint` — 범위 주소를 좌표로(예 `"A1:C3"` → `{s:{r:0,c:0}, e:{r:2,c:2}}`). `:` 없는 단일 주소면 `s`=`e`.
+- `stringifyRangeAddr(point: ExcelAddressRangePoint): string` — 범위 좌표를 문자열로. `s`=`e` 면 단일 주소 1개만 반환.
 
-Excel 은 1900-01-01 을 1 로 계산(1899-12-30 이 날짜 0). 변환 시 로컬 타임존을 보정한다.
+## 날짜 시리얼 변환
 
-- `convertTimeTickToNumber(tick: number): number` — JS 타임스탬프(ms) → Excel 날짜 시리얼 숫자.
-- `convertNumberToTimeTick(value: number): number` — Excel 날짜 시리얼 숫자 → JS 타임스탬프(ms).
+엑셀은 1900-01-01 을 1 로 세는 시리얼 날짜 체계(1899-12-30 = 0)를 쓴다. 로컬 타임존 보정을 포함한다.
+
+- `convertTimeTickToNumber(tick: number): number` — JS 타임스탬프(ms)를 엑셀 날짜 시리얼 숫자로. 셀에 날짜를 쓸 때 내부적으로 사용.
+- `convertNumberToTimeTick(value: number): number` — 엑셀 날짜 시리얼 숫자를 JS 타임스탬프(ms)로. 셀에서 날짜를 읽을 때 사용.
 
 ## 숫자형식 변환
 
-- `convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat` — formatCode 문자열을 분석해 `"number"`/`"DateOnly"`/`"DateTime"`/`"Time"`/`"string"` 판별. `"General"` 은 `"number"`. 시간 문맥의 `mm`(분)은 날짜 판별에서 제외. 어디에도 해당 안 되면 throw.
-- `convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat` — Excel 내장 numFmtId 를 형식명으로. 범위: 0~13·37~40·48 → `"number"`, 14~17·27~31·34~36·50~58 → `"DateOnly"`, 22 → `"DateTime"`, 18~21·32~33·45~47 → `"Time"`, 49 → `"string"`. 범위 밖이면 throw.
-- `convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number` — 역방향. `"number"` → 0, `"DateOnly"` → 14, `"DateTime"` → 22, `"Time"` → 18, `"string"` → 49.
+`ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` 와 엑셀 formatCode/numFmtId 사이 변환.
+
+- `convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat` — formatCode 문자열을 형식 이름으로. `"General"`→`"number"`, yy/dd/mm·h/ss 패턴 조합으로 `"DateOnly"`/`"DateTime"`/`"Time"` 판별(시간 문맥의 `mm` 은 분으로 제외), 숫자 패턴이면 `"number"`. 미해석 코드면 throw.
+- `convertNumFmtIdToName(numFmtId: number): ExcelNumberFormat` — 엑셀 내장 형식 ID 를 이름으로. 0~13·37~40·48→`"number"`, 14~17·27~31·34~36·50~58→`"DateOnly"`, 22→`"DateTime"`, 18~21·32~33·45~47→`"Time"`, 49→`"string"`. 그 외 ID 면 throw.
+- `convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number` — 이름을 내장 형식 ID 로. `"number"`→0, `"DateOnly"`→14, `"DateTime"`→22, `"Time"`→18, `"string"`→49.
 
 ## 사용 예
 
 ```typescript
-const { r, c } = ExcelUtils.parseCellAddr("C5");                       // { r: 4, c: 2 }
-const ref = ExcelUtils.stringifyRangeAddr({ s: { r: 0, c: 0 }, e: { r: 9, c: 1 } }); // "A1:B10"
-const serial = ExcelUtils.convertTimeTickToNumber(Date.now());        // Excel 날짜 숫자
+ExcelUtils.parseRangeAddr("A1:C3"); // { s:{r:0,c:0}, e:{r:2,c:2} }
+ExcelUtils.stringifyAddr({ r: 1, c: 2 }); // "C2"
+ExcelUtils.convertNumFmtIdToName(22); // "DateTime"
 ```
+
+## 주의사항
+
+- 행/열 인덱스는 0 기반(엑셀 표기 A1 = `{r:0,c:0}`). 엑셀 화면 숫자와 1 차이.
+- `stringifyColAddr` 의 유효 열 범위는 0~16383(엑셀 최대 16384열, XFD). 벗어나면 throw.
+- 날짜 변환은 시리얼 1 = 1900-01-01 기준이며 타임존 보정이 들어가므로, 직접 산술하지 말고 이 메서드로 왕복.