@simplysm/sd-claude 14.0.98 → 14.0.99

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

@@ -1,62 +1,62 @@
 # @simplysm/excel — ExcelCell / ExcelRow / ExcelCol
 
-개별 셀의 값·수식·병합·스타일을 읽고 쓰거나, 행/열 단위로 셀을 순회하고 열 너비를 줄 때 함께 읽는 묶음. 셀 객체는 `ws.cell(r,c)` / `ws.row(r)` / `ws.col(c)` 로 얻으며(모두 0 기반, 동기 반환·인스턴스 캐시), 실제 I/O 는 셀의 `async` 메서드에서 일어난다.
+개별 셀의 값·수식·병합·스타일을 읽고 쓰거나, 행/열 단위로 셀을 순회하고 열 너비를 줄 때 함께 읽는 묶음. 핸들은 `ws.cell(r,c)` / `ws.row(r)` / `ws.col(c)` 로 얻으며(모두 0 기반, 동기 반환·인스턴스 캐시), 실제 I/O 는 셀의 `async` 메서드에서 일어난다.
 
 ## ExcelCell
 
-`ws.cell(r, c)` 또는 `row.cell(c)` / `col.cell(r)` 로 얻는다.
+`ws.cell(r, c)` 가 반환. 셀 타입에 필요한 XML(SharedStrings/Styles)만 그때그때 로드하므로 모든 메서드가 `async`.
 
-- `readonly addr: ExcelAddressPoint` — 이 셀의 0 기반 좌표 `{ r, c }`. 병합·복사 인자로 재사용.
+- `readonly addr: ExcelAddressPoint` — 셀 0 기반 `{r,c}` 좌표.
 
-값/수식:
+### 값·수식
 
-- `getValue(): Promise<ExcelValueType>` — 셀 값을 타입 추론해 반환. SharedString(`s`)→string, `str`/`inlineStr`→string, `b`→boolean, 빈 셀→`undefined`. 타입 코드가 없는 셀은 스타일 numFmt 로 분기: 숫자형→number, 텍스트형(`string`)→string, 날짜/시간형→`DateOnly`/`DateTime`/`Time`. 셀 타입이 `e`(에러)이거나 시리얼/ID 파싱 실패면 throw.
-- `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)"`).
+- `getValue(): Promise<ExcelValueType>` — 셀 값 반환. 셀 타입·numFmt 를 보고 `string`/`boolean`/`number`/`DateOnly`/`DateTime`/`Time` 로 자동 변환. 빈 셀은 `undefined`. 에러 셀(`t="e"`)은 throw.
+- `setValue(val: ExcelValueType): Promise<void>` — 셀 값 설정. `string` → SharedString, `boolean` → `b`, `number` → 숫자, `DateOnly`/`DateTime`/`Time` → 시리얼 숫자 + 날짜 numFmt 자동 부여. `undefined` → 셀 삭제. 그 외 타입은 throw.
+- `getFormula(): Promise<string | undefined>` — 셀 수식 문자열 반환.
+- `setFormula(val: string | undefined): Promise<void>` — 셀 수식 설정. `undefined` 면 셀 삭제(수식 제거).
 
-병합:
+### 병합
 
-- `merge(r: number, c: number): Promise<void>` — 현재 셀(좌상단)부터 끝 좌표 `(r, c)`(0 기반, inclusive)까지 병합. 예: `ws.cell(0,0).merge(2,2)` → A1:C3(3×3) 병합.
+- `merge(r: number, c: number): Promise<void>` — 현재 셀을 좌상단으로 끝 좌표 `(r,c)`(0 기반, inclusive)까지 병합.
 
-스타일:
+### 스타일
 
-- `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).
+- `getStyleId(): Promise<string | undefined>` — 셀 스타일 ID 반환.
+- `setStyleId(styleId: string | undefined): Promise<void>` — 셀 스타일 ID 직접 설정(다른 셀에서 얻은 ID 재사용 등).
+- `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, 3)); // 날짜 numFmt 자동
-await ws.cell(1, 1).setFormula("SUM(C2:C10)");
-const v = await ws.cell(1, 0).getValue(); // DateOnly 로 복원
+await ws.cell(0, 0).setValue("이름");
+await ws.cell(1, 0).setValue(new DateOnly(2024, 6, 15)); // 날짜 numFmt 자동
+await ws.cell(0, 0).merge(0, 2); // A1:C1 병합
 ```
 
 ## ExcelRow
 
-`ws.row(r)` 로 얻는다.
+`ws.row(r)` 가 반환. 한 행의 셀 접근.
 
-- `cell(c: number): ExcelCell` — 이 행의 0 기반 열 `c` 셀 반환.
-- `getCells(): Promise<ExcelCell[]>` — 이 행에서 시트 range 의 열 범위에 해당하는 셀들을 배열로 반환(인덱스 = 열 번호, range 시작 전 앞쪽 인덱스는 비어 있음).
+- `cell(c: number): ExcelCell` — 이 행의 0 기반 열 셀.
+- `getCells(): Promise<ExcelCell[]>` — 시트 데이터 범위 열 폭만큼 셀 배열(열 인덱스 위치에 채움).
 
 ## ExcelCol
 
-`ws.col(c)` 로 얻는다.
+`ws.col(c)` 가 반환. 한 열의 셀 접근 및 너비.
 
-- `cell(r: number): ExcelCell` — 이 열의 0 기반 행 `r` 셀 반환.
-- `getCells(): Promise<ExcelCell[]>` — 이 열에서 시트 range 의 행 범위에 해당하는 셀들을 배열로 반환(인덱스 = 행 번호).
-- `setWidth(size: number): Promise<void>` — 열 너비 설정(엑셀 문자 너비 단위). 열 1개 단위로 cols 정의를 갱신.
-
-열 너비 예:
+- `cell(r: number): ExcelCell` — 이 열의 0 기반 행 셀.
+- `getCells(): Promise<ExcelCell[]>` — 시트 데이터 범위 행 높이만큼 셀 배열.
+- `setWidth(size: number): Promise<void>` — 열 너비 설정.
 
 ```typescript
-await ws.col(0).setWidth(20);
+await ws.col(2).setWidth(20);
+for (const cell of await ws.row(0).getCells()) {
+  // 헤더 셀 순회
+}
 ```
 
 ## 주의사항
 
-- 행/열/셀 인덱스는 모두 0 기반(엑셀 화면의 1행/A열 = 인덱스 0).
-- `getCells()` 가 반환하는 배열은 range 시작 인덱스부터 채워지므로 앞쪽 인덱스가 비어 있을 수 있다. `for..of` 보다 `range` 경계로 직접 순회하는 편이 안전.
-- `setStyle` 은 누적 병합(기존 스타일 위에 지정 필드만 덮어씀)이고, `setStyleId(undefined)` 는 스타일 전체 해제다. 둘을 혼동하지 말 것.
+- 좌표·인덱스는 모두 0 기반. `cell(0,0)` = A1.
+- `getValue` 의 결측은 `undefined` 로 보존된다(빈 셀과 "값 없음" 을 같은 것으로 다룸).
+- 날짜 값은 `setValue` 에 `DateOnly`/`DateTime`/`Time` 인스턴스를 직접 넣으면 numFmt 가 자동 부여되므로, 별도 `setStyle({ numberFormat })` 가 보통 불필요하다.

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

@@ -8,28 +8,27 @@
 ws.addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>
 ```
 
-- `opts.ref: string` — 적용 대상. 단일 셀(`"A1"`) 또는 범위(`"A1:B10"`) 엑셀 주소. text 류 규칙의 비교 기준 셀은 ref 의 좌상단 셀.
-- `opts.rules: ExcelConditionalRule[]` — 적용 규칙 배열. 배열 순서가 priority(앞이 우선)이며, 같은 시트에 여러 번 호출하면 호출마다 `<conditionalFormatting>` 블록이 누적되고 priority 는 시트 전역 카운터로 이어붙는다. 빈 배열이면 no-op.
+- `ref` — 단일 셀(`"A1"`) 또는 범위(`"A1:B10"`) 엑셀 주소. text/expression 규칙의 수식은 범위 좌상단(`ref` 의 `:` 앞 토큰)을 기준 셀로 삼는다.
+- `rules` — 적용할 규칙 배열. 배열 순서가 priority(앞이 우선)이며, 같은 시트에 여러 번 호출하면 priority 가 시트 전역 카운터로 이어붙는다(1,2,3,…). 빈 배열이면 no-op.
 
-## ExcelConditionalRule
-
-값 비교(단일):
-
-- `{ 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` = `"between"`(구간 안)/`"notBetween"`(구간 밖). `value` = `[a, b]` 튜플.
+같은 시트에 여러 번 호출하면 호출마다 `<conditionalFormatting>` 블록이 누적되고, 동일 `style` 의 규칙은 dxf 가 dedupe 되어 1개로 등록된다.
 
-텍스트 매칭:
-
-- `{ type: "text"; op: "contains" | "notContains" | "beginsWith" | "endsWith"; value: string; style }` — 문자열 매칭. `op` = `"contains"`(포함)/`"notContains"`(미포함)/`"beginsWith"`(시작)/`"endsWith"`(끝). 내부적으로 SEARCH 기반(대소문자 무시) formula 로 변환되며 비교 기준은 ref 좌상단 셀. 부분 문자열·접두/접미 강조에.
+## ExcelConditionalRule
 
-수식:
+네 가지 변형의 유니온.
 
-- `{ type: "expression"; formula: string; style }` — 임의 엑셀 수식 기반. `formula` 가 TRUE 인 셀에 style 적용. `=` 없이 본문만(예 `"$B2>$C2"`). 다른 셀 참조·복합 조건 등 위 프리셋으로 안 되는 규칙에.
+```typescript
+type ExcelConditionalRule =
+  | { type: "cellIs"; op: "<" | ">" | "<=" | ">=" | "=" | "<>"; value: number | string; style: ExcelConditionalRuleStyle }
+  | { type: "cellIs"; op: "between" | "notBetween"; value: [number, number] | [string, string]; style: ExcelConditionalRuleStyle }
+  | { type: "text"; op: "contains" | "notContains" | "beginsWith" | "endsWith"; value: string; style: ExcelConditionalRuleStyle }
+  | { type: "expression"; formula: string; style: ExcelConditionalRuleStyle };
+```
 
-각 규칙의 `style` 은 아래 `ExcelConditionalRuleStyle`.
+- `type: "cellIs"` 단일 비교 — `op` 가 `<`/`>`/`<=`/`>=`/`=`/`<>`. `value` 는 `number`(raw formula `<formula>4999</formula>`) 또는 `string`(따옴표 리터럴 `<formula>"OK"</formula>`). OOXML operator(`lessThan`/`greaterThan`/`lessThanOrEqual`/`greaterThanOrEqual`/`equal`/`notEqual`)로 매핑.
+- `type: "cellIs"` 구간 — `op` 가 `between`/`notBetween`. `value` 는 `[a, b]` 튜플(양 끝 inclusive), number 튜플은 `["1000","2000"]`, string 튜플은 `['"A"','"M"']` 두 formula 로 emit.
+- `type: "text"` 텍스트 매칭 — `op` 가 `contains`/`notContains`/`beginsWith`/`endsWith`. `value` 는 string. `contains` 는 `NOT(ISERROR(SEARCH(...)))`, `notContains` 는 `ISERROR(SEARCH(...))`, `beginsWith` 는 `LEFT(...)=v`, `endsWith` 는 `RIGHT(...)=v` 수식으로 emit(SEARCH 기반, 대소문자 무시 고정). 따옴표는 OOXML escape 규칙대로 두 배(`a"b` → `a""b`).
+- `type: "expression"` — 임의 수식. `formula` 문자열을 raw 그대로 1개 formula 로 emit(operator 미부여). `AND($F2<>"",$F2-TODAY()<=7)` 같은 복합 조건에 사용.
 
 ## ExcelConditionalRuleStyle
 
@@ -41,11 +40,11 @@ interface ExcelConditionalRuleStyle {
 }
 ```
 
-- `background?: string` — 강조 배경색(ARGB 8자리, 예 `"00FFFF00"`). 미지정 시 base 셀 배경 유지.
-- `fontColor?: string` — 강조 글자색(ARGB 8자리). 미지정 시 base 글자색 유지.
-- `fontWeight?: "bold" | "normal"` — 글자 굵기. `"bold"` = 굵게, `"normal"` = base 가 bold 라도 강제 보통. 미지정 시 base 유지.
+- `background` — 강조 배경색(ARGB 8자리, 예 `"00FFFF00"`).
+- `fontColor` — 강조 글자색(ARGB 8자리).
+- `fontWeight` — `"bold"` = 굵게, `"normal"` = base 가 bold 라도 강제 normal.
 
-지정한 필드만 OOXML dxf 로 emit 되어 native CF 오버레이로 합성된다(미지정 필드는 base 그대로).
+미지정 필드는 base 셀 스타일을 그대로 두고, 지정 필드만 OOXML dxf 로 emit 되어 native CF 오버레이로 합성된다.
 
 ## 사용 예
 
@@ -62,6 +61,6 @@ await ws.addConditionalFormat({
 
 ## 주의사항
 
-- `rules` 배열 순서 = priority(앞이 우선). 겹치는 조건은 앞 규칙이 이긴다.
-- 여러 번 호출하면 블록이 누적되고 priority 카운터가 시트 전역으로 이어진다 — 한 범위의 규칙은 한 번의 호출에 모아 넣는 편이 우선순위 예측에 유리.
-- `value: string` 과 `expression.formula` 의 따옴표/이스케이프는 라이브러리가 처리하므로 원문 그대로 전달.
+- 규칙 배열 순서 = priority. 앞 규칙이 먼저 평가된다.
+- `value` 의 number/string 구분이 formula emit 방식을 바꾼다 — 비교 대상이 텍스트면 반드시 `string` 으로 줄 것.
+- toBytes → 재오픈 roundtrip 에서 type/operator/text/formula/dxf 가 보존된다.

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

@@ -1,6 +1,6 @@
 # @simplysm/excel — 셀 스타일
 
-셀(`cell.setStyle(opts)`)이나 워크북 default(`wb.setDefaultStyle(opts)`)에 배경·테두리·정렬·숫자형식·폰트를 줄 때 참조. 두 호출 모두 동일한 `ExcelStyleOptions` 를 받는다. 미지정 필드는 emit 하지 않아 엑셀 기본값으로 표시되며, `cell.setStyle` 은 기존 셀 스타일을 clone 후 지정 필드만 병합(부분 갱신)한다.
+셀(`cell.setStyle(opts)`)이나 워크북 default(`wb.setDefaultStyle(opts)`)에 배경·테두리·정렬·숫자형식·폰트를 줄 때 참조. 두 호출 모두 동일한 `ExcelStyleOptions` 를 받는다. 미지정 필드는 OOXML 자식 엘리먼트로 emit 하지 않아 엑셀 기본값으로 표시되며, `cell.setStyle` 은 기존 셀 스타일을 clone 후 지정 필드만 병합(부분 갱신)한다.
 
 ## ExcelStyleOptions
 
@@ -16,13 +16,13 @@ interface ExcelStyleOptions {
 }
 ```
 
-- `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 폰트로 표시.
+- `background` — 배경색(ARGB 8자리 16진수, 예 `"00FF0000"` = 빨강). solid fill 로 채운다.
+- `border: ExcelBorderPosition[]` — 테두리를 그릴 변(`"left"|"right"|"top"|"bottom"`)의 배열. 4변 전부면 4개를 모두 넣는다.
+- `horizontalAlign` — 가로 정렬(`"center"|"left"|"right"`). 미지정 시 엑셀 기본.
+- `verticalAlign` — 세로 정렬(`"center"|"top"|"bottom"`). 미지정 시 엑셀 기본.
+- `numberFormat: ExcelNumberFormat` — 숫자형식 프리셋(`"number"|"string"|"DateOnly"|"DateTime"|"Time"`). 내장 numFmtId(0/49/14/22/18)로 매핑된다.
+- `numberFormatCode` — 임의 Excel formatCode 문자열(예 `"0.000000"`, `"#,##0.00"`, `"0.00%"`). `numberFormat` 과 동시 지정 시 이 필드가 우선 적용된다.
+- `font: ExcelFont` — 폰트 속성(아래). 미지정 폰트 속성은 워크북 default 폰트로 표시된다.
 
 ## ExcelFont
 
@@ -38,36 +38,30 @@ interface ExcelFont {
 }
 ```
 
-- `size?: number` — 폰트 크기(pt).
-- `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` = 취소선 표시.
+- `size` — 폰트 크기(pt).
+- `family` — 폰트명(예 `"맑은 고딕"`, `"Calibri"`).
+- `bold` — 굵게.
+- `italic` — 기울임.
+- `underline: ExcelFontUnderline` — 밑줄 종류(`"single"|"double"|"singleAccounting"|"doubleAccounting"`). `<u val="...">` 의 val 에 그대로 매핑.
+- `color` — 글자색(ARGB 8자리, 예 `"00FF0000"`).
+- `strike` — 취소선.
+
+`ExcelFont` 은 셀 단위 override(`ExcelStyleOptions.font`)와 워크북 default(`wb.setDefaultStyle({ font })`) 양쪽이 공유한다. 미지정 속성은 `<font>` 자식 엘리먼트로 emit 되지 않으며 엑셀 자체 기본값으로 표시된다.
 
 ## 사용 예
 
 ```typescript
-// 셀 단위
-await ws.cell(0, 0).setStyle({
-  background: "00FFFF00",          // 노랑 헤더
+await cell.setStyle({
+  background: "00FFFF00",
   border: ["left", "right", "top", "bottom"],
   horizontalAlign: "center",
-  verticalAlign: "center",
-  font: { family: "맑은 고딕", bold: true },
+  numberFormatCode: "#,##0",
+  font: { family: "맑은 고딕", size: 10, 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 로 줄 항목은 한 번에 모아 호출. horizontalAlign/verticalAlign/numberFormat/numberFormatCode 는 `cellXfs[0].xf[0]` 에 직접 박힌다.
-- `numberFormat` 과 `numberFormatCode` 동시 지정 시 `numberFormatCode` 우선.
-- 색상은 모두 ARGB 8자리(알파 포함). RGB 6자리만 주면 의도와 다르게 해석될 수 있다.
-- 날짜/시간 셀은 값으로 `DateOnly`/`DateTime`/`Time` 을 넣으면 numFmt 가 자동 부여되므로 보통 `numberFormat` 을 따로 줄 필요가 없다.
+- `cell.setStyle` 은 부분 갱신(clone + merge)이므로, 같은 셀에 두 번 호출하면 두 호출의 지정 필드가 누적된다.
+- `wb.setDefaultStyle` 은 0번 자원 슬롯 자체를 덮어쓰는 전역 설정이라 동작이 다르다 — `font`/`background`/`border` 미지정 슬롯은 빈 슬롯으로 reset 되고, `horizontalAlign`/`verticalAlign`/`numberFormat`/`numberFormatCode` 는 `cellXfs[0]` 에 박힌다(상세는 [workbook-worksheet.md](./workbook-worksheet.md)).
+- 색상은 모두 ARGB 8자리(앞 2자리 알파). 6자리 RGB 가 아님.

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

@@ -4,42 +4,39 @@
 
 ## 주소 변환
 
-좌표는 `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개만 반환.
+- `stringifyAddr(point: ExcelAddressPoint): string` — 좌표 `{r,c}`(0 기반)를 `"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`.
+- `parseColAddr(addr: string): number` — 주소에서 열 인덱스 추출. 예 `"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` 면 단일 주소로 축약.
 
 ## 날짜 시리얼 변환
 
-엑셀은 1900-01-01 을 1 로 세는 시리얼 날짜 체계(1899-12-30 = 0)를 쓴다. 로컬 타임존 보정을 포함한다.
+엑셀은 1899-12-30 을 날짜 0(1900-01-01 = 1)으로 계산한다. 로컬 타임존 보정을 포함한다.
 
-- `convertTimeTickToNumber(tick: number): number` — JS 타임스탬프(ms)를 엑셀 날짜 시리얼 숫자로. 셀에 날짜를 쓸 때 내부적으로 사용.
-- `convertNumberToTimeTick(value: number): number` — 엑셀 날짜 시리얼 숫자를 JS 타임스탬프(ms)로. 셀에서 날짜를 읽을 때 사용.
+- `convertTimeTickToNumber(tick: number): number` — JS 타임스탬프(ms)를 엑셀 날짜 시리얼 숫자로.
+- `convertNumberToTimeTick(value: number): number` — 엑셀 날짜 시리얼 숫자를 JS 타임스탬프(ms)로.
 
 ## 숫자형식 변환
 
-`ExcelNumberFormat` = `"number" | "string" | "DateOnly" | "DateTime" | "Time"` 와 엑셀 formatCode/numFmtId 사이 변환.
+`ExcelNumberFormat`(`"number"|"string"|"DateOnly"|"DateTime"|"Time"`) 과 엑셀 numFmtId/formatCode 사이 변환.
 
-- `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.
+- `convertNumFmtCodeToName(numFmtCode: string): ExcelNumberFormat` — formatCode 문자열을 프리셋 이름으로. `"General"` → `"number"`, `yy`/`dd`/`mm`(시간 문맥 제외) 포함 → 날짜, `h`/`hh`/`ss` 포함 → 시간, 날짜+시간 동시 → `"DateTime"`. 순수 숫자 패턴은 `"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"`. 그 외 throw.
+- `convertNumFmtNameToId(numFmtName: ExcelNumberFormat): number` — 이름을 ID 로. `"number"`→0, `"DateOnly"`→14, `"DateTime"`→22, `"Time"`→18, `"string"`→49.
 
 ## 사용 예
 
 ```typescript
-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"
+const { s, e } = ExcelUtils.parseRangeAddr("A1:C3"); // {s:{r:0,c:0}, e:{r:2,c:2}}
+const addr = ExcelUtils.stringifyAddr({ r: 0, c: 27 }); // "AB1"
 ```
 
 ## 주의사항
 
-- 행/열 인덱스는 0 기반(엑셀 표기 A1 = `{r:0,c:0}`). 엑셀 화면 숫자와 1 차이.
-- `stringifyColAddr` 의 유효 열 범위는 0~16383(엑셀 최대 16384열, XFD). 벗어나면 throw.
-- 날짜 변환은 시리얼 1 = 1900-01-01 기준이며 타임존 보정이 들어가므로, 직접 산술하지 말고 이 메서드로 왕복.
+- 모든 좌표·인덱스는 0 기반, 주소 문자열은 1 기반(엑셀 표기).
+- 날짜 변환은 타임존 보정을 포함하므로 시리얼 ↔ tick 왕복이 로컬 기준으로 일관된다.
+- 알 수 없는 numFmtCode/numFmtId 는 silent fallback 없이 throw — 외부 생성 파일의 비정형 형식을 만나면 예외로 드러난다.

package/claude/references/sd-simplysm14/apis/excel/workbook-worksheet.md

@@ -1,6 +1,6 @@
 # @simplysm/excel — ExcelWorkbook / ExcelWorksheet
 
-.xlsx 파일을 열거나 새로 만들고, 시트를 추가/조회하고, 시트 단위로 데이터 테이블·매트릭스·레코드 읽기·쓰기·행 복사/삽입·이미지·뷰를 다룬 뒤 바이트/Blob 로 내보내는 진입 흐름. 워크북은 내부적으로 ZIP 리소스를 잡으므로 사용 후 반드시 `close()` 해야 한다(미해제 시 리소스 누수).
+`.xlsx` 워크북을 열거나(기존 바이트/Blob) 새로 만들고, 시트를 추가·조회하고, 시트 단위로 데이터·뷰·이미지·복사·내보내기를 다루는 핵심 클래스 군. 워크북은 내부적으로 ZIP 리소스를 lazy-load 로 관리하므로 사용 후 반드시 `close()` 로 해제해야 한다. 행/열·단일 셀 핸들은 [cell.md](./cell.md) 참조.
 
 ## ExcelWorkbook
 
@@ -8,20 +8,22 @@
 new ExcelWorkbook(arg?: Blob | Bytes)
 ```
 
-- `arg?: Blob | Bytes` — 기존 .xlsx 파일 데이터. 생략하면 빈 워크북을 새로 만든다(ContentTypes/rels/workbook 기본 파트 자동 구성). 파일을 읽을 땐 바이트나 Blob 을 그대로 전달.
+- `arg` — 기존 Excel 파일 데이터(`Blob` 또는 `Uint8Array`/`Bytes`). 생략하면 빈 워크북을 새로 생성한다(ContentTypes/rels/workbook 기본 파트 자동 구성).
+- `readonly zipCache: ZipCache` — 내부 ZIP 파트 캐시. 일반 사용에서 직접 만질 일은 없다.
 
-메서드:
+### 메서드
 
-- `getWorksheetNames(): Promise<string[]>` — 워크북의 모든 시트 이름을 정의 순서로 반환. 시트 존재 여부·선택지를 미리 알아야 할 때.
-- `addWorksheet(name: string): Promise<ExcelWorksheet>` — 새 시트를 만들어 반환. workbook/ContentTypes/rels 파트를 함께 갱신한다. 새 파일 쓰기 시작점.
-- `getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>` — 이름(string) 또는 0 기반 인덱스(number)로 시트 조회. 없으면 throw. 같은 시트는 캐시되어 동일 인스턴스를 반환한다.
-- `setDefaultStyle(opts: ExcelStyleOptions): Promise<void>` — 워크북 전역 기본 셀 스타일. `styles.xml` 의 0번 자원 슬롯(font/fill/border)을 덮어써, fontId/fillId/borderId 를 따로 지정하지 않은 모든 셀에 적용된다. 옵션 풀이는 [style.md](./style.md) 참조.
-- `toBytes(): Promise<Bytes>` — 워크북을 ZIP 바이트로 직렬화. 파일 저장·서버 전송용.
-- `toBlob(): Promise<Blob>` — 워크북을 `.sheet` MIME 의 Blob 으로 직렬화. 브라우저 다운로드용.
-- `close(): Promise<void>` — ZIP 리더·내부 캐시 해제. 이후 인스턴스 사용 불가. 이미 닫혔으면 no-op(중복 호출 안전). 모든 작업을 `try/finally` 로 감싸 반드시 호출.
-- `readonly zipCache: ZipCache` — 내부 ZIP 캐시 핸들(저수준). 일반 사용에서 직접 만질 일 없음.
+- `getWorksheetNames(): Promise<string[]>` — 워크북의 모든 워크시트 이름을 순서대로 반환.
+- `addWorksheet(name: string): Promise<ExcelWorksheet>` — 새 워크시트를 생성해 반환. ContentTypes/rels/workbook 파트를 함께 갱신한다.
+- `getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>` — 이름(string) 또는 0 기반 인덱스(number)로 워크시트 조회. 못 찾으면 throw. 같은 시트를 다시 요청하면 동일 인스턴스를 캐시 반환.
+- `setDefaultStyle(opts: ExcelStyleOptions): Promise<void>` — 워크북 default cell style 설정. `styles.xml` 의 `fonts[0]`/`fills[0]`/`borders[0]`(OOXML 0번 자원 슬롯) 자체를 덮어써, fontId/fillId/borderId 를 명시하지 않은 모든 셀에 전역 적용된다. 옵션이 없는 자원 슬롯은 빈 슬롯으로 reset. 옵션 상세는 [style.md](./style.md).
+- `toBytes(): Promise<Bytes>` — 워크북을 바이트 배열로 직렬화.
+- `toBlob(): Promise<Blob>` — 워크북을 `.xlsx` MIME 의 `Blob` 으로 직렬화(다운로드용).
+- `close(): Promise<void>` — ZIP 리더·내부 캐시 해제. 호출 후 인스턴스 사용 불가. 이미 닫힌 워크북에 호출해도 안전(no-op).
 
-읽기 예:
+닫힌 워크북의 시트/스타일/내보내기 메서드를 호출하면 throw 된다.
+
+### 사용 예
 
 ```typescript
 const wb = new ExcelWorkbook(bytes);
@@ -33,89 +35,76 @@ try {
 }
 ```
 
-쓰기 예:
-
-```typescript
-const wb = new ExcelWorkbook();
-try {
-  await wb.setDefaultStyle({ font: { family: "맑은 고딕", size: 10 } });
-  const ws = await wb.addWorksheet("결과");
-  await ws.setRecords([{ 코드: "A1", 수량: 3 }]);
-  return await wb.toBytes();
-} finally {
-  await wb.close();
-}
-```
-
 ## ExcelWorksheet
 
-`wb.addWorksheet` / `wb.getWorksheet` 로만 얻는다(직접 생성 안 함). 0 기반 행/열 인덱스를 쓴다.
+`getWorksheet`/`addWorksheet` 가 반환. 셀/행/열 접근, 데이터 일괄 입출력, 복사, 뷰, 조건부 서식, 이미지 삽입을 제공한다.
 
-이름:
+### 이름
 
-- `getName(): Promise<string>` — 시트 이름 반환. ID 에 대응하는 이름이 없으면 throw.
+- `getName(): Promise<string>` — 시트 이름 반환.
 - `setName(newName: string): Promise<void>` — 시트 이름 변경.
 
-셀 접근:
+### 셀·행·열 접근
 
-- `cell(r: number, c: number): ExcelCell` — 0 기반 행 `r`·열 `c` 의 셀 객체 반환(동기, 인스턴스 캐시). 값/스타일 실제 I/O 는 ExcelCell 의 async 메서드에서. 상세 [cell.md](./cell.md).
-- `row(r: number): ExcelRow` — 0 기반 행 객체 반환.
-- `col(c: number): ExcelCol` — 0 기반 열 객체 반환.
+- `cell(r: number, c: number): ExcelCell` — 0 기반 행/열 셀 핸들. 동일 좌표는 같은 인스턴스 캐시 반환.
+- `row(r: number): ExcelRow` — 0 기반 행 핸들.
+- `col(c: number): ExcelCol` — 0 기반 열 핸들.
 
-범위:
+(셀/행/열 API 상세는 [cell.md](./cell.md))
 
-- `getRange(): Promise<ExcelAddressRangePoint>` — 시트의 데이터 범위(`{s,e}`, 양끝 inclusive) 반환. 전체 셀 순회 루프 경계로 사용.
-- `getCells(): Promise<ExcelCell[][]>` — 데이터 범위 전체 셀을 행 우선 2차원 배열로 반환. 채워지는 인덱스는 range 기준(앞쪽 빈 행/열은 비어 있음).
+### 범위·일괄 입출력
 
-데이터(테이블/매트릭스/레코드):
+- `getRange(): Promise<ExcelAddressRangePoint>` — 시트 데이터 범위(`{s,e}`, 양 끝 inclusive) 반환.
+- `getCells(): Promise<ExcelCell[][]>` — 데이터 범위 전체를 행 우선 2차원 셀 배열로 반환.
+- `getDataTable(opt?): Promise<Record<string, ExcelValueType>[]>` — 헤더 행을 키로 하는 레코드 배열 반환.
+  - `opt.headerRowIndex` — 헤더 행 인덱스(기본: 데이터 범위 첫 행).
+  - `opt.checkEndColIndex` — 이 열이 비면 데이터 끝으로 판단해 이후 행을 끊는다.
+  - `opt.usableHeaderNameFn: (headerName: string) => boolean` — `true` 인 헤더명만 컬럼으로 채택(필터링). 중복 헤더는 throw.
+- `setDataMatrix(matrix: ExcelValueType[][]): Promise<void>` — 2차원 배열을 행 우선(인덱스 0 = 첫 행)으로 기록. `undefined` 셀은 삭제.
+- `setRecords(records: Record<string, ExcelValueType>[]): Promise<void>` — 레코드 배열 기록. 0 행에 키 합집합 헤더를 자동 생성하고 이후 행에 값 기록(빈 헤더 제외).
 
-- `getDataTable(opt?): Promise<Record<string, ExcelValueType>[]>` — 헤더 행을 키로 한 레코드 배열로 읽기.
-  - `opt.headerRowIndex?: number` — 헤더로 쓸 행 인덱스. 미지정 시 range 시작 행. 상단에 제목 행이 있으면 실제 헤더 행 인덱스를 지정.
-  - `opt.checkEndColIndex?: number` — 데이터 끝 판정 열. 그 열 셀이 비면 이후 행을 더 읽지 않고 종료. 빈 행으로 데이터가 끊기는 양식에서 사용.
-  - `opt.usableHeaderNameFn?: (headerName: string) => boolean` — 헤더 채택 필터. `true` 인 헤더만 키로 사용. 일부 열만 읽을 때. 채택된 헤더가 한 행 내 중복이면 throw.
-- `setDataMatrix(matrix: ExcelValueType[][]): Promise<void>` — 2차원 배열을 0,0 부터 행 우선으로 쓰기. 헤더 없이 좌표 그대로 채울 때. `undefined` 원소는 해당 셀 삭제.
-- `setRecords(records: Record<string, ExcelValueType>[]): Promise<void>` — 0행에 헤더(전 레코드 키 합집합, 빈 키 제외)를 자동 생성하고 1행부터 값 기록. 키 순서는 첫 등장 순. 표 형태 출력의 기본 수단.
+### 복사·삽입
 
-뷰:
+- `copyCellStyle(srcAddr, targetAddr): Promise<void>` — 셀 스타일 ID 만 복사.
+- `copyRowStyle(srcR, targetR): Promise<void>` — 데이터 범위 폭만큼 행 셀 스타일 복사.
+- `copyCell(srcAddr, targetAddr): Promise<void>` — 셀 전체 복사.
+- `copyRow(srcR, targetR): Promise<void>` — 원본 행을 대상 행에 복사(덮어쓰기).
+- `insertCopyRow(srcR: number, targetR: number): Promise<void>` — 원본 행을 대상 위치에 삽입 복사. 대상 이하 기존 행은 한 칸 아래로 밀리고, 삽입 지점을 관통하는 다중행 병합은 1행 확장, 원본의 단일행 병합은 대상 행에 복사된다.
 
-- `setTabColor(color: string): Promise<void>` — 시트 탭 색(ARGB 8자리, 예 `"00FF0000"`). 시트 구분 강조용.
-- `setZoom(percent: number): Promise<void>` — 확대/축소 비율(퍼센트). 워크북 뷰를 함께 초기화한다.
-- `freezeAt(point: { r?: number; c?: number }): Promise<void>` — 틀 고정. `r` = 위쪽 고정할 행 분할 지점, `c` = 왼쪽 고정할 열 분할 지점(0 기반). 헤더 한 줄 고정이면 `{ r: 0 }`(0행까지 위가 고정되고 1행부터 스크롤). 워크북 뷰를 함께 초기화한다.
-- `setAutoFilter(range: ExcelAddressRangePoint): Promise<void>` — 헤더 자동 필터(드롭다운) 설정. `range`(`{s,e}`, 0 기반, 양끝 inclusive) = 필터를 거는 범위로 보통 헤더행~데이터 끝 전체를 덮는다. `getRange()` 반환값을 그대로 넘겨 표 전체에 적용할 수 있다.
+(`srcAddr`/`targetAddr` 는 `ExcelAddressPoint`)
 
-조건부 서식:
+### 뷰
 
-- `addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>` — 셀/범위에 native CF 규칙 추가. 상세 [conditional-format.md](./conditional-format.md).
+- `setTabColor(color: string): Promise<void>` — 시트 탭 색(ARGB 8자리, 예 `"00FF0000"`).
+- `setZoom(percent: number): Promise<void>` — 확대/축소 비율(퍼센트).
+- `freezeAt(point: { r?: number; c?: number }): Promise<void>` — 행/열 틀 고정. `r` 만 주면 가로 틀고정, `c` 만 주면 세로 틀고정, 둘 다 주면 교차 고정.
+- `setAutoFilter(range: ExcelAddressRangePoint): Promise<void>` — 헤더 자동 필터(드롭다운). 범위는 헤더행~데이터 끝 전체를 덮도록 지정. 단일 셀 범위는 단일 주소로 축약 emit.
 
-복사/삽입:
+### 조건부 서식
 
-- `copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>` — 셀 스타일 ID 만 복사(값 제외). 원본에 스타일이 없으면 무변경.
-- `copyRowStyle(srcR: number, targetR: number): Promise<void>` — range 내 모든 열에 대해 행 스타일 복사.
-- `copyCell(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>` — 셀(값+스타일)을 대상에 복사.
-- `copyRow(srcR: number, targetR: number): Promise<void>` — 행 전체를 대상 행에 복사(대상 기존 내용 덮어쓰기).
-- `insertCopyRow(srcR: number, targetR: number): Promise<void>` — 원본 행을 대상 위치에 "삽입" 복사. 대상 이하 기존 행은 1칸 아래로 밀리고, 삽입 지점을 관통하는 다중행 병합은 1행 확장, 원본의 단일행 병합은 대상 행에 복제된다. 템플릿 행을 반복 펼칠 때 사용(덮어쓰기 방지).
+- `addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>` — 셀/범위에 native CF 규칙 추가. 상세는 [conditional-format.md](./conditional-format.md).
 
-이미지:
+### 이미지
 
-- `addImage(opts): Promise<void>` — 시트에 이미지 삽입. 같은 시트에 여러 번 호출하면 기존 drawing 파트에 이어 붙인다.
+- `addImage(opts): Promise<void>` — 워크시트에 이미지 삽입.
   - `opts.bytes: Bytes` — 이미지 바이너리.
-  - `opts.ext: string` — 확장자(`"png"`, `"jpg"` 등). MIME 미해석 시 throw. media 파일명/타입 결정에 사용.
-  - `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 }` — 끝 위치. 생략 시 `from` 의 한 칸 우하단(`from.r+1, from.c+1`)에 배치되어 약 1셀 크기로 들어간다. 명시하면 두 셀 앵커 사이로 늘려 배치.
+  - `opts.ext: string` — 확장자(`png`/`jpg` 등). MIME 결정 불가 시 throw.
+  - `opts.from: { r; c; rOff?: number | string; cOff?: number | string }` — 시작 위치(0 기반 행/열, `rOff`/`cOff` 는 EMU 오프셋).
+  - `opts.to?: { r; c; rOff?; cOff? }` — 끝 위치. 생략 시 `from` 의 1행 1열 아래(원본 1셀 크기)로 삽입.
 
-데이터 읽기 예:
+### 사용 예
 
 ```typescript
-const ws = await wb.getWorksheet("입력");
-const rows = await ws.getDataTable({
-  headerRowIndex: 1,
-  checkEndColIndex: 0,
-  usableHeaderNameFn: (h) => ["코드", "수량"].includes(h),
-});
+const wb = new ExcelWorkbook();
+const ws = await wb.addWorksheet("목록");
+await ws.setRecords([{ 이름: "홍길동", 나이: 30 }]);
+await ws.freezeAt({ r: 0 });
+const blob = await wb.toBlob();
+await wb.close();
 ```
 
 ## 주의사항
 
-- 거의 모든 셀/시트 I/O 메서드는 `async` — lazy XML 로드 때문. 반복 쓰기는 await 누적이 필요하다(`cell`/`row`/`col` 객체 획득만 동기).
-- `ExcelWorkbook` 은 반드시 `close()` 해야 한다. 닫힌 워크북의 시트 조회·내보내기 메서드는 throw.
-- `setRecords` 헤더는 레코드 키에서 자동 생성되므로 열 순서를 고정하려면 모든 레코드의 키 등장 순을 일정하게 유지하거나 `setDataMatrix` 를 사용.
+- 모든 워크북 I/O 는 `close()` 로 마무리할 것. 예외 경로에서도 누락되지 않게 `try/finally` 사용.
+- `getDataTable`/`setRecords`/`getValue` 는 모두 결측을 `undefined` 로 보존한다(빈 셀 = `undefined`).
+- 셀 좌표·범위·시트 인덱스는 전부 0 기반.