KorDoc Studio 에디터 통합 API(v3.1.0)와 문단 들여쓰기 보존 픽스(v3.1.1)를 함께 배포합니다.

npm은 3.0.1 → 3.1.1로 점프합니다. v3.1.0은 npm에 배포되지 않았으며, 본 릴리스에 그 변경사항이 모두 포함됩니다.

✨ 에디터 통합 API (3.1.0)

• HwpxSession — 블록 단위 증분 패치 세션 (openHwpxDocument(bytes)). patchBlocks / capability / sourceRef. "n회 연속 증분 패치 ≡ 일괄 패치" 바이트 동일 동등성을 CI 게이트로 보장.
• extractFormSchema — 양식 필드 타입 추론 7종(text/date/phone/email/amount/checkbox/idnum) + required/empty 판정. 폼 UI 자동 생성용.
• fillHwpx splice 전환 — 수정 텍스트 범위 외 섹션 XML은 원본 바이트 그대로 보존(서식·구조 무손상).
• 소스맵 저수준 API export — scanSectionXml / buildParagraphSplices / buildRangeSplices(t-도메인 좌표계) / applySplices.
• CJS 빌드 import.meta 잔존 수정 — require("kordoc") 시 SyntaxError 해결.
• 적대적 리뷰(26-에이전트) 확정 22건 전부 수정. 테스트 458 → 491.

🐛 들여쓰기 보존 픽스 (3.1.1)

• 문단 통째 교체 시 원본 들여쓰기(선행/후행 공백) 소실 수정 — IR sanitize로 제거됐던 양끝 공백을 원본 t-도메인 텍스트에서 복원. 클릭-편집 후 해당 줄만 왼쪽으로 튀어나오던 정렬 회귀 해결. HwpxSession.patchBlocks / patchHwpx / fillHwpx / 표 셀 공통 경로 적용, 증분 ≡ 일괄 동등성 유지. (#35)

전체 변경 내역은 CHANGELOG.md 참조.

🔄 patchHwp — HWPX 패치의 HWP 5.x(바이너리) 대응

• patchHwp(원본HWP, 편집된마크다운) 신규 API — OLE2 바이너리에서 변경된 문단/표 셀의 PARA_TEXT만 치환 (PARA_HEADER 글자수·CHAR_SHAPE·LINE_SEG 연쇄 갱신)
• 섹터 레벨 컨테이너 수술: CFB 전체 재조립 없이 대상 스트림 섹터/FAT 체인/디렉토리 엔트리만 갱신 — 수정 외 영역은 원본과 바이트 동일 (실측: 133섹터 중 5섹터만 변경)
• 안전 게이트: 레코드 재직렬화 바이트 동일성 검증, 순수 텍스트 문단만 수정, 암호화/배포용/DRM 거부, 미지원 편집은 graceful skip
• CLI kordoc patch가 .hwp/.hwpx 매직바이트 자동 분기

🔧 CI

• Node 18 ESM __dirname 미정의로 테스트 매트릭스가 실패하던 문제 수정

🔄 서식 보존 무손실 라운드트립

• patchHwpx(원본HWPX, 편집된마크다운) 신규 API — 변경된 문단/표 셀의 텍스트만 원본 XML 안에서 in-place 치환, 나머지 ZIP 엔트리는 바이트 그대로 보존
• 미지원 편집(블록 추가/삭제, 표 구조 변경)은 원본을 건드리지 않고 skipped[]로 보고, 패치 후 자동 재파싱 검증(verification) 제공
• CLI: kordoc patch 원본.hwpx 편집.md

🎯 파서 정확도 대도약

• 실측 공문서 코퍼스 324건 기준: HWPX 99.998% / 표 exact 100% / PDF 99.16% / HWP5쌍 99.94%
• 신규 코퍼스 120건(서울시 결재문서·옛 문서) 추가, HWP5쌍 정식 게이트 승격

전체 변경사항은 README v3.0.0 섹션 참고.

Fixed

• PageQuality / DocumentQualitySummary 타입 export 누락 수정 — v2.9.0 PDF 품질 신호 타입이 public export에서 빠져 import type { PageQuality } from \"kordoc\"가 동작하지 않던 문제.

Docs

• README / README-EN 현행화 — v2.8.0/v2.9.0 변경사항, parseHwp3·parseXls·Print Renderer(markdownToPdf/blocksToPdf/renderHtml) API, HWP 3.x/XLS 지원 포맷, detectFormat 반환 타입 정정.

PDF 텍스트 품질 신호 + OCR 필요 판정

Added

• parsePdf 결과에 페이지별 품질 신호 pageQuality + 문서 요약 qualitySummary 추가
• 페이지 메트릭: textChars, hangulRatio, controlCharRatio, replacementCharRatio, puaRatio
• needsOcr / ocrReason (low_text | high_pua | high_control | high_replacement)로 OCR 큐 자동 라우팅 가능
• 신규 모듈 src/pdf/quality.ts (임계치 상수 명시)

Changed

• PDF 블록/마크다운에서 비표시 제어문자 제거 (C0/DEL/C1 strip, PUA는 신호 보존 위해 유지)

kordoc은 OCR을 기본 탑재하지 않고 품질 신호만 노출합니다. 전국 지자체 주요업무계획 PDF 190건(45,399쪽) 대량 처리 중 도출.

markdownToHwpx 테마 옵션 (#31)

• 헤딩/본문/인용/표 헤더 셀의 텍스트 색상과 표 헤더 굵기를 옵션으로 지정 가능
• 새 export 타입 HwpxTheme, MarkdownToHwpxOptions
• 옵션 미지정 시 기존과 동일하게 검정으로 출력 (baseline 백워드 호환)
• charProperties itemCnt 9 → 11 (표 헤더 셀용 charPr id=9, 인용문용 charPr id=10 신설), HWPX 1.4 호환 유지

Fixed

fillHwpx(hwpx-preserve 모드) 빈 셀 미삽입 버그 (#29, #30)

한컴오피스에서 HWP→HWPX로 변환한 양식에서 빈 값 셀의 <hp:run>이 <hp:t> 자식 없이 self-closing(<hp:run charPrIDRef=\"...\"/>)인 경우, 값이 실제로 삽입되지 않으면서 filled/matched 결과에는 성공으로 보고되던 false-positive를 수정했습니다.

수정 내용

• setRunText가 <hp:t> 없는 run을 만나면 부모 run의 prefix/namespace를 따라 <hp:t>를 새로 생성해 텍스트 삽입
• 빈 문자열 호출(replaceCellText에서 run 비우기) 케이스와의 호환성 유지를 위한 가드 포함
• 회귀 테스트 추가 — self-closing <hp:run/>을 가진 minimal HWPX로 실제 XML 삽입까지 검증 (tests/filler-hwpx.test.ts)

영향

한컴오피스 변환 HWPX 양식이 한국 공공기관 양식의 거의 전부라 임팩트가 큽니다. 기존에는 placeholder 텍스트가 있는 일부 필드만 채워졌고 빈 셀은 false-positive로 보고되어 사용자가 결과를 신뢰할 수 없었습니다.

임시 우회법 (이전 버전 사용 시)

한컴오피스에서 빈 셀에 임의 placeholder 텍스트(예: _)를 한 번 입력 후 저장하면 <hp:t>가 생성되어 정상 작동합니다.

기여: @amnotyoung — 정확한 진단·재현·우회법까지 정리해주셔서 큰 도움이 되었습니다.

Full Changelog: v2.7.1...v2.7.2

Contributors

• @amnotyoung