kordoc 4.14.2 → 4.14.3

package/README.md

@@ -84,18 +84,31 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 *   **✏️ 양식 자동 채우기**: 공문서 양식 템플릿(신청서, 보고서)에 값을 넣으면 자동으로 빈칸을 채웁니다. 원본 서식(글꼴, 크기, 정렬)을 100% 보존합니다.
 *   **👓 내장 OCR — API 키 없이 (v4.2)**: 스캔본·이미지 PDF와 PNG/JPG/WebP 이미지를 **로컬 CPU 추론**(PP-OCRv5 korean)으로 읽습니다. 외부 서비스도 API 키도 없이, 텍스트층이 깨진 페이지만 골라 OCR 하고, 래스터 괘선까지 찾아 스캔본에서도 표를 복원합니다.
 *   **📑 RAG·인용 대응 (v4.1~4.8)**: 헤딩·개조식 위계를 breadcrumb으로 보존한 구조 청크(`--format chunks`)와, 조판 캐시로 복원한 **실제 쪽 번호** 기준 페이지별 마크다운(`pages`)을 냅니다 — 답변에 "몇 쪽" 각주를 붙일 수 있습니다.
-*   **🕶️ 개인정보 마스킹 (v4.1)**: 주민번호·전화·이메일·카드·계좌를 탐지해 **원본 서식 그대로** 가린 문서를 냅니다 (`kordoc redact`). 자동 검출 보조 도구이므로 공개 전 사람 확인은 필수입니다.
+*   **🕶️ 개인정보 마스킹 (v4.1)**: 주민·외국인등록번호·전화·이메일·카드·계좌·사업자등록번호·여권·운전면허를 탐지해 **원본 서식 그대로** 가린 HWPX/HWP를 냅니다 (`kordoc redact`). 본문·표·머리말/꼬리말·각주·글상자·필드·미리보기(텍스트·이미지)·문서 정보(제목·작성자)까지 가리고, 결과 파일을 다시 훑어 남은 개인정보가 있으면 실패(exit 2)로 알립니다. **PDF·DOCX·XLSX 등은 원본 파일을 고치지 않고 마스킹된 마크다운만** 냅니다 — PDF 자체의 가림(redaction)은 지원하지 않습니다. 이미지 속 글자·이름·주소는 탐지하지 못하는 자동 검출 보조 도구이므로 공개 전 사람 확인은 필수입니다.
 *   **🤖 AI 에이전트 연동 (MCP)**: `Claude Desktop`, `Cursor`, `Codex`와 같은 도구에서 직접 `kordoc`을 호출해 문서를 읽고 코딩할 수 있습니다.
 
 ---
 
+## v4.14.3 변경사항
+
+읽기 품질을 전면 점검했습니다. 코퍼스를 넓히고(rhwp 표본 1,351파일·정책브리핑 hwpx+pdf 짝 200쌍) 포맷마다 정답지 벤치를 다시 세운 뒤 표·PDF·OCR·개인정보 마스킹을 고쳤고, 검색 색인처럼 글자만 필요한 호출자를 위한 두 가지를 더했습니다.
+
+- **📊 PDF 표 복원**: 쪽을 넘는 표를 잇고, 표 안의 표를 틀 칸 안에 넣습니다. hwpx↔pdf 430쌍 1,784표 정확 일치 64.1% → 90.1%, 셀 F1 0.790 → 0.945.
+- **🧾 HWP·HWP3·HWPX 표와 주석**: HWP 표를 HWPX 와 같은 규칙으로 배치해 hwp↔hwpx 쌍 3,593표가 모두 정확히 일치합니다(0.824 → 1). HWP3 표 격자를 복원하고, HWPX 각주·미주 번호와 문서 정보(제목·지은이 등)를 읽습니다.
+- **👓 OCR**: 기울기를 보정하고 세로로 이어진 글 상자를 나눠 읽으며 공문서 기호(○·△·따옴표)를 되살립니다. 글자 오류율 0.201 → 0.171, 3° 기울어진 스캔 57.6% → 22.0%.
+- **🕶️ 개인정보 마스킹**: 파일 안 모든 글자 저장소(머리말·각주·글상자·필드·미리보기·문서 정보 등)를 같은 길이로 가리고 결과를 다시 훑습니다. 5,081문서 오탐 387 → 0.
+- **💲 본문의 `$` 가 수식이 되지 않습니다**: 한글 문서(HWPX·HWP·HWP3)의 리터럴 `$` 는 `\$` 로 내고 `$…$` 는 수식에만 씁니다. "echo $HOME $PATH" 같은 글이 마크다운 렌더러에서 수식으로 바뀌던 것. 역슬래시 뒤 구두점("C:\.Pls")에서 역슬래시가 사라지던 것도 고쳤습니다.
+- **📝 미기입 누름틀 안내문을 빼고 읽습니다**: 한컴이 화면에만 흐리게 보이고 인쇄하지 않는 HWPX 안내문을 마크다운에서 뺍니다(블록 글에는 남김). 누름틀을 채우면 수정 표시를 켭니다.
+- **🖼️ 이미지 끄기** (`images: false` / `--no-images`): 결과에 이미지 바이트를 싣지 않습니다. 그림 자리 표시(`![image](…)`)와 본문 글자는 그대로라 그림 위치는 알 수 있습니다. PDF 는 PNG 인코딩을 건너뜁니다. 그림 많은 PDF 실측: JSON 출력 200MB → 9.5MB, CPU 시간 30% 감소.
+- **🚀 상주 파싱 워커** (`kordoc parse-worker`): 프로세스를 띄워 둔 채 stdin 요청 한 줄마다 한 줄 JSON 을 돌려줍니다. 파일마다 node 를 새로 띄우지 않아 대량 색인에 알맞습니다. 응답에 메모리 사용량(`rss`)을 실어 호스트가 워커 교체 시점을 정할 수 있습니다.
+
 ## v4.14.2 변경사항
 
 공문서 출력을 한글 2024 실렌더 PDF로 다시 대조해 "진짜 공문처럼" 다듬었습니다.
 
 - **📐 항목 둘째 줄이 첫 줄 내용과 정확히 맞습니다**: 부호(□ ○ - ※ 1. 가.) 뒤를 공백이 아니라 탭으로 두고, 한글의 "내어쓰기용 자동 탭"을 씁니다. 양쪽 정렬이 부호 뒤 공백을 늘려 첫 줄 내용이 밀리던 것, 자간을 줄인 줄에서 내용이 당겨지던 것이 구조적으로 없어졌습니다. 기안문·보고서·계획서·통지·회의록·업무보고·개조식·보도자료 전부.
 - **✂️ 낱말이 줄 끝에서 쪼개지지 않습니다**: 본문을 어절 단위 줄바꿈으로 바꾸고("동대/문" → "동대문") 외톨이줄 보호를 켰습니다. 날짜·금액은 묶음 빈칸으로 묶어 "2026. 1. / 22." 처럼 갈라지지 않습니다. 곧은따옴표는 ‘ ’ “ ”로 바꿉니다.
-- **📏 한글 글꼴 실폭으로 조판을 재현합니다**: 한컴돋움·HY견고딕·휴먼명조 등 8종의 실제 글자 폭으로 줄바꿈을 계산해(한글 2024 PDF 154줄 전부 일치), 짧은 꼬리 줄은 자간으로 올리고 긴 어절이 넘어가 공백이 크게 벌어지는 줄은 자간을 살짝 줄여 메웁니다. 종전처럼 한 줄을 과하게 눌러 옆 줄과 밀도가 달라 보이는 일이 줄었습니다.
+- **📏 한글 글꼴 실폭으로 조판을 재현합니다**: 한컴돋움·HY견고딕·휴먼명조 등 8종의 실제 글자 폭으로 줄바꿈을 계산합니다(한글 2024 PDF 154줄 전부 일치). 마지막 줄이 짧으면(줄 폭 절반 이하) 자간·장평을 최대 15%까지 줄여 한 줄 올리고, 한 줄에 맞춘다는 판단엔 2% 여유를 둬 한글에서 넘치지 않게 했습니다. 공백 없는 긴 목록("구(강남·강서·…·종로)가")처럼 한 줄보다 긴 어절이 있는 문단은 그 문단만 글자 단위로 조판하되 가운뎃점·쉼표 뒤에서만 끊어, 앞 줄이 크게 벌어지지 않습니다.
 - **🧩 PPTX 감지** (#80, PR #81 @LimePencil): PPTX 를 넣으면 "HWPX 섹션 없음" 대신 지원하지 않는 형식이라고 알려 줍니다.
 - **🧹 기술부채**: 1,200줄 넘던 `mcp.ts`·`cli.ts`·`hwp5/parser.ts`·`svg-render.ts` 를 기능별 모듈로 나눴고, 파서가 묶음 빈칸을 버리던 것과 `kordoc render` 미리보기의 탭 폭·줄 끝 공백 정렬을 고쳤습니다.
 
@@ -898,6 +911,24 @@ CLI로도: `kordoc render 결재문서.hwpx -o 결재문서.svg` — 조판 캐
 reflow 조판되며 `--no-reflow`로 끌 수 있습니다 (`--highlight 예산,집행` 지원),
 연속 렌더는 `kordoc render-worker`(stdin NDJSON, 미리보기 앱 연동용)
 
+### 글자만 필요할 때 (이미지 끄기·상주 파싱 워커)
+
+```typescript
+const result = await parse(buffer, { images: false }) // 이미지 바이트 없이 (그림 자리 표시는 남김)
+```
+
+CLI 는 `kordoc 문서.pdf --format json --no-images`. 대량 변환은 `kordoc parse-worker` 를 띄워 두고
+stdin 으로 한 줄씩 요청합니다 (한 줄 = 한 JSON).
+
+```text
+시작  {"ready":true,"version":"4.14.3","protocol":1}
+요청  {"id":1,"file":"문서.hwpx","images":false,"ocr":"off"}
+응답  {"id":1,"rss":183500800,"result":{ …--format json 과 같은 결과, 실패도 success:false 로… }}
+종료  {"cmd":"quit"}  (또는 stdin 닫기)
+```
+
+`ocr` 은 `"off"`·`"auto"`(OCR 필요 페이지만)·`"force"`, 그 밖에 `formulaOcr`·`password` 를 받습니다.
+
 ### 페이지 범위 지정
 
 ```typescript
@@ -973,8 +1004,10 @@ npx kordoc patch 원본.hwpx 편집.md -o 반영.hwpx      # 서식 보존 라
 npx kordoc seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 날인.hwpx  # 도장/서명 날인
 npx kordoc validate 산출물.hwpx                      # HWPX 구조 검증 (ZIP·필수 파트·XML)
 npx kordoc lint 보고서.md                            # 공문서 표기법 검수 19룰 — 입력은 md/txt('-'=stdin), error 있으면 exit 1
-npx kordoc redact 민원서류.hwpx -o 마스킹.hwpx       # 개인정보 탐지 + 서식 보존 마스킹 (v4.1)
+npx kordoc redact 민원서류.hwpx -o 마스킹.hwpx       # 개인정보 탐지 + 서식 보존 마스킹 (머리말·각주·미리보기·문서 정보 포함, 잔존 재검사 — 남으면 exit 2)
 npx kordoc redact 민원서류.hwpx --mask-char '*' -o 마스킹.hwpx   # 마스크 문자 지정 (기본 ●)
+npx kordoc redact 계약서.hwp --rules rrn,phone,crn --json --dry-run  # 룰 선택(법인등록번호 crn·IP 는 opt-in) + 위치별 리포트만
+npx kordoc redact 공문.pdf                            # PDF·DOCX 등은 원본을 고치지 않고 마스킹된 마크다운(.redacted.md)만 — PDF 가림 미지원
 npx kordoc profile 기관서식.hwpx                     # 표 서식 프로필(JSON) 추출 → generate --profile 로 재현
 npx kordoc render 결재문서.hwpx -o 미리보기.svg      # 레이아웃 보존 SVG 렌더 (캐시 없는 문서는 자동 reflow 조판, --no-reflow로 끔)
 npx kordoc render 결재문서.hwpx --reflow-mode charAll -o 미리보기.svg  # reflow 줄바꿈: keep(어절, 기본) | charAll(글자)
@@ -1091,7 +1124,7 @@ codex mcp add kordoc -- npx -y kordoc mcp
 | `generate_document` | 마크다운(표·수식·차트 포함) → HWPX 생성, 공문서 프리셋 (v3.5) |
 | `place_seal` | 도장/서명 이미지를 앵커 문구 위에 부유 배치 (v3.16) |
 | `render_document` | HWPX·HWP를 조판 그대로 PNG/JPEG 이미지(응답)·SVG/HTML/PDF 파일로 렌더 — 생성·수정 결과를 AI가 눈으로 검증 (v4.1, HWP·포맷 확장 v4.13.1) |
-| `redact_document` | 개인정보(주민번호·전화·이메일·카드·계좌) 탐지 + 서식 보존 마스킹, 리포트 반환 (v4.1) |
+| `redact_document` | 개인정보(주민·외국인등록번호·전화·이메일·카드·계좌·사업자등록번호·여권·운전면허, opt-in 법인등록번호·IP) 탐지 + 서식 보존 마스킹 — HWPX/HWP는 머리말·각주·미리보기·문서 정보까지 가리고 잔존 재검사, 그 외 포맷은 마스킹된 마크다운만 (v4.1) |
 | `parse_chunks` | RAG용 구조 청크 JSON — 헤딩·개조식 위계 breadcrumb + 표 독립 청크 (v4.1) |
 | `crop_regions` | 렌더 영역(표·이미지·문단·도형)을 페이지 이미지에서 실배율로 잘라 저장 + regions.json (v4.13) |
 | `extract_tables` | 표 분류(데이터표/조직도류/불확실) + 페이지·bbox + 정책별 crop — 조직도는 이미지로, 데이터표는 구조로 (v4.13.1) |
@@ -1148,7 +1181,7 @@ PPTX는 감지만 지원합니다. `parse()`는 PPTX 입력에 `success: false`,
 | `placeSealHwpx(buffer, seals)` | 도장/서명 이미지를 앵커 문구 위에 부유 배치 (v3.16) |
 | `validateHwpx(buffer)` | HWPX 구조 검증 — ZIP·mimetype·필수 파트·XML 웰폼드 (v3.16) |
 | `lintGongmunText(text, { document? })` | 공문서 표기법 검수 19룰 + AI 슬롭 2룰 — 텍스트/마크다운 입력 (v4.0.1, v4.12.1 보강). `document: true` 면 붙임/"끝." 문서 단위 검사 포함 |
-| `redactMarkdown(text, options?)` / `redactText(...)` | 개인정보 탐지 + 마스킹 (기본 룰: 주민번호·전화·이메일·카드·계좌, v4.1) |
+| `redactMarkdown(text, options?)` / `redactText(...)` | 개인정보 탐지 + 마스킹 (기본 룰: 주민·외국인등록번호·전화·이메일·카드·계좌·사업자등록번호·여권·운전면허, opt-in: 법인등록번호·IP — 텍스트 단위, 파일 단위 마스킹은 CLI `redact`/MCP `redact_document`, v4.1) |
 | `blocksToChunks(blocks, options?)` | RAG용 구조 청크 — 헤딩·개조식 위계 breadcrumb + 표 독립 청크 (v4.1) |
 | `blocksToMarkdown(blocks)` | IRBlock[] → Markdown 문자열 |
 | `blocksToPages(blocks)` | IRBlock[] → `[{ pageNumber, markdown }]` 페이지별 마크다운 (v4.8) |

package/dist/{-AQKXLFIM.js → -7XBPXCXN.js}

@@ -51,22 +51,22 @@ import {
   unknownFontWarnings,
   usesGaejosikMunche,
   validateHwpx
-} from "./chunk-EISO3POT.js";
+} from "./chunk-CVEERPMP.js";
 import {
   applySplices,
   buildParagraphSplices,
   buildRangeSplices,
   placeSealHwpx,
   scanSectionXml
-} from "./chunk-ZWOFQRIB.js";
+} from "./chunk-JCVIOLBF.js";
 import {
   DEFAULT_REDACT_RULES,
   redactMarkdown,
   redactText
-} from "./chunk-DZIXKL7E.js";
+} from "./chunk-IH56ZISC.js";
 import {
   blocksToChunks
-} from "./chunk-EDNJLUSE.js";
+} from "./chunk-IHZEFW4L.js";
 import {
   SPACE_EM_FIXED,
   SPACE_EM_FONT,
@@ -91,19 +91,20 @@ import {
   renderSceneToHtml,
   simulateWrap,
   simulateWrapKeepWord
-} from "./chunk-TSFS5VKD.js";
+} from "./chunk-YGBZABI4.js";
 import "./chunk-7FCNOKOR.js";
-import "./chunk-7IAQ4HOK.js";
+import "./chunk-NQCUAGLR.js";
 import "./chunk-MOL7MDBG.js";
-import "./chunk-ILU76UF3.js";
+import "./chunk-4RJ5D7MT.js";
 import {
   blocksToMarkdown,
+  flattenLayoutTables,
   hasStructuredCellContent
-} from "./chunk-QC5T6D4J.js";
-import "./chunk-C7FQBSON.js";
+} from "./chunk-QGW7NMTX.js";
+import "./chunk-VNFJPTU4.js";
 import {
   VERSION
-} from "./chunk-UET462HB.js";
+} from "./chunk-I4NNYWIR.js";
 export {
   BUILTIN_TEMPLATES,
   DEFAULT_REDACT_RULES,
@@ -140,6 +141,7 @@ export {
   fillHwpx,
   fillWithUniqueGuard,
   fitRatioForFewerLines,
+  flattenLayoutTables,
   formatFillValue,
   gongmunLintWarnings,
   hasStructuredCellContent,
@@ -192,4 +194,4 @@ export {
   usesGaejosikMunche,
   validateHwpx
 };
-//# sourceMappingURL=-AQKXLFIM.js.map
+//# sourceMappingURL=-7XBPXCXN.js.map

package/dist/{chunk-FOJZNMMK.js → chunk-2LQGSDZ6.js}

@@ -8,4 +8,4 @@ export {
   HEADING_RATIO_H2,
   HEADING_RATIO_H3
 };
-//# sourceMappingURL=chunk-FOJZNMMK.js.map
+//# sourceMappingURL=chunk-2LQGSDZ6.js.map

package/dist/chunk-2LQGSDZ6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/** kordoc 공통 타입 정의 */\n\n// ─── 중간 표현 (Intermediate Representation) ─────────\n\nexport interface CellContext {\n  text: string\n  colSpan: number\n  rowSpan: number\n  /** HWP5 셀 열 주소 (0-based) — 병합 테이블 배치용 */\n  colAddr?: number\n  /** HWP5 셀 행 주소 (0-based) — 병합 테이블 배치용 */\n  rowAddr?: number\n}\n\n/** 블록 타입 — v2.0에서 heading, list, image, separator 추가 */\nexport type IRBlockType = \"paragraph\" | \"table\" | \"heading\" | \"list\" | \"image\" | \"separator\"\n\n/** 인라인 강조 run-span — 문단 텍스트를 서식 단위로 쪼갠 조각 (텍스트 연결 = block.text) */\nexport interface IRSpan {\n  text: string\n  bold?: boolean\n  italic?: boolean\n  strike?: boolean\n  /** 밑줄 — 개정문 추가·변경 표시 등. GFM 문법이 없어 <u>…</u> 인라인 HTML 로 방출 */\n  underline?: boolean\n  code?: boolean\n  /**\n   * 미기입 누름틀의 안내문(HWPX CLICK_HERE, 수정 안 됨). 한컴은 화면에만 흐리게 보이고 인쇄하지 않는다.\n   * 블록 `text` 에는 남기고(양식 채우기·패치가 원문 자리와 맞대도록) 마크다운에서는 뺀다 (v4.14.3)\n   */\n  placeholder?: boolean\n}\n\nexport interface IRBlock {\n  type: IRBlockType\n  /** 블록 글. HWPX·HWP5·HWP3 은 원문의 리터럴 `$` 를 `\\$` 로 담고 `$…$`·`$$…$$` 는 수식 스팬에만 쓴다 (v4.14.3) */\n  text?: string\n  table?: IRTable\n  /** 헤딩 레벨 (1-6), type=\"heading\"일 때 사용 */\n  level?: number\n  /** 원본 페이지 번호 (1-based) */\n  pageNumber?: number\n  /** 바운딩 박스 — PDF에서만 제공 */\n  bbox?: BoundingBox\n  /** 텍스트 스타일 정보 (선택) */\n  style?: InlineStyle\n  /** 리스트 타입, type=\"list\"일 때 사용 */\n  listType?: \"ordered\" | \"unordered\"\n  /** 중첩 리스트 아이템 */\n  children?: IRBlock[]\n  /** 하이퍼링크 URL */\n  href?: string\n  /** 각주/미주 텍스트 (인라인 삽입용) */\n  footnoteText?: string\n  /** 이미지 데이터 (type=\"image\"일 때) */\n  imageData?: ImageData\n  /** 인라인 강조 run-span (선택 — kordoc 생성 hwpx 왕복 채널 + 외래 실속성 볼드/이탤릭).\n   *  존재하면 마크다운 변환이 **·*·` 마커를 재방출한다 */\n  spans?: IRSpan[]\n  /** 인용문 문단 (선택 — kordoc 생성 hwpx 왕복 채널) — 마크다운 변환이 \"> \" 접두 재방출 */\n  quote?: boolean\n  /**\n   * 문단 들여쓰기(HWPUNIT, 선택) — HWPX paraPr `<hh:margin>` 자식요소형 hc:left\n   * (+양수 hc:intent 첫줄분). 마크다운 방출엔 쓰지 않는 관찰 슬롯 — gongmun 리스트\n   * depth 재유도·양식 분석 등 소비자 몫 (v4.0.4)\n   */\n  indent?: number\n  /**\n   * gongmun 리스트 단계(1~7, 선택) — indent를 levelIndent 단위로 역산한 소비 결과\n   * (v4.0.5). md 리스트 문법과 충돌하는 부호('- '·'1) ') 문단에만 채워지며,\n   * 마크다운 변환이 2칸/단계 선행 공백을 방출해 재생성 시 depth가 복원된다\n   */\n  listDepth?: number\n}\n\n/** 추출된 이미지 바이너리 데이터 */\nexport interface ImageData {\n  /** 이미지 바이너리 */\n  data: Uint8Array\n  /** MIME 타입 (image/png, image/jpeg, image/gif, image/bmp, image/wmf, image/emf) */\n  mimeType: string\n  /** 원본 파일명 (있는 경우) */\n  filename?: string\n}\n\n/** 바운딩 박스 — PDF 포인트 단위 (72pt = 1인치) */\nexport interface BoundingBox {\n  page: number\n  x: number\n  y: number\n  width: number\n  height: number\n}\n\n/** 인라인 텍스트 스타일 */\nexport interface InlineStyle {\n  bold?: boolean\n  italic?: boolean\n  /** 취소선 — 법령 개정문 등의 삭제 표시. 판정은 취소선 모양 whitelist (비트만 믿으면 오탐) */\n  strike?: boolean\n  /** 밑줄 — 판정은 밑줄 종류 BOTTOM 한정 (NONE 이 기본 잡음, 코퍼스 실측) */\n  underline?: boolean\n  fontSize?: number\n  fontName?: string\n}\n\n// ─── 표 분류 계약 (#76) — 분류기 내부 점수 구조(TableSignals)는 노출하지 않는다 ───\n\nexport type TableClassificationKind = \"semantic-table\" | \"non-tabular-layout\" | \"uncertain\"\n\nexport type TableClassificationReason =\n  | \"repeated-row-schema\"\n  | \"grid-regularity\"\n  | \"high-active-density\"\n  | \"column-type-consistency\"\n  | \"nested-structure-wrapper\"\n  | \"span-irregularity\"\n  | \"spacer-bands\"\n  | \"extreme-sparsity\"\n  | \"diagram-context-keyword\"\n  | \"low-evidence\"\n  | \"ambiguous-scores\"\n\n/** 휴리스틱 분류 결과 — confidence 는 확률이 아니라 두 점수의 격차 */\nexport interface TableClassificationSummary {\n  kind: TableClassificationKind\n  confidence: number\n  semanticScore: number\n  nonTabularScore: number\n  reasons: TableClassificationReason[]\n}\n\nexport interface IRTable {\n  rows: number\n  cols: number\n  cells: IRCell[][]\n  /** 첫 행을 헤더로 렌더링할지 여부 (현재: rows > 1이면 true — 의미적 감지가 아닌 레이아웃 힌트) */\n  hasHeader: boolean\n  /** opt-in 분류(`ParseOptions.classifyTables`) 결과 — #76 */\n  classification?: TableClassificationSummary\n  /** 원본 표 식별자(HWPX `hp:tbl id`) — 렌더 region(`RenderRegion.sourceId`)과의 조인 키 */\n  sourceId?: string\n  /** 렌더 인프라가 준 페이지 로컬 pt 조각(다중 페이지 표는 여럿) — extractTables 가 채운다 */\n  regions?: BoundingBox[]\n  /** 표 캡션 (예: \"표 1. 부서별 예산\") — v3.0 */\n  caption?: string\n  /**\n   * 캡션 내부 블록 콘텐츠 — v4.2.8 (#55).\n   * 캡션 안 중첩표·문단을 구조 그대로, 원문 순서대로 보존한다 (IRCell.blocks와 같은 계약).\n   * 표가 있을 때만 채워지며, caption은 하위 호환용 평탄화 문자열로 계속 제공된다.\n   */\n  captionBlocks?: IRBlock[]\n}\n\nexport interface IRCell {\n  text: string\n  colSpan: number\n  rowSpan: number\n  /**\n   * 셀 내부 블록 콘텐츠 — v3.0.\n   * 중첩 표·이미지 등 구조 콘텐츠(또는 왕복 채널 span 문단)가 있는 셀에만 채워지며,\n   * 그 안의 문단·표·이미지를 문서(원문) 순서대로 보존한다. 다중 문단뿐인 평문 셀은\n   * blocks 없이 text 평탄화(문단을 `\\n`으로 결합)로만 제공된다 (blocks 무게 억제, #57).\n   * 표와 텍스트가 한 줄에 번갈아 놓인 셀도 배치 순서를 따른다 (v4.2.3, #49).\n   * blocks가 있으면 text는 blocks의 평탄화 텍스트(하위 호환용)다.\n   */\n  blocks?: IRBlock[]\n  /** 제목 셀 여부 (HWP5 width_ref bit2 / HWPX header 속성) — v3.0 */\n  isHeader?: boolean\n}\n\n// ─── 메타데이터 ─────────────────────────────────────\n\n/** 문서 메타데이터 — 각 포맷에서 추출 가능한 필드만 채워짐 */\nexport interface DocumentMetadata {\n  /** 문서 제목 */\n  title?: string\n  /** 작성자 */\n  author?: string\n  /** 작성 프로그램 (예: \"한글 2020\", \"Adobe Acrobat\") */\n  creator?: string\n  /** 생성일시 (ISO 8601) */\n  createdAt?: string\n  /** 수정일시 (ISO 8601) */\n  modifiedAt?: string\n  /** 페이지/섹션 수 — pageMode=\"layout\"이면 실제 페이지 수, \"section\"이면 섹션 수 */\n  pageCount?: number\n  /**\n   * 페이지 경계 신뢰도 (#66) — \"layout\": 조판 정보 기반 실제 페이지\n   * (한컴 저장본 HWP/HWPX·PDF·COM), \"section\": 섹션 단위 근사\n   * (조판 캐시 없는 생성 파일). HWP/HWPX/PDF에서만 설정된다.\n   */\n  pageMode?: \"layout\" | \"section\"\n  /** 문서 포맷 버전 (예: HWP \"5.1.0.1\") */\n  version?: string\n  /** 설명 */\n  description?: string\n  /** 키워드 */\n  keywords?: string[]\n}\n\n// ─── 파싱 옵션 ──────────────────────────────────────\n\n/** 파싱 옵션 — parse() 함수에 전달 */\nexport interface ParseOptions {\n  /**\n   * 파싱할 페이지/섹션 범위 (1-based).\n   * - 배열: [1, 2, 3]\n   * - 문자열: \"1-3\", \"1,3,5-7\"\n   *\n   * PDF: 정확한 페이지 단위. HWP/HWPX: 섹션 단위 근사치.\n   */\n  pages?: number[] | string\n  /** 이미지 기반 PDF OCR (선택).\n   *  - `true`: 내장 엔진(PP-OCRv5 korean, ~18MB 자동 다운로드)으로 OCR 필요 판정\n   *    페이지만 인식 (스캔 페이지·글꼴 매핑 깨진 페이지). 정상 페이지는 파싱 결과 유지.\n   *  - `\"force\"`: 전 페이지를 내장 엔진으로 강제 OCR.\n   *  - 함수: 사용자 제공 OcrProvider (Claude Vision·Tesseract 등) — 판정은 `true`와 동일. */\n  ocr?: boolean | \"force\" | OcrProvider\n  /** 진행률 콜백 — current: 현재 페이지/섹션, total: 전체 수 */\n  onProgress?: (current: number, total: number) => void\n  /** PDF 머리글/바닥글 자동 제거 */\n  removeHeaderFooter?: boolean\n  /** 표 오른쪽 끝의 빈 열(서식 문서의 입력란) 보존 (#47).\n   *  기본 false: 마크다운 가독성을 위해 후행 빈 열을 트림.\n   *  양식 인식 경로(parse_form·fill)는 내부적으로 항상 켠다. */\n  keepTrailingEmptyCols?: boolean\n  /** 구조 파싱 뒤 표를 의미표/레이아웃/불확실로 분류해 `IRTable.classification` 에 붙인다 (#76).\n   *  기본 false — 기본 parse 출력 불변. 중첩표·셀 blocks·캡션 blocks 까지 재귀, 원문 순서는 바꾸지 않는다. */\n  classifyTables?: boolean\n  /** 빈 문단(텍스트 없는 hp:p) 보존 (#57). 기본 false: 종전대로 빈 문단 제거.\n   *  켜면 본문은 `text: \"\"` paragraph 블록으로, 표 셀은 빈 줄로 순서대로 보존해\n   *  \"원문 문단 수 = 줄 수\" 대응을 유지한다 (행 줄맞춤 서식 문서용).\n   *  개체(표·이미지·글상자)만 있는 문단은 개체 출력이 따로 있어 대상이 아니다.\n   *  현재 HWPX 경로 적용. */\n  keepEmptyParagraphs?: boolean\n  /** 비밀번호로 보호된 문서의 열기 암호.\n   *  HWPX(ODF AES-256-CBC)·HWP3(DES) 지원. 한컴 DRM(문서 보안)은 별개라 해당 없음. */\n  password?: string\n  /** 원본 파일 경로 (DRM COM fallback에 필요, 내부 전용) */\n  filePath?: string\n  /**\n   * PDF 수식 OCR 활성화 (기본 false).\n   *\n   * 활성화 시 각 PDF 페이지를 이미지로 렌더링 → YOLOv8 기반 수식 영역 검출 →\n   * TrOCR 기반 LaTeX 인식. 감지된 수식은 `$...$` (inline) / `$$...$$` (display) 로\n   * 블록 텍스트에 삽입된다.\n   *\n   * 필수 optional 의존성: `onnxruntime-node`, `@huggingface/transformers`,\n   * `@hyzyla/pdfium`, `sharp`. 미설치 시 parse 에 실패하지 않고 **경고만** 남기고\n   * 수식 인식은 skip 한다 (일반 텍스트 추출은 정상 동작).\n   *\n   * 모델(~155MB) 은 첫 사용 시 HuggingFace 에서 자동 다운로드 되어\n   * `~/.cache/kordoc/models/pix2text/` 에 SHA-256 검증과 함께 저장된다.\n   */\n  formulaOcr?: boolean\n  /**\n   * 레이아웃 표 페이지 반복 헤더(러닝 헤더) 정리 휴리스틱 활성화 (기본 false).\n   *\n   * 구형 HWP5 문서가 페이지마다 재삽입한 짧은 번호매김 러닝 헤더\n   * (\"2. 과제 구축 내용\")를 최초 1회만 남기고 이후 중복을 제거한다.\n   * 다만 페이지 위치 정보가 없는 HWP5 특성상 이 휴리스틱은 정당하게 반복되는\n   * 번호매김 문단(예: 붙임/별지별 재번호 \"1. 목적\")도 삭제할 수 있어 opt-in 으로\n   * 둔다. 활성 시 제거가 발생하면 HIDDEN_TEXT_FILTERED 경고를 남긴다.\n   */\n  dedupeRunningHeaders?: boolean\n  /**\n   * 추출된 이미지를 마크다운에 base64 data URI 로 인라인 (기본 false).\n   *\n   * 활성화 시 `![image](image_001.bmp)` 참조를 `![image](data:image/png;base64,...)` 로\n   * 치환한다. 임베드된 BMP 는 PNG 로 무손실 압축 후 인라인하여 용량을 크게 줄인다.\n   * 별도 이미지 파일 없이 자체 완결형 마크다운이 되어 MCP/AI 에이전트 소비에 적합하다.\n   * (현재 HWP5 경로 지원)\n   */\n  inlineImages?: boolean\n  /**\n   * 이미지 바이트 추출 (기본 true). false 면 결과에 이미지 바이트를 싣지 않는다.\n   * `images` 는 비고, 블록의 `imageData` 도 떼며, HWP5 `inlineImages` 도 무시한다.\n   * 그림 자리 표시(`![image](…)`)는 마크다운·블록에 그대로 남아 위치는 알 수 있다.\n   * PDF 는 PNG 인코딩을 건너뛴다. 거르는 기준은 같되 메모리 보호용 128MB 누적 상한은 걸리지\n   * 않아, 그 상한 뒤의 그림도 자리 표시가 남는다.\n   *\n   * 검색 색인처럼 글자만 필요한 호출자용이다. 그림이 많은 문서는 base64 로 불어난 이미지가\n   * JSON 출력의 대부분을 차지했다 (PDF 실측 200MB → 9.5MB, CPU 시간 30% 감소). 본문 글자와\n   * OCR 은 이 옵션과 무관하다.\n   */\n  images?: boolean\n  /**\n   * PDF 표 감지 활성화 (기본 true). false 면 선 기반 그리드·클러스터 표 감지를 모두 끄고\n   * 자연 읽기순 텍스트만 뽑는다 (#64).\n   *\n   * 시각적 테두리 박스(시험지 안내문·보기 상자)가 표로 잡히면 주변 본문이 셀 매핑으로\n   * 끌려 들어가 문항 순서가 뒤집히는데, 표가 애초에 필요 없는 텍스트 중심 사용처에는\n   * 우회 수단이 없었다. 표가 실제로 있는 문서에 켜면 표 구조가 문단으로 흩어지므로\n   * 문서 종류를 아는 호출자만 쓰는 opt-out 이다. PDF 전용 — 다른 포맷은 무시.\n   */\n  tables?: boolean\n}\n\n// ─── 파싱 경고 ──────────────────────────────────────\n\n/** 파싱 중 스킵/실패한 요소 보고 */\nexport interface ParseWarning {\n  /** 관련 페이지 번호 (알 수 있는 경우) */\n  page?: number\n  /** 경고 메시지 */\n  message: string\n  /** 구조화된 경고 코드 */\n  code: WarningCode\n}\n\nexport type WarningCode =\n  | \"SKIPPED_IMAGE\"\n  | \"SKIPPED_OLE\"\n  | \"TRUNCATED_TABLE\"\n  | \"OCR_FALLBACK\"\n  | \"UNSUPPORTED_ELEMENT\"\n  | \"BROKEN_ZIP_RECOVERY\"\n  | \"HIDDEN_TEXT_FILTERED\"\n  | \"MALFORMED_XML\"\n  | \"PARTIAL_PARSE\"\n  | \"LENIENT_CFB_RECOVERY\"\n  | \"NEEDS_OCR\"\n  | \"OCR_FAILED\"\n  | \"OCR_APPLIED\"\n  | \"OCR_LOW_CONF\"\n  | \"COM_EMPTY\"\n  | \"DRM_COM_FALLBACK\"\n  /** pages 옵션 요청됐으나 조판 캐시가 없어 섹션 단위 근사로 적용됨 (#66) */\n  | \"PAGE_BOUNDARY_APPROXIMATE\"\n\n/** 문서 구조 (헤딩 트리) */\nexport interface OutlineItem {\n  level: number\n  text: string\n  pageNumber?: number\n}\n\n// ─── 에러 코드 ──────────────────────────────────────\n\n/** 구조화된 에러 코드 — 프로그래밍적 에러 핸들링용 */\nexport type ErrorCode =\n  | \"EMPTY_INPUT\"\n  | \"UNSUPPORTED_FORMAT\"\n  | \"ENCRYPTED\"\n  | \"DRM_PROTECTED\"\n  | \"CORRUPTED\"\n  | \"DECOMPRESSION_BOMB\"\n  | \"ZIP_BOMB\"\n  | \"IMAGE_BASED_PDF\"\n  | \"NO_SECTIONS\"\n  | \"PARSE_ERROR\"\n  | \"MISSING_DEPENDENCY\"\n  /** 결과 직렬화가 런타임 문자열 한계를 넘음 — 이미지 다량 문서의 JSON 출력 (#65) */\n  | \"OUTPUT_TOO_LARGE\"\n\n// ─── 파싱 결과 (discriminated union) ────────────────\n\n/** 감지된 파일 형식. pptx는 감지만 지원하며 파싱 시 UNSUPPORTED_FORMAT을 반환한다. */\nexport type FileType = \"hwpx\" | \"hwp\" | \"hwp3\" | \"hwpml\" | \"pdf\" | \"xlsx\" | \"xls\" | \"docx\" | \"pptx\" | \"image\" | \"unknown\"\n\ninterface ParseResultBase {\n  fileType: FileType\n  /** 페이지/섹션 수 — PDF: 실제 페이지 수, HWP/HWPX: 섹션 수, XLSX: 시트 수 */\n  pageCount?: number\n  /** 이미지 기반 PDF 여부 (텍스트 추출 불가) */\n  isImageBased?: boolean\n}\n\nexport interface ParseSuccess extends ParseResultBase {\n  success: true\n  /** 추출된 마크다운 텍스트 */\n  markdown: string\n  /**\n   * 중간 표현 블록 (구조화된 데이터 접근용).\n   * 블록은 문서(원문) 읽기 순서를 따른다 — 한 문단 안에 글자취급(treatAsChar)\n   * 표와 텍스트가 섞여 있어도 배치 순서대로 방출된다 (v4.2.3, #50).\n   */\n  blocks: IRBlock[]\n  /** 문서 메타데이터 */\n  metadata?: DocumentMetadata\n  /** 문서 구조 (헤딩 트리) — v2.0 */\n  outline?: OutlineItem[]\n  /** 파싱 중 발생한 경고 — v2.0 */\n  warnings?: ParseWarning[]\n  /** 추출된 이미지 목록 — 마크다운에서 파일명으로 참조됨 */\n  images?: ExtractedImage[]\n  /**\n   * 페이지별 마크다운 (#68) — `blocks` 의 `pageNumber` 로 갈라 페이지마다 다시\n   * 마크다운을 만든 것. 페이지 경계의 신뢰도는 `metadata.pageMode` 를 따른다\n   * (\"layout\" = 실제 페이지, \"section\" = 섹션 근사). `pages` 옵션으로 범위를\n   * 줄이면 그 범위만 담긴다. 페이지 번호를 매기지 않는 포맷(DOCX 등)에서는 없고,\n   * XLSX 는 `pageCount` 와 같은 의미로 시트 한 장이 한 쪽이다.\n   *\n   * 여러 페이지에 걸친 표는 시작 페이지 한 블록이라, 표가 이어지는 중간\n   * 페이지의 `markdown` 은 빈 문자열일 수 있다 (현 IR 구조의 한계).\n   */\n  pages?: PageMarkdown[]\n  /** 페이지별 텍스트 품질 신호 — PDF에서만 제공 */\n  pageQuality?: PageQuality[]\n  /** 문서 단위 품질 요약 — PDF에서만 제공 */\n  qualitySummary?: DocumentQualitySummary\n}\n\n/** 페이지 한 장의 마크다운 (#68). ParseSuccess.pages 항목. */\nexport interface PageMarkdown {\n  /** 원본 페이지 번호 (1-based) */\n  pageNumber: number\n  /** 그 페이지 블록만으로 만든 마크다운. 블록이 없으면 빈 문자열 */\n  markdown: string\n}\n\n/** 페이지별 텍스트 품질 신호 (PDF 전용). 자세한 설명은 src/pdf/quality.ts */\nexport interface PageQuality {\n  page: number\n  textChars: number\n  hangulRatio: number\n  controlCharRatio: number\n  replacementCharRatio: number\n  puaRatio: number\n  needsOcr: boolean\n  ocrReason?: \"low_text\" | \"high_pua\" | \"high_control\" | \"high_replacement\" | \"garbled_hangul\"\n}\n\n/** 문서 단위 품질 요약 (PDF 전용). */\nexport interface DocumentQualitySummary {\n  totalPages: number\n  totalTextChars: number\n  avgHangulRatio: number\n  avgControlCharRatio: number\n  avgReplacementCharRatio: number\n  avgPuaRatio: number\n  lowTextPageCount: number\n  highPuaPageCount: number\n  needsOcr: boolean\n  ocrCandidatePages: number[]\n}\n\n/** 추출된 이미지 — ParseSuccess.images에 포함 */\nexport interface ExtractedImage {\n  /** 마크다운에서 참조되는 파일명 (예: image_001.png) */\n  filename: string\n  /** 이미지 바이너리 */\n  data: Uint8Array\n  /** MIME 타입 */\n  mimeType: string\n  /** 원본 컨테이너 내 항목명 (HWPX/DOCX ZIP 경로, HWP5 BinData 스토리지명 — PDF 등 합성 이미지는 없음, #70) */\n  source?: string\n}\n\nexport interface ParseFailure extends ParseResultBase {\n  success: false\n  /** 오류 메시지 */\n  error: string\n  /** 구조화된 에러 코드 */\n  code?: ErrorCode\n}\n\nexport type ParseResult = ParseSuccess | ParseFailure\n\n// ─── 문서 비교 (Diff) ───────────────────────────────\n\nexport type DiffChangeType = \"added\" | \"removed\" | \"modified\" | \"unchanged\"\n\nexport interface BlockDiff {\n  type: DiffChangeType\n  /** 원본 블록 (added이면 undefined) */\n  before?: IRBlock\n  /** 변경 후 블록 (removed이면 undefined) */\n  after?: IRBlock\n  /** modified 테이블의 셀 단위 diff */\n  cellDiffs?: CellDiff[][]\n  /** 유사도 (0-1) */\n  similarity?: number\n}\n\nexport interface CellDiff {\n  type: DiffChangeType\n  before?: string\n  after?: string\n}\n\nexport interface DiffResult {\n  stats: { added: number; removed: number; modified: number; unchanged: number }\n  diffs: BlockDiff[]\n}\n\n// ─── 라운드트립 패치 (v3.0) ─────────────────────────\n\n/** 패치 중 매핑 실패/미지원으로 건너뛴 항목 — silent 실패 금지 */\nexport interface PatchSkip {\n  /** 건너뛴 사유 */\n  reason: string\n  /** 원본 쪽 내용 요약 (최대 80자) */\n  before?: string\n  /** 편집 쪽 내용 요약 (최대 80자) */\n  after?: string\n  /**\n   * 부분 적용 표시 — 변경이 적용은 됐지만(applied 계상) 편집 원형 그대로는\n   * 아님 (예: 셀 내 줄 추가를 마지막 문단에 병합). 완전 미적용 skip과 구분.\n   */\n  partial?: boolean\n}\n\n/** patchHwpx 옵션 */\nexport interface PatchOptions {\n  /** 패치 후 재파싱 자동 검증 (기본 true) */\n  verify?: boolean\n}\n\n/** patchHwpx / patchBlocks 결과 */\nexport interface PatchResult {\n  success: boolean\n  /** 패치된 HWPX (success=true) */\n  data?: Uint8Array\n  /** 적용된 변경 수 */\n  applied: number\n  /** 매핑 실패 항목 (이유 포함) */\n  skipped: PatchSkip[]\n  /**\n   * 무손실 검증 (patchHwpx/patchHwp 전용): 패치본 재파싱 vs 편집 마크다운의\n   * 잔차 diff — modified/added/removed가 0이어야 의도가 전부 반영된 것.\n   * session.patchBlocks는 이 필드를 채우지 않는다 (changes 참조).\n   */\n  verification?: DiffResult\n  /**\n   * 변경 가시화 (session.patchBlocks 전용): 패치 전 → 후 문서 diff —\n   * 적용된 편집 수만큼 modified가 나오는 것이 정상. verification과 의미가\n   * 정반대이므로 혼용 금지.\n   */\n  changes?: DiffResult\n  /** 실패 사유 (success=false) */\n  error?: string\n}\n\n// ─── 양식 인식 ──────────────────────────────────────\n\nexport interface FormField {\n  label: string\n  value: string\n  /** 0-based 소스 행 */\n  row: number\n  /** 0-based 소스 열 */\n  col: number\n  /** 매칭된 입력 키(정규화) — 모호 라벨 거부 가드(fillWithUniqueGuard)의 집계 기준 */\n  key?: string\n  /** 매칭 근거. `clickhere`(누름틀 name 정확 일치)는 서식 제작자가 선언한 계약이라\n   *  여러 곳에 같은 이름이 있어도 \"모호\"가 아니다 — 모호 라벨 거부 집계에서 제외된다.\n   *  (머리말·본문에 같은 이름의 누름틀을 두는 서식이 실제로 있다) */\n  source?: \"clickhere\"\n}\n\nexport interface FormResult {\n  fields: FormField[]\n  /** 양식 확신도 (0-1) */\n  confidence: number\n}\n\n// ─── OCR 프로바이더 ─────────────────────────────────\n\n/** 사용자 제공 OCR 함수 — 페이지 이미지를 받아 텍스트 반환.\n *  PDF 경로는 항상 \"image/png\", 이미지 직접 입력 경로는 원본 mime 그대로 전달. */\nexport type OcrProvider = (\n  pageImage: Uint8Array,\n  pageNumber: number,\n  mimeType: \"image/png\" | \"image/jpeg\" | \"image/webp\"\n) => Promise<string>\n\n// ─── Watch 모드 ─────────────────────────────────────\n\nexport interface WatchOptions {\n  dir: string\n  outDir?: string\n  webhook?: string\n  format?: \"markdown\" | \"json\"\n  pages?: string\n  silent?: boolean\n}\n\n// ─── 헤딩 감지 공통 임계값 ──────────────────────────\n\n/** 폰트 크기 비율 → heading level (전 파서 공통) */\nexport const HEADING_RATIO_H1 = 1.5\nexport const HEADING_RATIO_H2 = 1.3\nexport const HEADING_RATIO_H3 = 1.15\n\n// ─── 내부 파서 반환 타입 ─────────────────────────────\n\n/** 내부 파서가 index.ts에 반환하는 공통 타입 (HWP5/HWPX/PDF/XLSX/DOCX) */\nexport interface InternalParseResult {\n  markdown: string\n  blocks: IRBlock[]\n  metadata?: DocumentMetadata\n  outline?: OutlineItem[]\n  warnings?: ParseWarning[]\n  images?: ExtractedImage[]\n  /** PDF 전용: 이미지 기반 PDF 여부 */\n  isImageBased?: boolean\n  /** PDF 전용: 페이지별 품질 신호 */\n  pageQuality?: PageQuality[]\n  /** PDF 전용: 문서 단위 품질 요약 */\n  qualitySummary?: DocumentQualitySummary\n}\n"],"mappings":";AAskBO,IAAM,mBAAmB;AACzB,IAAM,mBAAmB;AACzB,IAAM,mBAAmB;","names":[]}