kordoc 3.0.0 → 3.1.1

package/dist/index.d.ts

@@ -260,7 +260,7 @@ interface PatchOptions {
     /** 패치 후 재파싱 자동 검증 (기본 true) */
     verify?: boolean;
 }
-/** patchHwpx 결과 */
+/** patchHwpx / patchBlocks 결과 */
 interface PatchResult {
     success: boolean;
     /** 패치된 HWPX (success=true) */
@@ -269,8 +269,18 @@ interface PatchResult {
     applied: number;
     /** 매핑 실패 항목 (이유 포함) */
     skipped: PatchSkip[];
-    /** 자동 검증: 패치본 재파싱 vs 편집 마크다운 diff */
+    /**
+     * 무손실 검증 (patchHwpx/patchHwp 전용): 패치본 재파싱 vs 편집 마크다운의
+     * 잔차 diff — modified/added/removed가 0이어야 의도가 전부 반영된 것.
+     * session.patchBlocks는 이 필드를 채우지 않는다 (changes 참조).
+     */
     verification?: DiffResult;
+    /**
+     * 변경 가시화 (session.patchBlocks 전용): 패치 전 → 후 문서 diff —
+     * 적용된 편집 수만큼 modified가 나오는 것이 정상. verification과 의미가
+     * 정반대이므로 혼용 금지.
+     */
+    changes?: DiffResult;
     /** 실패 사유 (success=false) */
     error?: string;
 }
@@ -317,6 +327,28 @@ declare function isLabelCell(text: string): boolean;
  * 테이블의 label-value 패턴을 감지.
  */
 declare function extractFormFields(blocks: IRBlock[]): FormResult;
+/** 양식 필드 타입 — 폼 UI 위젯 선택의 근거 (데이트피커/체크박스 등) */
+type FormFieldType = "text" | "date" | "phone" | "email" | "amount" | "checkbox" | "idnum";
+/** 타입이 추론된 양식 필드 */
+interface FormFieldSchema extends FormField {
+    type: FormFieldType;
+    /** 라벨에 필수 표시(※·*·★·"(필수)")가 있을 때만 true */
+    required?: boolean;
+    /** 값이 비어 있거나 플레이스홀더(밑줄/괄호 빈칸)뿐 — 채움 대상 */
+    empty: boolean;
+}
+interface FormSchemaResult {
+    fields: FormFieldSchema[];
+    /** 양식 확신도 (0-1, extractFormFields와 동일) */
+    confidence: number;
+}
+/** 필드 타입 추론 — 기존 값의 패턴 우선, 없으면 라벨 키워드 */
+declare function inferFieldType(label: string, value: string): FormFieldType;
+/**
+ * 양식 필드 인식 + 타입/필수/빈값 추론 — 폼 UI 자동 생성용 (v3.1).
+ * extractFormFields 결과에 type(date/phone/amount/checkbox/...)·required·empty를 부여한다.
+ */
+declare function extractFormSchema(blocks: IRBlock[]): FormSchemaResult;
 
 /** 양식 서식 필드 값 채우기 — IRBlock[] 기반 in-place 교체 */
 
@@ -350,10 +382,26 @@ interface FillResult {
 declare function fillFormFields(blocks: IRBlock[], values: Record<string, string>): FillResult;
 
 /**
- * HWPX 원본 서식 유지 채우기 — ZIP 내 section XML 직접 수정
+ * HWPX 원본 서식 유지 채우기 — section XML 오프셋 splice (v3.1, 바이트 보존)
  *
- * IRBlock 중간 표현을 거치지 않고, 원본 HWPX ZIP의 section XML에서
- * 테이블 셀 텍스트(<hp:t>)만 교체하여 모든 스타일을 보존합니다.
+ * v3.0까지는 xmldom 전체 재직렬화 방식이라 변경하지 않은 영역도 속성 순서·
+ * 공백·자기닫힘 표기가 바뀔 수 있었다. v3.1부터 patchHwpx와 동일한
+ * source-map splice + ZIP in-place 재조립을 사용해, 변경 문단 외 XML과
+ * 비변경 ZIP 엔트리를 1바이트도 건드리지 않는다.
+ *
+ * 전략 (v3.0과 동일, 적용 순서 보존):
+ * 0. 인셀 패턴 — 체크박스 □→☑, 괄호 빈칸 (  )→(값), 어노테이션 (한자：)→(한자：값)
+ * 1. 인접 라벨-값 셀 — label | value (패턴 적용 셀은 값을 앞에 삽입해 어노테이션 보존)
+ * 2. 헤더+데이터 행 — 첫 행이 전부 라벨이면 열 단위 매칭 (나중 쓰기 우선 — v3.0 동일)
+ * 3. 인라인 "라벨: 값" — 표 밖 본문/글상자/머리말·꼬리말·각주 문단
+ *
+ * 적용 범위는 v3.0과 동일하게 머리말/꼬리말 등 ctrl 내부 표·문단을 포함하고
+ * (scan.orphanTables/excludedParagraphs), 셀 라벨 판정은 v3.0과 동일하게
+ * 글상자(drawText) 문단을 제외한다. 패턴 매칭·범위 치환은 hp:t 연결 텍스트
+ * (t-도메인) 좌표로 수행해 사이에 끼인 tab/br 요소를 건드리지 않는다.
+ *
+ * v3.0과의 의도적 차이: 인셀 패턴(전략 0)은 문단 단위로 매칭한다 — 문단
+ * 경계에 걸친 패턴(극히 드묾)은 채우지 않는다.
  */
 
 /** 채우기 결과 */
@@ -412,6 +460,122 @@ interface MarkdownToHwpxOptions {
  */
 declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOptions): Promise<ArrayBuffer>;
 
+/**
+ * HWPX 라운드트립 소스맵 — section XML 문자열에서 문단/표 셀의 문자 범위를 추적.
+ *
+ * DOM 재직렬화를 거치지 않고(속성 순서·공백·자기닫힘 표기까지 보존하기 위해)
+ * 정규식 토크나이저로 태그를 순회하며, 각 <hp:p>가 소유한 <hp:t> 콘텐츠 범위를
+ * 기록한다. 패치는 이 범위에 대한 문자열 splice로만 수행되어
+ * 변경 문단 외 XML 바이트가 그대로 보존된다 (filler-hwpx.ts 패턴의 오프셋 버전).
+ */
+/** <hp:t> 콘텐츠 범위 — [contentStart, contentEnd) 가 여는/닫는 태그 사이 */
+interface TRange {
+    contentStart: number;
+    contentEnd: number;
+    /** 자기닫힘 <hp:t/> — 범위가 태그 전체이며, 치환 시 태그째 교체 */
+    selfClosing?: boolean;
+    /** 자기닫힘 치환용 네임스페이스 프리픽스 (예: "hp") */
+    prefix?: string;
+}
+type ScanParaKind = "body" | "cell" | "draw" | "excluded";
+/** 스캔된 문단 — 소유한 hp:t 범위와 합산 텍스트 */
+interface ScanParagraph {
+    sectionIndex: number;
+    kind: ScanParaKind;
+    /** <hp:p ...> 여는 태그 시작 위치 (문서 순서 정렬용) */
+    start: number;
+    /** 소유 hp:t 콘텐츠 범위 (문서 순서) */
+    tRanges: TRange[];
+    /** hp:t 텍스트 합산 (엔티티 디코딩, 내부 태그는 공백화) */
+    text: string;
+    /** hp:t가 하나도 없을 때 텍스트 삽입 가능한 위치 (첫 run 닫는 태그 앞) */
+    runInsertPos?: number;
+    /** runInsertPos에 삽입할 때 쓸 t 태그 prefix (예: "hp") */
+    runPrefix?: string;
+    /** 자기닫힘 <hp:run/> 태그 범위 — t 삽입 시 펼쳐서 사용 (한컴 빈 문단 패턴) */
+    selfCloseRun?: {
+        start: number;
+        end: number;
+    };
+    /** 글상자(drawText) 경유 문단 — 셀 라벨 판정 등에서 본문과 구분 (v3.1) */
+    inTextbox?: boolean;
+}
+/** 스캔된 표 셀 — 앵커 좌표와 셀 내부 문단 */
+interface ScanCell {
+    rowAddr?: number;
+    colAddr?: number;
+    colSpan: number;
+    rowSpan: number;
+    paragraphs: ScanParagraph[];
+    /** 셀 내부 중첩표 (문서 순서) */
+    tables: ScanTable[];
+}
+/** 스캔된 표 */
+interface ScanTable {
+    sectionIndex: number;
+    start: number;
+    /** 최상위 표 여부 (다른 표/ctrl/캡션 내부가 아님) */
+    topLevel: boolean;
+    /** 비어있지 않은 행들 (tr 순서) */
+    rows: ScanCell[][];
+    /** 앵커 좌표 → 셀 ("r,c") */
+    cellByAnchor: Map<string, ScanCell>;
+}
+/** 섹션 하나의 스캔 결과 */
+interface SectionScan {
+    sectionIndex: number;
+    xml: string;
+    /** body + draw 문단 (문서 순서) — 본문 텍스트 매핑 대상 */
+    bodyParagraphs: ScanParagraph[];
+    /** 최상위 표 (문서 순서) */
+    tables: ScanTable[];
+    /** 머리말/꼬리말 문단 텍스트 (OB 앞/뒤 배치 블록 식별용) */
+    headerTexts: string[];
+    footerTexts: string[];
+    /**
+     * 파서 비가시 영역(머리말/꼬리말/각주/캡션/메모 등 ctrl 내부) 문단 — v3.1.
+     * patcher 매핑 대상이 아니며, filler가 이 영역의 인라인 패턴을 채울 때 사용.
+     */
+    excludedParagraphs: ScanParagraph[];
+    /**
+     * 어느 셀에도 속하지 않는 비최상위 표(머리말/꼬리말 등 ctrl 내부) — v3.1.
+     * filler 전용. patcher의 표 서수 매핑(tables)에는 포함되지 않는다.
+     */
+    orphanTables: ScanTable[];
+}
+/** 문자열 splice 편집 — [start, end) 를 replacement로 치환 */
+interface SpliceEdit {
+    start: number;
+    end: number;
+    replacement: string;
+}
+/**
+ * section XML 한 개를 스캔하여 소스맵을 만든다.
+ * 토크나이저는 xmldom과 무관하게 동작하며, 위치(오프셋) 정보가 핵심이다.
+ */
+declare function scanSectionXml(xml: string, sectionIndex: number): SectionScan;
+/**
+ * 문단 텍스트 치환용 splice 생성 — filler-hwpx.ts replaceCellText와 동일 전략:
+ * 첫 hp:t에 새 텍스트(이스케이프), 나머지 hp:t는 비움. run 구조/charPr 보존.
+ * t가 없으면 첫 run 끝에 <hp:t> 삽입. 실패 시 null.
+ *
+ * IR 텍스트는 sanitize로 양끝 공백이 제거된 상태라, 통째 교체 시 원본의
+ * 선행 공백(들여쓰기)/후행 공백이 소실된다 — 원본 t-도메인 텍스트에서
+ * 양끝 공백을 복원해 새 텍스트에 입힌다 (재파싱 IR은 동일하게 유지됨).
+ */
+declare function buildParagraphSplices(para: ScanParagraph, newText: string, xml?: string): SpliceEdit[] | null;
+/**
+ * t-도메인 텍스트(paraTText 좌표계)의 [start, end) 범위만 치환하는 정밀 splice
+ * — run/탭 구조 보존 (v3.1).
+ *
+ * 좌표계가 t-도메인이므로 tab/br이 사이에 끼어 있어도 동작한다 (해당 요소는
+ * 건드리지 않고 t 콘텐츠만 수술). hp:t 콘텐츠에 엔티티/내부 태그가 있으면
+ * 오프셋 정합이 깨지므로 null을 반환한다 (호출자가 폴백 결정).
+ */
+declare function buildRangeSplices(para: ScanParagraph, xml: string, start: number, end: number, replacement: string): SpliceEdit[] | null;
+/** splice 일괄 적용 — 겹침 검증 후 뒤에서부터 치환 */
+declare function applySplices(xml: string, splices: SpliceEdit[]): string;
+
 /**
  * HWPX 서식 보존 무손실 라운드트립 패치 — v3.0 킬러기능.
  *
@@ -433,6 +597,125 @@ declare function markdownToHwpx(markdown: string, options?: MarkdownToHwpxOption
  */
 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>;
+
+/**
+ * HWPX 문서 세션 — 에디터 통합용 블록 단위 증분 패치 API (v3.1).
+ *
+ * patchHwpx가 "편집된 마크다운 전체"를 받아 내부에서 LCS 정렬하는 것과 달리,
+ * 세션은 블록 인덱스로 직접 편집을 지정한다 (에디터의 블록 클릭-편집에 대응).
+ *
+ * 설계 원칙:
+ * - 매핑은 patcher와 동일한 알고리즘 재사용 (정규화 텍스트 버킷 + 표 서수) —
+ *   "n회 연속 patchBlocks ≡ 일괄 patchHwpx" 동등성이 성립하는 근거.
+ * - 패치 후 상태는 새 바이트에서 전체 재구축 (오프셋 리베이스 대신 재스캔 —
+ *   성능보다 정합성). patchBlocks 호출 후 이전 블록 인덱스는 무효이며
+ *   session.blocks를 다시 읽어야 한다.
+ * - capability()는 patcher의 graceful-skip 게이트를 사전 판정으로 노출 —
+ *   에디터가 편집 전에 잠금 UI를 띄울 수 있는 단일 진실 소스.
+ */
+
+/** 블록 편집 가능성 — 에디터 잠금 UI의 근거 */
+type BlockCapability = "text" | "cell-text" | "locked";
+interface CellCapability {
+    editable: boolean;
+    /** 편집 불가 사유 (한국어) */
+    reason?: string;
+}
+interface BlockCapabilityInfo {
+    capability: BlockCapability;
+    /** locked 사유 (한국어) */
+    reason?: string;
+    /** 표 블록: IRTable 격자 좌표(row×col)별 셀 편집 가능 여부 */
+    cells?: CellCapability[][];
+}
+/** 블록 → 원본 위치 참조 (에디터 하이라이트/점프용) */
+interface BlockSourceRef {
+    kind: "paragraph" | "table";
+    /** 0-based 섹션 인덱스 */
+    sectionIndex: number;
+    /** 섹션 XML 내 시작 문자 오프셋 (<hp:p>/<hp:tbl> 여는 태그) */
+    xmlStart: number;
+}
+/** 블록 단위 편집 — patchBlocks 입력 */
+interface BlockEdit {
+    /** session.blocks 기준 0-based 블록 인덱스 */
+    blockIndex: number;
+    /**
+     * 문단/헤딩 블록의 새 텍스트 (평문).
+     * 빈 문자열(비우기)은 미지원 — patchHwpx의 "블록 삭제 미지원"과 정합
+     * (비우면 재파싱 시 블록 핸들이 사라져 세션으로 복구 불가).
+     */
+    newText?: string;
+    /** 표 블록의 셀 편집 (IRTable 격자 좌표 기준). 이미지가 든 셀은 이미지
+     *  토큰(`![image](...)`/`[이미지: ...]`)을 유지한 채 텍스트만 수정해야 한다. */
+    cells?: Array<{
+        row: number;
+        col: number;
+        text: string;
+    }>;
+}
+declare class HwpxSession {
+    private state;
+    private constructor();
+    /** HWPX 바이트로 세션을 연다 (입력은 복사되어 외부 변이와 격리) */
+    static open(input: Uint8Array | ArrayBuffer): Promise<HwpxSession>;
+    /** 현재 문서의 IR 블록 — patchBlocks 후 갱신되므로 호출마다 다시 읽을 것 */
+    get blocks(): IRBlock[];
+    /** 현재 문서의 마크다운 */
+    get markdown(): string;
+    /** 현재 문서 바이트 (복사본) */
+    get bytes(): Uint8Array;
+    /** 블록 → 원본 위치 참조. 매핑 실패 시 undefined */
+    sourceRef(blockIndex: number): BlockSourceRef | undefined;
+    /** 블록 편집 가능성 사전 판정 — patcher graceful-skip 게이트의 사전 버전 */
+    capability(blockIndex: number): BlockCapabilityInfo;
+    /** 전 블록의 편집 가능성 */
+    capabilities(): BlockCapabilityInfo[];
+    /**
+     * 블록 단위 증분 패치 — 적용 후 세션 상태가 새 바이트로 갱신된다.
+     *
+     * - 호출은 내부적으로 직렬화된다 (동시 호출 시 도착 순서대로 누적 적용)
+     * - 무변경 편집(현재 텍스트와 동일)은 조용히 건너뜀 (applied/skipped 모두 제외)
+     * - 변경이 하나도 적용되지 않으면 반환 data는 현재 문서와 바이트 동일
+     * - changes는 "패치 전 → 후" 문서 diff — modified 수가 기대 편집 수와
+     *   일치하는지 확인 용도. patchHwpx의 verification(잔차 검증)과 의미가 다르다.
+     */
+    patchBlocks(edits: BlockEdit[], options?: PatchOptions): Promise<PatchResult>;
+    private opQueue;
+    private patchBlocksInner;
+    /** 문단/헤딩 평문 편집 — patcher.patchParagraphUnit의 평문 입력 버전 */
+    private patchParagraphPlain;
+}
+/** HWPX 문서 세션 열기 */
+declare function openHwpxDocument(input: Uint8Array | ArrayBuffer): Promise<HwpxSession>;
+/** 원샷 블록 패치 — 세션 없이 한 번에 (stateless RPC용) */
+declare function patchHwpxBlocks(original: Uint8Array | ArrayBuffer, edits: BlockEdit[], options?: PatchOptions): Promise<PatchResult>;
+
 /**
  * Print Renderer — Markdown / IRBlock[] → PDF (puppeteer-core 기반).
  *
@@ -578,4 +861,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 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, patchHwpx, renderHtml };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BoundingBox, type CellCapability, 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 FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type HwpxFillResult, HwpxSession, 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, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, type WarningCode, type WatchOptions, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, scanSectionXml };