kordoc 4.0.8 → 4.2.0

package/dist/index.d.cts

@@ -134,12 +134,20 @@ interface ParseOptions {
      * PDF: 정확한 페이지 단위. HWP/HWPX: 섹션 단위 근사치.
      */
     pages?: number[] | string;
-    /** 이미지 기반 PDF용 OCR 프로바이더 (선택) */
-    ocr?: OcrProvider;
+    /** 이미지 기반 PDF OCR (선택).
+     *  - `true`: 내장 엔진(PP-OCRv5 korean, ~18MB 자동 다운로드)으로 OCR 필요 판정
+     *    페이지만 인식 (스캔 페이지·글꼴 매핑 깨진 페이지). 정상 페이지는 파싱 결과 유지.
+     *  - `"force"`: 전 페이지를 내장 엔진으로 강제 OCR.
+     *  - 함수: 사용자 제공 OcrProvider (Claude Vision·Tesseract 등) — 판정은 `true`와 동일. */
+    ocr?: boolean | "force" | OcrProvider;
     /** 진행률 콜백 — current: 현재 페이지/섹션, total: 전체 수 */
     onProgress?: (current: number, total: number) => void;
     /** PDF 머리글/바닥글 자동 제거 */
     removeHeaderFooter?: boolean;
+    /** 표 오른쪽 끝의 빈 열(서식 문서의 입력란) 보존 (#47).
+     *  기본 false: 마크다운 가독성을 위해 후행 빈 열을 트림.
+     *  양식 인식 경로(parse_form·fill)는 내부적으로 항상 켠다. */
+    keepTrailingEmptyCols?: boolean;
     /** 원본 파일 경로 (DRM COM fallback에 필요, 내부 전용) */
     filePath?: string;
     /**
@@ -186,7 +194,7 @@ interface ParseWarning {
     /** 구조화된 경고 코드 */
     code: WarningCode;
 }
-type WarningCode = "SKIPPED_IMAGE" | "SKIPPED_OLE" | "TRUNCATED_TABLE" | "OCR_FALLBACK" | "UNSUPPORTED_ELEMENT" | "BROKEN_ZIP_RECOVERY" | "HIDDEN_TEXT_FILTERED" | "MALFORMED_XML" | "PARTIAL_PARSE" | "LENIENT_CFB_RECOVERY" | "NEEDS_OCR" | "COM_EMPTY" | "DRM_COM_FALLBACK";
+type WarningCode = "SKIPPED_IMAGE" | "SKIPPED_OLE" | "TRUNCATED_TABLE" | "OCR_FALLBACK" | "UNSUPPORTED_ELEMENT" | "BROKEN_ZIP_RECOVERY" | "HIDDEN_TEXT_FILTERED" | "MALFORMED_XML" | "PARTIAL_PARSE" | "LENIENT_CFB_RECOVERY" | "NEEDS_OCR" | "OCR_FAILED" | "OCR_APPLIED" | "COM_EMPTY" | "DRM_COM_FALLBACK";
 /** 문서 구조 (헤딩 트리) */
 interface OutlineItem {
     level: number;
@@ -466,6 +474,8 @@ interface FillResult {
     filled: FormField[];
     /** 매칭 실패한 라벨 (입력에는 있지만 서식에서 못 찾은 것) */
     unmatched: string[];
+    /** 비치명 경고 (입력 라벨 정규화 충돌 등) — 없으면 생략 */
+    warnings?: string[];
 }
 /**
  * IRBlock[]에서 양식 필드를 찾아 값을 교체.
@@ -522,6 +532,8 @@ interface HwpxFillResult {
     filled: FormField[];
     /** 매칭 실패한 라벨 */
     unmatched: string[];
+    /** 비치명 경고 (입력 라벨 정규화 충돌 등) — 없으면 생략 */
+    warnings?: string[];
 }
 /**
  * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
@@ -1260,6 +1272,102 @@ interface ValidateResult {
 /** HWPX 버퍼의 컨테이너 구조를 검증한다. 문제가 없으면 ok=true. */
 declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<ValidateResult>;
 
+/**
+ * 한국 공문서 PII(개인정보) 탐지·마스킹 순수 로직.
+ *
+ * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파싱/patch는 기존 인프라가
+ * 담당하고 여기서는 텍스트만 다룬다 (CLI/MCP 배선은 별도).
+ *
+ * 원칙:
+ * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이가 동일
+ * - 히트 리포트에 원본 PII를 절대 담지 않는다 (`masked` 필드만 존재)
+ * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된
+ *   구간과 겹치는 하위 룰 매치는 스킵 (RULE_PRIORITY 참조)
+ * - 정규식은 모듈 로드 시 1회 컴파일 (matchAll은 내부 클론이라 lastIndex 안전)
+ */
+type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver";
+interface RedactHit {
+    rule: RedactRule;
+    /** 마스킹 후 문자열 — 원본 PII는 리포트에 담지 않는다 */
+    masked: string;
+    /** 원문 내 시작 오프셋 (UTF-16 단위) */
+    index: number;
+    /** 매치 길이 (서식 보존이라 마스킹 전후 동일) */
+    length: number;
+}
+interface RedactTextResult {
+    text: string;
+    hits: RedactHit[];
+}
+interface RedactOptions {
+    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — passport·driver는 기본 OFF) */
+    rules?: RedactRule[];
+    /** 마스크 문자 — 1글자(UTF-16 1단위), 영숫자 금지. 기본 "●" (마크다운 특수문자 아님) */
+    maskChar?: string;
+}
+/** 기본 적용 룰 — passport(여권)·driver(운전면허)는 오탐 여지가 있어 opt-in */
+declare const DEFAULT_REDACT_RULES: readonly RedactRule[];
+/**
+ * 텍스트에서 PII를 탐지해 서식 보존 마스킹.
+ *
+ * @param text - 대상 텍스트 (마크다운 포함)
+ * @param options - 룰 선택·마스크 문자 (기본: rrn·phone·email·card·account, "●")
+ * @returns 마스킹된 텍스트 + 히트 리포트 (index 오름차순, 원본 PII 미포함)
+ */
+declare function redactText(text: string, options?: RedactOptions): RedactTextResult;
+/**
+ * 마크다운 문서 전용 래퍼 — base64 이미지(data URI) 라인은 마스킹에서 제외한다.
+ * base64 페이로드의 숫자열이 phone 등에 오탐되면 이미지가 깨지기 때문.
+ * hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다.
+ */
+declare function redactMarkdown(markdown: string, options?: RedactOptions): RedactTextResult;
+
+/**
+ * RAG용 구조 보존 청킹 — IRBlock[] → DocChunk[].
+ *
+ * 문서의 위계(마크다운 헤딩 스택 + 개조식 리스트 깊이)를 breadcrumb으로 보존한
+ * 청크 목록을 만든다. 토큰 상한·오버랩 등 자르기 정책은 의도적으로 없다 —
+ * "구조 트리 제공"까지가 이 모듈의 몫이고 실제 분할은 소비자(RAG 파이프라인)가 한다.
+ *
+ * breadcrumb 규칙:
+ * - 헤딩(level 1~6)은 스택 구조 — 같거나 깊은 level을 팝하고 push, 리스트 위계 리셋
+ * - 리스트 항목은 깊이 d 등장 시 depth>=d를 팝하고 push — 하위 항목이 뒤따르면
+ *   그 breadcrumb으로 승격되고, 자식이 없으면 다음 형제/헤딩이 팝해 자연 소멸
+ * - 깊이는 IR의 listDepth 그대로. listDepth가 없는 개조식 선두 부호 문단
+ *   (□·○·- / 1.·가.·1) 등)은 depth 0 항목으로 취급 — IR에 없는 깊이는 지어내지 않는다
+ * - 청크의 breadcrumb은 자기 자신을 제외한 상위 경로다
+ */
+
+interface DocChunk {
+    /** "c0001" 순번 id — 같은 입력이면 같은 출력 (결정적) */
+    id: string;
+    type: "text" | "table" | "heading";
+    /** 상위 헤딩 + 리스트 위계 경로 (예: ["1. 개요", "가. 목적"]) */
+    breadcrumb: string[];
+    /** 청크 본문 마크다운 — 표는 GFM/HTML 그대로 (blocksToMarkdown 재사용) */
+    text: string;
+    /** 원본 페이지/섹션 번호 (1-based) — IR에 없으면 생략 */
+    page?: number;
+    /** 원본 IRBlock 인덱스 범위 [start, end] (양끝 포함) — 출처 앵커 */
+    blockRange: [number, number];
+    /** 표 청크 전용 구조 요약 — cells는 includeTableCells 옵션 시에만 */
+    table?: {
+        rows: number;
+        cols: number;
+        cells?: string[][];
+    };
+}
+interface ChunkOptions {
+    /** 표 청크에 셀 텍스트 행렬 포함 여부 (기본 false) */
+    includeTableCells?: boolean;
+    /**
+     * "section"(기본): 같은 breadcrumb 아래 연속 텍스트 블록을 하나로 병합,
+     * "block": IRBlock 1개 = 청크 1개
+     */
+    granularity?: "block" | "section";
+}
+declare function blocksToChunks(blocks: IRBlock[], options?: ChunkOptions): DocChunk[];
+
 /**
  * HWPX 문서 세션 — 에디터 통합용 블록 단위 증분 패치 API (v3.1).
  *
@@ -1556,4 +1664,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type FormatProfile, type GongmunFont, type GongmunLintFinding, 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 PlaceSealResult, type PrintOptions, type PrintPreset, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, VERSION, type ValidateIssue, type ValidateResult, 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, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type FormatProfile, type GongmunFont, type GongmunLintFinding, 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 PlaceSealResult, type PrintOptions, type PrintPreset, type RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, redactMarkdown, redactText, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };

package/dist/index.d.ts

@@ -134,12 +134,20 @@ interface ParseOptions {
      * PDF: 정확한 페이지 단위. HWP/HWPX: 섹션 단위 근사치.
      */
     pages?: number[] | string;
-    /** 이미지 기반 PDF용 OCR 프로바이더 (선택) */
-    ocr?: OcrProvider;
+    /** 이미지 기반 PDF OCR (선택).
+     *  - `true`: 내장 엔진(PP-OCRv5 korean, ~18MB 자동 다운로드)으로 OCR 필요 판정
+     *    페이지만 인식 (스캔 페이지·글꼴 매핑 깨진 페이지). 정상 페이지는 파싱 결과 유지.
+     *  - `"force"`: 전 페이지를 내장 엔진으로 강제 OCR.
+     *  - 함수: 사용자 제공 OcrProvider (Claude Vision·Tesseract 등) — 판정은 `true`와 동일. */
+    ocr?: boolean | "force" | OcrProvider;
     /** 진행률 콜백 — current: 현재 페이지/섹션, total: 전체 수 */
     onProgress?: (current: number, total: number) => void;
     /** PDF 머리글/바닥글 자동 제거 */
     removeHeaderFooter?: boolean;
+    /** 표 오른쪽 끝의 빈 열(서식 문서의 입력란) 보존 (#47).
+     *  기본 false: 마크다운 가독성을 위해 후행 빈 열을 트림.
+     *  양식 인식 경로(parse_form·fill)는 내부적으로 항상 켠다. */
+    keepTrailingEmptyCols?: boolean;
     /** 원본 파일 경로 (DRM COM fallback에 필요, 내부 전용) */
     filePath?: string;
     /**
@@ -186,7 +194,7 @@ interface ParseWarning {
     /** 구조화된 경고 코드 */
     code: WarningCode;
 }
-type WarningCode = "SKIPPED_IMAGE" | "SKIPPED_OLE" | "TRUNCATED_TABLE" | "OCR_FALLBACK" | "UNSUPPORTED_ELEMENT" | "BROKEN_ZIP_RECOVERY" | "HIDDEN_TEXT_FILTERED" | "MALFORMED_XML" | "PARTIAL_PARSE" | "LENIENT_CFB_RECOVERY" | "NEEDS_OCR" | "COM_EMPTY" | "DRM_COM_FALLBACK";
+type WarningCode = "SKIPPED_IMAGE" | "SKIPPED_OLE" | "TRUNCATED_TABLE" | "OCR_FALLBACK" | "UNSUPPORTED_ELEMENT" | "BROKEN_ZIP_RECOVERY" | "HIDDEN_TEXT_FILTERED" | "MALFORMED_XML" | "PARTIAL_PARSE" | "LENIENT_CFB_RECOVERY" | "NEEDS_OCR" | "OCR_FAILED" | "OCR_APPLIED" | "COM_EMPTY" | "DRM_COM_FALLBACK";
 /** 문서 구조 (헤딩 트리) */
 interface OutlineItem {
     level: number;
@@ -466,6 +474,8 @@ interface FillResult {
     filled: FormField[];
     /** 매칭 실패한 라벨 (입력에는 있지만 서식에서 못 찾은 것) */
     unmatched: string[];
+    /** 비치명 경고 (입력 라벨 정규화 충돌 등) — 없으면 생략 */
+    warnings?: string[];
 }
 /**
  * IRBlock[]에서 양식 필드를 찾아 값을 교체.
@@ -522,6 +532,8 @@ interface HwpxFillResult {
     filled: FormField[];
     /** 매칭 실패한 라벨 */
     unmatched: string[];
+    /** 비치명 경고 (입력 라벨 정규화 충돌 등) — 없으면 생략 */
+    warnings?: string[];
 }
 /**
  * HWPX 원본을 직접 수정하여 서식 필드를 채움 — 스타일 100% 보존.
@@ -1260,6 +1272,102 @@ interface ValidateResult {
 /** HWPX 버퍼의 컨테이너 구조를 검증한다. 문제가 없으면 ok=true. */
 declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<ValidateResult>;
 
+/**
+ * 한국 공문서 PII(개인정보) 탐지·마스킹 순수 로직.
+ *
+ * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파싱/patch는 기존 인프라가
+ * 담당하고 여기서는 텍스트만 다룬다 (CLI/MCP 배선은 별도).
+ *
+ * 원칙:
+ * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이가 동일
+ * - 히트 리포트에 원본 PII를 절대 담지 않는다 (`masked` 필드만 존재)
+ * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된
+ *   구간과 겹치는 하위 룰 매치는 스킵 (RULE_PRIORITY 참조)
+ * - 정규식은 모듈 로드 시 1회 컴파일 (matchAll은 내부 클론이라 lastIndex 안전)
+ */
+type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver";
+interface RedactHit {
+    rule: RedactRule;
+    /** 마스킹 후 문자열 — 원본 PII는 리포트에 담지 않는다 */
+    masked: string;
+    /** 원문 내 시작 오프셋 (UTF-16 단위) */
+    index: number;
+    /** 매치 길이 (서식 보존이라 마스킹 전후 동일) */
+    length: number;
+}
+interface RedactTextResult {
+    text: string;
+    hits: RedactHit[];
+}
+interface RedactOptions {
+    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — passport·driver는 기본 OFF) */
+    rules?: RedactRule[];
+    /** 마스크 문자 — 1글자(UTF-16 1단위), 영숫자 금지. 기본 "●" (마크다운 특수문자 아님) */
+    maskChar?: string;
+}
+/** 기본 적용 룰 — passport(여권)·driver(운전면허)는 오탐 여지가 있어 opt-in */
+declare const DEFAULT_REDACT_RULES: readonly RedactRule[];
+/**
+ * 텍스트에서 PII를 탐지해 서식 보존 마스킹.
+ *
+ * @param text - 대상 텍스트 (마크다운 포함)
+ * @param options - 룰 선택·마스크 문자 (기본: rrn·phone·email·card·account, "●")
+ * @returns 마스킹된 텍스트 + 히트 리포트 (index 오름차순, 원본 PII 미포함)
+ */
+declare function redactText(text: string, options?: RedactOptions): RedactTextResult;
+/**
+ * 마크다운 문서 전용 래퍼 — base64 이미지(data URI) 라인은 마스킹에서 제외한다.
+ * base64 페이로드의 숫자열이 phone 등에 오탐되면 이미지가 깨지기 때문.
+ * hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다.
+ */
+declare function redactMarkdown(markdown: string, options?: RedactOptions): RedactTextResult;
+
+/**
+ * RAG용 구조 보존 청킹 — IRBlock[] → DocChunk[].
+ *
+ * 문서의 위계(마크다운 헤딩 스택 + 개조식 리스트 깊이)를 breadcrumb으로 보존한
+ * 청크 목록을 만든다. 토큰 상한·오버랩 등 자르기 정책은 의도적으로 없다 —
+ * "구조 트리 제공"까지가 이 모듈의 몫이고 실제 분할은 소비자(RAG 파이프라인)가 한다.
+ *
+ * breadcrumb 규칙:
+ * - 헤딩(level 1~6)은 스택 구조 — 같거나 깊은 level을 팝하고 push, 리스트 위계 리셋
+ * - 리스트 항목은 깊이 d 등장 시 depth>=d를 팝하고 push — 하위 항목이 뒤따르면
+ *   그 breadcrumb으로 승격되고, 자식이 없으면 다음 형제/헤딩이 팝해 자연 소멸
+ * - 깊이는 IR의 listDepth 그대로. listDepth가 없는 개조식 선두 부호 문단
+ *   (□·○·- / 1.·가.·1) 등)은 depth 0 항목으로 취급 — IR에 없는 깊이는 지어내지 않는다
+ * - 청크의 breadcrumb은 자기 자신을 제외한 상위 경로다
+ */
+
+interface DocChunk {
+    /** "c0001" 순번 id — 같은 입력이면 같은 출력 (결정적) */
+    id: string;
+    type: "text" | "table" | "heading";
+    /** 상위 헤딩 + 리스트 위계 경로 (예: ["1. 개요", "가. 목적"]) */
+    breadcrumb: string[];
+    /** 청크 본문 마크다운 — 표는 GFM/HTML 그대로 (blocksToMarkdown 재사용) */
+    text: string;
+    /** 원본 페이지/섹션 번호 (1-based) — IR에 없으면 생략 */
+    page?: number;
+    /** 원본 IRBlock 인덱스 범위 [start, end] (양끝 포함) — 출처 앵커 */
+    blockRange: [number, number];
+    /** 표 청크 전용 구조 요약 — cells는 includeTableCells 옵션 시에만 */
+    table?: {
+        rows: number;
+        cols: number;
+        cells?: string[][];
+    };
+}
+interface ChunkOptions {
+    /** 표 청크에 셀 텍스트 행렬 포함 여부 (기본 false) */
+    includeTableCells?: boolean;
+    /**
+     * "section"(기본): 같은 breadcrumb 아래 연속 텍스트 블록을 하나로 병합,
+     * "block": IRBlock 1개 = 청크 1개
+     */
+    granularity?: "block" | "section";
+}
+declare function blocksToChunks(blocks: IRBlock[], options?: ChunkOptions): DocChunk[];
+
 /**
  * HWPX 문서 세션 — 에디터 통합용 블록 단위 증분 패치 API (v3.1).
  *
@@ -1556,4 +1664,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type DiffChangeType, type DiffResult, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type FormatProfile, type GongmunFont, type GongmunLintFinding, 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 PlaceSealResult, type PrintOptions, type PrintPreset, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, VERSION, type ValidateIssue, type ValidateResult, 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, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type FormatProfile, type GongmunFont, type GongmunLintFinding, 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 PlaceSealResult, type PrintOptions, type PrintPreset, type RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, redactMarkdown, redactText, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };