kordoc 4.14.2 → 4.14.3

package/dist/index.d.cts

@@ -19,9 +19,15 @@ interface IRSpan {
     /** 밑줄 — 개정문 추가·변경 표시 등. GFM 문법이 없어 <u>…</u> 인라인 HTML 로 방출 */
     underline?: boolean;
     code?: boolean;
+    /**
+     * 미기입 누름틀의 안내문(HWPX CLICK_HERE, 수정 안 됨). 한컴은 화면에만 흐리게 보이고 인쇄하지 않는다.
+     * 블록 `text` 에는 남기고(양식 채우기·패치가 원문 자리와 맞대도록) 마크다운에서는 뺀다 (v4.14.3)
+     */
+    placeholder?: boolean;
 }
 interface IRBlock {
     type: IRBlockType;
+    /** 블록 글. HWPX·HWP5·HWP3 은 원문의 리터럴 `$` 를 `\$` 로 담고 `$…$`·`$$…$$` 는 수식 스팬에만 쓴다 (v4.14.3) */
     text?: string;
     table?: IRTable;
     /** 헤딩 레벨 (1-6), type="heading"일 때 사용 */
@@ -234,6 +240,18 @@ interface ParseOptions {
      * (현재 HWP5 경로 지원)
      */
     inlineImages?: boolean;
+    /**
+     * 이미지 바이트 추출 (기본 true). false 면 결과에 이미지 바이트를 싣지 않는다.
+     * `images` 는 비고, 블록의 `imageData` 도 떼며, HWP5 `inlineImages` 도 무시한다.
+     * 그림 자리 표시(`![image](…)`)는 마크다운·블록에 그대로 남아 위치는 알 수 있다.
+     * PDF 는 PNG 인코딩을 건너뛴다. 거르는 기준은 같되 메모리 보호용 128MB 누적 상한은 걸리지
+     * 않아, 그 상한 뒤의 그림도 자리 표시가 남는다.
+     *
+     * 검색 색인처럼 글자만 필요한 호출자용이다. 그림이 많은 문서는 base64 로 불어난 이미지가
+     * JSON 출력의 대부분을 차지했다 (PDF 실측 200MB → 9.5MB, CPU 시간 30% 감소). 본문 글자와
+     * OCR 은 이 옵션과 무관하다.
+     */
+    images?: boolean;
     /**
      * PDF 표 감지 활성화 (기본 true). false 면 선 기반 그리드·클러스터 표 감지를 모두 끄고
      * 자연 읽기순 텍스트만 뽑는다 (#64).
@@ -653,8 +671,10 @@ blockedLabels?: Set<string>): Promise<HwpxFillResult>;
  * 값을 비교하지 않고 무조건 사이 영역을 값으로 치환한다 — 값이 안내문과 동일해도
  * 침묵 유실이 없다 (rhwp 코어 결함 #3380 교훈).
  *
- * 치환은 filler-hwpx와 같은 철학의 원본 XML splice — fieldBegin/fieldEnd·안내문
- * 파라미터·둘러싼 run(charPr)을 1바이트도 건드리지 않고 사이 영역만 바꾼다.
+ * 치환은 filler-hwpx와 같은 철학의 원본 XML splice — fieldEnd·안내문 파라미터·둘러싼
+ * run(charPr)을 1바이트도 건드리지 않고 사이 영역만 바꾼다. 값을 넣으면 fieldBegin 의 수정
+ * 표시(dirty)만 "1" 로 켠다 — 미수정(dirty=0) 필드의 값이 안내문과 같으면 한컴은 화면에만 흐리게
+ * 보이고 인쇄하지 않으며 kordoc 파서도 그렇게 읽는다(v4.14.3). 한컴이 직접 채운 필드도 dirty=1.
  */
 
 /** 문서에서 발견한 누름틀 필드 */
@@ -1493,6 +1513,17 @@ declare function buildParagraphSplices(para: ScanParagraph, newText: string, xml
 declare function buildRangeSplices(para: ScanParagraph, xml: string, start: number, end: number, replacement: string): SpliceEdit[] | null;
 declare function applySplices(xml: string, splices: SpliceEdit[]): string;
 
+/** 2-pass colSpan/rowSpan 테이블 빌더 및 Markdown 변환 */
+
+declare function flattenLayoutTables(blocks: IRBlock[]): IRBlock[];
+declare function blocksToMarkdown(blocks: IRBlock[]): string;
+/**
+ * 셀에 GFM 표 문법으로 담을 수 없는 구조 콘텐츠(중첩표·구분선)가 있는가 (#76 Task 4) — hasNestedTables 의 일반화.
+ * 이미지는 GFM 셀에 `![image](src)` 로 인라인할 수 있어 여기 세지 않는다 — 대신 GFM 경로가 blocks 를 직접 직렬화해
+ * (아래 tableToMarkdown) 병합 없는 단순 표의 셀 이미지가 사라지지 않게 한다. span 문단(왕복 채널)도 GFM 그대로.
+ */
+declare function hasStructuredCellContent(table: IRTable): boolean;
+
 /**
  * HWPX 서식 보존 무손실 라운드트립 패치 — v3.0 킬러기능.
  *
@@ -1572,17 +1603,26 @@ declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<Validat
 /**
  * 한국 공문서 PII(개인정보) 탐지·마스킹 순수 로직.
  *
- * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파싱/patch는 기존 인프라가
- * 담당하고 여기서는 텍스트만 다룬다 (CLI/MCP 배선은 별도).
+ * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파일 단위 마스킹(머리말·각주·미리보기·메타데이터
+ * 포함)은 redact-doc.ts 가 이 엔진을 불러 쓴다.
  *
  * 원칙:
- * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이가 동일
+ * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이(UTF-16 단위)가 동일
  * - 히트 리포트에 원본 PII를 절대 담지 않는다 (`masked` 필드만 존재)
- * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된
- *   구간과 겹치는 하위 룰 매치는 스킵 (RULE_PRIORITY 참조)
+ * - 탐지는 같은 길이로 정규화한 그림자 문자열에서 한다 — 전각 숫자·영문·@, 유니코드 대시(‐‑–—−－·─·ㅡ),
+ *   NBSP·전각 공백을 ASCII 로 1:1 치환하므로 오프셋이 그대로이고, 마스킹은 원문 글자에 적용한다
+ * - 번호 모양만으로 모호한 형태(구분자 없는 13자리·10~14자리, 여권 구형 등)는 바로 앞 라벨
+ *   ("주민등록번호", "계좌", "여권" …) 이나 표 열 머리글이 해당 유형일 때만 잡는다. 가장 가까운
+ *   라벨이 이긴다 — "법인등록번호" 옆 6-7 번호는 주민번호로 보지 않는다
+ * - 체크섬: 카드 Luhn, 사업자·법인등록번호 가중합. 주민·외국인등록번호는 2020-10 이후 뒷자리가
+ *   임의 번호라 체크섬으로 거르지 않고 생년월일(세기 포함)·성별 자리만 검증한다
+ * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된 구간과 겹치는 하위 룰
+ *   매치는 스킵 (RULE_PRIORITY 참조)
  * - 정규식은 모듈 로드 시 1회 컴파일 (matchAll은 내부 클론이라 lastIndex 안전)
+ *
+ * 룰별 근거·오탐 실측은 bench/redact-bench.mjs (합성 정답 셋 + 실코퍼스) 참조.
  */
-type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver";
+type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver" | "brn" | "crn" | "ip";
 interface RedactHit {
     rule: RedactRule;
     /** 마스킹 후 문자열 — 원본 PII는 리포트에 담지 않는다 */
@@ -1597,25 +1637,32 @@ interface RedactTextResult {
     hits: RedactHit[];
 }
 interface RedactOptions {
-    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — passport·driver는 기본 OFF) */
-    rules?: RedactRule[];
-    /** 마스크 문자 — 1글자(UTF-16 1단위), 영숫자 금지. 기본 "●" (마크다운 특수문자 아님) */
+    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — crn·ip는 기본 OFF) */
+    rules?: readonly RedactRule[];
+    /** 마스크 문자 — 1글자(UTF-16 1단위). 영숫자·공백·제어문자·마크다운/XML 특수문자(|\<>&"')는 금지. 기본 "●" */
     maskChar?: string;
 }
-/** 기본 적용 룰 — passport(여권)·driver(운전면허)는 오탐 여지가 있어 opt-in */
+/**
+ * 기본 적용 룰. 실코퍼스 2,303문서 오탐 실측 근거(bench/redact-bench.mjs --corpus):
+ * - brn(사업자등록번호)은 종전 account 가 잡던 것을 체크섬으로 분리 — 기본 마스킹 범위 그대로
+ * - passport 는 신형(M123A4567)만 무문맥, 구형(M12345678)은 "여권" 라벨이 있을 때만 → 기본 ON
+ * - driver 는 지역코드(11~28)·지역명 검증으로 좁혔고 종전에도 account 로 가려지던 모양 → 기본 ON
+ * - crn(법인등록번호)은 개인정보가 아니고, ip 는 "1.2.3.4" 절 번호·버전과 겹쳐 opt-in
+ */
 declare const DEFAULT_REDACT_RULES: readonly RedactRule[];
 /**
  * 텍스트에서 PII를 탐지해 서식 보존 마스킹.
  *
  * @param text - 대상 텍스트 (마크다운 포함)
- * @param options - 룰 선택·마스크 문자 (기본: rrn·phone·email·card·account, "●")
+ * @param options - 룰 선택·마스크 문자 (기본: DEFAULT_REDACT_RULES, "●")
  * @returns 마스킹된 텍스트 + 히트 리포트 (index 오름차순, 원본 PII 미포함)
  */
 declare function redactText(text: string, options?: RedactOptions): RedactTextResult;
 /**
  * 마크다운 문서 전용 래퍼 — base64 이미지(data URI) 라인은 마스킹에서 제외한다.
  * base64 페이로드의 숫자열이 phone 등에 오탐되면 이미지가 깨지기 때문.
- * hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다.
+ * 표 셀은 열 머리글("주민등록번호"·"계좌번호" …)을 라벨 문맥으로 쓰고, 인라인 서식 표지(**·\\ 이스케이프 등)가
+ * 번호를 갈라도 잡는다. hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다 (masked 에는 표지가 그대로).
  */
 declare function redactMarkdown(markdown: string, options?: RedactOptions): RedactTextResult;
 
@@ -2094,16 +2141,6 @@ declare function chooseTableRepresentation(table: IRTable, opts?: {
     smartVisual?: boolean;
 }): TableRepresentation;
 
-/** 2-pass colSpan/rowSpan 테이블 빌더 및 Markdown 변환 */
-
-declare function blocksToMarkdown(blocks: IRBlock[]): string;
-/**
- * 셀에 GFM 표 문법으로 담을 수 없는 구조 콘텐츠(중첩표·구분선)가 있는가 (#76 Task 4) — hasNestedTables 의 일반화.
- * 이미지는 GFM 셀에 `![image](src)` 로 인라인할 수 있어 여기 세지 않는다 — 대신 GFM 경로가 blocks 를 직접 직렬화해
- * (아래 tableToMarkdown) 병합 없는 단순 표의 셀 이미지가 사라지지 않게 한다. span 문단(왕복 채널)도 GFM 그대로.
- */
-declare function hasStructuredCellContent(table: IRTable): boolean;
-
 /**
  * 분류된 표 ↔ 렌더 region 조인 (#76 Task 6·7). bbox 는 여기서 계산하지 않는다 — #75 의 RenderRegion.sourceId 로 IRTable.sourceId 를 잇는다
  * (HWPX 는 `hp:tbl id`, HWP5 는 table-ids.ts 의 문서 순번 `t{N}` — 파서·렌더 어댑터가 같은 프리패스를 쓴다).
@@ -2260,4 +2297,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { BUILTIN_TEMPLATES, type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type BuiltinTemplate, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, type ClassifyContext, type ClickHereField, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractRegionOptions, type ExtractTableVisualOptions, type ExtractedImage, type ExtractedTable, type ExtractedTableCrop, 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 MuncheLineKind, type MuncheLintFinding, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageBBox, type PageMargin, type PageMarkdown, type PageOptions, 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 RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RegionAsset, type RenderAsset, type RenderDocumentOptions, type RenderDocumentResult, type RenderFormat, type RenderObjectType, type RenderRegion, type RenderScene, type RenderSourceFormat, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type ScenePage, type SceneRenderOptions, type SceneRenderResult, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, type TableRepresentation, type TableVisualPolicy, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPages, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, chooseTableRepresentation, classifyTable, classifyTableTree, collectTableBlocks, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractClickHereFields, extractFormFields, extractFormSchema, extractRenderedRegions, extractTables, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hasStructuredCellContent, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, lintMuncheText, markdownToHwpx, markdownToPdf, measureTextWidth, muncheLintWarnings, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parseImage, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, readBuiltinTemplate, readBuiltinTemplateSample, redactMarkdown, redactText, renderDocument, renderDocumentToScene, renderHtml, renderHwp5Pages, renderHwpxToSvg, renderSceneToHtml, resolveBuiltinTemplate, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, usesGaejosikMunche, validateHwpx };
+export { BUILTIN_TEMPLATES, type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type BuiltinTemplate, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, type ClassifyContext, type ClickHereField, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractRegionOptions, type ExtractTableVisualOptions, type ExtractedImage, type ExtractedTable, type ExtractedTableCrop, 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 MuncheLineKind, type MuncheLintFinding, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageBBox, type PageMargin, type PageMarkdown, type PageOptions, 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 RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RegionAsset, type RenderAsset, type RenderDocumentOptions, type RenderDocumentResult, type RenderFormat, type RenderObjectType, type RenderRegion, type RenderScene, type RenderSourceFormat, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type ScenePage, type SceneRenderOptions, type SceneRenderResult, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, type TableRepresentation, type TableVisualPolicy, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPages, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, chooseTableRepresentation, classifyTable, classifyTableTree, collectTableBlocks, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractClickHereFields, extractFormFields, extractFormSchema, extractRenderedRegions, extractTables, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, flattenLayoutTables, formatFillValue, gongmunLintWarnings, hasStructuredCellContent, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, lintMuncheText, markdownToHwpx, markdownToPdf, measureTextWidth, muncheLintWarnings, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parseImage, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, readBuiltinTemplate, readBuiltinTemplateSample, redactMarkdown, redactText, renderDocument, renderDocumentToScene, renderHtml, renderHwp5Pages, renderHwpxToSvg, renderSceneToHtml, resolveBuiltinTemplate, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, usesGaejosikMunche, validateHwpx };

package/dist/index.d.ts

@@ -19,9 +19,15 @@ interface IRSpan {
     /** 밑줄 — 개정문 추가·변경 표시 등. GFM 문법이 없어 <u>…</u> 인라인 HTML 로 방출 */
     underline?: boolean;
     code?: boolean;
+    /**
+     * 미기입 누름틀의 안내문(HWPX CLICK_HERE, 수정 안 됨). 한컴은 화면에만 흐리게 보이고 인쇄하지 않는다.
+     * 블록 `text` 에는 남기고(양식 채우기·패치가 원문 자리와 맞대도록) 마크다운에서는 뺀다 (v4.14.3)
+     */
+    placeholder?: boolean;
 }
 interface IRBlock {
     type: IRBlockType;
+    /** 블록 글. HWPX·HWP5·HWP3 은 원문의 리터럴 `$` 를 `\$` 로 담고 `$…$`·`$$…$$` 는 수식 스팬에만 쓴다 (v4.14.3) */
     text?: string;
     table?: IRTable;
     /** 헤딩 레벨 (1-6), type="heading"일 때 사용 */
@@ -234,6 +240,18 @@ interface ParseOptions {
      * (현재 HWP5 경로 지원)
      */
     inlineImages?: boolean;
+    /**
+     * 이미지 바이트 추출 (기본 true). false 면 결과에 이미지 바이트를 싣지 않는다.
+     * `images` 는 비고, 블록의 `imageData` 도 떼며, HWP5 `inlineImages` 도 무시한다.
+     * 그림 자리 표시(`![image](…)`)는 마크다운·블록에 그대로 남아 위치는 알 수 있다.
+     * PDF 는 PNG 인코딩을 건너뛴다. 거르는 기준은 같되 메모리 보호용 128MB 누적 상한은 걸리지
+     * 않아, 그 상한 뒤의 그림도 자리 표시가 남는다.
+     *
+     * 검색 색인처럼 글자만 필요한 호출자용이다. 그림이 많은 문서는 base64 로 불어난 이미지가
+     * JSON 출력의 대부분을 차지했다 (PDF 실측 200MB → 9.5MB, CPU 시간 30% 감소). 본문 글자와
+     * OCR 은 이 옵션과 무관하다.
+     */
+    images?: boolean;
     /**
      * PDF 표 감지 활성화 (기본 true). false 면 선 기반 그리드·클러스터 표 감지를 모두 끄고
      * 자연 읽기순 텍스트만 뽑는다 (#64).
@@ -653,8 +671,10 @@ blockedLabels?: Set<string>): Promise<HwpxFillResult>;
  * 값을 비교하지 않고 무조건 사이 영역을 값으로 치환한다 — 값이 안내문과 동일해도
  * 침묵 유실이 없다 (rhwp 코어 결함 #3380 교훈).
  *
- * 치환은 filler-hwpx와 같은 철학의 원본 XML splice — fieldBegin/fieldEnd·안내문
- * 파라미터·둘러싼 run(charPr)을 1바이트도 건드리지 않고 사이 영역만 바꾼다.
+ * 치환은 filler-hwpx와 같은 철학의 원본 XML splice — fieldEnd·안내문 파라미터·둘러싼
+ * run(charPr)을 1바이트도 건드리지 않고 사이 영역만 바꾼다. 값을 넣으면 fieldBegin 의 수정
+ * 표시(dirty)만 "1" 로 켠다 — 미수정(dirty=0) 필드의 값이 안내문과 같으면 한컴은 화면에만 흐리게
+ * 보이고 인쇄하지 않으며 kordoc 파서도 그렇게 읽는다(v4.14.3). 한컴이 직접 채운 필드도 dirty=1.
  */
 
 /** 문서에서 발견한 누름틀 필드 */
@@ -1493,6 +1513,17 @@ declare function buildParagraphSplices(para: ScanParagraph, newText: string, xml
 declare function buildRangeSplices(para: ScanParagraph, xml: string, start: number, end: number, replacement: string): SpliceEdit[] | null;
 declare function applySplices(xml: string, splices: SpliceEdit[]): string;
 
+/** 2-pass colSpan/rowSpan 테이블 빌더 및 Markdown 변환 */
+
+declare function flattenLayoutTables(blocks: IRBlock[]): IRBlock[];
+declare function blocksToMarkdown(blocks: IRBlock[]): string;
+/**
+ * 셀에 GFM 표 문법으로 담을 수 없는 구조 콘텐츠(중첩표·구분선)가 있는가 (#76 Task 4) — hasNestedTables 의 일반화.
+ * 이미지는 GFM 셀에 `![image](src)` 로 인라인할 수 있어 여기 세지 않는다 — 대신 GFM 경로가 blocks 를 직접 직렬화해
+ * (아래 tableToMarkdown) 병합 없는 단순 표의 셀 이미지가 사라지지 않게 한다. span 문단(왕복 채널)도 GFM 그대로.
+ */
+declare function hasStructuredCellContent(table: IRTable): boolean;
+
 /**
  * HWPX 서식 보존 무손실 라운드트립 패치 — v3.0 킬러기능.
  *
@@ -1572,17 +1603,26 @@ declare function validateHwpx(buffer: ArrayBuffer | Uint8Array): Promise<Validat
 /**
  * 한국 공문서 PII(개인정보) 탐지·마스킹 순수 로직.
  *
- * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파싱/patch는 기존 인프라가
- * 담당하고 여기서는 텍스트만 다룬다 (CLI/MCP 배선은 별도).
+ * 텍스트 in → 마스킹된 텍스트 + 히트 리포트 out. 문서 파일 단위 마스킹(머리말·각주·미리보기·메타데이터
+ * 포함)은 redact-doc.ts 가 이 엔진을 불러 쓴다.
  *
  * 원칙:
- * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이가 동일
+ * - 서식 보존 마스킹 — 자릿수·구분자를 유지해 마스킹 전후 길이(UTF-16 단위)가 동일
  * - 히트 리포트에 원본 PII를 절대 담지 않는다 (`masked` 필드만 존재)
- * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된
- *   구간과 겹치는 하위 룰 매치는 스킵 (RULE_PRIORITY 참조)
+ * - 탐지는 같은 길이로 정규화한 그림자 문자열에서 한다 — 전각 숫자·영문·@, 유니코드 대시(‐‑–—−－·─·ㅡ),
+ *   NBSP·전각 공백을 ASCII 로 1:1 치환하므로 오프셋이 그대로이고, 마스킹은 원문 글자에 적용한다
+ * - 번호 모양만으로 모호한 형태(구분자 없는 13자리·10~14자리, 여권 구형 등)는 바로 앞 라벨
+ *   ("주민등록번호", "계좌", "여권" …) 이나 표 열 머리글이 해당 유형일 때만 잡는다. 가장 가까운
+ *   라벨이 이긴다 — "법인등록번호" 옆 6-7 번호는 주민번호로 보지 않는다
+ * - 체크섬: 카드 Luhn, 사업자·법인등록번호 가중합. 주민·외국인등록번호는 2020-10 이후 뒷자리가
+ *   임의 번호라 체크섬으로 거르지 않고 생년월일(세기 포함)·성별 자리만 검증한다
+ * - 룰 우선순위 겹침 처리 — 우선순위순으로 매치를 수집하고, 이미 점유된 구간과 겹치는 하위 룰
+ *   매치는 스킵 (RULE_PRIORITY 참조)
  * - 정규식은 모듈 로드 시 1회 컴파일 (matchAll은 내부 클론이라 lastIndex 안전)
+ *
+ * 룰별 근거·오탐 실측은 bench/redact-bench.mjs (합성 정답 셋 + 실코퍼스) 참조.
  */
-type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver";
+type RedactRule = "rrn" | "phone" | "email" | "card" | "account" | "passport" | "driver" | "brn" | "crn" | "ip";
 interface RedactHit {
     rule: RedactRule;
     /** 마스킹 후 문자열 — 원본 PII는 리포트에 담지 않는다 */
@@ -1597,25 +1637,32 @@ interface RedactTextResult {
     hits: RedactHit[];
 }
 interface RedactOptions {
-    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — passport·driver는 기본 OFF) */
-    rules?: RedactRule[];
-    /** 마스크 문자 — 1글자(UTF-16 1단위), 영숫자 금지. 기본 "●" (마크다운 특수문자 아님) */
+    /** 적용할 룰 (기본: DEFAULT_REDACT_RULES — crn·ip는 기본 OFF) */
+    rules?: readonly RedactRule[];
+    /** 마스크 문자 — 1글자(UTF-16 1단위). 영숫자·공백·제어문자·마크다운/XML 특수문자(|\<>&"')는 금지. 기본 "●" */
     maskChar?: string;
 }
-/** 기본 적용 룰 — passport(여권)·driver(운전면허)는 오탐 여지가 있어 opt-in */
+/**
+ * 기본 적용 룰. 실코퍼스 2,303문서 오탐 실측 근거(bench/redact-bench.mjs --corpus):
+ * - brn(사업자등록번호)은 종전 account 가 잡던 것을 체크섬으로 분리 — 기본 마스킹 범위 그대로
+ * - passport 는 신형(M123A4567)만 무문맥, 구형(M12345678)은 "여권" 라벨이 있을 때만 → 기본 ON
+ * - driver 는 지역코드(11~28)·지역명 검증으로 좁혔고 종전에도 account 로 가려지던 모양 → 기본 ON
+ * - crn(법인등록번호)은 개인정보가 아니고, ip 는 "1.2.3.4" 절 번호·버전과 겹쳐 opt-in
+ */
 declare const DEFAULT_REDACT_RULES: readonly RedactRule[];
 /**
  * 텍스트에서 PII를 탐지해 서식 보존 마스킹.
  *
  * @param text - 대상 텍스트 (마크다운 포함)
- * @param options - 룰 선택·마스크 문자 (기본: rrn·phone·email·card·account, "●")
+ * @param options - 룰 선택·마스크 문자 (기본: DEFAULT_REDACT_RULES, "●")
  * @returns 마스킹된 텍스트 + 히트 리포트 (index 오름차순, 원본 PII 미포함)
  */
 declare function redactText(text: string, options?: RedactOptions): RedactTextResult;
 /**
  * 마크다운 문서 전용 래퍼 — base64 이미지(data URI) 라인은 마스킹에서 제외한다.
  * base64 페이로드의 숫자열이 phone 등에 오탐되면 이미지가 깨지기 때문.
- * hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다.
+ * 표 셀은 열 머리글("주민등록번호"·"계좌번호" …)을 라벨 문맥으로 쓰고, 인라인 서식 표지(**·\\ 이스케이프 등)가
+ * 번호를 갈라도 잡는다. hits의 index는 문서 전체 기준 절대 오프셋으로 환산된다 (masked 에는 표지가 그대로).
  */
 declare function redactMarkdown(markdown: string, options?: RedactOptions): RedactTextResult;
 
@@ -2094,16 +2141,6 @@ declare function chooseTableRepresentation(table: IRTable, opts?: {
     smartVisual?: boolean;
 }): TableRepresentation;
 
-/** 2-pass colSpan/rowSpan 테이블 빌더 및 Markdown 변환 */
-
-declare function blocksToMarkdown(blocks: IRBlock[]): string;
-/**
- * 셀에 GFM 표 문법으로 담을 수 없는 구조 콘텐츠(중첩표·구분선)가 있는가 (#76 Task 4) — hasNestedTables 의 일반화.
- * 이미지는 GFM 셀에 `![image](src)` 로 인라인할 수 있어 여기 세지 않는다 — 대신 GFM 경로가 blocks 를 직접 직렬화해
- * (아래 tableToMarkdown) 병합 없는 단순 표의 셀 이미지가 사라지지 않게 한다. span 문단(왕복 채널)도 GFM 그대로.
- */
-declare function hasStructuredCellContent(table: IRTable): boolean;
-
 /**
  * 분류된 표 ↔ 렌더 region 조인 (#76 Task 6·7). bbox 는 여기서 계산하지 않는다 — #75 의 RenderRegion.sourceId 로 IRTable.sourceId 를 잇는다
  * (HWPX 는 `hp:tbl id`, HWP5 는 table-ids.ts 의 문서 순번 `t{N}` — 파서·렌더 어댑터가 같은 프리패스를 쓴다).
@@ -2260,4 +2297,4 @@ interface FillFormOutput {
  */
 declare function fillForm(input: string | ArrayBuffer | Buffer, values: Record<string, FillInput>, outputFormat?: FillOutputFormat): Promise<FillFormOutput>;
 
-export { BUILTIN_TEMPLATES, type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type BuiltinTemplate, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, type ClassifyContext, type ClickHereField, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractRegionOptions, type ExtractTableVisualOptions, type ExtractedImage, type ExtractedTable, type ExtractedTableCrop, 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 MuncheLineKind, type MuncheLintFinding, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageBBox, type PageMargin, type PageMarkdown, type PageOptions, 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 RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RegionAsset, type RenderAsset, type RenderDocumentOptions, type RenderDocumentResult, type RenderFormat, type RenderObjectType, type RenderRegion, type RenderScene, type RenderSourceFormat, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type ScenePage, type SceneRenderOptions, type SceneRenderResult, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, type TableRepresentation, type TableVisualPolicy, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPages, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, chooseTableRepresentation, classifyTable, classifyTableTree, collectTableBlocks, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractClickHereFields, extractFormFields, extractFormSchema, extractRenderedRegions, extractTables, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, hasStructuredCellContent, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, lintMuncheText, markdownToHwpx, markdownToPdf, measureTextWidth, muncheLintWarnings, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parseImage, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, readBuiltinTemplate, readBuiltinTemplateSample, redactMarkdown, redactText, renderDocument, renderDocumentToScene, renderHtml, renderHwp5Pages, renderHwpxToSvg, renderSceneToHtml, resolveBuiltinTemplate, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, usesGaejosikMunche, validateHwpx };
+export { BUILTIN_TEMPLATES, type BlockCapability, type BlockCapabilityInfo, type BlockDiff, type BlockEdit, type BlockSourceRef, type BorderDef, type BorderFillDef, type BoundingBox, type BuiltinTemplate, type CellCapability, type CellContext, type CellDiff, type CellProfile, type CharPrDef, type ChunkOptions, type ClassifyContext, type ClickHereField, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, type DocumentMetadata, type DocumentQualitySummary, type ErrorCode, type ExtractRegionOptions, type ExtractTableVisualOptions, type ExtractedImage, type ExtractedTable, type ExtractedTableCrop, 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 MuncheLineKind, type MuncheLintFinding, type OcrProvider, type OutlineItem, PRESET_ALIAS, type PageBBox, type PageMargin, type PageMarkdown, type PageOptions, 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 RedactHit, type RedactOptions, type RedactRule, type RedactTextResult, type RegionAsset, type RenderAsset, type RenderDocumentOptions, type RenderDocumentResult, type RenderFormat, type RenderObjectType, type RenderRegion, type RenderScene, type RenderSourceFormat, type RenderSvgOptions, type RenderSvgResult, SPACE_EM_FIXED, SPACE_EM_FONT, type ScanCell, type ScanParaKind, type ScanParagraph, type ScanTable, type ScenePage, type SceneRenderOptions, type SceneRenderResult, type SealOp, type SealPlacement, type SectionScan, type SpliceEdit, type TRange, type TableProfile, type TableRepresentation, type TableVisualPolicy, VERSION, type ValidateIssue, type ValidateResult, ValueCursor, type WarningCode, type WatchOptions, type WrapMode, type WrapResult, applySplices, blocksToChunks, blocksToMarkdown, blocksToPages, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, chooseTableRepresentation, classifyTable, classifyTableTree, collectTableBlocks, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractClickHereFields, extractFormFields, extractFormSchema, extractRenderedRegions, extractTables, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, flattenLayoutTables, formatFillValue, gongmunLintWarnings, hasStructuredCellContent, hwpxToProfile, incompatibleGongmunWarnings, inferFieldType, isHwpxFile, isKnownFont, isLabelCell, isOldHwpFile, isPdfFile, isZipFile, lintGongmunText, lintMuncheText, markdownToHwpx, markdownToPdf, measureTextWidth, muncheLintWarnings, normalizeGongmunPreset, openHwpxDocument, parse, parseDocx, parseHwp, parseHwp3, parseHwpml, parseHwpx, parseImage, parsePdf, parseXls, parseXlsx, patchHwp, patchHwpx, patchHwpxBlocks, placeSealHwpx, readBuiltinTemplate, readBuiltinTemplateSample, redactMarkdown, redactText, renderDocument, renderDocumentToScene, renderHtml, renderHwp5Pages, renderHwpxToSvg, renderSceneToHtml, resolveBuiltinTemplate, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, usesGaejosikMunche, validateHwpx };