kordoc 2.9.1 → 3.0.1

package/dist/index.d.cts

@@ -63,11 +63,21 @@ interface IRTable {
     cells: IRCell[][];
     /** 첫 행을 헤더로 렌더링할지 여부 (현재: rows > 1이면 true — 의미적 감지가 아닌 레이아웃 힌트) */
     hasHeader: boolean;
+    /** 표 캡션 (예: "표 1. 부서별 예산") — v3.0 */
+    caption?: string;
 }
 interface IRCell {
     text: string;
     colSpan: number;
     rowSpan: number;
+    /**
+     * 셀 내부 블록 콘텐츠 — v3.0.
+     * 중첩 표·이미지·다중 문단을 구조 그대로 보존한다.
+     * blocks가 있으면 text는 blocks의 평탄화 텍스트(하위 호환용)다.
+     */
+    blocks?: IRBlock[];
+    /** 제목 셀 여부 (HWP5 width_ref bit2 / HWPX header 속성) — v3.0 */
+    isHeader?: boolean;
 }
 /** 문서 메타데이터 — 각 포맷에서 추출 가능한 필드만 채워짐 */
 interface DocumentMetadata {
@@ -133,7 +143,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";
+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";
 /** 문서 구조 (헤딩 트리) */
 interface OutlineItem {
     level: number;
@@ -236,6 +246,34 @@ interface DiffResult {
     };
     diffs: BlockDiff[];
 }
+/** 패치 중 매핑 실패/미지원으로 건너뛴 항목 — silent 실패 금지 */
+interface PatchSkip {
+    /** 건너뛴 사유 */
+    reason: string;
+    /** 원본 쪽 내용 요약 (최대 80자) */
+    before?: string;
+    /** 편집 쪽 내용 요약 (최대 80자) */
+    after?: string;
+}
+/** patchHwpx 옵션 */
+interface PatchOptions {
+    /** 패치 후 재파싱 자동 검증 (기본 true) */
+    verify?: boolean;
+}
+/** patchHwpx 결과 */
+interface PatchResult {
+    success: boolean;
+    /** 패치된 HWPX (success=true) */
+    data?: Uint8Array;
+    /** 적용된 변경 수 */
+    applied: number;
+    /** 매핑 실패 항목 (이유 포함) */
+    skipped: PatchSkip[];
+    /** 자동 검증: 패치본 재파싱 vs 편집 마크다운 diff */
+    verification?: DiffResult;
+    /** 실패 사유 (success=false) */
+    error?: string;
+}
 interface FormField {
     label: string;
     value: string;
@@ -374,6 +412,53 @@ interface MarkdownToHwpxOptions {
  */
 declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOptions): Promise<ArrayBuffer>;
 
+/**
+ * HWPX 서식 보존 무손실 라운드트립 패치 — v3.0 킬러기능.
+ *
+ * parse()로 얻은 마크다운을 편집한 뒤 patchHwpx()에 넘기면, 원본 HWPX의
+ * ZIP/XML 구조를 그대로 두고 변경된 문단/셀의 텍스트만 in-place 치환한다.
+ * 스타일·이미지·표 구조·설정은 1바이트도 건드리지 않는다 (section XML 외
+ * ZIP 엔트리는 원본 바이트 그대로, 변경 문단도 run 구조·charPr 보존).
+ *
+ * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표).
+ * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 구조 변경, 캡션·각주·
+ * 머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
+ */
+
+/**
+ * 원본 HWPX와 편집된 마크다운으로 서식 보존 패치본을 만든다.
+ *
+ * @param original 원본 HWPX 바이트
+ * @param editedMarkdown parse(original).markdown을 편집한 마크다운
+ */
+declare function patchHwpx(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
+
+/**
+ * HWP 5.x 바이너리 서식 보존 무손실 라운드트립 패치 — patchHwpx의 HWP5 대응.
+ *
+ * parse()로 얻은 마크다운을 편집한 뒤 patchHwp()에 넘기면, 원본 HWP의
+ * CFB/레코드 구조를 그대로 두고 변경된 문단/표 셀의 PARA_TEXT만 치환한다.
+ * 연쇄 갱신: PARA_HEADER nChars, CHAR_SHAPE 위치, LINE_SEG 재구성, 레코드
+ * 크기 재계산 → 섹션 스트림 재직렬화 → deflate 재압축 → CFB 재조립.
+ *
+ * 안전 게이트 (하나라도 깨지면 해당 수정은 graceful skip — 파일 무결성 우선):
+ *  - 섹션 레코드 재직렬화가 원본과 바이트 동일해야 패치 허용
+ *  - ctrlMask=0(순수 텍스트) + PARA_TEXT 1개 + 레코드 텍스트 재구성 일치 문단만 수정
+ *  - 배포용/암호화/DRM 문서는 전체 거부
+ *
+ * 지원: 본문 문단/헤딩 텍스트 수정, GFM 표 셀 텍스트 수정 (좌표 기반).
+ * 미지원(graceful skip): 블록 추가/삭제, 표 구조 변경, HTML 표 셀, 캡션·각주·
+ * 머리말/꼬리말, 컨트롤(탭/개체/필드) 포함 문단. skipped[]에 사유 보고.
+ */
+
+/**
+ * 원본 HWP 5.x와 편집된 마크다운으로 서식 보존 패치본을 만든다.
+ *
+ * @param original 원본 HWP 바이트 (OLE2/CFB)
+ * @param editedMarkdown parse(original).markdown을 편집한 마크다운
+ */
+declare function patchHwp(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
+
 /**
  * Print Renderer — Markdown / IRBlock[] → PDF (puppeteer-core 기반).
  *
@@ -519,4 +604,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockDiff, type BoundingBox, 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 FormResult, type HwpxFillResult, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PrintOptions, type PrintPreset, VERSION, type WarningCode, type WatchOptions, 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, renderHtml };
+export { type BlockDiff, type BoundingBox, 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 FormResult, type HwpxFillResult, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, VERSION, type WarningCode, type WatchOptions, 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, patchHwp, patchHwpx, renderHtml };

package/dist/index.d.ts

@@ -63,11 +63,21 @@ interface IRTable {
     cells: IRCell[][];
     /** 첫 행을 헤더로 렌더링할지 여부 (현재: rows > 1이면 true — 의미적 감지가 아닌 레이아웃 힌트) */
     hasHeader: boolean;
+    /** 표 캡션 (예: "표 1. 부서별 예산") — v3.0 */
+    caption?: string;
 }
 interface IRCell {
     text: string;
     colSpan: number;
     rowSpan: number;
+    /**
+     * 셀 내부 블록 콘텐츠 — v3.0.
+     * 중첩 표·이미지·다중 문단을 구조 그대로 보존한다.
+     * blocks가 있으면 text는 blocks의 평탄화 텍스트(하위 호환용)다.
+     */
+    blocks?: IRBlock[];
+    /** 제목 셀 여부 (HWP5 width_ref bit2 / HWPX header 속성) — v3.0 */
+    isHeader?: boolean;
 }
 /** 문서 메타데이터 — 각 포맷에서 추출 가능한 필드만 채워짐 */
 interface DocumentMetadata {
@@ -133,7 +143,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";
+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";
 /** 문서 구조 (헤딩 트리) */
 interface OutlineItem {
     level: number;
@@ -236,6 +246,34 @@ interface DiffResult {
     };
     diffs: BlockDiff[];
 }
+/** 패치 중 매핑 실패/미지원으로 건너뛴 항목 — silent 실패 금지 */
+interface PatchSkip {
+    /** 건너뛴 사유 */
+    reason: string;
+    /** 원본 쪽 내용 요약 (최대 80자) */
+    before?: string;
+    /** 편집 쪽 내용 요약 (최대 80자) */
+    after?: string;
+}
+/** patchHwpx 옵션 */
+interface PatchOptions {
+    /** 패치 후 재파싱 자동 검증 (기본 true) */
+    verify?: boolean;
+}
+/** patchHwpx 결과 */
+interface PatchResult {
+    success: boolean;
+    /** 패치된 HWPX (success=true) */
+    data?: Uint8Array;
+    /** 적용된 변경 수 */
+    applied: number;
+    /** 매핑 실패 항목 (이유 포함) */
+    skipped: PatchSkip[];
+    /** 자동 검증: 패치본 재파싱 vs 편집 마크다운 diff */
+    verification?: DiffResult;
+    /** 실패 사유 (success=false) */
+    error?: string;
+}
 interface FormField {
     label: string;
     value: string;
@@ -374,6 +412,53 @@ interface MarkdownToHwpxOptions {
  */
 declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOptions): Promise<ArrayBuffer>;
 
+/**
+ * HWPX 서식 보존 무손실 라운드트립 패치 — v3.0 킬러기능.
+ *
+ * parse()로 얻은 마크다운을 편집한 뒤 patchHwpx()에 넘기면, 원본 HWPX의
+ * ZIP/XML 구조를 그대로 두고 변경된 문단/셀의 텍스트만 in-place 치환한다.
+ * 스타일·이미지·표 구조·설정은 1바이트도 건드리지 않는다 (section XML 외
+ * ZIP 엔트리는 원본 바이트 그대로, 변경 문단도 run 구조·charPr 보존).
+ *
+ * 지원: 문단/헤딩 텍스트 수정, 표 셀 텍스트 수정 (GFM·HTML·1x1·1열 표).
+ * 미지원(graceful skip): 블록 추가/삭제/순서 변경, 표 구조 변경, 캡션·각주·
+ * 머리말/꼬리말·이미지 변경. skipped[]에 사유와 함께 보고된다.
+ */
+
+/**
+ * 원본 HWPX와 편집된 마크다운으로 서식 보존 패치본을 만든다.
+ *
+ * @param original 원본 HWPX 바이트
+ * @param editedMarkdown parse(original).markdown을 편집한 마크다운
+ */
+declare function patchHwpx(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
+
+/**
+ * HWP 5.x 바이너리 서식 보존 무손실 라운드트립 패치 — patchHwpx의 HWP5 대응.
+ *
+ * parse()로 얻은 마크다운을 편집한 뒤 patchHwp()에 넘기면, 원본 HWP의
+ * CFB/레코드 구조를 그대로 두고 변경된 문단/표 셀의 PARA_TEXT만 치환한다.
+ * 연쇄 갱신: PARA_HEADER nChars, CHAR_SHAPE 위치, LINE_SEG 재구성, 레코드
+ * 크기 재계산 → 섹션 스트림 재직렬화 → deflate 재압축 → CFB 재조립.
+ *
+ * 안전 게이트 (하나라도 깨지면 해당 수정은 graceful skip — 파일 무결성 우선):
+ *  - 섹션 레코드 재직렬화가 원본과 바이트 동일해야 패치 허용
+ *  - ctrlMask=0(순수 텍스트) + PARA_TEXT 1개 + 레코드 텍스트 재구성 일치 문단만 수정
+ *  - 배포용/암호화/DRM 문서는 전체 거부
+ *
+ * 지원: 본문 문단/헤딩 텍스트 수정, GFM 표 셀 텍스트 수정 (좌표 기반).
+ * 미지원(graceful skip): 블록 추가/삭제, 표 구조 변경, HTML 표 셀, 캡션·각주·
+ * 머리말/꼬리말, 컨트롤(탭/개체/필드) 포함 문단. skipped[]에 사유 보고.
+ */
+
+/**
+ * 원본 HWP 5.x와 편집된 마크다운으로 서식 보존 패치본을 만든다.
+ *
+ * @param original 원본 HWP 바이트 (OLE2/CFB)
+ * @param editedMarkdown parse(original).markdown을 편집한 마크다운
+ */
+declare function patchHwp(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
+
 /**
  * Print Renderer — Markdown / IRBlock[] → PDF (puppeteer-core 기반).
  *
@@ -519,4 +604,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, string>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { type BlockDiff, type BoundingBox, 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 FormResult, type HwpxFillResult, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PrintOptions, type PrintPreset, VERSION, type WarningCode, type WatchOptions, 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, renderHtml };
+export { type BlockDiff, type BoundingBox, 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 FormResult, type HwpxFillResult, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type OcrProvider, type OutlineItem, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PrintOptions, type PrintPreset, VERSION, type WarningCode, type WatchOptions, 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, patchHwp, patchHwpx, renderHtml };