kordoc 3.13.0 → 3.16.0

package/dist/index.d.cts

@@ -296,6 +296,8 @@ interface FormField {
     row: number;
     /** 0-based 소스 열 */
     col: number;
+    /** 매칭된 입력 키(정규화) — 모호 라벨 거부 가드(fillWithUniqueGuard)의 집계 기준 */
+    key?: string;
 }
 interface FormResult {
     fields: FormField[];
@@ -319,6 +321,21 @@ interface WatchOptions {
  * 배열이면 등장 순서대로 하나씩 소진(2~30장 반복 양식·명부형 표).
  */
 type FillValue = string | string[];
+/**
+ * 채울 값 입력 — 값만 주거나, 서식 변환(format)을 함께 지정한다.
+ * 프로필엔 정준값 하나(생년월일 "19900315"), 서식마다 모양이 다를 때
+ * format이 도구 안에서 변환한다 (claw-hwp secure-fill 포맷엔진 이식).
+ */
+type FillInput = FillValue | {
+    value: FillValue;
+    format?: string;
+};
+/**
+ * 값 서식 변환 — `종류:스타일` 접두형(date:/phone:/rrn:/mask:/digits/upper/lower/nospace)
+ * 또는 접두 없는 자유 패턴(`#` 포함 → 숫자마스크, yyyy·yy·mm·dd 포함 → 날짜 토큰).
+ * 모르는 포맷은 값 원형 반환 (fail-open — 채움 자체는 진행).
+ */
+declare function formatFillValue(value: string, format?: string): string;
 /**
  * 다중값 커서 — 라벨별 값 소비 상태를 추적한다.
  * 스칼라 값은 무한 반복(기존 동작), 배열 값은 적용 순서대로 소진되며
@@ -338,6 +355,20 @@ declare class ValueCursor {
     /** 값 소비 — 배열이면 커서 전진, 소진 시 undefined */
     consume(key: string): string | undefined;
 }
+/**
+ * 모호 라벨 거부 가드 — 한 입력 키(스칼라)가 서식의 2곳 이상에 채워지면 남의 블록
+ * 오염 위험(대표자 행에 참여인력 값이 들어가는 류)이므로, 그 키는 채우지 않고
+ * rejected로 보고한 뒤 나머지 키만으로 다시 채운다 (claw-hwp require_occurrence 이식).
+ * 배열 값은 다중 등장 소진이 의도된 동작이라 거부 대상이 아니다.
+ * @param run 같은 원본에 대해 결정적으로 재실행 가능한 채우기 함수
+ */
+declare function fillWithUniqueGuard<R extends {
+    filled: Array<{
+        key?: string;
+    }>;
+}>(values: Record<string, FillInput>, run: (vals: Record<string, FillInput>) => R | Promise<R>): Promise<R & {
+    rejected: string[];
+}>;
 
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
@@ -412,7 +443,7 @@ interface FillResult {
  * })
  * ```
  */
-declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillValue>): FillResult;
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillInput>): FillResult;
 
 /**
  * HWPX 원본 서식 유지 채우기 — section XML 오프셋 splice (v3.1, 바이트 보존)
@@ -455,7 +486,71 @@ interface HwpxFillResult {
  *   문자열이면 기존처럼 모든 등장에 동일값.
  * @returns HwpxFillResult
  */
-declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillValue>): Promise<HwpxFillResult>;
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillInput>): Promise<HwpxFillResult>;
+
+/**
+ * place_seal — 도장/서명 이미지를 앵커 문구("(인)"·"서명 또는 인" 등) 위에
+ * 부유(글 앞) 배치. 표/페이지 불확장 (P6, claw-hwp placeSeal 이식).
+ *
+ * 원리:
+ * - 앵커 문구가 든 문단을 찾아 그 문단에 <hp:pic> 부유 개체를 anchor 한다.
+ *   핵심 속성: treatAsChar="0" + flowWithText="0" + allowOverlap="1" +
+ *   textWrap="IN_FRONT_OF_TEXT" — flowWithText="1"이면 한컴이 개체 높이만큼
+ *   셀/페이지를 키운다 (claw-hwp GT 검증 규칙).
+ * - 수평 위치는 폰트 메트릭으로 계산: 전각(한글/CJK)=1em, ASCII·반각=0.5em,
+ *   em = 앵커 run charPr 높이(1/100pt). 렌더 없이 배치하고 렌더는 검증용.
+ * - 가운데/오른쪽 정렬 문단(서식 셀에 흔함)은 블록 전체가 밀리므로
+ *   (사용가능폭 − 문단폭)의 정렬 이동분을 x에 더한다.
+ * - 위치 프레임은 PARA(문단 좌상단 기준) — 한컴은 문단 위로는 못 올라가게
+ *   클램프하므로, 여유 공간이 있는 표 셀에서는 줄 세로 중앙에 앉고 본문
+ *   최상단 줄에서는 상단 정렬로 눕는다.
+ *
+ * 적용 범위: 본문/표 셀/글상자 문단 (머리말·꼬리말·각주 내 앵커는 제외).
+ * ZIP 재조립은 patchZipEntries — 비변경 엔트리는 1바이트도 건드리지 않고,
+ * 도장 PNG는 BinData 신규 엔트리 + manifest(opf:item) 등재로 추가한다.
+ */
+/** 도장 배치 요청 */
+interface SealOp {
+    /** 앵커 문구 (예: "(인)", "서명 또는 인") */
+    anchor: string;
+    /** 같은 앵커가 여럿일 때 0-based 선택 (기본 0) */
+    occurrence?: number;
+    /** 도장/서명 이미지 바이트 (투명 배경 PNG 권장) */
+    image: Uint8Array;
+    /** 이미지 확장자 (기본 png) */
+    ext?: "png" | "jpg" | "jpeg" | "bmp" | "gif";
+    /** 도장 한 변 크기 mm (기본: 줄높이×1.6, 7~18mm 클램프) */
+    sizeMm?: number;
+    /** overlap=문구 위에 겹침, right=문구 오른쪽 옆, auto=공간 있으면 right (기본 auto) */
+    mode?: "overlap" | "right" | "auto";
+    /** 미세조정 mm */
+    dxMm?: number;
+    dyMm?: number;
+}
+/** 배치 결과 (도장 1개당 1건) */
+interface SealPlacement {
+    anchor: string;
+    occurrence: number;
+    sectionIndex: number;
+    mode: "overlap" | "right";
+    posXMm: number;
+    posYMm: number;
+    sizeMm: number;
+    /** ZIP에 추가된 이미지 파트 경로 (BinData/imageN.ext) */
+    entry: string;
+}
+interface PlaceSealResult {
+    buffer: ArrayBuffer;
+    placed: SealPlacement[];
+}
+/**
+ * HWPX에 도장/서명 이미지를 앵커 문구 기준으로 부유 배치한다.
+ *
+ * @param hwpxBuffer 원본 HWPX
+ * @param ops 도장 배치 요청 (여러 개 가능 — 같은 이미지 재사용 시에도 op마다 파트가 추가됨)
+ * @throws KordocError 앵커 미발견 (본문 내 등장 횟수를 메시지에 포함)
+ */
+declare function placeSealHwpx(hwpxBuffer: ArrayBuffer, ops: SealOp[]): Promise<PlaceSealResult>;
 
 /**
  * 공문서(公文書) 모드 — 한국 행정 공문서 표준 서식 렌더링 로직
@@ -802,6 +897,33 @@ declare function patchHwpx(original: Uint8Array, editedMarkdown: string, options
  */
 declare function patchHwp(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
 
+/**
+ * HWPX 구조 검증 — 한컴오피스/한컴독스가 열기를 거부하는 컨테이너 결함을 사전에 잡는다.
+ *
+ * 검사 항목 (claw-hwp validate.py의 실측 검사셋 이식 — MIT © DoHyun468/claw-hwp):
+ * - 유효한 ZIP인지, mimetype이 첫 엔트리이고 내용이 application/hwp+zip인지
+ * - 필수 파일 존재 (META-INF/container.xml, content.hpf, header.xml, section0.xml)
+ * - XML/HPF/RDF 엔트리 웰폼드
+ * - header.xml secCnt == 실제 Contents/sectionN.xml 수
+ *   (한컴독스는 실제 파일 목록이 아니라 secCnt를 신뢰하고, 불일치 시 열기를 거부한다)
+ * - content.hpf manifest의 <opf:item href>가 전부 실존하는지
+ */
+/** 검증에서 발견된 문제 하나 */
+interface ValidateIssue {
+    /** 문제가 발견된 zip 내부 경로 (컨테이너 전역 문제면 생략) */
+    path?: string;
+    message: string;
+}
+/** validateHwpx 결과 */
+interface ValidateResult {
+    ok: boolean;
+    issues: ValidateIssue[];
+    /** 검사한 zip 엔트리 수 (디렉토리 제외) */
+    entryCount: number;
+}
+/** HWPX 버퍼의 컨테이너 구조를 검증한다. 문제가 없으면 ok=true. */
+declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<ValidateResult>;
+
 /**
  * HWPX 문서 세션 — 에디터 통합용 블록 단위 증분 패치 API (v3.1).
  *
@@ -955,17 +1077,33 @@ declare function blocksToPdf(blocks: IRBlock[], options?: PrintOptions): Promise
  * - 좌표 속성엔 uint32로 저장된 음수가 섞여 있다(toInt32 필수).
  * - 표 열은 span 제약 경계 전파로, 행은 rs=1 max + 콘텐츠 초과 성장으로 푼다.
  *
- * 범위: 1페이지(section0) 한정, 수식·그리기개체 도형은 미지원(경고 수집).
+ * 페이지: 최상위 lineseg vertpos는 페이지 로컬(페이지마다 0부터 리셋)이므로 역행
+ *   지점을 페이지 경계로 감지, 전 페이지를 세로 스택으로 그린다(페이지별 흰 배경 +
+ *   클립). 페이지에 걸친 표는 시작 페이지에서 잘린다(조판 캐시에 분할점이 없음).
+ *
+ * 범위: section0 한정(다중 구역은 첫 구역만), 수식·그리기개체 도형은 미지원(경고 수집).
  */
+
 interface RenderSvgOptions {
     /** 이미지 1장당 허용 최대 바이트 (기본 40MB) */
     maxImageBytes?: number;
+    /** 검색어 형광펜 — 텍스트 조각 내 매치 구간에 배경 rect (대소문자 무시).
+     *  charPr(스타일) 경계에 걸친 매치는 칠하지 못한다. */
+    highlights?: string[];
+    /** Tier-2 reflow — 조판 캐시(linesegarray) 없는 파일도 순수 TS 조판으로 렌더.
+     *  캐시가 있으면 무시(한컴본은 캐시 재생). 기본 false(캐시 없으면 KordocError). */
+    reflow?: boolean;
+    /** reflow 줄바꿈 모드 — 'keep'(어절, Windows 한글·공문서) / 'charAll'(글자, macOS·전자결재) */
+    reflowMode?: WrapMode;
 }
 interface RenderSvgResult {
     svg: string;
-    /** 페이지 크기 (pt) */
+    /** 페이지 폭 (pt) */
     width: number;
+    /** 전체 캔버스 높이 (pt) — 페이지 세로 스택 + 간격 */
     height: number;
+    /** 렌더된 페이지 수 */
+    pageCount: number;
     warnings: string[];
     stats: {
         texts: number;
@@ -1077,6 +1215,6 @@ interface FillFormOutput {
  * console.log(result.output)  // 채워진 마크다운
  * ```
  */
-declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillValue>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-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 FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, 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 RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fitRatioForFewerLines, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord };
+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 FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PlaceSealResult, type PrintOptions, type PrintPreset, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, validateHwpx };

package/dist/index.d.ts

@@ -296,6 +296,8 @@ interface FormField {
     row: number;
     /** 0-based 소스 열 */
     col: number;
+    /** 매칭된 입력 키(정규화) — 모호 라벨 거부 가드(fillWithUniqueGuard)의 집계 기준 */
+    key?: string;
 }
 interface FormResult {
     fields: FormField[];
@@ -319,6 +321,21 @@ interface WatchOptions {
  * 배열이면 등장 순서대로 하나씩 소진(2~30장 반복 양식·명부형 표).
  */
 type FillValue = string | string[];
+/**
+ * 채울 값 입력 — 값만 주거나, 서식 변환(format)을 함께 지정한다.
+ * 프로필엔 정준값 하나(생년월일 "19900315"), 서식마다 모양이 다를 때
+ * format이 도구 안에서 변환한다 (claw-hwp secure-fill 포맷엔진 이식).
+ */
+type FillInput = FillValue | {
+    value: FillValue;
+    format?: string;
+};
+/**
+ * 값 서식 변환 — `종류:스타일` 접두형(date:/phone:/rrn:/mask:/digits/upper/lower/nospace)
+ * 또는 접두 없는 자유 패턴(`#` 포함 → 숫자마스크, yyyy·yy·mm·dd 포함 → 날짜 토큰).
+ * 모르는 포맷은 값 원형 반환 (fail-open — 채움 자체는 진행).
+ */
+declare function formatFillValue(value: string, format?: string): string;
 /**
  * 다중값 커서 — 라벨별 값 소비 상태를 추적한다.
  * 스칼라 값은 무한 반복(기존 동작), 배열 값은 적용 순서대로 소진되며
@@ -338,6 +355,20 @@ declare class ValueCursor {
     /** 값 소비 — 배열이면 커서 전진, 소진 시 undefined */
     consume(key: string): string | undefined;
 }
+/**
+ * 모호 라벨 거부 가드 — 한 입력 키(스칼라)가 서식의 2곳 이상에 채워지면 남의 블록
+ * 오염 위험(대표자 행에 참여인력 값이 들어가는 류)이므로, 그 키는 채우지 않고
+ * rejected로 보고한 뒤 나머지 키만으로 다시 채운다 (claw-hwp require_occurrence 이식).
+ * 배열 값은 다중 등장 소진이 의도된 동작이라 거부 대상이 아니다.
+ * @param run 같은 원본에 대해 결정적으로 재실행 가능한 채우기 함수
+ */
+declare function fillWithUniqueGuard<R extends {
+    filled: Array<{
+        key?: string;
+    }>;
+}>(values: Record<string, FillInput>, run: (vals: Record<string, FillInput>) => R | Promise<R>): Promise<R & {
+    rejected: string[];
+}>;
 
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
@@ -412,7 +443,7 @@ interface FillResult {
  * })
  * ```
  */
-declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillValue>): FillResult;
+declare function fillFormFields(blocks: IRBlock[], values: Record<string, FillInput>): FillResult;
 
 /**
  * HWPX 원본 서식 유지 채우기 — section XML 오프셋 splice (v3.1, 바이트 보존)
@@ -455,7 +486,71 @@ interface HwpxFillResult {
  *   문자열이면 기존처럼 모든 등장에 동일값.
  * @returns HwpxFillResult
  */
-declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillValue>): Promise<HwpxFillResult>;
+declare function fillHwpx(hwpxBuffer: ArrayBuffer, values: Record<string, FillInput>): Promise<HwpxFillResult>;
+
+/**
+ * place_seal — 도장/서명 이미지를 앵커 문구("(인)"·"서명 또는 인" 등) 위에
+ * 부유(글 앞) 배치. 표/페이지 불확장 (P6, claw-hwp placeSeal 이식).
+ *
+ * 원리:
+ * - 앵커 문구가 든 문단을 찾아 그 문단에 <hp:pic> 부유 개체를 anchor 한다.
+ *   핵심 속성: treatAsChar="0" + flowWithText="0" + allowOverlap="1" +
+ *   textWrap="IN_FRONT_OF_TEXT" — flowWithText="1"이면 한컴이 개체 높이만큼
+ *   셀/페이지를 키운다 (claw-hwp GT 검증 규칙).
+ * - 수평 위치는 폰트 메트릭으로 계산: 전각(한글/CJK)=1em, ASCII·반각=0.5em,
+ *   em = 앵커 run charPr 높이(1/100pt). 렌더 없이 배치하고 렌더는 검증용.
+ * - 가운데/오른쪽 정렬 문단(서식 셀에 흔함)은 블록 전체가 밀리므로
+ *   (사용가능폭 − 문단폭)의 정렬 이동분을 x에 더한다.
+ * - 위치 프레임은 PARA(문단 좌상단 기준) — 한컴은 문단 위로는 못 올라가게
+ *   클램프하므로, 여유 공간이 있는 표 셀에서는 줄 세로 중앙에 앉고 본문
+ *   최상단 줄에서는 상단 정렬로 눕는다.
+ *
+ * 적용 범위: 본문/표 셀/글상자 문단 (머리말·꼬리말·각주 내 앵커는 제외).
+ * ZIP 재조립은 patchZipEntries — 비변경 엔트리는 1바이트도 건드리지 않고,
+ * 도장 PNG는 BinData 신규 엔트리 + manifest(opf:item) 등재로 추가한다.
+ */
+/** 도장 배치 요청 */
+interface SealOp {
+    /** 앵커 문구 (예: "(인)", "서명 또는 인") */
+    anchor: string;
+    /** 같은 앵커가 여럿일 때 0-based 선택 (기본 0) */
+    occurrence?: number;
+    /** 도장/서명 이미지 바이트 (투명 배경 PNG 권장) */
+    image: Uint8Array;
+    /** 이미지 확장자 (기본 png) */
+    ext?: "png" | "jpg" | "jpeg" | "bmp" | "gif";
+    /** 도장 한 변 크기 mm (기본: 줄높이×1.6, 7~18mm 클램프) */
+    sizeMm?: number;
+    /** overlap=문구 위에 겹침, right=문구 오른쪽 옆, auto=공간 있으면 right (기본 auto) */
+    mode?: "overlap" | "right" | "auto";
+    /** 미세조정 mm */
+    dxMm?: number;
+    dyMm?: number;
+}
+/** 배치 결과 (도장 1개당 1건) */
+interface SealPlacement {
+    anchor: string;
+    occurrence: number;
+    sectionIndex: number;
+    mode: "overlap" | "right";
+    posXMm: number;
+    posYMm: number;
+    sizeMm: number;
+    /** ZIP에 추가된 이미지 파트 경로 (BinData/imageN.ext) */
+    entry: string;
+}
+interface PlaceSealResult {
+    buffer: ArrayBuffer;
+    placed: SealPlacement[];
+}
+/**
+ * HWPX에 도장/서명 이미지를 앵커 문구 기준으로 부유 배치한다.
+ *
+ * @param hwpxBuffer 원본 HWPX
+ * @param ops 도장 배치 요청 (여러 개 가능 — 같은 이미지 재사용 시에도 op마다 파트가 추가됨)
+ * @throws KordocError 앵커 미발견 (본문 내 등장 횟수를 메시지에 포함)
+ */
+declare function placeSealHwpx(hwpxBuffer: ArrayBuffer, ops: SealOp[]): Promise<PlaceSealResult>;
 
 /**
  * 공문서(公文書) 모드 — 한국 행정 공문서 표준 서식 렌더링 로직
@@ -802,6 +897,33 @@ declare function patchHwpx(original: Uint8Array, editedMarkdown: string, options
  */
 declare function patchHwp(original: Uint8Array, editedMarkdown: string, options?: PatchOptions): Promise<PatchResult>;
 
+/**
+ * HWPX 구조 검증 — 한컴오피스/한컴독스가 열기를 거부하는 컨테이너 결함을 사전에 잡는다.
+ *
+ * 검사 항목 (claw-hwp validate.py의 실측 검사셋 이식 — MIT © DoHyun468/claw-hwp):
+ * - 유효한 ZIP인지, mimetype이 첫 엔트리이고 내용이 application/hwp+zip인지
+ * - 필수 파일 존재 (META-INF/container.xml, content.hpf, header.xml, section0.xml)
+ * - XML/HPF/RDF 엔트리 웰폼드
+ * - header.xml secCnt == 실제 Contents/sectionN.xml 수
+ *   (한컴독스는 실제 파일 목록이 아니라 secCnt를 신뢰하고, 불일치 시 열기를 거부한다)
+ * - content.hpf manifest의 <opf:item href>가 전부 실존하는지
+ */
+/** 검증에서 발견된 문제 하나 */
+interface ValidateIssue {
+    /** 문제가 발견된 zip 내부 경로 (컨테이너 전역 문제면 생략) */
+    path?: string;
+    message: string;
+}
+/** validateHwpx 결과 */
+interface ValidateResult {
+    ok: boolean;
+    issues: ValidateIssue[];
+    /** 검사한 zip 엔트리 수 (디렉토리 제외) */
+    entryCount: number;
+}
+/** HWPX 버퍼의 컨테이너 구조를 검증한다. 문제가 없으면 ok=true. */
+declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<ValidateResult>;
+
 /**
  * HWPX 문서 세션 — 에디터 통합용 블록 단위 증분 패치 API (v3.1).
  *
@@ -955,17 +1077,33 @@ declare function blocksToPdf(blocks: IRBlock[], options?: PrintOptions): Promise
  * - 좌표 속성엔 uint32로 저장된 음수가 섞여 있다(toInt32 필수).
  * - 표 열은 span 제약 경계 전파로, 행은 rs=1 max + 콘텐츠 초과 성장으로 푼다.
  *
- * 범위: 1페이지(section0) 한정, 수식·그리기개체 도형은 미지원(경고 수집).
+ * 페이지: 최상위 lineseg vertpos는 페이지 로컬(페이지마다 0부터 리셋)이므로 역행
+ *   지점을 페이지 경계로 감지, 전 페이지를 세로 스택으로 그린다(페이지별 흰 배경 +
+ *   클립). 페이지에 걸친 표는 시작 페이지에서 잘린다(조판 캐시에 분할점이 없음).
+ *
+ * 범위: section0 한정(다중 구역은 첫 구역만), 수식·그리기개체 도형은 미지원(경고 수집).
  */
+
 interface RenderSvgOptions {
     /** 이미지 1장당 허용 최대 바이트 (기본 40MB) */
     maxImageBytes?: number;
+    /** 검색어 형광펜 — 텍스트 조각 내 매치 구간에 배경 rect (대소문자 무시).
+     *  charPr(스타일) 경계에 걸친 매치는 칠하지 못한다. */
+    highlights?: string[];
+    /** Tier-2 reflow — 조판 캐시(linesegarray) 없는 파일도 순수 TS 조판으로 렌더.
+     *  캐시가 있으면 무시(한컴본은 캐시 재생). 기본 false(캐시 없으면 KordocError). */
+    reflow?: boolean;
+    /** reflow 줄바꿈 모드 — 'keep'(어절, Windows 한글·공문서) / 'charAll'(글자, macOS·전자결재) */
+    reflowMode?: WrapMode;
 }
 interface RenderSvgResult {
     svg: string;
-    /** 페이지 크기 (pt) */
+    /** 페이지 폭 (pt) */
     width: number;
+    /** 전체 캔버스 높이 (pt) — 페이지 세로 스택 + 간격 */
     height: number;
+    /** 렌더된 페이지 수 */
+    pageCount: number;
     warnings: string[];
     stats: {
         texts: number;
@@ -1077,6 +1215,6 @@ interface FillFormOutput {
  * console.log(result.output)  // 채워진 마크다운
  * ```
  */
-declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillValue>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
+declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-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 FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, 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 RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SectionScan, type SpliceEdit, type TRange, VERSION, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fitRatioForFewerLines, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord };
+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 FillInput, type FillOutputFormat, type FillResult, type FillValue, type FormField, type FormFieldSchema, type FormFieldType, type FormResult, type FormSchemaResult, type GongmunFont, type GongmunNumbering, type GongmunOptions, type GongmunPreset, type GongmunPresetInput, type HwpxFillResult, HwpxSession, type HwpxTheme, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type MarkdownToHwpxOptions, type MeasureOptions, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageMargin, type PageQuality, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type PatchOptions, type PatchResult, type PatchSkip, type PlaceSealResult, type PrintOptions, type PrintPreset, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToMarkdown, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, inferFieldType, isHwpxFile, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, validateHwpx };