kordoc 4.0.3 → 4.0.5

package/dist/index.d.cts

@@ -10,6 +10,13 @@ interface CellContext {
 }
 /** 블록 타입 — v2.0에서 heading, list, image, separator 추가 */
 type IRBlockType = "paragraph" | "table" | "heading" | "list" | "image" | "separator";
+/** 인라인 강조 run-span — 문단 텍스트를 서식 단위로 쪼갠 조각 (텍스트 연결 = block.text) */
+interface IRSpan {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
 interface IRBlock {
     type: IRBlockType;
     text?: string;
@@ -32,6 +39,23 @@ interface IRBlock {
     footnoteText?: string;
     /** 이미지 데이터 (type="image"일 때) */
     imageData?: ImageData;
+    /** 인라인 강조 run-span (선택 — kordoc 생성 hwpx 왕복 채널 + 외래 실속성 볼드/이탤릭).
+     *  존재하면 마크다운 변환이 **·*·` 마커를 재방출한다 */
+    spans?: IRSpan[];
+    /** 인용문 문단 (선택 — kordoc 생성 hwpx 왕복 채널) — 마크다운 변환이 "> " 접두 재방출 */
+    quote?: boolean;
+    /**
+     * 문단 들여쓰기(HWPUNIT, 선택) — HWPX paraPr `<hh:margin>` 자식요소형 hc:left
+     * (+양수 hc:intent 첫줄분). 마크다운 방출엔 쓰지 않는 관찰 슬롯 — gongmun 리스트
+     * depth 재유도·양식 분석 등 소비자 몫 (v4.0.4)
+     */
+    indent?: number;
+    /**
+     * gongmun 리스트 단계(1~7, 선택) — indent를 levelIndent 단위로 역산한 소비 결과
+     * (v4.0.5). md 리스트 문법과 충돌하는 부호('- '·'1) ') 문단에만 채워지며,
+     * 마크다운 변환이 2칸/단계 선행 공백을 방출해 재생성 시 depth가 복원된다
+     */
+    listDepth?: number;
 }
 /** 추출된 이미지 바이너리 데이터 */
 interface ImageData {
@@ -735,6 +759,12 @@ interface GongmunOptions {
 declare const PRESET_ALIAS: Record<string, GongmunPreset>;
 /** 프리셋 입력(영문 키 또는 한글 별칭)을 내부 GongmunPreset로 정규화. 미상은 'official' */
 declare function normalizeGongmunPreset(preset?: string): GongmunPreset;
+/**
+ * 프리셋과 비호환이라 resolveGongmun이 조용히 폐기/무시하는 옵션의 경고 목록 (v4.0.6).
+ * 순수 함수 — 배선은 호출자 몫 (CLI stderr / MCP 응답 병기, unknownFontWarnings 관례).
+ * 게이팅 조건은 resolveGongmun 본문과 1:1 — 여기 조건을 바꾸면 본문도 함께.
+ */
+declare function incompatibleGongmunWarnings(opts: GongmunOptions): string[];
 
 /** HWPX 생성 시 적용할 시각 테마 (모두 선택) */
 interface HwpxTheme {
@@ -799,6 +829,12 @@ interface CharPrDef {
     underline?: boolean;
     /** fontfaces HANGUL 순번. render는 이름표로 손실하므로 원본 순번 보존용 */
     fontRef_hangul?: string;
+    /**
+     * HANGUL 글꼴 이름 (스키마 0.3.0) — 순번(fontRef_hangul)은 원본 fontfaces에서만
+     * 유효하므로, 이름을 실어 생성 문서 header에 fontface를 append + 리맵해 재현한다.
+     * 없으면(구버전 프로필) 생성 header 범위 내 순번만 존중, 밖이면 기본(0) 폴딩.
+     */
+    fontName_hangul?: string;
 }
 /** 셀 하나의 서식 참조 (좌표 = 병합 셀 좌상단 앵커) */
 interface CellProfile {
@@ -825,6 +861,12 @@ interface TableProfile {
      * 어긋나도, 앵커+치수가 맞는 프로필만 골라 적용해 남의 서식 오적용을 막는다(v3.18.1).
      */
     anchor_text?: string;
+    /**
+     * 첫 행 전체 텍스트의 정규화 지문(normalizeRowAnchor) — 다중 지문 2순위 키 (0.3.0).
+     * (0,0)이 빈 셀인 크로스탭은 anchor_text가 비어 순번 폴백뿐이었는데, 첫 행 전체를
+     * 이어붙인 지문으로 동형 쌍둥이 표를 가른다.
+     */
+    anchor_row?: string;
     width_hwpunit?: string;
     col_widths_hwpunit?: string[];
     cells: CellProfile[];
@@ -963,11 +1005,21 @@ declare function charWidthEm1000(cp: number): number;
 /** HWP 공백 폭(em×1000) — useFontSpace=0(기본): 반각 고정 500 / =1: 글꼴값 300 */
 declare const SPACE_EM_FIXED = 500;
 declare const SPACE_EM_FONT = 300;
+/**
+ * 폭 테이블 클래스 — 'hcr'(함초롬 실측, 기본) / 'fixedPitch'(고정폭 글꼴:
+ * ASCII 0.5em·그 외 1.0em). 굴림체·돋움체·바탕체·궁서체('체' 접미 = 고정폭)가
+ * 대상 — 전자결재 변환기 산출물의 지배 본문 글꼴. 한글이 HCR(0.97em)보다 3%
+ * 넓어 함초롬 테이블로 재면 줄당 1~2자 과대적재로 wrap 지점이 어긋난다
+ * (bench/verify-linebreak.mjs seoul 코퍼스 실측: fixedPitch 테이블로 74/75 일치).
+ */
+type FaceClass = "hcr" | "fixedPitch";
 interface MeasureOptions {
     /** 공백 폭(em×1000). 기본 SPACE_EM_FIXED(500) = useFontSpace 0 */
     spaceEm?: number;
     /** 자간(charPr spacing %) — 글자폭의 %가 문자마다 추가 */
     spacingPct?: number;
+    /** 폭 테이블 클래스 — 기본 'hcr' (함초롬 실측 테이블) */
+    faceClass?: FaceClass;
 }
 /**
  * 텍스트 폭(HWPUNIT). height=charPr height(pt×100), ratioPct=장평 %.
@@ -1504,4 +1556,4 @@ interface 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 BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, 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 FormatProfile, type GongmunFont, type GongmunLintFinding, 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, type TableProfile, 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, gongmunLintWarnings, hwpxToProfile, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, 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 FormatProfile, type GongmunFont, type GongmunLintFinding, 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, type TableProfile, 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, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };

package/dist/index.d.ts

@@ -10,6 +10,13 @@ interface CellContext {
 }
 /** 블록 타입 — v2.0에서 heading, list, image, separator 추가 */
 type IRBlockType = "paragraph" | "table" | "heading" | "list" | "image" | "separator";
+/** 인라인 강조 run-span — 문단 텍스트를 서식 단위로 쪼갠 조각 (텍스트 연결 = block.text) */
+interface IRSpan {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
 interface IRBlock {
     type: IRBlockType;
     text?: string;
@@ -32,6 +39,23 @@ interface IRBlock {
     footnoteText?: string;
     /** 이미지 데이터 (type="image"일 때) */
     imageData?: ImageData;
+    /** 인라인 강조 run-span (선택 — kordoc 생성 hwpx 왕복 채널 + 외래 실속성 볼드/이탤릭).
+     *  존재하면 마크다운 변환이 **·*·` 마커를 재방출한다 */
+    spans?: IRSpan[];
+    /** 인용문 문단 (선택 — kordoc 생성 hwpx 왕복 채널) — 마크다운 변환이 "> " 접두 재방출 */
+    quote?: boolean;
+    /**
+     * 문단 들여쓰기(HWPUNIT, 선택) — HWPX paraPr `<hh:margin>` 자식요소형 hc:left
+     * (+양수 hc:intent 첫줄분). 마크다운 방출엔 쓰지 않는 관찰 슬롯 — gongmun 리스트
+     * depth 재유도·양식 분석 등 소비자 몫 (v4.0.4)
+     */
+    indent?: number;
+    /**
+     * gongmun 리스트 단계(1~7, 선택) — indent를 levelIndent 단위로 역산한 소비 결과
+     * (v4.0.5). md 리스트 문법과 충돌하는 부호('- '·'1) ') 문단에만 채워지며,
+     * 마크다운 변환이 2칸/단계 선행 공백을 방출해 재생성 시 depth가 복원된다
+     */
+    listDepth?: number;
 }
 /** 추출된 이미지 바이너리 데이터 */
 interface ImageData {
@@ -735,6 +759,12 @@ interface GongmunOptions {
 declare const PRESET_ALIAS: Record<string, GongmunPreset>;
 /** 프리셋 입력(영문 키 또는 한글 별칭)을 내부 GongmunPreset로 정규화. 미상은 'official' */
 declare function normalizeGongmunPreset(preset?: string): GongmunPreset;
+/**
+ * 프리셋과 비호환이라 resolveGongmun이 조용히 폐기/무시하는 옵션의 경고 목록 (v4.0.6).
+ * 순수 함수 — 배선은 호출자 몫 (CLI stderr / MCP 응답 병기, unknownFontWarnings 관례).
+ * 게이팅 조건은 resolveGongmun 본문과 1:1 — 여기 조건을 바꾸면 본문도 함께.
+ */
+declare function incompatibleGongmunWarnings(opts: GongmunOptions): string[];
 
 /** HWPX 생성 시 적용할 시각 테마 (모두 선택) */
 interface HwpxTheme {
@@ -799,6 +829,12 @@ interface CharPrDef {
     underline?: boolean;
     /** fontfaces HANGUL 순번. render는 이름표로 손실하므로 원본 순번 보존용 */
     fontRef_hangul?: string;
+    /**
+     * HANGUL 글꼴 이름 (스키마 0.3.0) — 순번(fontRef_hangul)은 원본 fontfaces에서만
+     * 유효하므로, 이름을 실어 생성 문서 header에 fontface를 append + 리맵해 재현한다.
+     * 없으면(구버전 프로필) 생성 header 범위 내 순번만 존중, 밖이면 기본(0) 폴딩.
+     */
+    fontName_hangul?: string;
 }
 /** 셀 하나의 서식 참조 (좌표 = 병합 셀 좌상단 앵커) */
 interface CellProfile {
@@ -825,6 +861,12 @@ interface TableProfile {
      * 어긋나도, 앵커+치수가 맞는 프로필만 골라 적용해 남의 서식 오적용을 막는다(v3.18.1).
      */
     anchor_text?: string;
+    /**
+     * 첫 행 전체 텍스트의 정규화 지문(normalizeRowAnchor) — 다중 지문 2순위 키 (0.3.0).
+     * (0,0)이 빈 셀인 크로스탭은 anchor_text가 비어 순번 폴백뿐이었는데, 첫 행 전체를
+     * 이어붙인 지문으로 동형 쌍둥이 표를 가른다.
+     */
+    anchor_row?: string;
     width_hwpunit?: string;
     col_widths_hwpunit?: string[];
     cells: CellProfile[];
@@ -963,11 +1005,21 @@ declare function charWidthEm1000(cp: number): number;
 /** HWP 공백 폭(em×1000) — useFontSpace=0(기본): 반각 고정 500 / =1: 글꼴값 300 */
 declare const SPACE_EM_FIXED = 500;
 declare const SPACE_EM_FONT = 300;
+/**
+ * 폭 테이블 클래스 — 'hcr'(함초롬 실측, 기본) / 'fixedPitch'(고정폭 글꼴:
+ * ASCII 0.5em·그 외 1.0em). 굴림체·돋움체·바탕체·궁서체('체' 접미 = 고정폭)가
+ * 대상 — 전자결재 변환기 산출물의 지배 본문 글꼴. 한글이 HCR(0.97em)보다 3%
+ * 넓어 함초롬 테이블로 재면 줄당 1~2자 과대적재로 wrap 지점이 어긋난다
+ * (bench/verify-linebreak.mjs seoul 코퍼스 실측: fixedPitch 테이블로 74/75 일치).
+ */
+type FaceClass = "hcr" | "fixedPitch";
 interface MeasureOptions {
     /** 공백 폭(em×1000). 기본 SPACE_EM_FIXED(500) = useFontSpace 0 */
     spaceEm?: number;
     /** 자간(charPr spacing %) — 글자폭의 %가 문자마다 추가 */
     spacingPct?: number;
+    /** 폭 테이블 클래스 — 기본 'hcr' (함초롬 실측 테이블) */
+    faceClass?: FaceClass;
 }
 /**
  * 텍스트 폭(HWPUNIT). height=charPr height(pt×100), ratioPct=장평 %.
@@ -1504,4 +1556,4 @@ interface 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 BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, 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 FormatProfile, type GongmunFont, type GongmunLintFinding, 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, type TableProfile, 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, gongmunLintWarnings, hwpxToProfile, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };
+export { type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, 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 FormatProfile, type GongmunFont, type GongmunLintFinding, 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, type TableProfile, 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, gongmunLintWarnings, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, markdownToHwpx, markdownToPdf, measureTextWidth, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, renderHtml, renderHwpxToSvg, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, validateHwpx };