kordoc 2.9.0 → 3.0.0

package/README.md

@@ -62,20 +62,67 @@ Windows 도 자동으로 `cmd /c npx` 래핑. 수동 JSON 편집 불필요. 재
 *   **📊 복잡한 표(Table) 완벽 재현**: 선이 없는 PDF나 복잡하게 병합된 HWP 표도 구조를 분석하여 정확한 마크다운 테이블로 복원합니다.
 *   **🔍 신구대조표 자동 생성**: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (HWP와 HWPX 간의 비교도 가능!)
 *   **📝 마크다운을 다시 HWPX로**: AI가 작성한 내용을 다시 보고서 양식(`HWPX`)으로 되돌려줍니다. 이제 복사-붙여넣기 노가다에서 해방되세요.
+*   **🔄 서식 보존 무손실 라운드트립 (v3.0)**: 변환된 마크다운을 편집해서 `patchHwpx`에 넘기면, **원본 서식을 1바이트도 건드리지 않고** 바뀐 문단/표 셀의 텍스트만 원본 HWPX 안에서 교체합니다. AI가 공문 내용을 고치고 서식 그대로 돌려받는 워크플로가 가능해집니다.
 *   **✏️ 양식 자동 채우기**: 공문서 양식 템플릿(신청서, 보고서)에 값을 넣으면 자동으로 빈칸을 채웁니다. 원본 서식(글꼴, 크기, 정렬)을 100% 보존합니다.
 *   **🤖 AI 에이전트 연동 (MCP)**: `Claude`, `Cursor`와 같은 도구에서 직접 `kordoc`을 호출해 문서를 읽고 코딩할 수 있습니다.
 
 ---
 
-## v2.7.1 변경사항
+## v3.0.0 변경사항
+
+- **🔄 서식 보존 무손실 라운드트립** — `patchHwpx(원본HWPX, 편집된마크다운)` 신규 API. 변경된 문단/셀의 텍스트만 원본 XML 안에서 in-place 치환하고 나머지 ZIP 엔트리는 바이트 그대로 보존. 미지원 편집(블록 추가/삭제, 표 구조 변경)은 원본을 건드리지 않고 `skipped[]`로 정직하게 보고하며, 패치 후 자동 재파싱 검증 리포트(`verification`)를 제공합니다.
+
+  ```ts
+  import { parse, patchHwpx } from "kordoc"
+
+  const r = await parse(buf)                       // HWPX → 마크다운
+  const edited = r.markdown.replace("개최 예정", "개최 완료") // LLM이 편집했다고 가정
+  const res = await patchHwpx(new Uint8Array(buf), edited)
+  // res.data — 서식 그대로, 텍스트만 바뀐 HWPX 바이트
+  // res.applied / res.skipped / res.verification — 적용·미지원·검증 리포트
+  ```
+
+- **🎯 "99.9% 정확도" 파서 대도약** — 실측 공문서 코퍼스 324건(정부 보도자료 + 서울시 결재문서 + 2014~2016 옛 문서) 자기참조 채점 기준:
+
+  | 지표 | v2.9.1 | v3.0.0 |
+  |------|--------|--------|
+  | HWPX 텍스트 재현율 | 99.699% | **99.998%** |
+  | HWPX 표 구조 정확일치 | 99.875% | **100%** (1,421표 · 중첩표 343 포함) |
+  | PDF coverage | 97.013% | **99.16%** |
+  | HWP5↔HWPX 쌍 유사도 | — | **99.94%** |
+
+  중첩표 구조 보존(`IRCell.blocks`), 한컴 PUA 매핑, HWP5 이미지 추출(0→90건), 자동번호 카운터, 머리말/각주 정밀 처리 등. 채점기·코퍼스 수집기·게이트는 `bench/`에 포함 — `node bench/score.mjs`로 재현 가능.
+
+## v2.9.0 변경사항
+
+- **📊 PDF 텍스트 품질 신호 + OCR 필요 판정** — PDF는 텍스트층이 있어도 ToUnicode/CMap 이 깨져 한글이 깨진 글리프로 떨어지거나 NUL 등 제어문자가 섞이는 경우가 많습니다. `parsePdf` 결과에 페이지별 품질 신호(`pageQuality`)와 문서 요약(`qualitySummary`)을 추가 — `needsOcr`/`ocrReason` 으로 OCR 큐 자동 라우팅이 가능. kordoc 은 OCR 을 기본 탑재하지 않고 **신호만** 노출합니다. 전국 지자체 주요업무계획 PDF 190건(45,399쪽) 대량 처리 중 도출. (아래 [PDF 텍스트 품질 신호](#pdf-텍스트-품질-신호-v290) 참고)
+
+## v2.8.0 변경사항
+
+- **🎨 `markdownToHwpx` 테마 옵션** (#31) — 헤딩/본문/인용/표 헤더 셀의 텍스트 색상과 표 헤더 굵기를 옵션으로 지정 가능. 새 export 타입 `HwpxTheme`, `MarkdownToHwpxOptions`. 옵션 미지정 시 기존과 동일하게 검정으로 출력(baseline 백워드 호환).
+
+<details>
+<summary>v2.7.2 변경사항</summary>
+
+- **🐛 HWPX 양식 채우기 빈 셀 버그픽스** (#29, #30) — 한컴오피스에서 HWP→HWPX 로 변환한 양식의 빈 값 셀(`<hp:run>` 이 `<hp:t>` 자식 없이 self-closing)에 값이 삽입되지 않으면서 결과에는 성공으로 보고되던 false-positive 수정. `setRunText` 가 `<hp:t>` 없는 run 에 새로 생성해 텍스트 삽입. 기여: @amnotyoung
+
+</details>
+
+<details>
+<summary>v2.7.1 변경사항</summary>
 
 - **🕰️ HWP 3.0 (구버전) 파서 추가** — 1996~2002년 한컴이 쓰던 단일 binary 포맷 (`"HWP Document File V3.00"` 시그니처) 텍스트 추출. 기존 kordoc 이 거부하던 구버전 판결문/공문서 등이 검색 인덱싱 가능. 상용조합형(johab) → 유니코드 + 5,893개 한자/기호 lookup. 표 cell / 머리말 / 각주 의 nested paragraph 재귀 추출. [@edwardkim/rhwp](https://github.com/edwardkim/rhwp) 의 Rust 구현을 TypeScript 로 포팅.
 
-## v2.5.0 변경사항
+</details>
+
+<details>
+<summary>v2.5.0 변경사항</summary>
 
 - **🏛️ macOS 한컴오피스 호환 HWPX 생성** (#4) — `markdownToHwpx()` 가 만든 HWPX 가 macOS 한컴에서 "파일이 깨졌다"며 거부되던 문제 해결. 테이블 XML 을 최소 스켈레톤에서 완전 스펙 형태로 재작성 — `<hp:tbl>` 필수 속성 10종 + `<hp:sz>`/`<hp:pos>`/`<hp:outMargin>`/`<hp:inMargin>`, `<hp:tc>` 안에 `<hp:subList>` 래퍼 + `<hp:cellAddr>`/`<hp:cellSpan>`/`<hp:cellSz>`/`<hp:cellMargin>`, paragraph 래핑. `Preview/PrvText.txt` 추가 + `borderFill` id=1(SOLID 0.12mm) 추가.
 - **🔓 HWP 5.x 배포용 문서 COM fallback** (#25) — `.hwp` 바이너리에서 "이 문서는 상위 버전의 배포용 문서입니다..." 경고 플레이스홀더만 나오는 케이스에서, Windows + 한컴오피스 환경이면 자동으로 `HWPFrame.HwpObject` COM API 로 재시도. v2.4.0 의 HWPX DRM fallback 인프라를 `.hwp` 에도 확장.
 
+</details>
+
 <details>
 <summary>v2.4.0 변경사항</summary>
 
@@ -404,11 +451,13 @@ npx -y kordoc setup
 | `parse(buffer, options?)` | 포맷 자동 감지 → Markdown + IRBlock[] |
 | `parseHwpx(buffer, options?)` | HWPX 전용 |
 | `parseHwp(buffer, options?)` | HWP 5.x 전용 |
+| `parseHwp3(buffer, options?)` | HWP 3.x (1996~2002 구버전) 전용 |
 | `parsePdf(buffer, options?)` | PDF 전용 |
 | `parseXlsx(buffer, options?)` | XLSX 전용 |
+| `parseXls(buffer, options?)` | XLS (Excel 97~2003, BIFF8) 전용 |
 | `parseDocx(buffer, options?)` | DOCX 전용 |
 | `parseHwpml(buffer, options?)` | HWPML (XML 기반 HWP) 전용 |
-| `detectFormat(buffer)` | `"hwpx" \| "hwp" \| "hwpml" \| "pdf" \| "xlsx" \| "docx" \| "unknown"` |
+| `detectFormat(buffer)` | `"hwpx" \| "hwp" \| "hwp3" \| "hwpml" \| "pdf" \| "xlsx" \| "xls" \| "docx" \| "unknown"` |
 
 ### 고급 함수
 
@@ -419,7 +468,11 @@ npx -y kordoc setup
 | `fillForm(buffer, values, options?)` | 양식 템플릿에 값 채우기 (markdown/hwpx/hwpx-preserve) |
 | `fillFormFields(blocks, values)` | IRBlock[] 기반 필드 값 교체 |
 | `fillHwpx(buffer, values)` | HWPX XML 직접 조작 (원본 서식 보존) |
-| `markdownToHwpx(markdown)` | Markdown → HWPX 역변환 |
+| `patchHwpx(original, editedMarkdown, options?)` | 편집 마크다운 → 원본 HWPX 서식 보존 in-place 패치 (v3.0) |
+| `markdownToHwpx(markdown, options?)` | Markdown → HWPX 역변환 (테마 옵션 지원) |
+| `markdownToPdf(markdown, options?)` | Markdown → PDF 생성 (Print Renderer) |
+| `blocksToPdf(blocks, options?)` | IRBlock[] → PDF 생성 |
+| `renderHtml(blocks, options?)` | IRBlock[] → 인쇄용 HTML |
 | `blocksToMarkdown(blocks)` | IRBlock[] → Markdown 문자열 |
 
 ### 타입
@@ -427,10 +480,13 @@ npx -y kordoc setup
 ```typescript
 import type {
   ParseResult, ParseSuccess, ParseFailure, FileType,
-  IRBlock, IRTable, IRCell, CellContext,
-  DocumentMetadata, ParseOptions, ErrorCode,
+  IRBlock, IRBlockType, IRTable, IRCell, CellContext,
+  DocumentMetadata, ParseOptions, ErrorCode, OutlineItem,
   DiffResult, BlockDiff, CellDiff, DiffChangeType,
-  FormField, FormResult, FillResult, HwpxFillResult, FillOutputFormat,
+  FormField, FormResult, FillResult, HwpxFillResult, FillOutputFormat, FillFormOutput,
+  PatchOptions, PatchResult, PatchSkip,
+  HwpxTheme, MarkdownToHwpxOptions,
+  PrintPreset, PrintOptions, PageMargin,
   OcrProvider, WatchOptions,
 } from "kordoc"
 ```
@@ -441,9 +497,11 @@ import type {
 |------|------|------|
 | **HWPX** (한컴 2020+) | ZIP + XML DOM | 매니페스트, 중첩 테이블, 병합 셀, 손상 ZIP 복구 |
 | **HWP 5.x** (한컴 레거시) | OLE2 + CFB | 배포용 복호화, 손상 CFB 복구, 각주/하이퍼링크, 21종 제어문자, 이미지 추출 |
+| **HWP 3.x** (1996~2002) | 단일 binary | 상용조합형→유니코드, 5,893자 한자/기호 lookup, nested paragraph 추출 |
 | **HWPML 2.x** (XML 기반 HWP) | XML DOM | HeadingType 기반 헤딩 감지, 병합 셀, DoS 방어 |
-| **PDF** | pdfjs-dist | 선 기반 테이블, XY-Cut 읽기 순서, 헤딩 감지, OCR |
+| **PDF** | pdfjs-dist | 선 기반 테이블, XY-Cut 읽기 순서, 헤딩 감지, OCR, 텍스트 품질 신호 |
 | **XLSX** (Excel) | ZIP + XML DOM | 공유 문자열, 병합 셀, 다중 시트, 수식 표시 |
+| **XLS** (Excel 97~2003) | OLE2 + BIFF8 | Workbook 스트림, SST 공유 문자열, 셀/시트 추출 |
 | **DOCX** (Word) | ZIP + XML DOM | 스타일 heading, 번호 매기기, 각주, 이미지 추출 |
 
 ## 보안

package/dist/-K5SLEFZD.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import {
+  blocksToPdf,
+  compare,
+  diffBlocks,
+  extractFormFields,
+  fillForm,
+  fillFormFields,
+  fillHwpx,
+  isLabelCell,
+  markdownToHwpx,
+  markdownToPdf,
+  parse,
+  parseDocx,
+  parseHwp,
+  parseHwp3,
+  parseHwpml,
+  parseHwpx,
+  parsePdf,
+  parseXls,
+  parseXlsx,
+  patchHwpx,
+  renderHtml
+} from "./chunk-326STEDU.js";
+import {
+  detectFormat,
+  detectOle2Format,
+  detectZipFormat,
+  isHwpxFile,
+  isOldHwpFile,
+  isPdfFile,
+  isZipFile
+} from "./chunk-MEPHGCPQ.js";
+import {
+  VERSION,
+  blocksToMarkdown
+} from "./chunk-SA2PERJ5.js";
+import "./chunk-MOL7MDBG.js";
+export {
+  VERSION,
+  blocksToMarkdown,
+  blocksToPdf,
+  compare,
+  detectFormat,
+  detectOle2Format,
+  detectZipFormat,
+  diffBlocks,
+  extractFormFields,
+  fillForm,
+  fillFormFields,
+  fillHwpx,
+  isHwpxFile,
+  isLabelCell,
+  isOldHwpFile,
+  isPdfFile,
+  isZipFile,
+  markdownToHwpx,
+  markdownToPdf,
+  parse,
+  parseDocx,
+  parseHwp,
+  parseHwp3,
+  parseHwpml,
+  parseHwpx,
+  parsePdf,
+  parseXls,
+  parseXlsx,
+  patchHwpx,
+  renderHtml
+};
+//# sourceMappingURL=-K5SLEFZD.js.map

package/dist/-K5SLEFZD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}