kordoc 3.5.4 → 3.8.0

package/dist/index.d.cts

@@ -254,6 +254,11 @@ interface PatchSkip {
     before?: string;
     /** 편집 쪽 내용 요약 (최대 80자) */
     after?: string;
+    /**
+     * 부분 적용 표시 — 변경이 적용은 됐지만(applied 계상) 편집 원형 그대로는
+     * 아님 (예: 셀 내 줄 추가를 마지막 문단에 병합). 완전 미적용 skip과 구분.
+     */
+    partial?: boolean;
 }
 /** patchHwpx 옵션 */
 interface PatchOptions {
@@ -308,6 +313,32 @@ interface WatchOptions {
     silent?: boolean;
 }
 
+/** 양식 필드 매칭 공용 유틸 — filler.ts, filler-hwpx.ts에서 공유 */
+/**
+ * 채울 값 — 문자열이면 같은 라벨 모든 등장에 동일값(단일 양식),
+ * 배열이면 등장 순서대로 하나씩 소진(2~30장 반복 양식·명부형 표).
+ */
+type FillValue = string | string[];
+/**
+ * 다중값 커서 — 라벨별 값 소비 상태를 추적한다.
+ * 스칼라 값은 무한 반복(기존 동작), 배열 값은 적용 순서대로 소진되며
+ * 다 쓰면 available=false가 되어 이후 등장은 채우지 않는다.
+ */
+declare class ValueCursor {
+    private values;
+    private nextIdx;
+    constructor(values: Map<string, FillValue>);
+    keys(): IterableIterator<string>;
+    has(key: string): boolean;
+    isArray(key: string): boolean;
+    /** 남은 값이 있으면 true (스칼라는 항상 true) */
+    available(key: string): boolean;
+    /** 현재 값 미리보기 (소진 없음) */
+    peek(key: string): string | undefined;
+    /** 값 소비 — 배열이면 커서 전진, 소진 시 undefined */
+    consume(key: string): string | undefined;
+}
+
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
 /**
@@ -366,6 +397,8 @@ interface FillResult {
  *
  * @param blocks 원본 IRBlock[] (변경하지 않음 — deep clone)
  * @param values 채울 값 맵 (라벨 → 새 값). 라벨은 접두사 매칭 지원.
+ *   값이 배열이면 같은 라벨의 등장 순서대로 하나씩 소진(반복 양식·명부형 표),
+ *   문자열이면 모든 등장에 동일값.
  * @returns FillResult
  *
  * @example
@@ -379,7 +412,7 @@ interface FillResult {
  * })
  * ```
  */
-declare function fillFormFields(blocks: IRBlock[], values: Record<string, string>): FillResult;
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillValue>): FillResult;
 
 /**
  * HWPX 원본 서식 유지 채우기 — section XML 오프셋 splice (v3.1, 바이트 보존)
@@ -417,10 +450,12 @@ interface HwpxFillResult {
  * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
  *
  * @param hwpxBuffer 원본 HWPX 파일 버퍼
- * @param values 채울 값 맵 (라벨 → 값)
+ * @param values 채울 값 맵 (라벨 → 값). 값이 배열이면 같은 라벨의 등장 순서대로
+ *   하나씩 소진된다 — 2~30장 반복 양식·명부형 표(헤더+여러 데이터 행) 채우기용.
+ *   문자열이면 기존처럼 모든 등장에 동일값.
  * @returns HwpxFillResult
  */
-declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string>): Promise<HwpxFillResult>;
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillValue>): Promise<HwpxFillResult>;
 
 /**
  * 공문서(公文書) 모드 — 한국 행정 공문서 표준 서식 렌더링 로직
@@ -458,6 +493,14 @@ interface GongmunOptions {
     };
     /** 문서 제목(첫 h1)을 가운데 정렬. 기본 true (행정기관명·보고서 제목) */
     centerTitle?: boolean;
+    /**
+     * 문단별 자동 장평 — 한두 글자(짧은 꼬리)만 다음 줄로 넘어가는 문단의 장평을
+     * 95→90%까지 자동 축소해 한 줄에 담는다(공무원 실무 관행의 자동화).
+     * false로 끄거나 minRatio(기본 90)로 하한 조정. 기본 켜짐.
+     */
+    autoFit?: boolean | {
+        minRatio?: number;
+    };
 }
 /** 프리셋 별칭(한글/영문) → 내부 preset 키. CLI·라이브러리 공용 */
 declare const PRESET_ALIAS: Record<string, GongmunPreset>;
@@ -509,6 +552,73 @@ interface MarkdownToHwpxOptions {
  */
 declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOptions): Promise<ArrayBuffer>;
 
+/**
+ * 한글 조판 텍스트 폭 계산 — 함초롬바탕(HCR Batang) 실측 advance 테이블
+ *
+ * 공문서 표준 본문 글꼴인 함초롬바탕 정품 TTF(한컴 공개 배포)의 hmtx advance를
+ * upem=1000 기준으로 추출한 값이다. Bold도 advance가 Regular와 완전히 동일함을
+ * 전수 확인했다(한컴이 굵기 간 폭을 통일해 제작). 한글 음절 11,172자 전수 = 970,
+ * 한자 = 1000, 전각형·원문자·도형·화살표·단위기호 = 970으로 균일하다.
+ *
+ * 단위: em×1000. 실제 폭(HWPUNIT) = w/1000 × charPr.height × ratio(장평)/100.
+ * (1em = 글자크기 = charPr.height HWPUNIT — 1pt = 100 HWPUNIT이므로)
+ *
+ * 공백: HWP는 charPr useFontSpace=0(기본)일 때 글꼴의 space advance(0.30em) 대신
+ * 반각 고정폭(0.50em)을 쓴다 — kordoc 생성 문서는 모두 useFontSpace=0이므로
+ * 기본 SPACE_EM=500. (글꼴값을 쓰려면 measure 옵션 fontSpace로 300 지정)
+ *
+ * 다른 글꼴(맑은 고딕 등)도 한글=전각 균일·숫자≈0.55em의 동일 부류 구조라
+ * 이 테이블로 근사한다(오차 수 % 이내 — 공문서 본문은 어차피 함초롬바탕 관행).
+ */
+/** 코드포인트의 advance(em×1000). 미상 문자는 CJK권 970 / 라틴권 550 폴백 */
+declare function charWidthEm1000(cp: number): number;
+/** HWP 공백 폭(em×1000) — useFontSpace=0(기본): 반각 고정 500 / =1: 글꼴값 300 */
+declare const SPACE_EM_FIXED = 500;
+declare const SPACE_EM_FONT = 300;
+interface MeasureOptions {
+    /** 공백 폭(em×1000). 기본 SPACE_EM_FIXED(500) = useFontSpace 0 */
+    spaceEm?: number;
+    /** 자간(charPr spacing %) — 글자폭의 %가 문자마다 추가 */
+    spacingPct?: number;
+}
+/**
+ * 텍스트 폭(HWPUNIT). height=charPr height(pt×100), ratioPct=장평 %.
+ * 결과는 float — 호출부에서 비교 시 ±0.5 HWPUNIT 오차 허용 권장.
+ */
+declare function measureTextWidth(text: string, height: number, ratioPct: number, opts?: MeasureOptions): number;
+type WrapMode = "keep" | "charAll";
+interface WrapResult {
+    /** 줄 수 */
+    lines: number;
+    /** 각 줄의 시작 오프셋(UTF-16) — [0, …] */
+    starts: number[];
+    /** 마지막 줄 텍스트 폭(HWPUNIT) */
+    lastLineWidth: number;
+}
+/**
+ * 문단 줄바꿈 시뮬레이션.
+ * mode 'keep' = breakNonLatinWord=KEEP_WORD(어절 단위, 공문서 모드·Windows 한글),
+ * mode 'charAll' = 글자 단위(BREAK_WORD·macOS 한글·전자결재 변환기의 실동작).
+ * 한 어절이 줄보다 길면 keep에서도 글자 단위로 강제 분해(한컴 동일).
+ *
+ * @param text        문단 전체 텍스트(항목 부호 포함)
+ * @param firstWidth  첫 줄 가용 폭(HWPUNIT)
+ * @param contWidth   둘째 줄부터 가용 폭(HWPUNIT) — 내어쓰기 반영
+ * @param height      charPr height (pt×100)
+ * @param ratioPct    장평 %
+ */
+declare function simulateWrap(text: string, firstWidth: number, contWidth: number, height: number, ratioPct: number, mode?: WrapMode, opts?: MeasureOptions): WrapResult;
+/** @deprecated simulateWrap(text, …, 'keep') 별칭 — 하위 호환 */
+declare function simulateWrapKeepWord(text: string, firstWidth: number, contWidth: number, height: number, ratioPct: number, opts?: MeasureOptions): WrapResult;
+/**
+ * 한두 글자(짧은 꼬리)가 다음 줄로 넘어간 문단을 장평 축소로 한 줄 줄일 수 있는지
+ * 탐색. baseRatio에서 줄 수 N≥2일 때 r=baseRatio-1…minRatio를 내려가며 처음으로
+ * 줄 수가 줄어드는(가장 큰) r을 반환. 불가능하면 null.
+ * (실무 관행: 공무원이 문단 장평을 95→92 등으로 줄여 orphan을 위로 당기는 조작의 자동화.
+ * keep 모드로 판정 — 글자 단위 조판은 항상 keep 이하의 줄 수라 함께 만족된다.)
+ */
+declare function fitRatioForFewerLines(text: string, firstWidth: number, contWidth: number, height: number, baseRatio: number, minRatio: number, opts?: MeasureOptions): number | null;
+
 /**
  * HWPX 라운드트립 소스맵 — section XML 문자열에서 문단/표 셀의 문자 범위를 추적.
  *
@@ -558,6 +668,11 @@ interface ScanCell {
     paragraphs: ScanParagraph[];
     /** 셀 내부 중첩표 (문서 순서) */
     tables: ScanTable[];
+    /** <hp:cellAddr> 태그 범위 (자기닫힘=태그 전체, 펼친형=여는 태그) — rowAddr 재작성용 */
+    addrTagRange?: {
+        start: number;
+        end: number;
+    };
 }
 /** 스캔된 표 */
 interface ScanTable {
@@ -567,6 +682,11 @@ interface ScanTable {
     topLevel: boolean;
     /** 비어있지 않은 행들 (tr 순서) */
     rows: ScanCell[][];
+    /** rows[i]의 <hp:tr>...</hp:tr> XML 범위 (행 추가/삭제 splice용, rows와 정렬) */
+    rowRanges: {
+        start: number;
+        end: number;
+    }[];
     /** 앵커 좌표 → 셀 ("r,c") */
     cellByAnchor: Map<string, ScanCell>;
 }
@@ -632,9 +752,11 @@ declare function applySplices(xml: string, splices: SpliceEdit[]): string;
  * 스타일·이미지·표 구조·설정은 1바이트도 건드리지 않는다 (section XML 외
  * ZIP 엔트리는 원본 바이트 그대로, 변경 문단도 run 구조·charPr 보존).
  *
- * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표).
- * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 구조 변경, 캡션·각주·
- * 머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
+ * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표),
+ * 문단 → GFM 표 인플레이스 변환 (v3.5 — table-insert.ts),
+ * GFM/HTML 표 행 추가/삭제 (v3.7 — table-rows.ts, 병합 교차·개체 포함 행은 skip).
+ * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 열/병합 변경,
+ * 캡션·각주·머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
  */
 
 /**
@@ -907,6 +1029,6 @@ interface FillFormOutput {
  * console.log(result.output)  // 채워진 마크다운
  * ```
  */
-declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillValue>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, type WarningCode, type WatchOptions, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, scanSectionXml };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fitRatioForFewerLines, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, scanSectionXml, simulateWrap, simulateWrapKeepWord };

package/dist/index.d.ts

@@ -254,6 +254,11 @@ interface PatchSkip {
     before?: string;
     /** 편집 쪽 내용 요약 (최대 80자) */
     after?: string;
+    /**
+     * 부분 적용 표시 — 변경이 적용은 됐지만(applied 계상) 편집 원형 그대로는
+     * 아님 (예: 셀 내 줄 추가를 마지막 문단에 병합). 완전 미적용 skip과 구분.
+     */
+    partial?: boolean;
 }
 /** patchHwpx 옵션 */
 interface PatchOptions {
@@ -308,6 +313,32 @@ interface WatchOptions {
     silent?: boolean;
 }
 
+/** 양식 필드 매칭 공용 유틸 — filler.ts, filler-hwpx.ts에서 공유 */
+/**
+ * 채울 값 — 문자열이면 같은 라벨 모든 등장에 동일값(단일 양식),
+ * 배열이면 등장 순서대로 하나씩 소진(2~30장 반복 양식·명부형 표).
+ */
+type FillValue = string | string[];
+/**
+ * 다중값 커서 — 라벨별 값 소비 상태를 추적한다.
+ * 스칼라 값은 무한 반복(기존 동작), 배열 값은 적용 순서대로 소진되며
+ * 다 쓰면 available=false가 되어 이후 등장은 채우지 않는다.
+ */
+declare class ValueCursor {
+    private values;
+    private nextIdx;
+    constructor(values: Map<string, FillValue>);
+    keys(): IterableIterator<string>;
+    has(key: string): boolean;
+    isArray(key: string): boolean;
+    /** 남은 값이 있으면 true (스칼라는 항상 true) */
+    available(key: string): boolean;
+    /** 현재 값 미리보기 (소진 없음) */
+    peek(key: string): string | undefined;
+    /** 값 소비 — 배열이면 커서 전진, 소진 시 undefined */
+    consume(key: string): string | undefined;
+}
+
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
 /**
@@ -366,6 +397,8 @@ interface FillResult {
  *
  * @param blocks 원본 IRBlock[] (변경하지 않음 — deep clone)
  * @param values 채울 값 맵 (라벨 → 새 값). 라벨은 접두사 매칭 지원.
+ *   값이 배열이면 같은 라벨의 등장 순서대로 하나씩 소진(반복 양식·명부형 표),
+ *   문자열이면 모든 등장에 동일값.
  * @returns FillResult
  *
  * @example
@@ -379,7 +412,7 @@ interface FillResult {
  * })
  * ```
  */
-declare function fillFormFields(blocks: IRBlock[], values: Record<string, string>): FillResult;
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillValue>): FillResult;
 
 /**
  * HWPX 원본 서식 유지 채우기 — section XML 오프셋 splice (v3.1, 바이트 보존)
@@ -417,10 +450,12 @@ interface HwpxFillResult {
  * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
  *
  * @param hwpxBuffer 원본 HWPX 파일 버퍼
- * @param values 채울 값 맵 (라벨 → 값)
+ * @param values 채울 값 맵 (라벨 → 값). 값이 배열이면 같은 라벨의 등장 순서대로
+ *   하나씩 소진된다 — 2~30장 반복 양식·명부형 표(헤더+여러 데이터 행) 채우기용.
+ *   문자열이면 기존처럼 모든 등장에 동일값.
  * @returns HwpxFillResult
  */
-declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string>): Promise<HwpxFillResult>;
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillValue>): Promise<HwpxFillResult>;
 
 /**
  * 공문서(公文書) 모드 — 한국 행정 공문서 표준 서식 렌더링 로직
@@ -458,6 +493,14 @@ interface GongmunOptions {
     };
     /** 문서 제목(첫 h1)을 가운데 정렬. 기본 true (행정기관명·보고서 제목) */
     centerTitle?: boolean;
+    /**
+     * 문단별 자동 장평 — 한두 글자(짧은 꼬리)만 다음 줄로 넘어가는 문단의 장평을
+     * 95→90%까지 자동 축소해 한 줄에 담는다(공무원 실무 관행의 자동화).
+     * false로 끄거나 minRatio(기본 90)로 하한 조정. 기본 켜짐.
+     */
+    autoFit?: boolean | {
+        minRatio?: number;
+    };
 }
 /** 프리셋 별칭(한글/영문) → 내부 preset 키. CLI·라이브러리 공용 */
 declare const PRESET_ALIAS: Record<string, GongmunPreset>;
@@ -509,6 +552,73 @@ interface MarkdownToHwpxOptions {
  */
 declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOptions): Promise<ArrayBuffer>;
 
+/**
+ * 한글 조판 텍스트 폭 계산 — 함초롬바탕(HCR Batang) 실측 advance 테이블
+ *
+ * 공문서 표준 본문 글꼴인 함초롬바탕 정품 TTF(한컴 공개 배포)의 hmtx advance를
+ * upem=1000 기준으로 추출한 값이다. Bold도 advance가 Regular와 완전히 동일함을
+ * 전수 확인했다(한컴이 굵기 간 폭을 통일해 제작). 한글 음절 11,172자 전수 = 970,
+ * 한자 = 1000, 전각형·원문자·도형·화살표·단위기호 = 970으로 균일하다.
+ *
+ * 단위: em×1000. 실제 폭(HWPUNIT) = w/1000 × charPr.height × ratio(장평)/100.
+ * (1em = 글자크기 = charPr.height HWPUNIT — 1pt = 100 HWPUNIT이므로)
+ *
+ * 공백: HWP는 charPr useFontSpace=0(기본)일 때 글꼴의 space advance(0.30em) 대신
+ * 반각 고정폭(0.50em)을 쓴다 — kordoc 생성 문서는 모두 useFontSpace=0이므로
+ * 기본 SPACE_EM=500. (글꼴값을 쓰려면 measure 옵션 fontSpace로 300 지정)
+ *
+ * 다른 글꼴(맑은 고딕 등)도 한글=전각 균일·숫자≈0.55em의 동일 부류 구조라
+ * 이 테이블로 근사한다(오차 수 % 이내 — 공문서 본문은 어차피 함초롬바탕 관행).
+ */
+/** 코드포인트의 advance(em×1000). 미상 문자는 CJK권 970 / 라틴권 550 폴백 */
+declare function charWidthEm1000(cp: number): number;
+/** HWP 공백 폭(em×1000) — useFontSpace=0(기본): 반각 고정 500 / =1: 글꼴값 300 */
+declare const SPACE_EM_FIXED = 500;
+declare const SPACE_EM_FONT = 300;
+interface MeasureOptions {
+    /** 공백 폭(em×1000). 기본 SPACE_EM_FIXED(500) = useFontSpace 0 */
+    spaceEm?: number;
+    /** 자간(charPr spacing %) — 글자폭의 %가 문자마다 추가 */
+    spacingPct?: number;
+}
+/**
+ * 텍스트 폭(HWPUNIT). height=charPr height(pt×100), ratioPct=장평 %.
+ * 결과는 float — 호출부에서 비교 시 ±0.5 HWPUNIT 오차 허용 권장.
+ */
+declare function measureTextWidth(text: string, height: number, ratioPct: number, opts?: MeasureOptions): number;
+type WrapMode = "keep" | "charAll";
+interface WrapResult {
+    /** 줄 수 */
+    lines: number;
+    /** 각 줄의 시작 오프셋(UTF-16) — [0, …] */
+    starts: number[];
+    /** 마지막 줄 텍스트 폭(HWPUNIT) */
+    lastLineWidth: number;
+}
+/**
+ * 문단 줄바꿈 시뮬레이션.
+ * mode 'keep' = breakNonLatinWord=KEEP_WORD(어절 단위, 공문서 모드·Windows 한글),
+ * mode 'charAll' = 글자 단위(BREAK_WORD·macOS 한글·전자결재 변환기의 실동작).
+ * 한 어절이 줄보다 길면 keep에서도 글자 단위로 강제 분해(한컴 동일).
+ *
+ * @param text        문단 전체 텍스트(항목 부호 포함)
+ * @param firstWidth  첫 줄 가용 폭(HWPUNIT)
+ * @param contWidth   둘째 줄부터 가용 폭(HWPUNIT) — 내어쓰기 반영
+ * @param height      charPr height (pt×100)
+ * @param ratioPct    장평 %
+ */
+declare function simulateWrap(text: string, firstWidth: number, contWidth: number, height: number, ratioPct: number, mode?: WrapMode, opts?: MeasureOptions): WrapResult;
+/** @deprecated simulateWrap(text, …, 'keep') 별칭 — 하위 호환 */
+declare function simulateWrapKeepWord(text: string, firstWidth: number, contWidth: number, height: number, ratioPct: number, opts?: MeasureOptions): WrapResult;
+/**
+ * 한두 글자(짧은 꼬리)가 다음 줄로 넘어간 문단을 장평 축소로 한 줄 줄일 수 있는지
+ * 탐색. baseRatio에서 줄 수 N≥2일 때 r=baseRatio-1…minRatio를 내려가며 처음으로
+ * 줄 수가 줄어드는(가장 큰) r을 반환. 불가능하면 null.
+ * (실무 관행: 공무원이 문단 장평을 95→92 등으로 줄여 orphan을 위로 당기는 조작의 자동화.
+ * keep 모드로 판정 — 글자 단위 조판은 항상 keep 이하의 줄 수라 함께 만족된다.)
+ */
+declare function fitRatioForFewerLines(text: string, firstWidth: number, contWidth: number, height: number, baseRatio: number, minRatio: number, opts?: MeasureOptions): number | null;
+
 /**
  * HWPX 라운드트립 소스맵 — section XML 문자열에서 문단/표 셀의 문자 범위를 추적.
  *
@@ -558,6 +668,11 @@ interface ScanCell {
     paragraphs: ScanParagraph[];
     /** 셀 내부 중첩표 (문서 순서) */
     tables: ScanTable[];
+    /** <hp:cellAddr> 태그 범위 (자기닫힘=태그 전체, 펼친형=여는 태그) — rowAddr 재작성용 */
+    addrTagRange?: {
+        start: number;
+        end: number;
+    };
 }
 /** 스캔된 표 */
 interface ScanTable {
@@ -567,6 +682,11 @@ interface ScanTable {
     topLevel: boolean;
     /** 비어있지 않은 행들 (tr 순서) */
     rows: ScanCell[][];
+    /** rows[i]의 <hp:tr>...</hp:tr> XML 범위 (행 추가/삭제 splice용, rows와 정렬) */
+    rowRanges: {
+        start: number;
+        end: number;
+    }[];
     /** 앵커 좌표 → 셀 ("r,c") */
     cellByAnchor: Map<string, ScanCell>;
 }
@@ -632,9 +752,11 @@ declare function applySplices(xml: string, splices: SpliceEdit[]): string;
  * 스타일·이미지·표 구조·설정은 1바이트도 건드리지 않는다 (section XML 외
  * ZIP 엔트리는 원본 바이트 그대로, 변경 문단도 run 구조·charPr 보존).
  *
- * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표).
- * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 구조 변경, 캡션·각주·
- * 머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
+ * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표),
+ * 문단 → GFM 표 인플레이스 변환 (v3.5 — table-insert.ts),
+ * GFM/HTML 표 행 추가/삭제 (v3.7 — table-rows.ts, 병합 교차·개체 포함 행은 skip).
+ * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 열/병합 변경,
+ * 캡션·각주·머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
  */
 
 /**
@@ -907,6 +1029,6 @@ interface FillFormOutput {
  * console.log(result.output)  // 채워진 마크다운
  * ```
  */
-declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillValue>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, type WarningCode, type WatchOptions, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, scanSectionXml };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fitRatioForFewerLines, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, scanSectionXml, simulateWrap, simulateWrapKeepWord };