kordoc 2.5.2 → 2.7.1

package/dist/index.d.cts

@@ -108,6 +108,21 @@ interface ParseOptions {
     removeHeaderFooter?: boolean;
     /** 원본 파일 경로 (DRM COM fallback에 필요, 내부 전용) */
     filePath?: string;
+    /**
+     * PDF 수식 OCR 활성화 (기본 false).
+     *
+     * 활성화 시 각 PDF 페이지를 이미지로 렌더링 → YOLOv8 기반 수식 영역 검출 →
+     * TrOCR 기반 LaTeX 인식. 감지된 수식은 `$...$` (inline) / `$$...$$` (display) 로
+     * 블록 텍스트에 삽입된다.
+     *
+     * 필수 optional 의존성: `onnxruntime-node`, `@huggingface/transformers`,
+     * `@hyzyla/pdfium`, `sharp`. 미설치 시 parse 에 실패하지 않고 **경고만** 남기고
+     * 수식 인식은 skip 한다 (일반 텍스트 추출은 정상 동작).
+     *
+     * 모델(~155MB) 은 첫 사용 시 HuggingFace 에서 자동 다운로드 되어
+     * `~/.cache/kordoc/models/pix2text/` 에 SHA-256 검증과 함께 저장된다.
+     */
+    formulaOcr?: boolean;
 }
 /** 파싱 중 스킵/실패한 요소 보고 */
 interface ParseWarning {
@@ -127,7 +142,7 @@ interface OutlineItem {
 }
 /** 구조화된 에러 코드 — 프로그래밍적 에러 핸들링용 */
 type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "MISSING_DEPENDENCY";
-type FileType = "hwpx" | "hwp" | "hwpml" | "pdf" | "xlsx" | "docx" | "unknown";
+type FileType = "hwpx" | "hwp" | "hwp3" | "hwpml" | "pdf" | "xlsx" | "xls" | "docx" | "unknown";
 interface ParseResultBase {
     fileType: FileType;
     /** 페이지/섹션 수 — PDF: 실제 페이지 수, HWP/HWPX: 섹션 수, XLSX: 시트 수 */
@@ -305,6 +320,51 @@ declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string
  */
 declare function markdownToHwpx(markdown: string): Promise<ArrayBuffer>;
 
+/**
+ * Print Renderer — Markdown / IRBlock[] → PDF (puppeteer-core 기반).
+ *
+ * 흐름:
+ *   blocks → markdown (blocksToMarkdown)
+ *   markdown → HTML (markdown-it)
+ *   HTML + 프리셋 CSS → PDF (puppeteer-core)
+ *
+ * puppeteer-core는 optional peer dep. 미설치 시 markdownToPdf는 명확한 에러를 던지지만
+ * `renderHtml()`은 항상 동작 (외부 PDF 엔진과 결합용).
+ *
+ * 참조: docs/SPEC.md §1.3
+ */
+
+type PrintPreset = "default" | "gov-formal" | "compact";
+interface PageMargin {
+    top: string | number;
+    right: string | number;
+    bottom: string | number;
+    left: string | number;
+}
+interface PrintOptions {
+    preset?: PrintPreset;
+    pageSize?: "A4" | "Letter";
+    orientation?: "portrait" | "landscape";
+    margin?: PageMargin;
+    /** 페이지 머리글 (HTML 허용, gov-formal 프리셋에서 자동 표시) */
+    header?: string;
+    /** 페이지 바닥글 (HTML 허용) */
+    footer?: string;
+    /** 워터마크 텍스트 (대각선 회색) */
+    watermark?: string;
+    /** 사용자 정의 추가 CSS */
+    extraCss?: string;
+}
+/**
+ * Markdown 또는 IRBlock[] → HTML 문자열.
+ * 외부 PDF 엔진(weasyprint, wkhtmltopdf 등)과 결합 가능.
+ */
+declare function renderHtml(markdown: string, options?: PrintOptions): string;
+/** Markdown → PDF (Buffer). */
+declare function markdownToPdf(markdown: string, options?: PrintOptions): Promise<Buffer>;
+/** IRBlock[] → PDF (Buffer). */
+declare function blocksToPdf(blocks: IRBlock[], options?: PrintOptions): Promise<Buffer>;
+
 /** 매직 바이트 기반 파일 포맷 감지 */
 
 /** ZIP 파일 여부: PK\x03\x04 */
@@ -317,6 +377,13 @@ declare function isOldHwpFile(buffer: ArrayBuffer): boolean;
 declare function isPdfFile(buffer: ArrayBuffer): boolean;
 /** 동기 포맷 감지 — ZIP은 모두 "hwpx"로 반환 (하위 호환) */
 declare function detectFormat(buffer: ArrayBuffer): FileType;
+/**
+ * OLE2 컨테이너 내부 스트림 기반 포맷 세분화.
+ * HWP 5.x, XLS 모두 OLE2이므로 스트림 이름으로 구분.
+ *  - "Workbook" 또는 "Book" → 'xls'
+ *  - 그 외 (FileHeader 등) → 'hwp'
+ */
+declare function detectOle2Format(buffer: ArrayBuffer): "hwp" | "xls" | "unknown";
 /**
  * ZIP 내부 구조 기반 포맷 세분화.
  * HWPX, XLSX, DOCX 모두 ZIP이므로 내부 파일로 구분.
@@ -343,6 +410,8 @@ declare const VERSION: string;
  * ```
  */
 declare function parse(input: string | ArrayBuffer | Buffer, options?: ParseOptions): Promise<ParseResult>;
+/** HWP 3.x (구버전 한컴 워드프로세서) 파일을 Markdown 으로 변환. */
+declare function parseHwp3(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWPX 파일을 Markdown으로 변환 */
 declare function parseHwpx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWP 5.x 바이너리 파일을 Markdown으로 변환 */
@@ -351,6 +420,8 @@ declare function parseHwp(buffer: ArrayBuffer, options?: ParseOptions): Promise<
 declare function parsePdf(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** XLSX 파일을 Markdown으로 변환 */
 declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
+/** XLS (Excel 97-2003) 파일을 Markdown으로 변환 */
+declare function parseXls(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWPML (XML 기반 한컴 문서) 파일을 Markdown으로 변환 */
@@ -394,4 +465,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 ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, fillForm, fillFormFields, fillHwpx, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpml, parseHwpx, parsePdf, parseXlsx };
+export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type PageMargin, 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 };

package/dist/index.d.ts

@@ -108,6 +108,21 @@ interface ParseOptions {
     removeHeaderFooter?: boolean;
     /** 원본 파일 경로 (DRM COM fallback에 필요, 내부 전용) */
     filePath?: string;
+    /**
+     * PDF 수식 OCR 활성화 (기본 false).
+     *
+     * 활성화 시 각 PDF 페이지를 이미지로 렌더링 → YOLOv8 기반 수식 영역 검출 →
+     * TrOCR 기반 LaTeX 인식. 감지된 수식은 `$...$` (inline) / `$$...$$` (display) 로
+     * 블록 텍스트에 삽입된다.
+     *
+     * 필수 optional 의존성: `onnxruntime-node`, `@huggingface/transformers`,
+     * `@hyzyla/pdfium`, `sharp`. 미설치 시 parse 에 실패하지 않고 **경고만** 남기고
+     * 수식 인식은 skip 한다 (일반 텍스트 추출은 정상 동작).
+     *
+     * 모델(~155MB) 은 첫 사용 시 HuggingFace 에서 자동 다운로드 되어
+     * `~/.cache/kordoc/models/pix2text/` 에 SHA-256 검증과 함께 저장된다.
+     */
+    formulaOcr?: boolean;
 }
 /** 파싱 중 스킵/실패한 요소 보고 */
 interface ParseWarning {
@@ -127,7 +142,7 @@ interface OutlineItem {
 }
 /** 구조화된 에러 코드 — 프로그래밍적 에러 핸들링용 */
 type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "MISSING_DEPENDENCY";
-type FileType = "hwpx" | "hwp" | "hwpml" | "pdf" | "xlsx" | "docx" | "unknown";
+type FileType = "hwpx" | "hwp" | "hwp3" | "hwpml" | "pdf" | "xlsx" | "xls" | "docx" | "unknown";
 interface ParseResultBase {
     fileType: FileType;
     /** 페이지/섹션 수 — PDF: 실제 페이지 수, HWP/HWPX: 섹션 수, XLSX: 시트 수 */
@@ -305,6 +320,51 @@ declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, string
  */
 declare function markdownToHwpx(markdown: string): Promise<ArrayBuffer>;
 
+/**
+ * Print Renderer — Markdown / IRBlock[] → PDF (puppeteer-core 기반).
+ *
+ * 흐름:
+ *   blocks → markdown (blocksToMarkdown)
+ *   markdown → HTML (markdown-it)
+ *   HTML + 프리셋 CSS → PDF (puppeteer-core)
+ *
+ * puppeteer-core는 optional peer dep. 미설치 시 markdownToPdf는 명확한 에러를 던지지만
+ * `renderHtml()`은 항상 동작 (외부 PDF 엔진과 결합용).
+ *
+ * 참조: docs/SPEC.md §1.3
+ */
+
+type PrintPreset = "default" | "gov-formal" | "compact";
+interface PageMargin {
+    top: string | number;
+    right: string | number;
+    bottom: string | number;
+    left: string | number;
+}
+interface PrintOptions {
+    preset?: PrintPreset;
+    pageSize?: "A4" | "Letter";
+    orientation?: "portrait" | "landscape";
+    margin?: PageMargin;
+    /** 페이지 머리글 (HTML 허용, gov-formal 프리셋에서 자동 표시) */
+    header?: string;
+    /** 페이지 바닥글 (HTML 허용) */
+    footer?: string;
+    /** 워터마크 텍스트 (대각선 회색) */
+    watermark?: string;
+    /** 사용자 정의 추가 CSS */
+    extraCss?: string;
+}
+/**
+ * Markdown 또는 IRBlock[] → HTML 문자열.
+ * 외부 PDF 엔진(weasyprint, wkhtmltopdf 등)과 결합 가능.
+ */
+declare function renderHtml(markdown: string, options?: PrintOptions): string;
+/** Markdown → PDF (Buffer). */
+declare function markdownToPdf(markdown: string, options?: PrintOptions): Promise<Buffer>;
+/** IRBlock[] → PDF (Buffer). */
+declare function blocksToPdf(blocks: IRBlock[], options?: PrintOptions): Promise<Buffer>;
+
 /** 매직 바이트 기반 파일 포맷 감지 */
 
 /** ZIP 파일 여부: PK\x03\x04 */
@@ -317,6 +377,13 @@ declare function isOldHwpFile(buffer: ArrayBuffer): boolean;
 declare function isPdfFile(buffer: ArrayBuffer): boolean;
 /** 동기 포맷 감지 — ZIP은 모두 "hwpx"로 반환 (하위 호환) */
 declare function detectFormat(buffer: ArrayBuffer): FileType;
+/**
+ * OLE2 컨테이너 내부 스트림 기반 포맷 세분화.
+ * HWP 5.x, XLS 모두 OLE2이므로 스트림 이름으로 구분.
+ *  - "Workbook" 또는 "Book" → 'xls'
+ *  - 그 외 (FileHeader 등) → 'hwp'
+ */
+declare function detectOle2Format(buffer: ArrayBuffer): "hwp" | "xls" | "unknown";
 /**
  * ZIP 내부 구조 기반 포맷 세분화.
  * HWPX, XLSX, DOCX 모두 ZIP이므로 내부 파일로 구분.
@@ -343,6 +410,8 @@ declare const VERSION: string;
  * ```
  */
 declare function parse(input: string | ArrayBuffer | Buffer, options?: ParseOptions): Promise<ParseResult>;
+/** HWP 3.x (구버전 한컴 워드프로세서) 파일을 Markdown 으로 변환. */
+declare function parseHwp3(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWPX 파일을 Markdown으로 변환 */
 declare function parseHwpx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWP 5.x 바이너리 파일을 Markdown으로 변환 */
@@ -351,6 +420,8 @@ declare function parseHwp(buffer: ArrayBuffer, options?: ParseOptions): Promise<
 declare function parsePdf(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** XLSX 파일을 Markdown으로 변환 */
 declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
+/** XLS (Excel 97-2003) 파일을 Markdown으로 변환 */
+declare function parseXls(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions): Promise<ParseResult>;
 /** HWPML (XML 기반 한컴 문서) 파일을 Markdown으로 변환 */
@@ -394,4 +465,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 ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, fillForm, fillFormFields, fillHwpx, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, parse, parseDocx, parseHwp, parseHwpml, parseHwpx, parsePdf, parseXlsx };
+export { type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FillFormOutput, type FillOutputFormat, type FillResult, type FormField, type FormResult, type HwpxFillResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type OcrProvider, type OutlineItem, type PageMargin, 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 };