@simplysm/sd-claude 14.0.88 → 14.0.90

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 기준이며 타임존 보정이 들어가므로, 직접 산술하지 말고 이 메서드로 왕복.

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

@@ -1,6 +1,6 @@
 # @simplysm/excel — ExcelWorkbook / ExcelWorksheet
 
-.xlsx 파일을 열거나 새로 만들고, 시트를 추가·조회하고, 시트 단위로 데이터 테이블/매트릭스/이미지/뷰를 다루고, 바이트/Blob 로 내보낼 때 함께 읽는 묶음. 워크북은 내부 ZIP 리소스를 lazy-load 하므로 사용 후 반드시 `close()` 해야 한다.
+.xlsx 파일을 열거나 새로 만들고, 시트를 추가/조회하고, 시트 단위로 데이터 테이블·매트릭스·레코드 쓰기·행 복사/삽입·이미지·뷰를 다룬 뒤 바이트/Blob 로 내보내는 진입 흐름. 워크북은 내부적으로 ZIP 리소스를 잡으므로 사용 후 반드시 `close()` 해야 한다(미해제 시 리소스 누수).
 
 ## ExcelWorkbook
 
@@ -8,28 +8,40 @@
 new ExcelWorkbook(arg?: Blob | Bytes)
 ```
 
-- 생성자 `arg` — 기존 .xlsx 데이터(`Blob` 또는 `Uint8Array`). 생략하면 빈 워크북(ContentTypes/rels/workbook 골격)을 새로 만든다. 기존 파일 편집이면 전달, 새 파일 생성이면 생략.
+- `arg?: Blob | Bytes` — 기존 .xlsx 파일 데이터. 생략하면 빈 워크북을 새로 만든다(ContentTypes/rels/workbook 기본 파트 자동 구성). 파일을 읽을 땐 바이트나 Blob 을 그대로 전달.
 
 메서드:
 
-- `getWorksheetNames(): Promise<string[]>` — 워크북의 모든 시트 이름을 정의 순서로 반환.
-- `addWorksheet(name: string): Promise<ExcelWorksheet>` — 새 시트를 만들어 반환. ContentTypes·workbook rels 도 함께 갱신. `name` = 추가할 시트 이름.
-- `getWorksheet(nameOrIndex: string | number): Promise<ExcelWorksheet>` — 이름(string) 또는 0 기반 인덱스(number)로 시트 조회. 같은 시트는 캐시돼 동일 인스턴스 반환. 없으면 throw.
-- `setDefaultStyle(opts: ExcelStyleOptions): Promise<void>` — 워크북 전역 default 셀 스타일. fontId/fillId/borderId 를 명시하지 않은 모든 셀에 적용. 자세히: [style.md](./style.md).
-- `toBytes(): Promise<Bytes>` — 워크북을 ZIP 직렬화해 바이트로 반환.
-- `toBlob(): Promise<Blob>` — `toBytes()` 결과를 xlsx MIME 의 `Blob` 으로 래핑. 브라우저 다운로드용.
-- `close(): Promise<void>` — ZIP 리더·내부 캐시 해제. 호출 후 워크북 사용 불가. 이미 닫혔으면 no-op(안전). 미호출 시 리소스 누수.
-- `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 캐시 핸들(저수준). 일반 사용에서 직접 만질 일 없음.
 
-`close()` 외 모든 메서드는 닫힌 워크북에서 호출 시 throw.
-
-### 사용 예
+읽기 예:
 
 ```typescript
-const wb = new ExcelWorkbook(bytes); // 기존 파일 열기
+const wb = new ExcelWorkbook(bytes);
 try {
   const ws = await wb.getWorksheet(0);
-  const table = await ws.getDataTable({ checkEndColIndex: 0 });
+  const rows = await ws.getDataTable();
+} finally {
+  await wb.close();
+}
+```
+
+쓰기 예:
+
+```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();
 }
@@ -37,61 +49,72 @@ try {
 
 ## ExcelWorksheet
 
-`wb.getWorksheet` / `wb.addWorksheet` 로 얻는다. 행/열/셀 접근, 복사, 데이터 변환, 뷰, 조건부 서식, 이미지를 제공.
+`wb.addWorksheet` / `wb.getWorksheet` 로만 얻는다(직접 생성 안 함). 0 기반 행/열 인덱스를 쓴다.
 
-### 이름
+이름:
 
-- `getName(): Promise<string>` — 시트 이름 반환(못 찾으면 throw).
+- `getName(): Promise<string>` — 시트 이름 반환.
 - `setName(newName: string): Promise<void>` — 시트 이름 변경.
 
-### 셀/행/열 접근 (모두 0 기반)
+셀 접근:
+
+- `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 기반 열 객체 반환.
+
+범위:
+
+- `getRange(): Promise<ExcelAddressRangePoint>` — 시트의 데이터 범위(`{s,e}`, 양끝 inclusive) 반환. 전체 셀 순회 루프 경계로 사용.
+- `getCells(): Promise<ExcelCell[][]>` — 데이터 범위 전체 셀을 행 우선 2차원 배열로 반환. 채워지는 인덱스는 range 기준(앞쪽 빈 행/열은 비어 있음).
 
-- `row(r): ExcelRow` — `r` 행 객체(캐시). 행 단위 순회·셀 접근. 자세히: [cell.md](./cell.md).
-- `col(c): ExcelCol` — `c` 열 객체(캐시). 열 단위 순회·너비 설정.
-- `cell(r, c): ExcelCell` — 단일 셀 객체(캐시). 값/수식/스타일/병합.
-- `getRange(): Promise<ExcelAddressRangePoint>` — 시트의 데이터 범위(`{s, e}`).
-- `getCells(): Promise<ExcelCell[][]>` — 데이터 범위 전체를 행 우선 2차원 셀 배열로.
+데이터(테이블/매트릭스/레코드):
 
-### 복사
+- `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 만 복사(값 미복사). `srcAddr`/`targetAddr` = `ExcelAddressPoint`.
-- `copyRowStyle(srcR, targetR): Promise<void>` — 데이터 범위 폭만큼 한 행의 셀 스타일을 다른 행에 복사.
-- `copyCell(srcAddr, targetAddr): Promise<void>` — 셀 전체(값·수식·스타일) 복사.
-- `copyRow(srcR, targetR): Promise<void>` — 한 행을 다른 행으로 복사(대상 덮어쓰기).
-- `insertCopyRow(srcR, targetR): Promise<void>` — `srcR` 행을 `targetR` 위치에 삽입 복사. `targetR` 이하 기존 행은 한 칸 아래로 밀리고, 삽입 지점을 관통하는 다중행 병합은 1행 확장된다. 행 추가 삽입(기존 보존)이 필요할 때 `copyRow`(덮어쓰기) 대신 사용.
+뷰:
 
-### 데이터 변환
+- `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행부터 스크롤).
 
-- `getDataTable(opt?): Promise<Record<string, ExcelValueType>[]>` — 헤더 행을 키로, 이후 행을 레코드로 변환.
-  - `opt.headerRowIndex?: number` — 헤더로 쓸 행 인덱스. 미지정 시 데이터 범위 첫 행.
-  - `opt.checkEndColIndex?: number` — 데이터 끝 판정 열. 이 열이 비면 그 행에서 중단. 빈 행 뒤 잡음 데이터를 끊을 때 지정.
-  - `opt.usableHeaderNameFn?: (headerName: string) => boolean` — `true` 반환한 헤더만 컬럼으로 채택. 일부 컬럼만 읽을 때.
-  - 헤더 문자열이 중복되면 throw.
-- `setDataMatrix(matrix: ExcelValueType[][]): Promise<void>` — 0행 0열부터 행 우선으로 2차원 배열을 그대로 기록.
-- `setRecords(records: Record<string, ExcelValueType>[]): Promise<void>` — 0행에 헤더(전 레코드 키의 distinct, 빈 키 제외) 자동 생성 후 1행부터 값 기록.
+조건부 서식:
 
-### 뷰
+- `addConditionalFormat(opts: { ref: string; rules: ExcelConditionalRule[] }): Promise<void>` — 셀/범위에 native CF 규칙 추가. 상세 [conditional-format.md](./conditional-format.md).
 
-- `setTabColor(color): Promise<void>` — 시트 탭 색. `color` = ARGB 8자리(예: `"00FF0000"`).
-- `setZoom(percent): Promise<void>` — 확대/축소 비율(퍼센트).
-- `freezeAt(point: { r?: number; c?: number }): Promise<void>` — 틀 고정. `r` = 이 행 위에서 고정, `c` = 이 열 왼쪽에서 고정. 둘 다/하나만 지정 가능.
+복사/삽입:
 
-### 조건부 서식 / 이미지
+- `copyCellStyle(srcAddr: ExcelAddressPoint, targetAddr: ExcelAddressPoint): Promise<void>` — 셀 스타일 ID 만 복사(값 제외). 원본에 스타일이 없으면 무변경.
+- `copyRowStyle(srcR: number, targetR: number): Promise<void>` — range 내 모든 열에 대해 행 스타일 복사.
+- `copyCell(srcAddr, targetAddr): Promise<void>` — 셀(값+스타일)을 대상에 복사.
+- `copyRow(srcR: number, targetR: number): Promise<void>` — 행 전체를 대상 행에 복사(대상 기존 내용 덮어쓰기).
+- `insertCopyRow(srcR: number, targetR: number): Promise<void>` — 원본 행을 대상 위치에 "삽입" 복사. 대상 이하 기존 행은 1칸 아래로 밀리고, 삽입 지점을 관통하는 다중행 병합은 1행 확장, 원본의 단일행 병합은 대상 행에 복제된다. 템플릿 행을 반복 펼칠 때 사용(덮어쓰기 방지).
 
-- `addConditionalFormat(opts): Promise<void>` — 셀/범위에 native CF 규칙 추가. 자세히: [conditional-format.md](./conditional-format.md).
-- `addImage(opts): Promise<void>` — 이미지 삽입.
+이미지:
+
+- `addImage(opts): Promise<void>` — 시트에 이미지 삽입.
   - `opts.bytes: Bytes` — 이미지 바이너리.
-  - `opts.ext: string` — 확장자(png/jpg 등). MIME 결정 불가 시 throw.
-  - `opts.from: { r, c, rOff?, cOff? }` — 시작 앵커(0 기반 행/열, `rOff`/`cOff` 는 EMU 오프셋).
-  - `opts.to?: { r, c, rOff?, cOff? }` — 끝 앵커. 생략 시 `from` 기준 1행·1열 크기로 배치.
-  - 같은 시트의 기존 drawing 이 있으면 재사용하고 없으면 새로 만든다.
+  - `opts.ext: string` — 확장자(`"png"`, `"jpg"` 등). MIME 미해석 시 throw.
+  - `opts.from: { r: number; c: number; rOff?: number | string; cOff?: number | string }` — 시작 위치(0 기반 행/열, `rOff`/`cOff` 는 셀 내부 EMU 오프셋).
+  - `opts.to?: { r; c; rOff?; cOff? }` — 끝 위치. 생략 시 `from` 의 한 칸 우하단(`from.r+1, from.c+1`)에 배치되어 약 1셀 크기로 들어간다. 명시하면 두 셀 앵커 사이로 늘려 배치.
 
-### 사용 예
+데이터 읽기 예:
 
 ```typescript
-const ws = await wb.addWorksheet("매출");
-await ws.setRecords([{ 품목: "사과", 수량: 10 }]);
-await ws.setZoom(85);
-await ws.freezeAt({ r: 0 });
-await ws.addImage({ bytes, ext: "png", from: { r: 0, c: 3 } });
+const ws = await wb.getWorksheet("입력");
+const rows = await ws.getDataTable({
+  headerRowIndex: 1,
+  checkEndColIndex: 0,
+  usableHeaderNameFn: (h) => ["코드", "수량"].includes(h),
+});
 ```
+
+## 주의사항
+
+- 모든 셀/시트 I/O 메서드는 `async` — lazy XML 로드 때문. 반복 쓰기는 await 누적이 필요하다.
+- `ExcelWorkbook` 은 반드시 `close()` 해야 한다. 닫힌 워크북의 모든 메서드는 throw.
+- `setRecords` 헤더는 레코드 키에서 자동 생성되므로 열 순서를 고정하려면 모든 레코드의 키 등장 순을 일정하게 유지하거나 `setDataMatrix` 를 사용.