kordoc 4.12.2 → 4.13.0

package/dist/index.d.ts

@@ -88,12 +88,28 @@ interface InlineStyle {
     fontSize?: number;
     fontName?: string;
 }
+type TableClassificationKind = "semantic-table" | "non-tabular-layout" | "uncertain";
+type TableClassificationReason = "repeated-row-schema" | "grid-regularity" | "high-active-density" | "column-type-consistency" | "nested-structure-wrapper" | "span-irregularity" | "spacer-bands" | "extreme-sparsity" | "diagram-context-keyword" | "low-evidence" | "ambiguous-scores";
+/** 휴리스틱 분류 결과 — confidence 는 확률이 아니라 두 점수의 격차 */
+interface TableClassificationSummary {
+    kind: TableClassificationKind;
+    confidence: number;
+    semanticScore: number;
+    nonTabularScore: number;
+    reasons: TableClassificationReason[];
+}
 interface IRTable {
     rows: number;
     cols: number;
     cells: IRCell[][];
     /** 첫 행을 헤더로 렌더링할지 여부 (현재: rows > 1이면 true — 의미적 감지가 아닌 레이아웃 힌트) */
     hasHeader: boolean;
+    /** opt-in 분류(`ParseOptions.classifyTables`) 결과 — #76 */
+    classification?: TableClassificationSummary;
+    /** 원본 표 식별자(HWPX `hp:tbl id`) — 렌더 region(`RenderRegion.sourceId`)과의 조인 키 */
+    sourceId?: string;
+    /** 렌더 인프라가 준 페이지 로컬 pt 조각(다중 페이지 표는 여럿) — extractTables 가 채운다 */
+    regions?: BoundingBox[];
     /** 표 캡션 (예: "표 1. 부서별 예산") — v3.0 */
     caption?: string;
     /**
@@ -170,6 +186,9 @@ interface ParseOptions {
      *  기본 false: 마크다운 가독성을 위해 후행 빈 열을 트림.
      *  양식 인식 경로(parse_form·fill)는 내부적으로 항상 켠다. */
     keepTrailingEmptyCols?: boolean;
+    /** 구조 파싱 뒤 표를 의미표/레이아웃/불확실로 분류해 `IRTable.classification` 에 붙인다 (#76).
+     *  기본 false — 기본 parse 출력 불변. 중첩표·셀 blocks·캡션 blocks 까지 재귀, 원문 순서는 바꾸지 않는다. */
+    classifyTables?: boolean;
     /** 빈 문단(텍스트 없는 hp:p) 보존 (#57). 기본 false: 종전대로 빈 문단 제거.
      *  켜면 본문은 `text: ""` paragraph 블록으로, 표 셀은 빈 줄로 순서대로 보존해
      *  "원문 문단 수 = 줄 수" 대응을 유지한다 (행 줄맞춤 서식 문서용).
@@ -781,6 +800,15 @@ type GongmunNumbering = "standard" | "report" | "gaejosik";
 type GongmunFont = "myeongjo" | "gothic";
 /** 프리셋 입력값 — 영문 키 또는 한글 별칭(기안문·보고서·계획서·통지·회의록 등) */
 type GongmunPresetInput = GongmunPreset | "기안문" | "시행문" | "공문" | "공문서" | "보고서" | "계획서" | "계획" | "통지" | "알림" | "안내" | "회의록" | "개조식" | "개조식보고서" | "정부보고서" | "정부표준개조식보고서" | "보도자료";
+/** 항목부호 단계 하나의 타이포 — 셋 다 선택(미지정=본문 계열 유지) */
+interface GongmunLevelStyle {
+    /** 글꼴명 (예: HY견고딕·한컴돋움·휴먼명조) */
+    font?: string;
+    /** 글자 크기 pt (6~60) */
+    pt?: number;
+    /** 굵게 */
+    bold?: boolean;
+}
 /** 공문서 모드 옵션 (전부 선택 — 프리셋 기본값을 개별 override) */
 interface GongmunOptions {
     /** 문서 종류 프리셋(영문 키 또는 한글 별칭). 기본 'official'(일반 기안문) */
@@ -800,6 +828,7 @@ interface GongmunOptions {
     cover?: boolean | {
         date?: string;
         org?: string;
+        dept?: string;
     };
     /** 목차 페이지(개조식 프리셋 기본 켜짐) — h2 목록을 Ⅰ Ⅱ Ⅲ…로 자동 생성. false로 끔 */
     toc?: boolean;
@@ -834,6 +863,14 @@ interface GongmunOptions {
     };
     /** 개조식 요소별 글자 크기(pt) 오버라이드 — 미지정 요소는 bodyPt 비례 기본값 */
     sizes?: GaejosikSizeOverrides;
+    /**
+     * 항목부호 단계별 위계 타이포(v4.12.3) — depth(0~7)마다 글꼴·크기(pt)·굵기를 지정한다.
+     * 실측(실결재 기안문 206 + 보고서 337건): 법정 8단계(1. 가. 1))는 본문과 동일이 90%라 기본은
+     * 무변경, □/ㅇ/- 계열 전자결재 기안문은 □=HY견고딕 +2~3pt bold·ㅇ=한컴돋움 bold·-=휴먼명조가
+     * 지배 관행이다(docs/gongmunseo-reference.md 2.7). 지정한 단계만 바뀌고 나머지는 본문 계열.
+     * 개조식·보고서의 실측 □(HY헤드라인M)·보도자료 각주보다 우선한다(명시 옵션).
+     */
+    levels?: Record<number | string, GongmunLevelStyle>;
     /** 쪽번호(하단 중앙 "- 1 -", 표지·목차는 카운트 제외). 기본: 개조식·보고서·계획서 켜짐 */
     pageNumbers?: boolean;
     /** 본문 끝 2타+"끝." 표시(행정업무규정). 기본: 기안문(official)만 켜짐 */
@@ -843,11 +880,11 @@ interface GongmunOptions {
     /** 본문 첫 페이지 제목 박스(개조식) — 목차 뒤 본문 시작에 제목 반복(실측 관행). 기본: 표지 있으면 켜짐 */
     bodyTitleBox?: boolean;
     /**
-     * h2 섹션 제목 말머리 (비개조식 — 개조식 h2는 로마숫자 장 헤더가 대체).
-     * 'box'=□ 대항목(실측 보고서 양식 관행) / 'number'=아라비아 번호(1. 2. — 공고문 관행)
-     * / 'none'=말머리 없음. 기본: 보고서·계획서 'box', 공고문 'number', 그 외 'none'.
+     * h2 장 제목 표기 (v5): 'band'=로마자 채움 칸 + 제목 띠 표(보고서·계획서 기본 — 계획서 장르 실측 37~39%) /
+     * 'roman'=Ⅰ. Ⅱ. 텍스트 / 'number'=1. 2. (통지 기본) / 'box'=장 없이 □ 대항목으로 / 'none'=번호 없음.
+     * 기안문 본문의 h2는 항상 법정 1. 항목.
      */
-    h2Marker?: "box" | "number" | "none";
+    h2Marker?: "band" | "roman" | "box" | "number" | "none";
     /**
      * 2단계 항목부호 — 'ㅇ'(이응, 전자결재 기안문·공고문 실측 지배) / '○'(원, 보고서
      * 양식 계열 실측). 기본: notice·press 'ㅇ', 그 외 '○' (v4.1.0 실결재 60건 분포).
@@ -860,22 +897,29 @@ interface GongmunOptions {
      * 적용되지 않으므로, 기본 numbering이 report인 plan 프리셋은 numbering:'standard' 병기 필요.
      */
     suppressSingle?: boolean;
-    /** 기안문 두문 — 행정기관명·수신·경유·제목 (별지 제1호서식, official 전용) */
+    /** 기안문 두문표 — 행정기관명·(원훈 slogan)·수신·경유·제목 (별지 제1호서식·서울 실결재 6행 표, official 전용) */
     docHead?: {
         org?: string;
+        slogan?: string;
         to?: string;
         via?: string;
         title?: string;
     };
-    /** 기안문 결문 — 발신명의·기안/검토/결재·시행/접수·주소·연락처·공개구분 (official 전용) */
+    /**
+     * 기안문 결문표 — 발신명의·결재선(기안/검토/결재 또는 approvers 배열 "직위 성명")·협조자·수신자·
+     * 시행/접수·우편번호(zip)·주소·홈페이지·전화·전송·이메일·공개구분 (official 전용)
+     */
     docFoot?: {
         sender?: string;
         drafter?: string;
         reviewer?: string;
         approver?: string;
+        approvers?: string[];
         cooperator?: string;
+        recipients?: string;
         docNum?: string;
         receive?: string;
+        zip?: string;
         address?: string;
         site?: string;
         phone?: string;
@@ -883,6 +927,15 @@ interface GongmunOptions {
         email?: string;
         disclosure?: string;
     };
+    /** 보고서 요약 박스(제목표 아래 #DFE6F7 상자, 서울 실결재) — 마크다운 제목 직후 인용문(>)으로도 지정 가능 */
+    summary?: string;
+    /** 보고서 표지 문서정보표 — 문서번호·결재일자·공개여부·방침번호 (cover와 함께) */
+    docInfo?: {
+        docNum?: string;
+        date?: string;
+        disclosure?: string;
+        policyNo?: string;
+    };
     /** 업무보고 우상단 보고정보 행 — "(보고일시, 보고자, 연락처)" (실측 t3: 휴먼명조 12pt RIGHT) */
     reportInfo?: string;
     /** 공고문 두문·결문 — 공고번호(본문 위)·날짜·발신명의(본문 아래 우측, 실측 바이오헬스 공고) */
@@ -1102,6 +1155,11 @@ interface MarkdownToHwpxOptions {
      * URI는 이 맵 없이도 임베드. 바이트가 없는 url은 종전 placeholder 참조 보존.
      */
     images?: Record<string, Uint8Array | ArrayBuffer>;
+    /**
+     * 경고 수집 싱크 (v5) — 생성기가 조용히 처리한 것(□ 한 줄 축소 한계 초과·제목 축소 등)을
+     * 여기에 push한다. 호출 표면(CLI stderr·MCP 응답)이 노출.
+     */
+    warnings?: string[];
 }
 /**
  * 마크다운 텍스트를 HWPX (ArrayBuffer)로 변환.
@@ -1151,6 +1209,7 @@ declare function unknownFontWarnings(fonts: Record<string, string | undefined>):
  * (v4.0.1). URL 쌍점 오탐 가드 등 일부 보강. v4.12.1 에 금액 한글 병기·물결표·두음법칙·
  * 외래어·차별 표현·"끝." 누락 6룰 보강 (pyhwpxlib Gongmun 검사 항목 대조). 검사는 조언용이다 — 생성은 막지 않고
  * 경고만 낸다 (A2 폰트경고와 같은 원칙). 별도 CLI `kordoc lint`는 error 시 exit 1.
+ * v4.13.0: 하이픈 날짜(2026-07-18) 룰, 금액 한글 병기·하이픈 날짜는 실제 변환값을 제안.
  */
 interface GongmunLintFinding {
     /** 1-based 줄 번호 */
@@ -1248,7 +1307,7 @@ declare const SPACE_EM_FONT = 300;
  * 넓어 함초롬 테이블로 재면 줄당 1~2자 과대적재로 wrap 지점이 어긋난다
  * (bench/verify-linebreak.mjs seoul 코퍼스 실측: fixedPitch 테이블로 74/75 일치).
  */
-type FaceClass = "hcr" | "fixedPitch";
+type FaceClass = "hcr" | "fixedPitch" | "gothic";
 interface MeasureOptions {
     /** 공백 폭(em×1000). 기본 SPACE_EM_FIXED(500) = useFontSpace 0 */
     spaceEm?: number;
@@ -1730,6 +1789,56 @@ declare function markdownToPdf(markdown: string, options?: PrintOptions): Promis
 /** IRBlock[] → PDF (Buffer). */
 declare function blocksToPdf(blocks: IRBlock[], options?: PrintOptions): Promise<Buffer>;
 
+/**
+ * 공유 렌더 장면(RenderScene) 계약 — HWPX/HWP5 어댑터가 채우고 SVG·HTML·래스터·PDF·crop 이 소비한다 (#75).
+ *
+ * 좌표 규약: 공개 bbox 는 **pt**, **페이지 로컬**(물리 페이지 좌상단 원점), 페이지 번호 **1-based**.
+ * 한 논리 개체가 여러 페이지에 걸치면 `regions` 에 페이지별 조각을 여럿 둔다(세로 스택 전역 좌표 금지).
+ * region id 는 같은 문서·같은 옵션이면 결정적 — 그리기(문서) 순서로 유형별 일련번호를 매긴다.
+ */
+type RenderSourceFormat = "hwpx" | "hwp";
+type RenderObjectType = "paragraph" | "table" | "image" | "shape" | "equation" | "unknown";
+interface PageBBox {
+    /** 1-based 페이지 */
+    page: number;
+    /** pt, 페이지 로컬, 좌상단 원점 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface RenderRegion {
+    /** 결정적 id — `table-000017` 꼴 */
+    id: string;
+    type: RenderObjectType;
+    /** 첫 조각의 페이지 (편의 필드) */
+    page: number;
+    /** 페이지별 조각 — 한 논리 개체가 여러 물리 페이지에 걸칠 수 있다 */
+    regions: PageBBox[];
+    /** 원본 식별자(HWPX `hp:tbl id` 등) — 있을 때만 */
+    sourceId?: string;
+    /** 중첩 표·셀 안 이미지·문단 안 개체의 부모 region */
+    parentId?: string;
+}
+interface ScenePage {
+    page: number;
+    /** pt */
+    width: number;
+    height: number;
+}
+interface RenderScene {
+    format: RenderSourceFormat;
+    pages: ScenePage[];
+    regions: RenderRegion[];
+    warnings: string[];
+    stats: {
+        texts: number;
+        tables: number;
+        images: number;
+        shapes: number;
+    };
+}
+
 /**
  * 레이아웃 보존 렌더 — HWPX 조판 캐시(lineseg·cellAddr·hp:pos)를 SVG 절대배치로 그린다.
  *
@@ -1779,7 +1888,10 @@ interface RenderSvgResult {
         texts: number;
         images: number;
         tables: number;
+        shapes: number;
     };
+    /** 개체 region(페이지 로컬 pt bbox·결정적 id) — #75 */
+    regions: RenderRegion[];
 }
 /**
  * HWPX(한컴 저장본) → 레이아웃 보존 SVG. **전 구역(section*)을 세로 스택으로** 렌더한다.
@@ -1788,6 +1900,191 @@ interface RenderSvgResult {
  */
 declare function renderHwpxToSvg(input: ArrayBuffer | Uint8Array, options?: RenderSvgOptions): Promise<RenderSvgResult>;
 
+/**
+ * 통합 문서 렌더 API (#75 Task 3·8) — 입력(경로/버퍼) → 포맷 감지 → 어댑터 → RenderScene + 페이지 SVG
+ * → SVG/HTML/PNG/JPEG/PDF 자산. 다운스트림은 RenderScene 만 알면 된다.
+ *
+ *   hwpx → HWPX 어댑터(svg-render, 조판 캐시 재생·reflow 폴백)
+ *   hwp  → HWP5 어댑터는 후속(#75 Task 7) — 지금은 KordocError
+ *   기타 → 미지원
+ */
+
+type RenderFormat = "svg" | "html" | "png" | "jpeg" | "pdf";
+interface SceneRenderOptions {
+    /** 1-based 페이지 선택 — [2,3] 또는 "1-3,7". 미지정이면 전 페이지 */
+    pages?: number[] | string;
+    /** 조판 캐시 없는 HWPX 를 순수 TS 조판으로 렌더 (기본 true — 캐시가 있으면 무시) */
+    reflow?: boolean;
+    reflowMode?: WrapMode;
+    highlights?: string[];
+    maxImageBytes?: number;
+}
+interface SceneRenderResult {
+    scene: RenderScene;
+    /** 선택된 페이지의 standalone SVG (페이지 로컬 좌표) */
+    pageSvgs: Map<number, string>;
+}
+interface RenderDocumentOptions extends SceneRenderOptions {
+    format: RenderFormat;
+    /** 래스터 출력 최대 폭 px */
+    maxWidthPx?: number;
+    /** JPEG 품질 */
+    quality?: number;
+    /** PDF 용 Chromium 실행 파일 */
+    browserExecutablePath?: string;
+    /** HTML/PDF 문서 제목 */
+    title?: string;
+}
+interface RenderAsset {
+    format: RenderFormat;
+    /** 페이지 단위 산출은 page, 문서 단위(HTML/PDF)는 없음 */
+    page?: number;
+    data: string | Buffer;
+    /** 픽셀(래스터) 또는 pt(SVG) */
+    width?: number;
+    height?: number;
+    /** 래스터 pt→px 실배율 */
+    scale?: number;
+    mimeType?: string;
+}
+interface RenderDocumentResult {
+    scene: RenderScene;
+    assets: RenderAsset[];
+}
+type RenderInput = string | ArrayBuffer | Buffer | Uint8Array;
+/**
+ * 문서 → RenderScene + 선택 페이지 SVG. 페이지 선택은 조립 단계에서 걸러 비선택 페이지의 SVG 문자열을 만들지 않는다.
+ * 선택 결과가 비면(범위 밖) KordocError.
+ */
+declare function renderDocumentToScene(input: RenderInput, options?: SceneRenderOptions): Promise<SceneRenderResult>;
+/** 통합 렌더 — 포맷별 자산. 래스터·PDF 는 선택 페이지만 처리한다 */
+declare function renderDocument(input: RenderInput, options: RenderDocumentOptions): Promise<RenderDocumentResult>;
+
+/**
+ * 레이아웃 보존 HTML — 페이지별 standalone SVG 를 `.kordoc-page[data-page]` 로 감싼 자급자족 문서 (#75 Task 4).
+ * 의미 HTML(IRBlock → <h1>/<p>/<table>) 이 아니다 — 원본 조판 재현이 목적. CDN·외부 자원 없음.
+ * 인쇄 CSS(@page 크기 = 첫 페이지 크기, 페이지마다 break-after) 를 포함해 PDF 경로가 그대로 소비한다.
+ */
+
+interface SceneHtmlOptions {
+    /** <title> — 기본 "kordoc" */
+    title?: string;
+}
+/**
+ * @param scene    페이지 크기 메타(전 페이지)
+ * @param pageSvgs 페이지 번호 → standalone SVG (선택된 페이지만 있어도 된다 — 있는 페이지만 방출)
+ */
+declare function renderSceneToHtml(scene: RenderScene, pageSvgs: Map<number, string>, options?: SceneHtmlOptions): string;
+
+type RasterFormat = "png" | "jpeg";
+
+/**
+ * region crop (#75 Task 5) — RenderScene 의 페이지 로컬 bbox 를 래스터 실배율로 픽셀 환산해 잘라낸다.
+ * DPI 를 여기서 다시 추정하지 않는다: pixel = pt × rasterize 가 돌려준 scale.
+ * 의미 판단(진짜 표인지 조직도인지)은 하지 않는다 — 렌더러가 표라고 아는 개체를 자르는 것뿐.
+ */
+
+interface ExtractRegionOptions extends Pick<SceneRenderOptions, "pages" | "reflow" | "reflowMode"> {
+    /** 기본 전 유형 */
+    types?: RenderObjectType[];
+    format?: RasterFormat;
+    /** bbox 둘레 여백(pt) — 페이지 안으로 클램프 */
+    paddingPt?: number;
+    /** 페이지 래스터 최대 폭 px (crop 해상도) */
+    maxWidthPx?: number;
+    quality?: number;
+    /** region 선별 — sourceId·id 로 특정 개체만 자를 때 (extractTables). types 필터 뒤에 적용 */
+    filter?: (region: RenderRegion) => boolean;
+}
+interface RegionAsset {
+    region: RenderRegion;
+    page: number;
+    bbox: PageBBox;
+    mimeType: "image/png" | "image/jpeg";
+    data: Buffer;
+    widthPx: number;
+    heightPx: number;
+}
+/** 렌더러가 아는 개체(표·이미지·문단·도형)를 페이지 이미지에서 잘라낸다. 페이지당 래스터 1회 */
+declare function extractRenderedRegions(input: RenderInput, options?: ExtractRegionOptions): Promise<RegionAsset[]>;
+
+/**
+ * 표 분류기 (#76) — IRTable 이 "데이터 표"인지 "표를 레이아웃 캔버스로 쓴 것"(조직도·비상연락망·체계도)인지 휴리스틱 판정.
+ *
+ * 신호는 두 축. 의미 신호: 반복 행 스키마·격자 규칙성·활성 밀도·열 타입 일관성. 비표 신호: 병합 불규칙·빈 띠(행/열)·
+ * 극단적 희소·중첩 구조 래퍼. 도표 문맥 키워드(조직도 등)는 구조 증거가 있을 때만 가산한다 — "조직도" 한 단어가 정상 표를
+ * 도표로 바꾸면 안 된다. LLM·네트워크 없음. confidence 는 확률이 아니라 두 점수의 격차.
+ */
+
+interface ClassifyContext {
+    /** 표 앞뒤 문단·캡션 텍스트 — 도표 문맥 키워드 판정용 */
+    nearbyText?: string[];
+}
+declare function classifyTable(table: IRTable, ctx?: ClassifyContext): TableClassificationSummary;
+/** 셀 안 블록에서 표 블록 재귀 수집 (문서 순서) — analyze·visual 이 공유 */
+declare function collectTableBlocks(blocks: IRBlock[], out?: IRBlock[]): IRBlock[];
+
+/**
+ * 표 분류 배선 (#76 Task 3·5) — 파싱이 끝난 IRBlock 트리를 재귀하며 `IRTable.classification` 을 붙인다.
+ * 원문 순서·셀 텍스트·캡션은 건드리지 않는다(메타만 추가). 기본 parse 는 이 함수를 부르지 않는다(opt-in).
+ */
+
+/** 트리 전체 분류(변경은 classification 필드 추가뿐). 같은 배열을 돌려준다 */
+declare function classifyTableTree(blocks: IRBlock[]): IRBlock[];
+type TableRepresentation = "gfm" | "html" | "visual";
+/**
+ * 분류 인식 표현 정책 — `visual` 은 명시 요청(스마트 시각 출력)에서만 나온다. 기본 마크다운 경로는 이 함수를 쓰지 않는다.
+ *   단순 의미표 → gfm(손실 없을 때) · 구조 셀/병합 → html · non-tabular(+smart) → visual · uncertain(+smart) → html(구조)+시각은 호출자
+ */
+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(hp:tbl id) 로 IRTable.sourceId 를 잇는다.
+ * HWP5 는 렌더 어댑터가 없어 분류만 되고 regions/crops 는 비며 경고를 남긴다.
+ */
+
+type TableVisualPolicy = "none" | "non-tabular" | "non-tabular-and-uncertain" | "all";
+interface ExtractTableVisualOptions {
+    /** 어떤 분류에 crop 을 만들지 — 기본 non-tabular-and-uncertain. none 이면 분류·region 만 */
+    policy?: TableVisualPolicy;
+    format?: "png" | "jpeg";
+    paddingPt?: number;
+    /** 페이지 래스터 최대 폭 px */
+    maxWidthPx?: number;
+}
+interface ExtractedTableCrop {
+    page: number;
+    bbox: PageBBox;
+    mimeType: "image/png" | "image/jpeg";
+    data: Buffer;
+}
+interface ExtractedTable {
+    /** sourceId(HWPX) 또는 문서 순서 `tbl-N` */
+    id: string;
+    page: number;
+    table: IRTable;
+    classification: TableClassificationSummary;
+    sourceId?: string;
+    regions: PageBBox[];
+    crops: ExtractedTableCrop[];
+    /** 표별 경고 — region 미매칭·중복 매칭·HWP5 미지원 */
+    warnings: string[];
+}
+/** 문서 → 분류된 표 목록(+HWPX 는 region·crop). 정상 parse 는 래스터하지 않는다 — 이 API 만 명시적으로 */
+declare function extractTables(input: string | ArrayBuffer | Buffer, options?: ExtractTableVisualOptions): Promise<ExtractedTable[]>;
+
 /** 매직 바이트 기반 파일 포맷 감지 */
 
 /** ZIP 파일 여부: PK\x03\x04 */
@@ -1813,10 +2110,6 @@ declare function detectOle2Format(buffer: ArrayBuffer): "hwp" | "xls" | "unknown
  */
 declare function detectZipFormat(buffer: ArrayBuffer): Promise<"hwpx" | "xlsx" | "docx" | "unknown">;
 
-/** 2-pass colSpan/rowSpan 테이블 빌더 및 Markdown 변환 */
-
-declare function blocksToMarkdown(blocks: IRBlock[]): string;
-
 /**
  * 페이지별 마크다운 사영 (#68)
  *
@@ -1913,4 +2206,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 ClickHereField, DEFAULT_REDACT_RULES, type DiffChangeType, type DiffResult, type DocChunk, 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 MuncheLineKind, type MuncheLintFinding, type OcrProvider, type OutlineItem, PRESET_ALIAS, 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 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, blocksToChunks, blocksToMarkdown, blocksToPages, blocksToPdf, buildParagraphSplices, buildRangeSplices, charWidthEm1000, compare, detectFormat, detectOle2Format, detectZipFormat, diffBlocks, extractClickHereFields, extractFormFields, extractFormSchema, fillForm, fillFormFields, fillHwpx, fillWithUniqueGuard, fitRatioForFewerLines, formatFillValue, gongmunLintWarnings, 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, renderHtml, renderHwpxToSvg, 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, 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, renderHwpxToSvg, renderSceneToHtml, resolveBuiltinTemplate, scanSectionXml, simulateWrap, simulateWrapKeepWord, unknownFontWarnings, usesGaejosikMunche, validateHwpx };