Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HwpForge

한글 문서(HWP/HWPX)를 프로그래밍으로 제어하는 Rust 라이브러리

crates.io docs.rs License: MIT OR Apache-2.0

본 제품은 한컴의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.


HwpForge란?

HwpForge는 한컴 한글의 HWP/HWPX 문서를 Rust로 읽고, 쓰고, 변환할 수 있는 라이브러리입니다. CLI·Python의 지원 읽기·편집 연산은 HWP5 입력을 자동 변환하며 편집 결과는 HWPX입니다. .hwp 저장은 지원하지 않습니다. 변환 손실의 거부·허용과 대상 명령은 CLI 입력 정책을 참고합니다. Rust의 hwpforge::ops와 MCP에는 명시적으로 변환한 HWPX를 전달합니다.

주요 기능

  • HWPX 풀 코덱 — HWPX 파일 디코딩/인코딩 + 무손실 라운드트립
  • HWP5 입력과 HWPX 출력 — CLI·Python의 지원 읽기·편집 자동 변환과 명시적 변환·점검 경로를 제공합니다
  • Markdown 브릿지 — GFM Markdown ↔ HWPX 변환
  • PDF 내보내기 — 문서에 들어 있는 조판 캐시(layout cache)를 재생해 PDF로 렌더 (to-pdf)
  • 편집 연산 (ops) — 누름틀 채우기, 표 셀 편집, 문단 삽입·삭제, 템플릿 스탬핑, diff·검증을 CLI·MCP·Python이 같은 구현으로 공유
  • Python 바인딩 — pip install hwpforge
  • MCP 서버 — AI 도구에서 한글 문서를 직접 생성·편집 (MCP 레퍼런스)
  • YAML 스타일 템플릿 — 재사용 가능한 디자인 토큰 (Figma 패턴)
  • 타입 안전 API — 브랜드 인덱스, 타입스테이트 검증, unsafe 코드 0

지원 콘텐츠

카테고리요소
텍스트런, 문자 모양, 문단 모양, 스타일 (한컴 기본 스타일 18/22/23개, 스타일 세트별)
구조표 (중첩), 이미지, 글상자, 캡션
레이아웃다단, 페이지 설정, 가로/세로, 여백, 마스터페이지
머리글/바닥글머리글, 바닥글, 쪽번호 (autoNum)
주석각주, 미주
도형선, 사각형, 타원, 다각형, 호, 곡선, 연결선, 묶음 객체, 글맵시 (채움/회전/화살표)
글자 효과덧말, 글자겹침
수식HancomEQN 스크립트
차트18종 차트 (OOXML 호환)
참조책갈피, 상호참조, 필드, 메모, 찾아보기
MarkdownGFM 디코드, 손실/무손실 인코드, YAML 프론트매터

누구를 위한 라이브러리인가?

  • LLM/AI 에이전트 — 자연어로 한글 문서 자동 생성
  • 백엔드 개발자 — 서버에서 한글 문서 프로그래밍 생성
  • 자동화 도구 — CI/CD 파이프라인에서 보고서 자동 생성
  • 데이터 파이프라인 — HWPX 문서에서 텍스트/표 추출

빠른 맛보기

#![allow(unused)]
fn main() {
use hwpforge::core::{Document, Draft, Paragraph, Run, Section, PageSettings};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};
use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};
use hwpforge::core::ImageStore;

// 1. 문서 생성
let mut doc = Document::<Draft>::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("안녕하세요, HwpForge!", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

// 2. 검증 + 인코딩
let validated = doc.validate().unwrap();
let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
let image_store = ImageStore::new();
let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap();

// 3. 파일 저장
std::fs::write("output.hwpx", &bytes).unwrap();
}

다음 단계

설치

HwpForge는 순수 Rust로 작성된 라이브러리입니다. 별도의 시스템 의존성 없이 Cargo.toml에 추가하는 것만으로 사용할 수 있습니다.

최소 지원 Rust 버전 (MSRV)

라이브러리 크레이트(hwpforge umbrella와 하위 크레이트 대부분)는 Rust 1.89 이상이 필요합니다. 현재 버전을 확인하려면:

rustc --version

버전이 낮다면 rustup으로 업데이트합니다:

rustup update stable

PDF 렌더(krilla)에 의존하는 hwpforge-smithy-pdf, hwpforge-convert, hwpforge-bindings-cli, hwpforge-bindings-py는 각 Cargo.toml에 rust-version = "1.92"가 지정돼 있어 Rust 1.92 이상이 필요합니다. hwpforge umbrella만 쓰는 라이브러리 사용자는 1.89면 충분하고, CLI를 소스에서 설치하거나 Python sdist를 빌드할 때만 1.92가 필요합니다.

의존성 추가

Cargo.toml의 [dependencies] 섹션에 추가합니다:

[dependencies]
hwpforge = "0.20"

기본 설치에는 HWPX 인코더/디코더가 포함됩니다.

Feature Flags

HwpForge는 필요한 기능만 선택적으로 활성화할 수 있습니다.

Feature기본 포함설명
hwpx예HWPX 인코더/디코더 (ZIP + XML, KS X 6101)
md아니오Markdown(GFM) ↔ HWPX 변환
ops-hwpx아니오HWPX 전용 표면(검사·교환·읽기·편집·diff·stamp·스타일)이 공유하는 연산 계층. hwpx를 함께 켭니다
ops-md아니오연산 계층에 Markdown 연산(convert_md, to_md)을 더합니다. ops-hwpx와 md를 함께 켭니다
ops아니오연산 계층 전체의 별칭(ops-md)
schemars아니오ops가 소유한 wire DTO와 교환 DTO에 JsonSchema derive를 더합니다. HWPX 코덱을 따라 켜지지는 않습니다
full아니오hwpx + md + ops를 켭니다(schemars는 포함하지 않음)

HWPX만 사용 (기본)

[dependencies]
hwpforge = "0.20"

Markdown 변환 포함

[dependencies]
hwpforge = { version = "0.20", features = ["md"] }

편집 연산 계층 포함

CLI·MCP·Python이 공유하는 연산(hwpforge::ops)을 라이브러리에서 직접 쓰려면 ops를 켭니다.

[dependencies]
hwpforge = { version = "0.20", features = ["ops"] }

모든 기능 활성화

[dependencies]
hwpforge = { version = "0.20", features = ["full"] }

빌드 확인

의존성을 추가한 후 빌드가 정상적으로 되는지 확인합니다:

cargo build

다음과 같이 컴파일이 성공하면 설치가 완료된 것입니다:

Compiling hwpforge v0.20.0
 Finished `dev` profile [unoptimized + debuginfo] target(s) in ...

CLI · MCP · Python

Rust 라이브러리 외에 다른 창구도 있습니다. 설치 방법은 각 장에 있습니다.

  • CLI (hwpforge): crates.io에 배포하지 않으므로 git 또는 로컬 경로에서 설치합니다. Rust 1.92 이상이 필요합니다. CLI 레퍼런스
  • MCP 서버 (hwpforge-mcp): npx -y @hwpforge/mcp 또는 cargo install hwpforge-bindings-mcp. MCP 서버 레퍼런스
  • Python: pip install hwpforge. Python 가이드

다음 단계

설치가 완료되었습니다. 빠른 시작으로 이동하여 첫 번째 HWPX 문서를 생성해 보세요.

빠른 시작

이 페이지에서는 HwpForge의 세 가지 핵심 사용 패턴을 코드 예제와 함께 설명합니다.

세 예제 모두 hwpforge 하나만 의존성으로 두면 그대로 컴파일됩니다 — 오류 타입은 표준 라이브러리의 Box<dyn std::error::Error>를 쓰므로 오류 처리 크레이트를 따로 추가할 필요가 없습니다. 예제 3은 features = ["md"]가 필요합니다(설치).

예제 1: 텍스트 문서 생성 후 HWPX로 저장

가장 기본적인 사용 패턴입니다. 문서 구조를 직접 조립하고 HWPX 파일로 출력합니다.

use hwpforge::core::{Document, Draft, ImageStore, PageSettings, Paragraph, Run, Section};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};
use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Draft 상태의 문서 생성
    let mut doc = Document::<Draft>::new();

    // 2. 텍스트 Run 구성 — CharShapeIndex(0)은 기본 글자 스타일을 참조
    let run = Run::text("안녕하세요, HwpForge입니다!", CharShapeIndex::new(0));

    // 3. 문단 생성 — ParaShapeIndex(0)은 기본 문단 스타일을 참조
    let paragraph = Paragraph::with_runs(vec![run], ParaShapeIndex::new(0));

    // 4. 섹션(= 쪽 단위 컨테이너)에 문단 추가, A4 용지 설정
    let section = Section::with_paragraphs(vec![paragraph], PageSettings::a4());
    doc.add_section(section);

    // 5. 유효성 검증 — Draft → Validated 상태 전이 (타입스테이트)
    let validated = doc.validate()?;

    // 6. 스타일 스토어: 한컴 Modern(22종) 기본 스타일 사용
    let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");

    // 7. 이미지 스토어: 이미지가 없으므로 빈 스토어 사용
    let image_store = ImageStore::new();

    // 8. HWPX 바이트 인코딩 후 파일 저장
    let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store)?;
    std::fs::write("output.hwpx", &bytes)?;

    println!("output.hwpx 저장 완료 ({} bytes)", bytes.len());
    Ok(())
}

참고: CharShapeIndex::new(0)과 ParaShapeIndex::new(0)은 HwpxStyleStore::with_default_fonts()이 제공하는 기본 스타일(본문)을 가리킵니다. 커스텀 스타일을 사용하려면 스타일 템플릿 문서를 참고하세요.


예제 2: HWPX 파일 디코딩

기존 HWPX 파일을 읽어서 Core 문서 모델로 변환합니다.

use hwpforge::hwpx::HwpxDecoder;
use hwpforge::core::run::RunContent;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 파일 경로를 받아 HWPX를 디코딩
    let result = HwpxDecoder::decode_file("input.hwpx")?;

    let doc = &result.document;

    // 섹션 수 출력
    println!("섹션 수: {}", doc.sections().len());

    // 메타데이터 접근 (제목, 작성자, 작성일 등)
    let meta = doc.metadata();
    if let Some(title) = &meta.title {
        println!("제목: {}", title);
    }
    if let Some(author) = &meta.author {
        println!("작성자: {}", author);
    }

    // 각 섹션의 문단과 텍스트 출력
    for (sec_idx, section) in doc.sections().iter().enumerate() {
        println!("--- 섹션 {} ---", sec_idx + 1);
        for paragraph in &section.paragraphs {
            for run in &paragraph.runs {
                if let RunContent::Text(ref text) = run.content {
                    print!("{}", text);
                }
            }
            println!(); // 문단 끝 줄바꿈
        }
    }

    Ok(())
}

HwpxDecoder::decode_file은 경로를 받아 ZIP을 열고 XML을 파싱합니다. 반환값에는 document(문서 구조), style_store(글꼴/문단 스타일), image_store(이미지), warnings(디코드 중 표면화된 비치명 경고)가 포함됩니다. document.metadata()로 제목, 작성자 등의 메타데이터에 접근할 수 있습니다.


예제 3: Markdown → HWPX 변환

GFM(GitHub Flavored Markdown) 텍스트를 HWPX 파일로 변환합니다. features = ["md"] 또는 features = ["full"]이 필요합니다.

use hwpforge::core::ImageStore;
use hwpforge::hwpx::{HwpxEncoder, HwpxRegistryBridge};
use hwpforge::md::MdDecoder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. GFM Markdown 텍스트 (YAML 프론트매터 지원)
    let markdown = r#"---
title: 보고서 제목
author: 홍길동
date: 2026-03-06
---

1장. 서론

본 보고서는 HwpForge를 이용한 **자동 문서 생성** 예시입니다.

# 1.1 배경

- 항목 A
- 항목 B
- 항목 C

# 1.2 결론

> HwpForge는 LLM 에이전트가 한글 문서를 생성할 때 사용할 수 있습니다.
"#;

    // 2. Markdown → Core 문서 모델 변환
    //    MdDecoder::decode_with_default는 document + style_registry(스타일 매핑)를 반환
    let md_doc = MdDecoder::decode_with_default(markdown)?;

    // 3. registry-local 스타일 인덱스를 HWPX store-local 인덱스로 rebinding
    let bridge = HwpxRegistryBridge::from_registry(&md_doc.style_registry)?;
    let rebound = bridge.rebind_draft_document(md_doc.document)?;

    // 4. Draft → Validated 상태 전이
    let validated = rebound.validate()?;

    // 5. 이미지 없음
    let image_store = ImageStore::new();

    // 6. HWPX 인코딩 후 저장
    let bytes = HwpxEncoder::encode(&validated, bridge.style_store(), &image_store)?;
    std::fs::write("report.hwpx", &bytes)?;

    println!("report.hwpx 저장 완료");
    Ok(())
}

Markdown 변환 시 자동으로 처리되는 항목:

Markdown 요소변환 결과
# H1 ~ ###### H6한컴 개요 1 ~ 6 스타일
**굵게**글자 진하게
*기울임*글자 기울임
`코드`고정폭 글꼴
> 인용문들여쓰기 문단
- 목록글머리표 문단
1. 목록번호 문단
- [ ] 할 일체크 문단
YAML 프론트매터문서 메타데이터

다음 단계

아키텍처 개요

HwpForge는 대장간(Forge) 메타포를 기반으로 설계된 계층형 크레이트 구조를 갖습니다. 각 계층은 명확한 역할을 가지며, 상위 계층은 하위 계층에만 의존합니다.

Forge 메타포

쇠재료를 화덕에 달궈 모루에 올리고, 도면대로 망치로 두드리고, 바이스에 물려 다듬고, 집게로 옮깁니다. 대장장이는 사용자와 AI입니다.

계층역할이름
Foundation원시 타입, 단위, 인덱스Ingot · 쇠재료
Core형식 독립 문서 모델 — 모든 포맷이 거치는 허브Anvil · 모루
BlueprintYAML 스타일 템플릿Blueprint · 도면
Smithy형식별 인코더/디코더 (PDF는 쓰기 전용 렌더러)Hearth · 화덕
Convert포맷 간 변환 조율(비유 없음)
hwpforge우산 크레이트와 공유 연산Forge · 대장간
BindingsCLI, MCP, Python 인터페이스Hammer · Vise · Tongs

크레이트 의존성 그래프

graph TD
    F[hwpforge-foundation<br/>원시 타입] --> C[hwpforge-core<br/>문서 모델]
    F --> B[hwpforge-blueprint<br/>스타일 템플릿]
    C --> B
    F --> SH[hwpforge-smithy-hwpx<br/>HWPX 코덱]
    C --> SH
    B --> SH
    F --> SM[hwpforge-smithy-md<br/>Markdown 코덱]
    C --> SM
    B --> SM
    F --> S5[hwpforge-smithy-hwp5<br/>HWP5 decode/projection]
    C --> S5
    F --> SPDF[hwpforge-smithy-pdf<br/>레이아웃 캐시 재생 렌더러]
    C --> SPDF
    F --> CONV["hwpforge-convert<br/>HWP5 → HWPX 오케스트레이터"]
    C --> CONV
    SH --> CONV
    S5 --> CONV
    SPDF --> CONV
    F --> U[hwpforge<br/>umbrella crate]
    C --> U
    B --> U
    SH --> U
    SM --> U
    F --> CLI["hwpforge-bindings-cli<br/>CLI (shipped)"]
    C --> CLI
    U --> CLI
    SH --> CLI
    SM --> CLI
    S5 --> CLI
    SPDF --> CLI
    CONV --> CLI
    F --> MCP["hwpforge-bindings-mcp<br/>MCP (shipped)"]
    C --> MCP
    U --> MCP
    SH --> MCP
    SM --> MCP
    F --> PY["hwpforge-bindings-py<br/>Python"]
    U --> PY
    CONV --> PY
    SPDF --> PY

화살표는 Cargo.toml의 [dependencies] 직접 의존을 나타내며(A --> B는 B가 A에 의존), 개발용 의존성([dev-dependencies])은 제외했습니다. umbrella의 hwpforge-smithy-hwpx·hwpforge-smithy-md 의존은 각각 feature hwpx·md가 켜질 때만 생깁니다.

규칙: 의존성은 위에서 아래로만 흐릅니다. foundation을 수정하면 모든 크레이트가 재빌드됩니다. 따라서 foundation은 최소한으로 유지합니다.

공유 연산 계층: hwpforge::ops

공유 문서 연산은 umbrella crate hwpforge의 ops 모듈(feature ops)에 있고, HWP5 변환·PDF 렌더링 연산은 hwpforge-convert의 ops 모듈에 있습니다. 세 바인딩(CLI·MCP·Python)은 각자 포맷을 다루는 대신 이 연산 계층을 호출하며, 에러 코드 표(OpsCode)는 하나로 정의됩니다. 기존 공개 계약이 있는 CLI와 MCP는 레거시 코드 문자열을 각자의 호환 테이블로 유지하고, Python은 OpsCode 문자열을 직접 노출합니다.

핵심 원칙: 구조와 스타일의 분리

HwpForge는 HTML + CSS의 관계처럼 문서 구조와 스타일 정의를 완전히 분리합니다.

Core (구조)           Blueprint (스타일)
─────────────         ──────────────────
Paragraph             font: "맑은 고딕"
  style_ref: 2    ──▶  size: 10pt
  runs: [...]         color: #000000
  • Core는 스타일 ID(인덱스)만 보유합니다. 실제 글꼴 이름이나 크기를 모릅니다.
  • Blueprint는 스타일 정의를 YAML 템플릿으로 관리합니다.
  • Smithy 컴파일러가 Core + Blueprint를 조합해 최종 형식을 생성합니다.

이 구조 덕분에 하나의 YAML 템플릿을 여러 문서에 재사용하거나, 동일한 문서를 HWPX/Markdown 등 다른 형식으로 내보낼 수 있습니다.

타입스테이트 패턴: Document → Document

Document는 컴파일 타임에 상태를 추적하는 타입스테이트 패턴을 사용합니다.

#![allow(unused)]
fn main() {
use hwpforge::core::{Document, Draft, PageSettings, Paragraph, Run, Section};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};

// Draft 상태: 편집 가능, 저장 불가
let mut doc = Document::<Draft>::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("본문", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

// validate()를 호출해야만 Validated 상태로 전이
let validated = doc.validate().unwrap();

// Validated 상태에서만 인코딩 가능
// doc.validate()를 건너뛰면 컴파일 에러 발생
let bytes = hwpforge::hwpx::HwpxEncoder::encode(
    &validated,
    &hwpforge::hwpx::HwpxStyleStore::with_default_fonts("함초롬바탕"),
    &hwpforge::core::ImageStore::new(),
).unwrap();
}

잘못된 상태에서 저장을 시도하면 런타임 에러가 아닌 컴파일 에러가 발생합니다.

이중 포맷 설계: HWP5 + HWPX

한국에는 두 가지 주요 문서 포맷이 있습니다:

  • HWP5 (.hwp): OLE2/CFB 바이너리 컨테이너 + TLV 레코드 (1990년대~현재, 레거시)
  • HWPX (.hwpx): ZIP 컨테이너 + XML 파일 (KS X 6101 국가 표준, 2014년~현재)

HwpForge는 Core DOM이 포맷에 독립적이도록 설계하여 두 포맷을 통합 처리합니다:

HWP5 (.hwp)  ──decode──▶ ┌────────────────────┐ ◀──decode── Markdown (.md)
                          │  Document<Draft>   │
HWPX (.hwpx) ──decode──▶ │  (포맷 독립 IR)    │ ──encode──▶ HWPX / Markdown
                          └────────────────────┘

모든 Smithy 크레이트는 Core DOM으로/에서 변환만 수행합니다. 비즈니스 로직은 Core에만 의존하므로, 새 포맷(예: smithy-odt)을 추가해도 기존 코드를 수정할 필요가 없습니다.

CLI·Python의 지원 읽기·편집 연산은 hwpforge-convert를 통해 HWP5 입력을 HWPX로 자동 변환합니다. 편집 결과는 .hwpx이며 .hwp 저장은 지원하지 않습니다. Rust의 hwpforge::ops와 MCP는 자동 변환하지 않습니다. 대상 연산과 손실 정책은 CLI 입력 정책을 참고합니다.

자세한 내용은 HWP5와 HWPX: 이중 포맷 파이프라인을 참고하세요.

각 크레이트 설명

hwpforge-foundation

의존성이 없는 루트 크레이트입니다. 모든 크레이트가 공유하는 원시 타입을 정의합니다.

  • HwpUnit: 정수 기반 HWP 단위 (1pt = 100 HWPUNIT). 부동소수점 오차 없음
  • Color: BGR 바이트 순서 색상 타입. Color::from_rgb(r, g, b)로 생성
  • Index<T>: 팬텀 타입을 이용한 브랜드 인덱스. CharShapeIndex와 ParaShapeIndex를 혼용하면 컴파일 에러

hwpforge-core

형식에 독립적인 문서 모델입니다. 한글/Markdown/PDF 어디에도 종속되지 않습니다.

  • Document<S>, Section, Paragraph, Run — 기본 문서 구조
  • Table, Control, Shape — 복합 요소
  • PageSettings — 용지 크기, 여백, 가로/세로 방향

hwpforge-blueprint

YAML로 작성하는 스타일 템플릿 시스템입니다. 피그마의 디자인 토큰 개념과 유사합니다.

  • 상속(extends)과 병합(merge)을 지원하는 PartialCharShape / CharShape 두 타입 구조
  • StyleRegistry — 파싱 후 인덱스를 할당한 최종 스타일 집합

hwpforge-smithy-hwpx

HWPX ↔ Core 변환을 담당하는 핵심 코덱입니다. KS X 6101(OWPML) 국가 표준을 구현합니다.

  • HwpxDecoder — ZIP + XML 파싱 → Core 문서 모델
  • HwpxEncoder — Core 문서 모델 → ZIP + XML 바이트
  • HwpxStyleStore — 한컴 기본 스타일 22종(Modern) 내장

hwpforge-smithy-md

GFM(GitHub Flavored Markdown) ↔ Core 변환을 담당합니다.

  • MdDecoder — Markdown + YAML 프론트매터 → Core
  • MdEncoder — Core → Markdown (손실/무손실 모드)

hwpforge (umbrella crate)

모든 공개 크레이트를 재내보내기(re-export)하는 진입점 크레이트입니다. 사용자는 이 크레이트 하나만 의존성에 추가하면 됩니다.

다음 단계

Python

hwpforge 패키지는 HwpForge Rust 라이브러리를 얇게 감싼 Python 바인딩입니다. HWPX 문서를 읽고, 검사하고, 편집하고, Markdown·JSON·PDF로 내보냅니다. 지원 읽기·편집 연산은 옛 HWP5(.hwp) 입력도 자동 변환하며 편집 결과는 HWPX입니다. 연산의 의미는 CLI·MCP 서버와 같은 연산 계층(hwpforge::ops)에서 오므로 HWPX 입력에서는 세 창구가 같은 문서에 같은 결과를 내고, 메서드 이름·인자 표기·일부 실패 코드만 Python의 공개 계약으로 따로 정해져 있습니다.

이 페이지는 설치와 핵심 개념을 다루고, 세부는 하위 페이지로 나뉩니다.

페이지내용
문서 읽기와 검사open·inspect·outline·fields·read·validate·diff·stamp_plan
편집fill·patch·set_cell·insert_para/delete_para·stamp·restyle, 한컴 저장 문서에서 되는 것과 안 되는 것
변환과 내보내기convert_md·from_json·convert_hwp5·to_md·to_json·to_pdf
결과·경고·오류결과 객체, 보고서의 warnings, HwpForgeError의 다섯 속성, 코드 표
레시피양식 채우기 파이프라인, 표를 CSV로, 배치 처리, HWP → PDF, pip 없는 호스트
API 요약모든 메서드·함수의 시그니처와 반환형 한 표

설치

pip install hwpforge

uv를 쓴다면 uv add hwpforge(프로젝트) 또는 uv pip install hwpforge(환경)를 사용하세요.

정확 핀(==X.Y.Z)보다 ~=X.Y.Z를 권장합니다. Python 전용 수정은 X.Y.Z.N 형태로 나가는데, 정확 핀은 그 수정을 받지 못합니다.

CPython 3.9+를 커버하는 abi3 wheel을 다섯 플랫폼(Linux manylinux_2_28 x86_64/aarch64, macOS 11+ arm64, macOS 10.12+ x86_64, Windows x64)에 배포하며, sdist(소스 배포)는 Rust 1.92+와 maturin이 필요합니다. 런타임 의존성은 0개입니다. 자유 스레드(free-threaded) 빌드는 stable ABI가 다루지 않아 지원하지 않습니다.

pip 없는 호스트

wheel은 zip 파일이고 런타임 의존성이 없으므로, pip 없이 풀어서 바로 import할 수 있습니다. 기준은 배포판 버전이 아니라 glibc 2.28 이상입니다 — CPython 3.9+와 glibc 2.28+를 갖춘 Linux x86_64 호스트라면(예: Debian 10/11/12, Ubuntu 20.04 이상; 아래 파일명은 x86_64 wheel):

python3 -c "import zipfile; zipfile.ZipFile('hwpforge-<version>-cp39-abi3-manylinux_2_28_x86_64.whl').extractall('/opt/hf')"
PYTHONPATH=/opt/hf python3 -c "import hwpforge; print(hwpforge.__version__)"

wheel 파일 자체는 PyPI의 files 페이지에서 받을 수 있습니다 — pip이 설치할 때 받는 것과 같은 바이트·sha256입니다. GitHub Release는 발행 후 에셋을 붙일 수 없는 불변 객체라, 별도로 첨부되지 않습니다. 오프라인 배포의 전체 절차는 레시피에 있습니다.

30초 예제

import hwpforge

doc = hwpforge.Document.open("form.hwpx")
for field in doc.fields()["fields"]:
    print(field["name"], "→", field["current"])

result = doc.fill({"user_email": "kim@example.com"})
for warning in result.report["warnings"]:
    print(warning["code"], warning["message"])
result.document.save("form-filled.hwpx")

doc은 그대로이고, 채워진 문서는 result.document입니다. 이 재대입 구조가 이 패키지의 전부라고 해도 지나치지 않습니다 — 아래 네 개념이 그 이유입니다.

핵심 개념 네 가지

불변 값 Document

Document는 불변 값입니다. HWPX 패키지의 바이트를 들고 있는 값 객체로, 두 문서는 바이트가 같으면 같고(==, hash), 어떤 메서드도 받은 문서를 바꾸지 않습니다. 속성 대입은 AttributeError입니다. 편집 메서드는 새 문서를 돌려주므로, 결과를 변수에 다시 받아야 합니다.

값과 보고서를 함께 담는 결과

연산은 값과 보고서를 함께 돌려줍니다. 편집은 DocumentResult(document, report), 텍스트 내보내기는 TextResult(text, report), 바이트 내보내기는 BytesResult(data, report)입니다. 셋 다 frozen dataclass라 보고서를 따로 조회할 필요도, 잃어버릴 일도 없습니다. 검사 연산(inspect·outline 등)은 보고서(dict)만 돌려줍니다.

항상 있는 warnings

보고서의 warnings는 항상 있고, 저장 전에 봐야 합니다. 실패하지 않은 연산도 조용히 성공하지 않습니다. templates()·schema()를 뺀 모든 보고서에 warnings: [{code, message, hint?}]가 있으며, 비어 있을 수는 있어도 빠지지는 않습니다. 문서가 완전히 보존되지 않은 곳(예: 재인코드가 조판 캐시를 버림)을 여기서 알려줍니다.

하나뿐인 예외 HwpForgeError

실패는 HwpForgeError 하나이고, code로 분기합니다. 입력을 받아들인 뒤 연산이 거부하면 HwpForgeError를 던지며 code·message·hint·cause·details 다섯 속성을 가집니다. 인자 형이 틀리면 TypeError/ValueError, 파일 I/O는 OSError입니다. 예외 메시지 문자열이 아니라 exc.code 문자열로 분기하세요.

try:
    doc = doc.set_cell(table=0, at="0,1", text="값").document
except hwpforge.HwpForgeError as exc:
    print(exc.code)      # 예: "INPUT_ENTRIES_NOT_CARRIED"
    print(exc.hint)      # 연산이 아는 되는 길, 없으면 None

자주 나오는 용어

하위 페이지는 아래 용어를 설명 없이 씁니다.

용어뜻
누름틀한컴 문서의 입력 칸. 이름과 안내문을 가지며, fill이 이름으로 값을 채웁니다
조판 캐시한컴이 계산해 파일에 저장한 줄 나눔·줄 위치. PDF 렌더는 이것을 재생합니다. 캐시가 제거된 부분은 한컴에서 여는 순간 다시 배치하고, 다시 저장할 때 계산 결과를 캐시에 기록합니다
보존 우선(preserve-first) 편집바꿀 XML 조각만 고치고 패키지의 나머지 바이트는 그대로 두는 편집(fill·patch)
재인코드문서를 모델로 디코드해 고친 뒤 패키지를 새로 쓰는 것. 이때 한컴의 Preview/*·container.rdf는 사라지고, 조판 캐시는 연산에 따라 바뀌지 않은 곳만 남거나 모두 사라집니다. 그 밖의 엔트리를 남기는지는 연산마다 다릅니다. from_json(base=...)는 내용이 원본과 같으면 다시 쓰지 않고 원본을 그대로 돌려줍니다. 무엇을 경고하는지는 연산마다 다릅니다
fail-closed결과가 손상될 것 같으면 손상된 결과를 내는 대신 거부하는 정책

입력 크기 상한

Document.open은 파일을 읽을 때 CLI·MCP와 같은 상한(hwpforge._hwpforge.MAX_FILE_SIZE, 100 MB)을 적용하고, 넘으면 HwpForgeError(INPUT_TOO_LARGE)를 던집니다. 상한은 파일이 보고하는 크기가 아니라 읽은 바이트 수에 걸리므로, stat() 크기가 0으로 보이는 FIFO나 프로세스 치환으로도 더 큰 입력을 밀어 넣을 수 없습니다. Document.from_bytes에는 상한이 없습니다 — 호출자가 이미 바이트를 들고 있어 더 제한할 읽기가 남아 있지 않기 때문입니다. 100 MB보다 큰 문서를 다뤄야 한다면 직접 읽어서 from_bytes로 넘기면 됩니다.

읽기와 쓰기 포맷

지원 읽기·편집 연산은 .hwpx와 .hwp(HWP5)를 직접 받습니다. Document.open 또는 Document.from_bytes로 연 문서의 지원 연산이 HWP5를 자동 변환합니다. 손실 거부·허용과 보류 연산은 입력 정책을 참고합니다. 변환은 HWPX로 가는 한 방향이라 원본 .hwp로 되돌아가는 길은 없습니다. 쓰기는 .hwpx뿐이며(save는 무엇을 읽었든 HWPX 패키지를 씁니다), 한컴 오피스는 .hwpx를 그대로 엽니다.

예제에 쓰인 파일

하위 페이지의 예제는 저장소의 테스트 픽스처를 다음 이름으로 복사해 둔 것을 전제합니다. 같은 이름으로 준비하면 HWPX 코드 블록을 그대로 실행할 수 있습니다. hancom.hwpx(한컴에서 저장한 HWPX)와 HWP5 변환 예제의 old.hwp는 사용자가 준비한 입력입니다.

예제 파일원본 (tests/fixtures/…)특징
form.hwpxfields/clickhere_named.hwpx누름틀 user_email 하나
grid.hwpxtables/merged_grid_form.hwpx3×2 표(라벨 성명·비고), HwpForge 생성본
template.hwpxstamp/placeholder_basic.hwpx스탬프 후보 ( )·□
plain.hwpxstructural/plain_paragraphs.hwpx문단 4개, HwpForge 생성본

다음 단계

문서 읽기와 검사

읽기 연산은 문서를 바꾸지 않고 보고서(dict)를 돌려줍니다. 문서는 열 때 디코드되지 않습니다 — Document.open은 바이트만 들고, 각 연산이 필요할 때 디코드합니다. 그래서 잘못된 바이트는 open이 아니라 첫 연산에서 HwpForgeError(DECODE_FAILED)로 드러납니다.

열기

import hwpforge

doc = hwpforge.Document.open("hancom.hwpx")           # 파일에서, 100 MB 상한
same = hwpforge.Document.from_bytes(doc.to_bytes())    # 이미 든 바이트에서, 상한 없음

print(repr(doc), len(doc), doc == same)                # Document(<n> bytes) <n> True

Document(data) 생성자도 있지만 open/from_bytes가 바이트의 출처를 말해 주므로 그쪽을 쓰세요. bytes가 아닌 것을 넘기면 TypeError입니다.

inspect() — 무엇이 얼마나 있는가

report = doc.inspect()
print(report["sections"], report["paragraphs"], report["tables"], report["images"], report["charts"])
print(report["metadata"]["title"], report["metadata"]["author"], report["metadata"]["modified"])
print(report["fields"])                     # 누름틀 이름 목록
section = report["section_details"][0]
print(section["top_level_paragraphs"], section["all_tables"], section["has_header"])

metadata는 title·author·subject·description·last_saved_by·created·modified·keywords를 가지며, 날짜 둘은 없으면 None입니다.

styles=True를 주면 문서가 정의한 글꼴·글자 모양·문단 모양 요약이 styles 키로 더해집니다(기본은 생략).

styles = doc.inspect(styles=True)["styles"]
print(styles["fonts"][0])          # {'id': 0, 'face_name': '함초롬돋움', 'lang': 'HANGUL'}
print(styles["char_shapes"][0])    # id, font_id, size_pt, bold, italic, color
print(styles["para_shapes"][0])    # id, alignment, line_spacing

섹션 계수 — 접두사가 곧 범위

section_details[i]의 키는 접두사로 무엇을 셌는지를 말합니다. 네 집합은 서로 포함 관계가 아닙니다 — 접두사마다 재귀해 들어가는 곳이 달라, 어느 행도 다른 행을 넓힌 판본이 아닙니다.

접두사재귀해 들어가는 곳master page캡션
top_level_없음 — 섹션 본문 흐름 자체만아니오아니오
(접두사 없음)셀·글상자·각주/미주·메모·머리말/꼬리말예아니오
deep_머리말/꼬리말·셀·글상자/주석/도형/메모아니오아니오
all_섹션 XML이 담은 전부(묶음 객체의 자식 포함)아니오예

top_level_과 접두사 없는 키는 문단·표·이미지·차트를 세고, deep_은 문단만, all_은 여섯 가지 객체(all_tables·all_images·all_text_boxes·all_lines·all_rectangles·all_polygons)를 셉니다. non_empty_ 중위사는 세는 집합을 바꾸지 않고 “보이는 텍스트가 있는 문단“으로만 좁히므로, top_level_non_empty_paragraphs는 top_level_paragraphs를 넘지 않습니다. all_charts는 없습니다 — 디코더가 섹션 최상위 문단 밖의 차트를 복원하지 못해, 그런 키를 두면 정작 필요한 문서에서 조용히 과소 계수하게 됩니다.

all_ 키는 디코드된 객체를 세지, 원시 XML 요소를 세지 않습니다. CLI --json에는 같은 범위를 예전 철자(tables·images·text_boxes 등)로 내보내는 키가 있는데 그쪽은 원시 스캔이라, 디코더가 표현하지 못하는 요소를 받아들인 문서에서는 더 큰 값이 나올 수 있습니다. 두 값은 교환 가능하지 않습니다. 문단 키에는 이 단서가 붙지 않습니다.

outline() — 제목·표·누름틀·책갈피의 위치

outline = doc.outline()["outline"]
print(outline["title"])                                   # 없으면 None
for h in outline["headings"]:
    print(h["level"], h["text"], h["at"])                 # at = {'section': s, 'para': p}
for t in outline["tables"]:
    print(t["ordinal"], t["rows"], t["cols"], t["addressable"], t["caption"])
print(outline["fields"], outline["bookmarks"])

tables[i]["ordinal"]이 read(table=…)·set_cell(table=…)이 받는 표 번호입니다(0부터). addressable이 거짓인 표는 격자 주소로 셀을 지정할 수 없습니다(병합이 격자를 깨는 경우).

fields() — 누름틀

for f in hwpforge.Document.open("form.hwpx").fields()["fields"]:
    print(f["name"], f["hint"], f["current"], f["section"], f["fillable"])
# user_email 회사 이메일을 입력하세요 회사 이메일을 입력하세요 0 True

fillable이 거짓인 필드는 fill이 FIELD_NOT_FILLABLE로 거부합니다. name은 이름이 없는 필드에서 None 일 수 있습니다.

read() — 한 부분만

문단 범위·표·누름틀 셋 중 정확히 하나를 지정합니다. 보고서의 세 키(paragraphs·table·fields)는 항상 있고, 묻지 않은 것은 None입니다.

plain = hwpforge.Document.open("plain.hwpx")

view = plain.read(section=0, paras="0..2")["paragraphs"]     # 양끝 포함: 0, 1, 2
for p in view["paragraphs"]:
    print(p["at"]["para"], p["kind"], p["text"])

table = hwpforge.Document.open("grid.hwpx").read(table=0)["table"]
for cell in table["cells"]:
    print(cell["row"], cell["col"], cell["row_span"], cell["col_span"], repr(cell["text"]))

fields = hwpforge.Document.open("form.hwpx").read(field="user_email")["fields"]
print(fields[0]["current"])
  • paras는 "시작..끝"이고 양끝 포함입니다. 범위가 섹션을 넘으면 READ_PARA_RANGE_INVALID, 형식이 틀리면 READ_PARAS_INVALID.
  • 문단은 kind로 구분됩니다: "body", "heading"(level 포함), "list"(numbered·level·checked 포함 — checked는 체크 목록이 아니면 None). 문단이 표·그림 등을 품으면 contains 키가 더해집니다.
  • 표는 rows·cols와 셀 목록입니다. 병합된 영역은 기준 셀 하나로만 나오므로 셀 수가 rows × cols보다 적을 수 있습니다.
  • 아무것도 안 주거나 둘 이상 주면 READ_TARGET_REQUIRED, 표 번호가 넘치면 TABLE_NOT_FOUND.

validate() — 두 종류의 실패

report = doc.validate()
print(report["ok"], report["sections"], report["paragraphs"])
for problem in report["errors"]:
    print(problem["code"], problem["message"])

문서가 디코드는 되지만 모델 불변조건을 어기면 예외 없이 ok가 거짓인 보고서를 돌려주고, 이유는 errors에 담깁니다. 반면 디코드 자체가 안 되는 입력은 연산 실패이므로 HwpForgeError(DECODE_FAILED)를 던집니다. 즉 “유효하지 않은 문서“는 반환값으로, “문서가 아닌 바이트“는 예외로 옵니다.

try:
    hwpforge.Document.from_bytes(b"not a document").validate()
except hwpforge.HwpForgeError as exc:
    print(exc.code)        # DECODE_FAILED

CLI·MCP는 같은 필드를 valid라 부릅니다. Python은 ok입니다.

diff() — 두 문서의 차이

edited = plain.insert_para(section=0, anchor=1, text="새 문단").document
d = plain.diff(edited)
print(d["identical"])                      # False
print(d["package"]["changed"])             # ['Contents/section0.xml']
print(len(d["semantic"]["paragraphs"]), len(d["semantic"]["structure"]))

semantic은 디코드된 모델의 차이(field_values·cells·paragraphs·structure·raw), package는 ZIP 엔트리를 바이트로 비교한 결과(added·removed·changed)입니다. note가 이 두 층의 의미를 한 줄로 설명합니다. 조판 캐시처럼 디코드 모델에 담기지 않는 XML의 차이는 raw로 잡히며 raw_dropped가 생략된 개수를 말합니다.

stamp_plan() — 스탬프할 자리 찾기

plan = hwpforge.Document.open("template.hwpx").stamp_plan()
for c in plan["text"]:
    print(c["path"], c["span"], repr(c["marker"]), c["pattern"], c["guard"])
for c in plan["cells"]:
    print(c["table"], c["at"], [label["normalized"] for label in c["labels"]], c.get("suggested_name"))
print(plan["schema_version"], plan["source_sha256"][:12])

text는 ( )·□ 같은 인라인 표시 후보, cells는 라벨 옆 빈 셀 후보입니다. guard가 있는 후보는 문맥상 채우면 안 될 가능성이 있는 자리(예: 안내문 안의 괄호)라 stamp가 승인 없이는 건드리지 않습니다. source_sha256은 이 계획이 어느 문서에서 나왔는지의 지문이고, 버전 있는 요청(StampRequestV2)에 그대로 들어갑니다. 계획을 실제 스탬프로 바꾸는 규칙은 편집에 있습니다.

to_json() · export_section() — 구조를 읽는 가장 넓은 창

to_json()은 문서 전체를, export_section(section=i)은 한 구역을 JSON으로 내보냅니다. 둘 다 TextResult라 .text(JSON 문자열)와 .report(같은 내용을 dict로 담은 document/section 키 + warnings)를 함께 줍니다. 두 JSON은 서로 다른 스키마입니다 — 전체 문서는 from_json이, 한 구역은 patch가 읽습니다. 자세한 것은 변환과 내보내기와 편집에 있습니다.

편집

모든 편집 메서드는 DocumentResult를 돌려줍니다 — .document가 새 문서, .report가 보고서입니다. 받은 문서는 바뀌지 않으므로 결과를 다시 받아야 합니다.

import hwpforge

doc = hwpforge.Document.open("form.hwpx")
result = doc.fill({"user_email": "kim@example.com"})
doc = result.document          # 이 줄이 없으면 아무것도 바뀌지 않은 것입니다

기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기(Preview)를 지우고 PREVIEW_REMOVED 경고를 냅니다. 한컴에서 다시 저장하면 미리보기가 다시 만들어집니다. 입력이 편집 가능 검사를 통과하고 내용이 같으면 원본 파일을 돌려줍니다. header.xml 정규화·스타일 정의 변경 등 문서 재인코드가 필요하거나 이전 형식의 문서 전체 JSON을 쓰는 경우는 이 보장 밖입니다.

편집기는 두 부류입니다. 보존 우선(preserve-first) 편집기(fill·patch)는 건드리는 XML 조각과 Preview 및 그 연결 정보를 바꾸며, 재인코드 편집기(stamp·restyle, 보존 범위 밖 set_cell)는 문서를 모델로 디코드해 고친 뒤 패키지를 다시 씁니다. insert_para는 구역 XML에서 문단을 넣으며 재인코드 편집기와 같은 사전 검사(원본 패키지 엔트리 보존·의미 왕복 안전성)를 통과해야 합니다. delete_para는 그 검사에서 마지막 의미 비교 또는 ZIP carry만 실패한 경우 검증 가능한 평문·빈 문단을 원문 보존 방식으로 삭제할 수 있습니다. 이 차이가 아래 “한컴 저장 문서” 표를 만듭니다.

요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.

HWP5 입력과 변환 손실

Document.open("form.hwp") 또는 Document.from_bytes(data)로 HWP5 입력을 받습니다. inspect, outline, read, fields, validate, diff(양쪽), stamp_plan, to_md, to_json, export_section과 편집 5종은 연산 전에 HWPX로 변환합니다. 확장자가 아니라 내용으로 판별하며, 편집 결과는 .hwpx입니다.

fill, set_cell, insert_para, delete_para, stamp는 의미 손실이 있으면 HWP5_CONVERSION_LOSS로 거부합니다. 거부 경고는 error.details["warnings"]에 있습니다. 경고를 검토한 뒤에만 키워드 accept_conversion_loss=True로 허용하세요. 변환 → 기존 연산의 검증·편집 → 변환 손실 거부 순서이며, 이 옵션은 편집 자체의 손실 거부를 해제하지 않습니다. 읽기는 변환 경고를 보고하며 손실 때문에 거부하지 않습니다.

doc = hwpforge.Document.open("form.hwp")
print(doc.fields().get("conversion"))
result = doc.fill({"name": "홍길동"}, accept_conversion_loss=True)
result.document.save("filled.hwpx")

기존 warnings의 형과 내용은 그대로입니다. 변환된 입력에는 별도 conversion = {"source_format": "hwp5", "warnings": [...]}가 더해집니다. 각 경고는 stage, code, message와 선택적인 location을 갖습니다. diff는 conversion.base·conversion.revised에 변환된 쪽만 싣습니다. JSON·Markdown 문서 본문에는 이 메타데이터를 넣지 않습니다.

save는 None을 반환합니다. HWP5를 그 자리에서 변환해 저장하면 파일 기록이 성공한 뒤 수락한 손실과 비손실 변환 경고를 코드와 알려진 위치를 담은 표준 UserWarning으로 알립니다. Python 경고 필터가 그대로 적용되어 기본 필터는 같은 경고를 한 번만 보여 주고, error 필터는 파일을 쓴 뒤 예외를 냅니다. 전체 목록은 읽기·편집 보고서의 conversion이나 warnings.simplefilter("always")를 넣은 warnings.catch_warnings(record=True)로 받습니다.

save는 .hwp 확장자(대소문자 무시)를 INVALID_EXTENSION으로 거부합니다. 원본 HWP5를 그대로 저장하려면 HWPX로 변환하며, 의미 손실은 기본 거부합니다 (save(..., accept_conversion_loss=True)로 명시적 허용). open이 읽은 파일의 정체성은 편집 결과에도 이어집니다. 원본 경로가 삭제되거나 교체되어도 당시 읽은 HWP5 파일의 심볼릭 링크·하드 링크·상대 경로 별칭에 저장하면 INVALID_OUTPUT_PATH로 거부합니다. 보호 대상은 open 때 읽은 파일이며 현재 그 경로가 가리키는 파일이 아닙니다. 파일은 장치와 inode로 식별하므로, 삭제된 원본의 inode를 파일 시스템이 다시 배정한 새 파일도 거부합니다. 이때는 다른 경로에 저장합니다. 저장 시 출력의 정체성만 조회하며, 출력 부재는 허용하고 그 밖의 조회 실패는 FILE_WRITE_FAILED입니다. HWPX의 제자리 저장은 허용합니다. 저장 호출 중 다른 프로세스가 출력 경로를 바꾸는 상황은 보호하지 않습니다.

Document(data)·from_bytes, convert_hwp5·convert_md·from_json의 생성 결과에는 원본 파일 정체성이 없습니다. 이 경우 원본 별칭인지 판별할 수 없으므로 호출자가 출력 경로를 구분해야 합니다. bytes·텍스트를 반환하는 연산은 파일을 쓰지 않습니다. from_json(base=...), patch, restyle의 HWP5 자동 변환은 이번 범위 밖이며 계속 HWP5_INPUT을 반환합니다. 명시적으로 변환한 HWPX를 넘기세요.

한컴 저장 문서에서 되는 것과 안 되는 것

한컴 오피스가 저장한 .hwpx에는 HwpForge 인코더가 재현하지 않는 패키지 엔트리(Preview/PrvText.txt·Preview/PrvImage.png·META-INF/container.rdf)가 들어 있습니다. insert_para·stamp와 보존 범위 밖 set_cell은 이런 문서를 fail-closed로 거부합니다. delete_para는 아래의 검증 가능한 범위를 지원합니다.

연산한컴 저장 문서결과
fill동작누름틀을 쓰고 내용 변경에서 기존 Preview 제거·경고(재인코드 제외)
patch동작기존 문단·셀의 텍스트를 바꾸고 기존 Preview 제거·경고(재인코드 제외)
set_cell보존 가능한 한 문단·한 Text run 칸원문 유지, 실제 값 변경 시 기존 Preview 제거
insert_para·stamp거부INPUT_ENTRIES_NOT_CARRIED 또는 INPUT_NOT_ROUNDTRIP_SAFE
delete_para검증 가능한 평문·빈 문단성공 또는 기존 admission 오류
restyle동작재인코드하므로 위 엔트리와 조판 캐시가 사라지며 warnings로 알림
from_json(base=...)부분 승계이미지만 승계하고 위 엔트리는 버려집니다(별도 경고 없음)
hancom = hwpforge.Document.open("hancom.hwpx")
# 아래 호출의 대상 칸이 여러 문단 또는 여러 Text run 등 보존 범위 밖인 경우의 예입니다.
# 보존 가능한 본문 직속 표의 한 문단·한 Text run 칸은 성공할 수 있습니다.
try:
    hancom.set_cell(table=0, at="0,0", text="값")
except hwpforge.HwpForgeError as exc:
    print(exc.code)     # INPUT_ENTRIES_NOT_CARRIED
    print(exc.hint)     # 되는 길: 텍스트는 export_section → 편집 → patch, 누름틀은 fill

실제 정부 서식에서 누름틀은 fill, 그 밖의 텍스트는 export_section → 편집 → patch로 바꿉니다. 검증 가능한 최상위 본문 평문·빈 문단을 없애려면 delete_para를 씁니다. 그 밖의 구조를 바꿔야 할 때만 from_json(base=...)을 쓰고, 결과를 한컴에서 열어 확인하세요.

fill — 누름틀 채우기

form = hwpforge.Document.open("form.hwpx")
result = form.fill({"user_email": "kim@example.com"})
print(result.report["filled"])
# [{'name': 'user_email', 'section': 0, 'previous': '회사 이메일을 입력하세요'}]
print(result.document.read(field="user_email")["fields"][0]["current"])
# kim@example.com
  • 이름이 없는 필드는 FIELD_NOT_FOUND(메시지에 사용 가능한 이름 목록이 붙습니다), 채울 수 없는 필드는 FIELD_NOT_FILLABLE, 빈 문자열은 EMPTY_FIELD_VALUE, 값 맵이 비어 있으면 NO_VALUES입니다. 값은 문자열이어야 하며 다른 형은 TypeError입니다.
  • 같은 이름의 필드가 문서에 둘 이상이면 어느 쪽인지 모호하므로 자동으로 전부 채우지 않고 FIELD_NAME_AMBIGUOUS로 거부합니다(아무것도 쓰지 않습니다). 문서에서 이름을 유일하게 만든 뒤 다시 채우세요.
  • fill과 patch는 본문 문단이나 본문 최상위 표의 직접 칸 문단이 편집 전후 한 줄 안에 들어간다고 확인되면 그 문단의 원래 줄 조판 캐시를 남깁니다. 한글·숫자·일부 문장부호와 공백으로 된 글에 한하며, 문단 전체의 글자 모양과 문자 종류별 크기·간격 설정이 같고 글자 효과(굵게·기울임·그림자 등), 커닝, 강조점, 글꼴 공백 설정이 없어야 합니다. 편집 가능한 누름틀과 앞뒤 글은 합쳐서 판단합니다. 편집 가능한 누름틀이 아닌 필드(책갈피와 편집할 수 없는 누름틀 포함)가 든 문단은 자기 캐시를 잃습니다. 그런 필드의 위치를 확인할 수 없으면 그 구역의 모든 편집 문단이 자기 캐시를 잃습니다. 여러 글 조각으로 나뉘거나 여러 문단에 걸치는 누름틀도 편집할 수 없는 누름틀에 해당합니다. 화면에 보이는 글 전체를 확인할 수 없거나, 폭을 넘거나, 탭·강제 줄바꿈·개체·빈 누름틀이 있거나, 원본 설정을 확인할 수 없으면 캐시를 지워 한컴이 줄을 다시 나누게 합니다. 직접 칸은 가로쓰기와 일반 줄바꿈(BREAK)이 원본에 명시되어 있어야 하며, 칸의 첫 문단뿐 아니라 뒤 문단도 각각 판단합니다. 본문 표 안에 한 단계 더 들어간 표(중첩 표)의 칸도 같은 확인을 통과하면 캐시를 남깁니다. 그보다 깊은 중첩, 글상자·각주·미주·머리말·꼬리말 안의 표와 표 캡션은 이 보존 대상이 아닙니다. 한 줄로 입증된 편집은 다른 문단의 캐시 삭제를 일으키지 않습니다. 따라서 다른 삭제 원인이 없으면 같은 칸의 뒤 문단, 표를 담은 문단과 그 뒤 문단까지 원본 캐시를 유지하며, 본문 편집 뒤에 표나 필드가 있어도 같습니다. 아래의 중첩 편집·구역·뒤 문단 제거 규칙이 적용되면 한 줄로 입증된 문단도 캐시를 지웁니다. 본문 문단을 고쳤을 때 그 뒤의 문단 가운데 글자와 누름틀만 담은 문단은 캐시를 그대로 둡니다. 그런 문단은 앞 문단이 길어져도 줄 나눔이 그대로이고, 한컴이 줄의 세로 위치만 다시 쌓기 때문입니다. 다음 경우에는 뒤 문단의 캐시도 함께 지웁니다.
    • 한 줄로 입증되지 않은 편집 뒤에 표·그림·도형 같은 개체, 누름틀이 아닌 필드(상호 참조, 날짜, 계산식, 하이퍼링크 등)의 어느 부분이나 쪽 번호를 담은 뒤 문단(필드는 여러 문단에 걸칠 수 있고, 고친 문단에서 시작한 필드도 해당합니다): 그런 첫 문단부터 그 흐름 끝까지 지웁니다. 쪽이 바뀌면 이런 문단의 폭이나 표시 글자가 달라질 수 있습니다.
    • 구역 어딘가(표 칸, 머리말·꼬리말 포함)에 글자처럼 취급하지 않는 개체가 있고 본문이 그 둘레를 감싸는 경우(배치 “어울림” 등): 고친 문단이 속한 흐름(그 흐름을 품은 바깥 흐름 포함)의 뒤 문단을 모두 지웁니다. 개체는 제자리에 있는데 문단만 밀리면 감싼 줄의 모양이 달라지기 때문입니다. 뒤에 오는 표 칸·글상자 안의 문단은 캐시를 그대로 둡니다.
    • 세로쓰기 구역이나 단 폭이 서로 다른 다단 구역: 고친 문단이 속한 흐름(그 흐름을 품은 바깥 흐름 포함)의 뒤 문단을 모두 지웁니다. 뒤에 오는 표 칸·글상자 안의 문단은 캐시를 그대로 둡니다.
    • 구역 어딘가(머리말·꼬리말 포함)에 문서 속 자리를 확인할 수 없는 필드가 있는 경우: 시작과 끝이 맞지 않는 필드(끝이 없는 필드 등)나 위치를 알 수 없는 필드(따로 저장된 바탕쪽에 있는 필드 등)가 해당합니다. 다만 위치를 찾지 못한 필드가 책갈피나 편집할 수 없는 누름틀이면, 그 구역의 편집한 본문 문단은 자기 캐시만 잃고 뒤의 평문 문단은 캐시를 유지합니다. 그 밖의 필드 위치를 찾지 못하거나 필드의 시작·끝 불일치 등 오류·경고가 있으면, 전과 같이 고친 문단이 속한 흐름(그 흐름을 품은 바깥 흐름 포함)의 뒤 문단까지 지웁니다. 구역의 다른 문단은 캐시를 그대로 둡니다.
    • 한 줄로 입증되지 않은 직접 칸·한 단계 중첩 칸 편집이나, 그보다 깊은 중첩 표·글상자·각주·미주 안의 문단을 고친 경우: 그 안의 뒤 문단과, 그 표·글상자·주석이 놓인 문단 및 그 뒤 문단을 지웁니다.
    • 머리말·꼬리말 안의 문단을 고친 경우: 그 머리말·꼬리말 안의 뒤 문단만 지웁니다. 본문 캐시는 그대로 둡니다.
    • 스타일 정의를 고쳐 써야 하는 문서라서 patch가 문서를 다시 쓰는 경우: 위 규칙 대신 재생성(from_json(base=...))의 규칙을 따르므로 더 많은 캐시가 지워질 수 있습니다. 쪽 번호나 떠 있는 개체가 있으면 구역이나 문서 전체의 캐시가 지워지기도 합니다(재생성의 캐시 규칙).
try:
    form.fill({"nope": "x"})
except hwpforge.HwpForgeError as exc:
    print(exc.code, "|", exc.message)
    # FIELD_NOT_FOUND | field 'nope' not found; available: [user_email]

patch — 구역 JSON을 편집해 되돌려 넣기

텍스트를 바꾸는 보존 우선 경로입니다. export_section이 낸 JSON의 텍스트를 고쳐 patch로 넣으면 그 구역의 텍스트를 바꿉니다. 변경의 영향을 받는 조판 캐시를 고칩니다. 기존 한컴 미리보기가 있던 문서에서는 내용을 실제로 바꾸면 미리보기와 그 연결 정보를 제거하며 PREVIEW_REMOVED를 보고합니다. 머리글 정규화 등 문서 재인코드가 필요한 경우는 이 보장 밖입니다.

import json

exported = hancom.export_section(section=0)
section = json.loads(exported.text)          # 키: section_index, section, styles, preservation
patched = hancom.patch(section=0, patch=json.dumps(section, ensure_ascii=False))
print(patched.report)                        # {'section': 0, 'warnings': []}
print(hancom.diff(patched.document)["identical"])   # 바꾼 게 없으면 True
  • JSON의 텍스트만 바꿀 수 있습니다. 문단을 더하거나 빼거나 표 구조·서식 참조를 바꾸면 PATCH_FAILED(구조 변경 감지)로 거부됩니다. 구조 변경은 insert_para/delete_para/set_cell 또는 from_json의 몫입니다.
  • preservation 키는 텍스트 슬롯과 원본 바이트 스팬의 대응표입니다. 손대지 말고 그대로 돌려보내세요.
  • JSON이 구역 스키마에 맞지 않으면 JSON_PARSE_FAILED, 격자 주소가 더 이상 맞지 않으면 PATCH_FAILED입니다. 스키마는 hwpforge.schema(kind="exported-section")으로 받을 수 있습니다.

텍스트를 실제로 바꾸는 예:

section = json.loads(hancom.export_section(section=0).text)
first_run = section["section"]["paragraphs"][0]["runs"][0]
if "text" in first_run:
    first_run["text"] = "바뀐 첫 문단"
doc2 = hancom.patch(section=0, patch=json.dumps(section, ensure_ascii=False)).document

문단의 runs[i]는 텍스트 런이면 text 키를, 표·그림 같은 컨트롤이면 다른 키를 가집니다. 표 셀의 텍스트도 같은 JSON 안에 있으므로(runs[i]["table"]["rows"][r]["cells"][c]["paragraphs"]…) 한컴 저장 문서의 셀 텍스트는 이 길로 바꿉니다.

set_cell — 표 셀에 쓰기

보존 가능한 칸은 기존 text patch와 같은 조판 캐시 판정을 사용하며 표 높이와 cellSz는 유지합니다. 한 문단·한 줄인 칸은 짧은 값으로 바꾼 뒤에도 줄 조판 캐시를 남길 수 있습니다. 글자 효과(굵게·기울임·그림자 등), 커닝, 강조점, 글꼴 공백 설정이 있는 칸은 캐시 보존 대상에서 제외합니다. 문자 종류별 장평·자간·상대 크기·글자 위치 설정이 모두 기록되어 있고 서로 같아야 하며, 원본 설정과 새 글의 폭을 확인할 수 없는 경우에도 캐시를 지웁니다.

격자 주소(at)나 라벨 기준(right_of·below)으로 셀 하나를 지정하거나, specs로 여럿을 한 번에 씁니다. 두 형태는 배타적입니다.

grid = hwpforge.Document.open("grid.hwpx")
print([(c["row"], c["col"], c["text"]) for c in grid.read(table=0)["table"]["cells"]])
# [(0, 0, '성명'), (0, 1, ''), (1, 0, '비고'), (1, 1, ''), (2, 1, '')]

one = grid.set_cell(table=0, at="0,1", text="홍길동")
print(one.report["results"][0])
# {'table': 0, 'requested': {'row': 0, 'col': 1}, 'anchor': {'row': 0, 'col': 1}, 'resolution': 'exact', 'cleared': False}

by_label = grid.set_cell(table=0, right_of="성명", text="홍길동")

many = grid.set_cell(specs=[
    {"table": 0, "at": {"row": 0, "col": 1}, "text": "홍길동"},
    {"table": 0, "right_of": "비고", "text": "없음"},
])
print([r["resolution"] for r in many.report["results"]])
  • at은 메서드 인자로는 "row,col" 문자열, specs 안에서는 {"row": r, "col": c} 객체입니다(0부터).
  • right_of/below는 그 텍스트를 가진 셀의 오른쪽/아래 셀입니다. 라벨이 없거나 그 방향에 셀이 없으면 CELL_NOT_FOUND, 라벨이 여럿이면 모호함으로 거부됩니다.
  • 병합된 영역을 지정하면 기준 셀로 해석되며 resolution이 그 사실을 말합니다(exact가 아닌 값). 표가 격자 주소를 지원하지 않으면(outline의 addressable 거짓) 거부됩니다.
  • 표 번호는 outline()["outline"]["tables"][i]["ordinal"]이며, 없으면 TABLE_NOT_FOUND.
  • 재인코드 편집기이므로 한컴 저장 문서는 INPUT_ENTRIES_NOT_CARRIED/INPUT_NOT_ROUNDTRIP_SAFE로 거부됩니다. 그 문서의 셀 텍스트는 patch로 바꾸세요.

insert_para / delete_para — 문단 넣고 빼기

plain = hwpforge.Document.open("plain.hwpx")
print([p["text"] for p in plain.read(section=0, paras="0..3")["paragraphs"]["paragraphs"]])
# ['첫째 문단입니다.', '둘째 문단입니다.', '셋째 문단입니다.', '넷째 문단입니다.']

ins = plain.insert_para(section=0, anchor=1, text=["새 문단 하나", "새 문단 둘"])
print(ins.report)                    # {'inserted': 2, 'deleted': 0, 'warnings': []}

above = plain.insert_para(section=0, anchor=1, text="위에", before=True)

dl = ins.document.delete_para(section=0, indexes=[2, 3])
print(dl.report)                     # {'inserted': 0, 'deleted': 2, 'warnings': []}
  • text는 문자열 하나 = 문단 하나, 시퀀스 = 원소마다 문단 하나입니다. 문자열을 글자 단위 시퀀스로 풀지 않습니다. 시퀀스의 원소는 str만 받습니다.
  • anchor/indexes는 그 구역의 최상위 문단 인덱스입니다(표 셀 안의 문단은 세지 않습니다). 범위를 넘으면 PARAGRAPH_OUT_OF_RANGE.
  • 삭제는 전부-아니면-무(all-or-nothing)이며 fail-closed 정책이 있습니다: 구역 속성을 가진 첫 문단(SECTION_PROPERTIES_PARAGRAPH), 책갈피·상호참조·각주 등 참조를 가진 문단, 쪽/단 나눔을 가진 문단(HARD_BREAK_LOSS), 구역을 비우는 삭제는 거부됩니다. 같은 이유로 첫 문단 앞에는 넣을 수 없습니다(INSERT_BEFORE_SECTION_PROPERTIES).
  • 두 연산은 대상 구역 XML을 고치며 관련 없는 내용을 유지합니다. 사전 검사를 통과한 문단 편집은 영향을 받는 조판 캐시도 갱신합니다. insert_para는 재인코드 편집기와 같은 사전 검사를 유지합니다. delete_para는 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.
try:
    plain.delete_para(section=0, indexes=[0])
except hwpforge.HwpForgeError as exc:
    print(exc.code)      # SECTION_PROPERTIES_PARAGRAPH

stamp — 템플릿에 누름틀 심기

stamp_plan이 찾은 후보를 누름틀로 바꾸는 연산입니다. 흐름은 계획 → 명세(spec) 작성 → 스탬프 이고, 가드 없는 후보는 전부 이름을 붙이거나 "ignore"로 명시해야 합니다 — 하나라도 빠지면 STAMP_CANDIDATE_UNCOVERED로 아무것도 쓰지 않습니다.

template = hwpforge.Document.open("template.hwpx")
plan = template.stamp_plan()

specs = []
for i, candidate in enumerate(plan["text"]):
    spec = dict(candidate)                     # section, path, span, marker 를 그대로 복사
    if i == 0:
        spec["action"] = {"field": {"name": "applicant", "hint": "신청인 이름"}}
    else:
        spec["action"] = "ignore"
    specs.append(spec)

stamped = template.stamp(specs)
print(stamped.report["stamped"])
# [{'name': 'applicant', 'section': 0, 'path': 'paragraphs[0].runs[0].text', 'span': {...}, 'marker': '(   )', 'pattern': 'paren_blank'}]
print(stamped.report["ignored"], stamped.report["skipped_guarded"])
print([(f["name"], f["hint"]) for f in stamped.document.fields()["fields"]])
# [('applicant', '신청인 이름')]

명세 작성 규칙:

  • 텍스트 후보: 계획의 후보 객체를 복사하고 action만 더합니다. section·path·span·marker가 빠지면 거부되고, 여분 키(pattern·guard)는 무시됩니다.
  • 셀 후보: 복사하지 말고 table·at·action으로 새로 만듭니다(label을 붙이면 text는 계획의 labels[].normalized여야 합니다). 후보 객체를 통째로 넘기면 알 수 없는 키로 거부됩니다.
  • action은 "ignore" 또는 {"field": {"name": ..., "hint": ...}}입니다.
  • 버전 있는 요청은 {"schema_version": plan["schema_version"], "source_sha256": plan["source_sha256"], "text": [...], "cells": [...]}이며, 지문이 문서와 다르면 거부됩니다 — 계획을 만든 문서에만 적용된다는 뜻입니다.
request = {
    "schema_version": plan["schema_version"],
    "source_sha256": plan["source_sha256"],
    "text": specs,
}
stamped = template.stamp(request, manifest=False)      # 보고서에서 manifest 생략

보고서의 manifest는 무엇을 어디에 심었는지의 기록(schema_version·source_sha256·output_sha256·fields)이고, stamped/stamped_cells는 적용 단계의 결과입니다. 재인코드 편집기이므로 의미가 손상될 인코딩은 ENCODE_SEMANTIC_LOSS로 거부하며(exc.details에 원인 경고), 한컴 저장 문서는 편집 전 사전 검사에서 거부됩니다.

restyle — 다른 프리셋으로

print([p["name"] for p in hwpforge.templates()["presets"]])   # ['default', 'modern', 'classic', 'latest']
restyled = hancom.restyle(preset="modern")
print(restyled.report["preset"], restyled.report["paragraphs"])
print([w["code"] for w in restyled.report["warnings"]])

문서를 다시 인코드하므로 조판 캐시와 인코더가 모르는 엔트리는 사라지고 그 사실이 warnings로 옵니다. 없는 프리셋은 PRESET_NOT_FOUND, 의미 손상은 ENCODE_SEMANTIC_LOSS입니다.

편집 뒤에 할 일

  1. result.report["warnings"]를 읽습니다. PREVIEW_REMOVED는 내용 변경에 따른 미리보기 제거를 뜻합니다. 조판 캐시가 제거된 문서는 한컴에서 여는 순간 다시 배치하며, 다시 저장할 때 조판 캐시와 미리보기를 재생성합니다. LAYOUT_CACHE_DROPPED는 조판 캐시 제거를 알리는 코드입니다.
  2. result.document.validate()["ok"]로 모델이 유효한지 봅니다.
  3. original.diff(result.document)로 바뀐 범위가 의도와 같은지 봅니다 — 대상 구역과 영향을 받는 캐시, 미리보기 연결 정보만 바뀌었는지 확인합니다. 기존 Preview가 있는 보존 우선 편집에서 package.removed의 Preview/PrvText.txt·Preview/PrvImage.png·빈 Preview/ 디렉터리(있는 경우), package.changed의 META-INF/container.xml rootfile 줄 제거와 Contents/content.hpf의 Preview manifest/spine 연결 제거는 정상입니다. 그 밖의 삭제나 관련 없는 descriptor 변경은 중단하고 확인합니다.
  4. save 합니다. 파일명은 .hwpx로.

변환과 내보내기

convert_md — Markdown에서 문서 만들기

import hwpforge

source = """---
title: 보고서
---

# 개요

본문입니다.

| 항목 | 값 |
| -- | -- |
| 예산 | 1,000 |
"""
result = hwpforge.convert_md(source, preset="classic")
print(result.report["sections"], result.report["paragraphs"])
print(result.document.inspect()["metadata"]["title"])     # 보고서
result.document.save("report.hwpx")
  • Markdown은 GFM이고, 맨 앞의 YAML frontmatter가 문서 메타데이터와 스타일을 정합니다(title 등). 스타일 문법은 Markdown에서 HWPX 로를 보세요.
  • preset은 hwpforge.templates()가 나열하는 이름 중 하나입니다(default·modern·classic·latest). 없는 이름은 PRESET_NOT_FOUND.
  • 이미지 ![…](path)는 base_dir를 기준으로 읽습니다. base_dir를 주지 않으면 파일 이미지는 버려지고 보고서에 남습니다. base_dir 밖의 경로는 읽지 않습니다.
result = hwpforge.convert_md("# 그림\n\n![도표](chart.png)\n")     # base_dir 없음
print(result.report["assets"])
# [{'kind': 'dropped', 'occurrence': {'paragraph': 1, 'run': 0}, 'reason': 'no_base_dir'}]
print([w["code"] for w in result.report["warnings"]])              # ['IMAGE_EMBED_SKIPPED']

assets의 각 항목은 kind로 구분됩니다: embedded(key·format 포함), dropped(reason 포함), remote(URL은 내려받지 않습니다).

to_md — 문서를 Markdown으로

doc = hwpforge.Document.open("hancom.hwpx")
styled = doc.to_md()                       # mode="styled": 스타일 frontmatter 유지
lossy = doc.to_md(mode="lossy")            # Markdown 이 못 담는 것은 버리고 warnings 로 알림
print(lossy.text[:200])
print(lossy.report["mode"], list(lossy.report["images"].keys()))
  • mode="lossless"는 보존 범위의 보존 목록은 보존하고, 거부 목록에 든 개체가 있으면 ENCODE_FAILED로 거부하며, 그 밖의 값(문단 스타일, 머리말 등)은 거부 없이 빠질 수 있습니다. 이 출력은 보존 범위를 확인하는 기계용 보기라 convert_md가 MD_DECODE_FAILED로 거부하므로, 왕복 편집에는 to_json/from_json을 사용하세요.
  • 보고서의 images는 문서가 참조한 이미지의 {키: 바이트}입니다. Markdown 텍스트가 그 키를 가리키므로, 파일로 저장할 때 같은 이름으로 옆에 써 두면 됩니다.

to_json · from_json — 전체 문서를 JSON으로

import json

exported = doc.to_json()                            # styles=True 가 기본
document = json.loads(exported.text)                # 키: format_version, document, styles
print(exported.report["document"] == document)      # 같은 내용을 dict 로도 줍니다

rebuilt = hwpforge.from_json(exported.text, base=doc)
print(rebuilt.report["paragraphs"], [w["code"] for w in rebuilt.report["warnings"]])
# 3 []
  • to_json의 JSON은 문서 전체와 style store이며, 표 셀에 격자 주소가 붙어 있습니다. styles=False는 구조만 내보냅니다.
  • from_json은 그 JSON을 다시 인코드해 새 문서를 만듭니다. base를 주면 이미지 바이너리와, 바뀌지 않은 문단의 줄 조판 캐시를 그 문서에서 가져옵니다. base 없이 이미지가 있는 문서를 재구성하면 이미지가 빠집니다. 스타일은 base에서 오지 않습니다. 값이 있는 style_ref가 하나라도 있으면 JSON의 styles가 필요해서 styles=False로 내보낸 JSON은 base를 줘도 거부됩니다. 모든 style_ref가 null이면 기본 프리셋으로 재구성합니다.
  • 생성은 fail-closed가 아닙니다: 의미가 손실돼도 거부하지 않고 warnings에 실어 돌려줍니다. 위 예제는 내용을 바꾸지 않아 base 바이트가 그대로 돌아오므로 경고가 없습니다. 내용을 바꾸면 줄 조판 캐시를 잃은 문단마다 LAYOUT_CACHE_DROPPED가 나옵니다(한컴에서 다시 저장하면 복원). base가 없으면 캐시를 싣지 않습니다.
  • 내용이 바뀌면 한컴 저장 문서의 Preview/*·container.rdf 엔트리는 base를 줘도 승계되지 않습니다(경고 없음). 텍스트만 바꿀 거라면 export_section → patch로 관련 없는 내용을 유지할 수 있습니다. 기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기와 그 연결 정보가 제거되고 PREVIEW_REMOVED가 나옵니다. 머리글 정규화 등 문서 재인코드가 필요한 경우는 이 보장 밖입니다.
  • JSON이 문서가 아니면 JSON_PARSE_FAILED. 스키마는 hwpforge.schema(kind="exported-document").
  • JSON 에 "format_version": 3 가 붙고 문단 여백과 탭 위치는 {"unit": "hwpunit" | "char", "value": 정수} 입니다. 이전 판이 내보낸 버전 없는 JSON 은 탭 위치가 있으면 LEGACY_JSON_TABS 로 거부되고, 없으면 여백을 풀어 읽으며 LEGACY_PARAGRAPH_MEASURES 경고를 냅니다. 원본에서 to_json 을 다시 실행하십시오. 자세한 규칙은 CLI 레퍼런스의 to-json 절에 있습니다.

전체 JSON(document/styles)과 구역 JSON(section_index/section/styles/preservation)은 서로 다른 스키마입니다 — 전자는 from_json, 후자는 patch가 읽습니다.

convert_hwp5 — 옛 .hwp를 HWPX로

with open("old.hwp", "rb") as handle:
    converted = hwpforge.convert_hwp5(handle.read())
print(len(converted.document), [w["code"] for w in converted.report["warnings"]])
converted.document.save("old.hwpx")
  • convert_hwp5의 인자는 파일 경로가 아니라 바이트입니다. 지원 읽기·편집 연산은 Document.open("old.hwp")으로 연 입력도 자동 변환합니다. HWP5 디코드 실패는 HWP5_DECODE_FAILED입니다.
  • 보고서의 warnings에 HWP5가 가졌지만 HWPX로 옮기지 못한 것이 전부 나옵니다.
  • 기본값(carry_layout_cache=True)은 한컴이 계산해 둔 줄 조판 캐시를 함께 옮깁니다. 결과가 원본의 줄 나눔 자리를 담고, PDF 렌더는 이 캐시를 재생합니다(아래). 줄 시작 자리를 정확히 옮길 수 없는 문단은 캐시를 버리고 LAYOUT_CACHE_DROPPED로 알립니다. 캐시 없이 쓰려면 carry_layout_cache=False를 줍니다.

to_pdf — PDF 렌더

렌더는 문서에 저장된 조판을 재생합니다(다시 계산하지 않습니다). 그래서 조판 캐시가 있는 문서만 렌더 대상입니다: 한컴이 저장한 HWPX, 그리고 convert_hwp5로 캐시를 옮긴 HWPX(기본값). Markdown이나 base 없는 JSON에서 생성한 문서는 캐시가 없어 PDF_RENDER_FAILED입니다.

캐시가 있어도 아직 재생하지 못하는 내용이 있습니다. 한컴이 저장한 문서라도 아래 경우는 실패하고, 한컴에서 다시 저장해도 풀리지 않습니다.

cause["code"]언제예
INVALID_CACHE문단 안에 재생하지 못하는 요소(각주·수식·상호참조 등 일부 필드·차트·도형 등)가 있음. 누름틀·하이퍼링크는 저장 방식에 따라 다르고, 메모만으로는 거부되지 않음상호참조·각주·수식이 든 문단
UNSUPPORTED_CONTENT아직 지원하지 않는 배치 — cause["kind"]가 무엇인지 말함kind == "non-default table position"

이 경우에 걸리는 문서는 한컴에서 PDF로 저장하세요.

with open("old.hwp", "rb") as handle:
    carried = hwpforge.convert_hwp5(handle.read()).document

try:
    pdf = carried.to_pdf(font_dirs=["/Library/Fonts/Hancom"])
    print(pdf.report["pages"])
    with open("old.pdf", "wb") as out:
        out.write(pdf.data)
except hwpforge.HwpForgeError as exc:
    print(exc.code, exc.cause)
    # PDF_RENDER_FAILED {'stage': 'render', 'code': 'FONT_UNRESOLVED'}      ← 글꼴을 못 찾음
    # PDF_RENDER_FAILED {'stage': 'render', 'code': 'NO_RENDERABLE_CACHE', 'location': 's0'}  ← 캐시 없음
    # PDF_RENDER_FAILED {'stage': 'render', 'code': 'INVALID_CACHE'}        ← 재생할 수 없는 요소가 든 문단
  • 글꼴은 기본 fail-closed입니다: 문서가 이름 붙인 글꼴 face를 font_dirs 안에서 찾지 못하면 추측하지 않고 실패합니다(cause["code"] == "FONT_UNRESOLVED"). degraded=True는 대체 글꼴로 렌더하며, 결과의 모양이 달라집니다.
  • discovery는 font_dirs 밖을 더 볼지의 선택입니다: "explicit"(기본, 결정적) · "hancom"(한컴 설치 글꼴 위치) · "platform"(OS 글꼴).
  • font_dirs는 시퀀스여야 합니다. 문자열 하나를 주면 한 글자짜리 디렉터리들로 읽히는 대신 TypeError로 거부됩니다.
  • partial_cache_reject=True는 캐시가 일부만 있는 문서를 다시 배치하지 않고 거부합니다.
  • 실패의 두 번째 분류는 exc.cause에 옵니다(stage·code·kind·location). exc.hint는 캐시가 없는 경우(NO_RENDERABLE_CACHE·MISSING_LAYOUT_CACHE, 한컴 재저장), 지원하지 않는 내용(UNSUPPORTED_CONTENT, 한컴에서 PDF 저장), 캐시가 재생과 맞지 않는 경우(INVALID_CACHE, 재저장 또는 메시지가 가리키는 내용에 따라 한컴 PDF 저장)만 가르고 그 밖에는 같은 문장이므로, 무엇을 할지는 cause["code"]로 가르세요: FONT_UNRESOLVED는 font_dirs·discovery, NO_RENDERABLE_CACHE·MISSING_LAYOUT_CACHE는 한컴에서 다시 저장, INVALID_CACHE·UNSUPPORTED_CONTENT는 위 표.

templates · schema

for preset in hwpforge.templates()["presets"]:
    print(preset["name"], preset["description"], preset["font"], preset["page_size"])

schema = hwpforge.schema(kind="exported-section")   # "document" | "exported-document" | "exported-section"
print(schema["title"], list(schema["properties"])[:4])

두 함수의 결과에는 warnings가 없습니다. schema는 JSON Schema dict이며 키는 스키마 자신의 것입니다.

스타일 참조는 style_ref와 styles.style_positions를 함께 보존하세요. styles 없는 독립 import에서 non-null 참조는 오류입니다. 명시 v2 입력은 위치 의미로 v3에 이행합니다.

결과·경고·오류

결과 객체 세 가지

값을 만들어 내는 연산은 값과 보고서를 한 객체로 돌려줍니다. 셋 다 frozen dataclass입니다.

타입필드돌려주는 연산
DocumentResult[R]document: Document, report: Rfill·set_cell·patch·insert_para·delete_para·stamp·restyle, convert_md·from_json·convert_hwp5
TextResult[R]text: str, report: Rto_json·export_section·to_md
BytesResult[R]data: bytes, report: Rto_pdf

검사 연산(inspect·outline·fields·validate·read·diff·stamp_plan)과 templates·schema는 보고서 dict만 돌려줍니다.

import hwpforge

result = hwpforge.convert_md("# 제목\n\n본문")
result.document          # Document
result.report            # {'sections': 1, 'paragraphs': ..., 'assets': [], 'warnings': []}
document, report = result.document, result.report      # 필드 이름으로 풀어 쓰는 편이 안전합니다

보고서와 타입 힌트

보고서는 TypedDict입니다. 키 이름은 연산 계층의 보고서 구조체 필드명과 같고, hwpforge._hwpforge 스텁(_hwpforge.pyi)에 전부 선언돼 있습니다. 편집기에서 자동 완성과 타입 검사를 받으려면 그 이름을 가져오세요(스텁 모듈 자체는 비공개이지만 타입 이름은 안정적인 편입니다).

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from hwpforge._hwpforge import FillReport, InspectReport

def summarize(report: "InspectReport") -> str:
    return f"{report['sections']} sections, {report['paragraphs']} paragraphs"

NotRequired로 선언된 키(예: InspectReport["styles"], StampReport["manifest"], 경고의 hint)는 없을 수 있으니 .get()으로 읽으세요. 그 밖의 키는 항상 있고, 값이 없으면 None입니다.

warnings — 조용한 손실을 드러내는 채널

templates()·schema()를 뺀 모든 보고서에 warnings: list[{code, message, hint?}]가 있습니다. 실패가 아니라 “성공했지만 이것은 보존되지 않았다“는 신호이므로, 저장하기 전에 읽는 습관이 필요합니다.

doc = hwpforge.Document.open("hancom.hwpx")
rebuilt = hwpforge.from_json(doc.to_json().text, base=doc)
for warning in rebuilt.report["warnings"]:
    print(warning["code"], "-", warning["message"])
    if warning.get("hint"):
        print("  →", warning["hint"])
# LAYOUT_CACHE_DROPPED - ...

자주 보게 되는 코드:

코드뜻어디서
LAYOUT_CACHE_DROPPED입력 해석이나 재인코드에서 줄 조판 캐시를 담지 못했다(최종 원문 캐시 잔존 여부와 구별하며, 보존 편집의 계획적 삭제는 이 경고를 만들지 않음) — 한컴에서 다시 저장하면 복원from_json·restyle 등 재인코드 경로, convert_hwp5
IMAGE_EMBED_SKIPPEDMarkdown의 이미지를 읽지 못해 뺐다(base_dir 없음, 경로 밖, 미지원 형식)convert_md
CONTAINER_TOO_DEEPMarkdown 보기(to_md lossy·styled)가 너무 깊이 중첩된 내용을 그리지 않고 표기((중첩 표 생략) 등)로 바꿨다 — lossy 는 표 안 표 8 단계, styled 는 컨테이너 32 겹이 한도to_md
EQUATION_AS_TEXTstyled Markdown 보기가 수식의 LaTeX를 Markdown에 안전하게 쓸 수 없어($·]( 를 담거나 \ 로 끝남) 수식 스크립트를 일반 글자로 썼다to_md
MARKUP_WRITTEN_AS_TEXTMarkdown 보기(to_md styled·lossy)의 최종 검사에서 인코더가 쓰지 않는 마크업(raw HTML, 만들지 않은 링크·그림, 링크 참조 정의)이 나온 문단을 모든 구두점을 escape 한 평문으로 다시 썼다. 정상이면 나오지 않는다to_md
CONTENT_LOST담지 못한 내용을 뺐다 — 디코드에서는 문서의 내용을 모델이, 인코드에서는 모델의 컨트롤을 HWPX가 담지 못했다. Markdown에서는 styled 보기의 <!-- chart -->·<!-- memo: … --> 주석을 읽지 않고 건너뛰었다디코드하는 연산, from_json, convert_md
LIST_SEMANTICS_LOST목록 문단이 목록 의미(종류·수준·체크) 없이 쓰였다 — Markdown 보기가 표 칸·글상자·각주·캡션 안의 목록 문단을 글로 쓸 때, 또는 Markdown 목록 항목 안의 제목·구분선이 항목 밖 문단이 될 때. 문단마다 하나, message 가 구역과 위치를 가리킨다to_md, convert_md
LIST_START_NORMALIZED1 이 아닌 수로 시작하는 Markdown 번호 목록을 1 부터 썼다convert_md
LIST_LEVEL_CLAMPED수준 9 보다 깊은 Markdown 목록을 수준 9 로 썼다convert_md
LIST_DEFINITION_MISSING템플릿에 그 종류(글머리표·번호·체크)의 목록 정의가 없어 Markdown 목록 항목을 목록이 아닌 문단으로 썼다. 종류마다 하나convert_md
NUMBERING_PRESENTATION_LOST번호 정의의 번호를 원래대로 보이지 못한다 — Markdown 에서는 상위 수준 번호를 쓰는 서식(^1.^2)이 있거나, 번호 정의 복제가 1024 번을 넘어 뒤의 목록이 템플릿 번호 정의를 함께 쓸 때(기본 템플릿에서는 1026 번째 독립 목록부터), Markdown 보기에서는 한컴 문서의 같은 번호 정의가 다른 블록 뒤에서 이어질 때(다시 1 부터 씀). 정의마다 하나convert_md, to_md
IMAGE_REFERENCE_UNRESOLVED그림·채우기가 가리키는 이미지가 패키지에 없다 — 대개 from_json에 base를 주지 않았을 때from_json (재인코드 편집은 거부)
XML_FORBIDDEN_CHARS_REMOVEDXML이 담을 수 없는 제어 문자(탭·줄바꿈 제외)를 지우고 썼다 — 편집 연산은 넘긴 값마다 하나, message가 필드·문단·셀·슬롯을 가리킨다(본문 글자의 U+001F는 지우지 않고 고정폭 빈칸으로 쓴다). 문서를 다시 쓰는 경로는 필드 이름·필드 매개변수 같은 XML 위치마다 하나, message가 그 요소·속성을 가리킨다fill·patch·insert_para·set_cell·stamp, 재인코드 경로
BEGIN_NUM_REPAIRED문서 머리의 시작 번호(쪽·그림·표·수식)가 0이었다 — 1 이상이어야 하므로 다시 쓸 때 1로 고친다(이전 판의 HwpForge 출력에 남은 흔적, 손실 아님)디코드하는 연산
디코더 경고문서가 가졌지만 모델이 담지 못한 것(예: 알 수 없는 컨트롤)디코드하는 모든 연산

CONTENT_LOST는 입력을 Core로 읽을 때 표현하지 못한 정보가 있다는 경고입니다. 원문 보존 삭제는 그 정보가 출력 원문에 보존되고 삭제 판정에 영향을 주지 않음을 별도로 확인한 경우에만 성공하며, 입력 decode 경고는 순서와 횟수 그대로 남습니다. 이는 원문 XML에 정보가 남는 일부 손실(예: 언어별 글자 값)에만 해당하며, 그 밖의 CONTENT_LOST 입력은 기존 거부를 유지합니다. 전체 재인코드 편집의 입력 손실 거부는 유지됩니다.

같은 경고를 validate()의 warnings로도 볼 수 있으므로, 문서를 처음 받았을 때 한 번 validate()를 부르는 것이 좋은 시작입니다.

HwpForgeError — 공통 예외, 다섯 속성

입력을 받아들인 뒤 연산이 거부하면 HwpForgeError를 던집니다. str(exc)는 "CODE: message"(힌트가 있으면 둘째 줄에 hint: …)입니다.

속성타입내용
codestr안정된 실패 코드. 분기는 이 문자열로
messagestr무엇이 잘못됐는지 한 문장
hintstr | None어떻게 해야 하는지 — 연산이 알 때만
causedict | None두 번째 분류. 현재는 PDF_RENDER_FAILED만 {"stage", "code", "kind"?, "location"?}를 가짐
detailsdict | None구조화된 페이로드. ENCODE_SEMANTIC_LOSS는 {"warnings": [...], "others": [...]}
try:
    doc.set_cell(table=0, at="9,9", text="값")
except hwpforge.HwpForgeError as exc:
    if exc.code == "CELL_NOT_FOUND":
        ...
    elif exc.code in ("INPUT_ENTRIES_NOT_CARRIED", "INPUT_NOT_ROUNDTRIP_SAFE"):
        ...     # 한컴 저장 문서 — patch 경로로
    else:
        raise

code는 대응하는 연산에서 같은 단계·사유라면 CLI·MCP·Python 모두 canonical OpsCode 문자열을 사용합니다. 검사 순서와 메시지·힌트는 창구마다 다를 수 있습니다.

다른 예외

예외언제
TypeError / ValueError인자 변환 실패 — fill 값에 정수, font_dirs에 문자열 하나, Document(…)에 bytes 아닌 것
HwpForgeIOError (OSError도 포착)Document.open·save의 파일 I/O
AttributeErrorDocument 속성 대입·삭제(불변)
pyo3_runtime.PanicException내부 Rust panic — 버그이니 이슈로 알려 주세요

코드 표

전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.

각 연산이 자기 특성 실패로 내는 코드입니다. 포함된 읽기·편집 연산은 HWP5(.hwp)를 자동 변환하며, 편집의 의미 손실은 HWP5_CONVERSION_LOSS로 거부합니다. from_json(base=...)·patch·restyle만 HWP5_INPUT으로 거부합니다. 변환 손실과 저장 보호를 참고하세요. 자동 변환 단계의 디코드 실패는 HWP5_DECODE_FAILED이며 변환·검증·인코드 실패는 각각 HWP5_CONVERT_FAILED·VALIDATION_FAILED·ENCODE_FAILED입니다. HWPX 입력의 디코드 실패는 fill·patch·set_cell·insert_para·delete_para·stamp·stamp_plan을 포함해 DECODE_FAILED입니다. 편집 전 no-op 검증·인코드·재디코드 실패는 INPUT_NOT_ROUNDTRIP_SAFE입니다. 코드는 hwpforge::foundation::diagnostics::OpsCode의 문자열 그대로이며, 아래 표는 Python이 부르는 연산에서 실제로 나올 수 있는 것만 적었습니다.

연산코드
Document.openINPUT_TOO_LARGE
보류 연산에 HWP5를 전달HWP5_INPUT — CLI hwpforge convert-hwp5 <in.hwp> -o <out.hwpx> 또는 Python convert_hwp5로 먼저 변환
그 밖에 HWPX를 디코드하는 연산DECODE_FAILED
readREAD_TARGET_REQUIRED · READ_PARAS_INVALID · READ_PARAS_WITHOUT_SECTION · SECTION_OUT_OF_RANGE · READ_PARA_RANGE_INVALID · TABLE_NOT_FOUND · FIELD_NOT_FOUND · TABLE_GRID_INVALID
export_sectionSECTION_OUT_OF_RANGE · GRID_ADDR_PROJECTION_FAILED · JSON_SERIALIZE_FAILED
to_jsonGRID_ADDR_PROJECTION_FAILED · JSON_SERIALIZE_FAILED
to_mdINVALID_INPUT (알 수 없는 mode) · ENCODE_FAILED (mode="lossless") · VALIDATION_FAILED
to_pdfINVALID_DISCOVERY · UNRECOGNIZED_FORMAT · HWP5_DECODE_FAILED · HWP5_CONVERT_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PDF_RENDER_FAILED (+ cause)
fillNO_VALUES · FIELD_NOT_FOUND · FIELD_NAME_AMBIGUOUS · FIELD_NOT_FILLABLE · EMPTY_FIELD_VALUE · FILL_FAILED(필드 목록 진단) · PATCH_FAILED · PROTECTED_FIELD_RANGE · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT
set_cellINVALID_SET_CELL_ARGS · INVALID_SET_CELL_MAP · TABLE_NOT_FOUND · TABLE_GRID_INVALID · CELL_NOT_FOUND · CELL_LABEL_AMBIGUOUS · CELL_HAS_NON_TEXT_CONTENT · CELL_TARGET_DUPLICATE · CELL_TARGET_CONFLICT · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · SELF_VERIFY_FAILED · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · ENCODE_SEMANTIC_LOSS
patchJSON_PARSE_FAILED · GRID_ADDR_INVALID · SECTION_OUT_OF_RANGE · SECTION_INDEX_MISMATCH · PATCH_FAILED(보존 경로가 받지 않는 변경·metadata) · PROTECTED_FIELD_RANGE · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT
insert_paraINSERT_TEXT_REQUIRED · MULTI_PARAGRAPH_TEXT · SECTION_OUT_OF_RANGE · PARAGRAPH_OUT_OF_RANGE · INSERT_BEFORE_SECTION_PROPERTIES · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PROTECTED_FIELD_RANGE · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · SELF_VERIFY_FAILED · SPAN_COUNT_MISMATCH
delete_paraDELETE_NO_TARGET · SECTION_OUT_OF_RANGE · PARAGRAPH_OUT_OF_RANGE · DUPLICATE_TARGET · REFERENCE_STRANDED · HARD_BREAK_LOSS · EMPTY_SECTION · SECTION_PROPERTIES_PARAGRAPH · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PROTECTED_FIELD_RANGE · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · SELF_VERIFY_FAILED · SPAN_COUNT_MISMATCH
stampINVALID_STAMP_MAP · STAMP_SPEC_STALE · STAMP_MARKER_MISMATCH · STAMP_SPEC_DUPLICATE · STAMP_NAME_EMPTY · STAMP_NAME_DUPLICATE · STAMP_NAME_COLLISION · STAMP_CANDIDATE_UNCOVERED · STAMP_CELL_NOT_ANCHOR · STAMP_CELL_NOT_EMPTY · STAMP_LABEL_DRIFT · STAMP_CELL_NOT_CANDIDATE · CELL_TARGET_DUPLICATE · STAMP_SOURCE_HASH_MISMATCH · STAMP_MANIFEST_INVARIANT · SELF_VERIFY_FAILED · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT · TABLE_NOT_FOUND · TABLE_GRID_INVALID · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · ENCODE_SEMANTIC_LOSS
stamp_planDECODE_FAILED
restylePRESET_NOT_FOUND · NO_FONTS · VALIDATION_FAILED · ENCODE_FAILED · ENCODE_SEMANTIC_LOSS
convert_mdPRESET_NOT_FOUND · MD_DECODE_FAILED · STYLE_STORE_FAILED · STYLE_REBIND_FAILED · VALIDATION_FAILED · ENCODE_FAILED
from_jsonJSON_PARSE_FAILED · GRID_ADDR_INVALID · VALIDATION_FAILED · ENCODE_FAILED
convert_hwp5HWP5_DECODE_FAILED(디코더의 스타일·테두리 참조 검사 포함) · VALIDATION_FAILED · ENCODE_FAILED · HWP5_CONVERT_FAILED(줄 배치 정보 재적용)
schemaINVALID_INPUT (알 수 없는 kind)

templates·schema를 뺀 대부분의 연산에서 UPSTREAM_UNMAPPED(이 버전이 아직 분류하지 못한 상류 오류)와 INTERNAL_INVARIANT(라이브러리 불변식 위반 — 버그)가 나올 수 있습니다. 둘 다 이슈로 알려 주세요.

fail-closed 거부 읽기 — ENCODE_SEMANTIC_LOSS

재인코드 편집기(stamp·restyle)는 인코딩이 의미를 잃을 것 같으면 바이트를 아예 만들지 않고 거부합니다. 무엇이 문제였는지는 details에 있습니다.

try:
    doc.restyle(preset="modern")
except hwpforge.HwpForgeError as exc:
    if exc.code == "ENCODE_SEMANTIC_LOSS":
        for w in exc.details["warnings"]:      # 거부를 일으킨 의미 손상
            print(w["code"], w["message"])
        for w in exc.details["others"]:        # 같은 인코딩이 낸 그 밖의 경고
            print("also:", w["code"])

예외를 직렬화·복제할 때

HwpForgeError는 copy·pickle이 다섯 속성을 그대로 보존하도록 __reduce__를 정의합니다. 멀티프로세스 워커에서 예외를 부모로 넘겨도 code·details가 살아 있습니다.

파일 I/O 예외 (0.18)

Document.open의 입력 부재는 HwpForgeFileNotFoundError/FILE_NOT_FOUND, 기타 읽기 실패는 HwpForgeIOError/FILE_READ_FAILED, save의 쓰기 실패는 HwpForgeIOError/FILE_WRITE_FAILED입니다. 크기 상한은 HwpForgeError/INPUT_TOO_LARGE를 유지합니다.

두 I/O 클래스는 HwpForgeError와 OSError로 모두 포착할 수 있고, 입력 부재는 FileNotFoundError로도 포착됩니다. 정확한 타입 비교(type(exc) is OSError)와 PermissionError 등 세부 OS 예외 포착은 보존하지 않습니다. .errno, .strerror, .filename, .filename2, 원래 오류에 있던 .winerror를 보존하며 원래 예외는 __cause__로 연결됩니다. copy·pickle은 클래스·다섯 공통 속성·OS 필드를 보존합니다. native extension과 Python 패키지는 같은 버전을 사용해야 합니다.

Document.save의 부모 디렉터리가 없을 때도 이제 FileNotFoundError 대신 HwpForgeIOError (FILE_WRITE_FAILED)가 발생합니다. save 주변의 except FileNotFoundError는 except HwpForgeIOError 또는 except OSError로 바꾸세요. 입력 부재인 Document.open의 FileNotFoundError 포착은 유지됩니다.

set_cell의 보존 가능한 한 문단·한 Text run 칸에서는 입력 경고를 한 번 유지하고 정리 경고 뒤에 Preview 제거 경고를 한 번 냅니다. 원문 header를 유지한 경우 BEGIN_NUM_REPAIRED는 입력 진단이며 수선 완료를 뜻하지 않습니다. 계획적으로 지운 조판 캐시에 가짜 LAYOUT_CACHE_DROPPED를 추가하지 않습니다. 범위 밖 batch의 기존 인코드·carry 경고 계약은 유지됩니다.

레시피

양식 채우기 파이프라인

정부 서식처럼 한컴이 저장한 양식을 값으로 채워 저장하는 가장 흔한 흐름입니다. 누름틀은 fill, 나머지는 검증·저장.

import hwpforge

def fill_form(src: str, dst: str, values: dict[str, str]) -> list[str]:
    doc = hwpforge.Document.open(src)

    available = {f["name"] for f in doc.fields()["fields"] if f["fillable"]}
    unknown = set(values) - available
    if unknown:
        raise ValueError(f"양식에 없는 필드: {sorted(unknown)}")

    result = doc.fill(values)
    problems = [f"{w['code']}: {w['message']}" for w in result.report["warnings"]]

    check = result.document.validate()
    if not check["ok"]:
        problems += [f"{e['code']}: {e['message']}" for e in check["errors"]]

    result.document.save(dst)
    return problems

print(fill_form("form.hwpx", "form-filled.hwpx", {"user_email": "kim@example.com"}))
  • 필드 이름을 미리 대조하면 FIELD_NOT_FOUND를 예외가 아니라 목록으로 다룰 수 있습니다.
  • 값이 비어 있으면 EMPTY_FIELD_VALUE입니다. 지우고 싶은 필드는 값 목록에서 빼세요.
  • fill은 한컴 저장 문서를 보존하므로 결과를 한컴에서 열면 그대로 보입니다. 편집 전후 한 줄임을 확인한 본문 문단과 본문 최상위 표의 직접 칸 문단은 원래 줄 조판 캐시를 남기며 뒤 문단의 캐시 삭제를 일으키지 않습니다. 그 확인을 통과하지 못한 편집 문단과, 편집 때문에 줄 모양이 달라질 수 있는 문단의 캐시는 지웁니다(fill의 캐시 규칙).

표를 읽어 CSV로

import csv
import hwpforge

def tables_to_csv(path: str, out_prefix: str) -> int:
    doc = hwpforge.Document.open(path)
    tables = doc.outline()["outline"]["tables"]
    for t in tables:
        view = doc.read(table=t["ordinal"])["table"]
        grid = [[""] * view["cols"] for _ in range(view["rows"])]
        for cell in view["cells"]:
            grid[cell["row"]][cell["col"]] = cell["text"]     # 병합 영역은 기준 셀에만 텍스트가 있습니다
        with open(f"{out_prefix}-{t['ordinal']}.csv", "w", newline="", encoding="utf-8") as f:
            csv.writer(f).writerows(grid)
    return len(tables)

print(tables_to_csv("grid.hwpx", "grid"))

텍스트만 바꾸기 — 한컴 저장 문서에서도 되는 길

import json
import hwpforge

def replace_text(doc: hwpforge.Document, section: int, old: str, new: str) -> hwpforge.Document:
    exported = doc.export_section(section=section)
    payload = json.loads(exported.text)

    def walk(node):
        if isinstance(node, dict):
            if isinstance(node.get("text"), str) and old in node["text"]:
                node["text"] = node["text"].replace(old, new)
            for value in node.values():
                walk(value)
        elif isinstance(node, list):
            for item in node:
                walk(item)

    walk(payload["section"])
    return doc.patch(section=section, patch=json.dumps(payload, ensure_ascii=False)).document

doc = hwpforge.Document.open("hancom.hwpx")
changed = replace_text(doc, 0, "표", "테이블")
print(doc.diff(changed)["package"]["changed"])

patch는 텍스트 편집을 지원하므로 문단 수·표 구조·서식 참조는 건드리면 안 됩니다. 위 함수는 text 값만 바꿉니다. 내용을 바꾸면 영향을 받는 조판 캐시와 미리보기 연결 정보도 바뀌며, 미리보기를 지운 경우 PREVIEW_REMOVED를 보고합니다. 입력이 지원 범위를 벗어나면 편집을 거부합니다.

디렉터리 배치 처리

from pathlib import Path
import hwpforge

def inventory(root: str) -> list[dict]:
    rows = []
    for path in sorted(Path(root).glob("*.hwpx")):
        doc = hwpforge.Document.open(path)
        try:
            report = doc.inspect()
        except hwpforge.HwpForgeError as exc:
            rows.append({"file": path.name, "error": exc.code})
            continue
        rows.append({
            "file": path.name,
            "title": report["metadata"]["title"],
            "paragraphs": report["paragraphs"],
            "tables": report["tables"],
            "fields": len(report["fields"]),
            "warnings": len(report["warnings"]),
        })
    return rows

for row in inventory("."):
    print(row)

문서는 open 시점에 디코드되지 않으므로 파일마다 inspect에서 실패를 잡으면 됩니다. CPU를 더 쓰고 싶으면 concurrent.futures.ProcessPoolExecutor로 파일 단위로 나누세요 — HwpForgeError는 pickle이 되므로 워커의 실패가 code 째로 부모에 돌아옵니다.

HWP를 PDF로

옛 .hwp를 한컴이 계산한 쪽 나눔 그대로 PDF로 만드는 길입니다. 글꼴 디렉터리는 문서가 이름 붙인 face가 실제로 있는 곳이어야 합니다.

import hwpforge

def hwp_to_pdf(src: str, dst: str, font_dirs: list[str]) -> int:
    with open(src, "rb") as handle:
        converted = hwpforge.convert_hwp5(handle.read())
    pdf = converted.document.to_pdf(font_dirs=font_dirs)
    with open(dst, "wb") as out:
        out.write(pdf.data)
    return pdf.report["pages"]

try:
    print(hwp_to_pdf("old.hwp", "old.pdf", ["/Library/Fonts/Hancom"]))
except hwpforge.HwpForgeError as exc:
    print(exc.code, exc.cause and exc.cause["code"])     # FONT_UNRESOLVED 면 font_dirs 를 확인

글꼴을 구할 수 없고 모양이 달라져도 괜찮다면 to_pdf(font_dirs=[...], degraded=True)로 대체 글꼴 렌더를 받을 수 있습니다.

Markdown으로 문서 생성 후 검토

import hwpforge

result = hwpforge.convert_md(open("report.md", encoding="utf-8").read(), preset="modern", base_dir=".")
for asset in result.report["assets"]:
    if asset["kind"] == "dropped":
        print("이미지 누락:", asset["occurrence"], asset["reason"])
result.document.save("report.hwpx")

back = result.document.to_md(mode="lossy")
print(back.text[:300])

생성한 문서는 조판 캐시가 없으므로 to_pdf는 되지 않습니다. 한컴에서 열어 저장하면 캐시가 생기고, 재생할 수 없는 요소가 없다면 그때부터 렌더됩니다(to_pdf 표).

pip 없는 호스트에 배포하기

NAS나 잠긴 서버처럼 pip이 없는 곳에서는 wheel을 풀어서 씁니다. 한 번만 하면 되는 절차입니다.

  1. 인터넷이 되는 곳에서 PyPI files 페이지에서 대상 플랫폼의 wheel을 받습니다 — Linux x86_64 면 hwpforge-<version>-cp39-abi3-manylinux_2_28_x86_64.whl. sha256도 그 페이지에 있습니다.
  2. 대상 호스트의 조건을 확인합니다: CPython 3.9 이상, glibc 2.28 이상(ldd --version).
  3. 파일을 옮겨 풉니다.
python3 -c "import zipfile; zipfile.ZipFile('hwpforge-<version>-cp39-abi3-manylinux_2_28_x86_64.whl').extractall('/opt/hf')"
PYTHONPATH=/opt/hf python3 -c "import hwpforge; print(hwpforge.__version__)"

런타임 의존성이 없으므로 이것으로 끝입니다. 스크립트에서는 sys.path.insert(0, "/opt/hf")로도 같은 효과를 냅니다.

문서 두 판을 비교해 검토 보고 만들기

import hwpforge

base = hwpforge.Document.open("form.hwpx")
revised = base.fill({"user_email": "kim@example.com"}).document

d = base.diff(revised)
print("동일:", d["identical"])
print("바뀐 엔트리:", d["package"]["changed"])
for change in d["semantic"]["field_values"]:
    print("필드:", change)
for change in d["semantic"]["paragraphs"]:
    print("문단:", change)

semantic의 다섯 목록(field_values·cells·paragraphs·structure·raw)은 각각 누름틀 값·셀 텍스트·문단 텍스트·구조·모델 밖 XML(조판 캐시 등)의 차이입니다. 편집이 의도한 범위만 건드렸는지 보는 가장 빠른 검사는 package["changed"]가 대상 구역 XML 하나뿐인지입니다.

API 요약

패키지의 공개 표면은 hwpforge.__all__의 열한 이름입니다: Document · DocumentResult · TextResult · BytesResult · HwpForgeError · convert_md · from_json · convert_hwp5 · templates · schema · __version__. 그 밖의 모듈(hwpforge._hwpforge 등)은 비공개이며 릴리스 사이에 바뀔 수 있습니다.

Document

생성과 바이트

이름시그니처설명
Document.open(path) -> Document파일에서. 100 MB 상한, 넘으면 INPUT_TOO_LARGE. I/O 실패는 OSError
Document.from_bytes(data: bytes) -> Document메모리의 바이트에서. 상한 없음
Document(data)(data: bytes)생성자. bytes 아니면 TypeError
to_bytes() -> bytesHWPX 패키지 바이트 그대로
save(path) -> None항상 HWPX로 씀. 기존 파일은 교체
bytes(doc) · len(doc) · == · hash · repr바이트 기준 값 의미. repr은 Document(<n> bytes)

검사 (보고서 dict 반환)

메서드시그니처보고서 키
inspect(*, styles: bool = False) -> InspectReportmetadata·sections·paragraphs·tables·images·charts·fields·section_details·styles?·warnings
outline() -> OutlineReportoutline{title, sections, headings, tables, fields, bookmarks}·warnings
fields() -> FieldsReportfields[{name, hint, current, section, fillable}]·warnings
validate() -> ValidateReportok·sections·paragraphs·errors·warnings
read(*, section=None, paras=None, table=None, field=None) -> ReadReportparagraphs·table·fields(하나만 채워짐)·warnings
diff(revised: Document) -> DiffReportidentical·note·semantic{…}·package{added, removed, changed}·warnings
stamp_plan() -> StampPlanReportschema_version·source_sha256·text·cells·skipped_tables·warnings

내보내기

메서드시그니처반환
to_json(*, styles: bool = True) -> TextResult[ToJsonReport].text JSON, .report{document, warnings}
export_section(*, section: int, styles: bool = True) -> TextResult[ExportSectionReport].text JSON, .report{section, warnings}
to_md(*, mode: "styled" | "lossy" | "lossless" = "styled") -> TextResult[ToMdReport].text Markdown, .report{mode, images, warnings}
to_pdf(*, font_dirs=(), discovery="explicit", degraded=False, partial_cache_reject=False) -> BytesResult[ToPdfReport].data PDF, .report{pages, warnings}

편집 (DocumentResult 반환 — .document 새 문서, .report 보고서)

메서드시그니처보고서 키
fill(values: Mapping[str, str])filled[{name, section, previous}]·warnings
set_cell(*, table=None, at=None, right_of=None, below=None, text=None, specs=None)results[{table, requested, anchor, resolution, cleared}]·warnings
patch(*, section: int, patch: str)section·warnings
insert_para(*, section: int, anchor: int, text: str | Sequence[str], before: bool = False)inserted·deleted·warnings
delete_para(*, section: int, indexes: Sequence[int])inserted·deleted·warnings
stamp(request: StampRequest, *, manifest: bool = True)manifest?·stamped·stamped_cells·ignored·skipped_guarded·warnings
restyle(*, preset: str)preset·sections·paragraphs·warnings

모듈 함수

함수시그니처반환
convert_md(text: str, *, preset: str = "default", base_dir=None)DocumentResult[ConvertMdReport] — sections·paragraphs·assets·warnings
from_json(text: str, *, base: Document | None = None)DocumentResult[EncodeReport] — paragraphs·warnings
convert_hwp5(data: bytes, *, carry_layout_cache: bool = True)DocumentResult[ConvertHwp5Report] — warnings
templates()TemplatesReport — presets[{name, description, font, page_size}]
schema(*, kind: "document" | "exported-document" | "exported-section" = "document")JSON Schema dict

결과 객체와 예외

타입필드/속성
DocumentResult[R]document: Document, report: R
TextResult[R]text: str, report: R
BytesResult[R]data: bytes, report: R
HwpForgeErrorcode: str, message: str, hint: str | None, cause: dict | None, details: dict | None

입력 형태

이름모양
CellSpec{"table": int, "text": str} + at: {"row", "col"} | right_of: str | below: str 중 하나
StampSpec{"section", "path", "span": {"start", "end"}, "marker", "action"} — action은 "ignore" 또는 {"field": {"name", "hint"}}
StampRequestSequence[StampSpec] 또는 {"schema_version", "source_sha256", "text"?: [...], "cells"?: [...]}
paras"시작..끝", 양끝 포함
at (메서드 인자)"row,col" 문자열, 0부터

상수

이름값
hwpforge.__version__설치된 패키지 버전
hwpforge._hwpforge.MAX_FILE_SIZEDocument.open의 상한, 104857600 (100 MB)

HWP5 입력 옵션

fill·set_cell·insert_para·delete_para·stamp와 save에는 키워드 accept_conversion_loss: bool = False가 있습니다. HWP5 자동 변환의 의미 손실만 허용하며 기존 편집 검증은 유지합니다. 포함 읽기·편집 결과에는 선택적인 conversion 메타데이터가 추가됩니다. 입력·저장 정책에 전체 범위가 있습니다.

HWPX 인코딩/디코딩

HWPX 포맷 소개

HWPX는 한글과컴퓨터의 공개 문서 표준(KS X 6101, OWPML)입니다. 내부 구조는 ZIP 컨테이너 안에 XML 파일들이 담긴 형태로, Microsoft DOCX와 유사합니다.

주요 구성 파일:

  • mimetype — 포맷 식별자
  • Contents/header.xml — 스타일 정의 (폰트, 문단 모양, 글자 모양)
  • Contents/section0.xml, section1.xml, … — 본문 내용
  • BinData/ — 이미지 등 바이너리 파일들
  • Chart/ — 차트 XML (OOXML xmlns:c 형식)

hwpforge-smithy-hwpx 크레이트가 이 포맷의 인코드/디코드를 담당합니다.

디코딩: HWPX 파일 읽기

HwpxDecoder::decode_file()로 .hwpx 파일을 HwpxDocument로 읽습니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();

// 섹션 수 확인
println!("섹션 수: {}", result.document.sections().len());

// 첫 번째 섹션의 문단 수
let section = &result.document.sections()[0];
println!("문단 수: {}", section.paragraphs.len());
}

HwpxDocument 결과 구조

HwpxDecoder::decode_file()은 HwpxDocument를 반환합니다. 네 가지 필드로 구성됩니다. HwpxDocument는 #[non_exhaustive]라서 구조 분해(let HwpxDocument { .. } = ...) 대신 필드로 접근합니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxDecoder, HwpxDocument};

let result: HwpxDocument = HwpxDecoder::decode_file("document.hwpx").unwrap();

// result.document: Document<Draft> — 문서 DOM (섹션/문단/런 트리)
// result.style_store: HwpxStyleStore — 폰트, 글자 모양, 문단 모양, 스타일
// result.image_store: ImageStore — 임베드된 이미지 바이너리 데이터
// result.warnings: Vec<DecodeWarning> — 디코드 중 표면화된 비치명 경고
for warning in &result.warnings {
    println!("경고: {warning:?}");
}
}
필드타입설명
documentDocument<Draft>섹션, 문단, 런 트리
style_storeHwpxStyleStore폰트/글자모양/문단모양/스타일
image_storeImageStore이미지 바이너리 저장소
warningsVec<DecodeWarning>디코드 중 표면화된 비치명 경고

메타데이터 접근

디코딩된 문서에서 metadata()로 제목, 작성자 등의 메타데이터에 접근합니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let meta = result.document.metadata();

if let Some(title) = &meta.title {
    println!("제목: {}", title);
}
if let Some(author) = &meta.author {
    println!("작성자: {}", author);
}
if let Some(created) = &meta.created {
    println!("작성일: {}", created);
}
}

전체 메타데이터 필드 목록과 사용법은 메타데이터 가이드를 참고하세요.

인코딩: Core → HWPX

HwpxEncoder::encode()로 Document<Validated>를 HWPX 바이트 벡터로 직렬화합니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxDecoder, HwpxEncoder, HwpxStyleStore};
use hwpforge_core::{Document, Section, Paragraph, PageSettings};
use hwpforge_core::run::Run;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

// 새 문서 생성
let mut doc = Document::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("안녕하세요, HwpForge!", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

let validated = doc.validate().unwrap();
let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
let image_store = Default::default();

let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap();
std::fs::write("output.hwpx", &bytes).unwrap();
}

HwpxStyleStore 생성 방법

with_default_fonts() — 간단한 기본 스타일

단일 글꼴 이름으로 빠르게 스타일 스토어를 생성합니다. 가장 간단한 방법입니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxStyleStore;

let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
}

from_registry() — Blueprint 템플릿에서 변환

커스텀 YAML 스타일 템플릿을 적용할 때 사용합니다. 자세한 내용은 스타일 템플릿 참조.

#![allow(unused)]
fn main() {
use hwpforge::blueprint::builtins::builtin_default;
use hwpforge::blueprint::registry::StyleRegistry;
use hwpforge::hwpx::HwpxRegistryBridge;

let template = builtin_default().unwrap();
let registry = StyleRegistry::from_template(&template).unwrap();
let bridge = HwpxRegistryBridge::from_registry(&registry).unwrap();
let style_store = bridge.style_store();
}

HwpxStyleStore::from_registry() 자체는 HWPX style table만 만듭니다.
Blueprint/Markdown 경로에서 만든 문서는 registry-local CharShapeIndex / ParaShapeIndex 를 들고 있으므로, encode 직전에는 HwpxRegistryBridge로 rebinding 해야 합니다.

라운드트립 예제 (decode → modify → encode)

기존 HWPX 파일을 읽어서 수정한 뒤 다시 저장하는 전형적인 패턴입니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxDecoder, HwpxEncoder};
use hwpforge_core::run::Run;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

// 1. 기존 파일 디코딩
let mut result = HwpxDecoder::decode_file("original.hwpx").unwrap();

// 2. 문서 수정: 새 문단 추가
let new_para = Paragraph::with_runs(
    vec![Run::text("추가된 문단입니다.", CharShapeIndex::new(0))],
    ParaShapeIndex::new(0),
);
// Draft 상태이므로 sections 직접 접근 가능
result.document.sections_mut()[0].paragraphs.push(new_para);

// 3. 검증 후 인코딩
let validated = result.document.validate().unwrap();
let bytes = HwpxEncoder::encode(
    &validated,
    &result.style_store,
    &result.image_store,
).unwrap();

std::fs::write("modified.hwpx", &bytes).unwrap();
}

기존 텍스트 찾기 및 수정

특정 텍스트를 찾아 수정하려면 sections_mut()으로 가변 접근 후 RunContent::Text를 패턴 매칭합니다.

텍스트 치환 (find & replace)

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxDecoder, HwpxEncoder};
use hwpforge_core::run::RunContent;

// 1. 디코딩
let mut result = HwpxDecoder::decode_file("template.hwpx").unwrap();

// 2. 모든 섹션의 모든 문단을 순회하며 텍스트 치환
for section in result.document.sections_mut() {
    for paragraph in &mut section.paragraphs {
        for run in &mut paragraph.runs {
            if let RunContent::Text(ref mut text) = run.content {
                if text.contains("{{회사명}}") {
                    *text = text.replace("{{회사명}}", "한국테크");
                }
                if text.contains("{{날짜}}") {
                    *text = text.replace("{{날짜}}", "2026년 3월 11일");
                }
            }
        }
    }
}

// 3. 검증 후 저장
let validated = result.document.validate().unwrap();
let bytes = HwpxEncoder::encode(&validated, &result.style_store, &result.image_store).unwrap();
std::fs::write("output.hwpx", &bytes).unwrap();
}

재사용 가능한 치환 함수

#![allow(unused)]
fn main() {
use hwpforge_core::document::{Document, Draft};
use hwpforge_core::run::RunContent;

/// 문서 내 모든 텍스트에서 `from`을 `to`로 치환합니다.
/// 치환된 횟수를 반환합니다.
fn replace_text(doc: &mut Document<Draft>, from: &str, to: &str) -> usize {
    let mut count = 0;
    for section in doc.sections_mut() {
        for paragraph in &mut section.paragraphs {
            for run in &mut paragraph.runs {
                if let RunContent::Text(ref mut text) = run.content {
                    if text.contains(from) {
                        *text = text.replace(from, to);
                        count += 1;
                    }
                }
            }
        }
    }
    count
}
}

완전한 읽기 → 수정 → 저장 예제

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxDecoder, HwpxEncoder};
use hwpforge_core::run::{Run, RunContent};
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

fn modify_document(
    input: &str,
    output: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    // 읽기
    let mut result = HwpxDecoder::decode_file(input)
        .map_err(|e| format!("디코딩 실패: {e}"))?;

    let sections = result.document.sections_mut();

    // 기존 텍스트 수정
    for section in sections.iter_mut() {
        for paragraph in &mut section.paragraphs {
            for run in &mut paragraph.runs {
                if let RunContent::Text(ref mut text) = run.content {
                    *text = text.replace("초안", "최종본");
                }
            }
        }
    }

    // 새 문단 추가
    if let Some(first_section) = result.document.sections_mut().first_mut() {
        first_section.paragraphs.push(Paragraph::with_runs(
            vec![Run::text("— 이 문서는 자동으로 수정되었습니다.", CharShapeIndex::new(0))],
            ParaShapeIndex::new(0),
        ));
    }

    // 저장
    let validated = result.document.validate()
        .map_err(|e| format!("검증 실패: {e}"))?;
    let bytes = HwpxEncoder::encode(&validated, &result.style_store, &result.image_store)
        .map_err(|e| format!("인코딩 실패: {e}"))?;
    std::fs::write(output, &bytes)?;

    Ok(())
}
}

오류 처리

모든 함수는 HwpxResult<T>를 반환합니다. HwpxError는 HwpxErrorCode와 메시지를 포함합니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;

match HwpxDecoder::decode_file("missing.hwpx") {
    Ok(_result) => println!("디코딩 성공"),
    Err(e) => eprintln!("디코딩 실패: {e}"),
}
}

엣지 케이스 및 주의사항

빈 문서

Document는 최소 1개의 섹션이 있어야 validate()를 통과합니다.

#![allow(unused)]
fn main() {
use hwpforge::core::{Document, Draft, PageSettings, Paragraph, Run, Section};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};

let mut doc = Document::<Draft>::new();

// ❌ 빈 문서 — validate() 실패
// let validated = doc.validate();  // Err: 섹션 없음

// ✅ 빈 텍스트 런을 포함한 문단 추가
// 이것을 실패시키는 것: 런 없는 Paragraph::new로 되돌리기(validate 실패).
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));
let validated = doc.validate().unwrap();  // OK
}

한국어/특수 문자

HwpForge는 내부적으로 UTF-8을 사용합니다. 한국어, 이모지, 특수 기호를 포함한 모든 유니코드 문자를 지원합니다.

#![allow(unused)]
fn main() {
use hwpforge::core::run::Run;
use hwpforge::foundation::CharShapeIndex;

// 모두 정상 동작
let run1 = Run::text("한글 텍스트 테스트", CharShapeIndex::new(0));
let run2 = Run::text("특수문자: ©®™ §¶ ±×÷", CharShapeIndex::new(0));
let run3 = Run::text("수학 기호: α β γ δ ∑ ∫", CharShapeIndex::new(0));
}

스타일 스토어 선택

생성 방법용도특징
with_default_fonts("글꼴명")빠른 프로토타이핑한컴 Modern 22종 기본 스타일
from_registry(&registry)커스텀 템플릿 적용YAML로 정의한 스타일 사용
디코딩된 result.style_store기존 문서 수정원본 스타일 보존

메타데이터 (Metadata)

HwpForge의 모든 문서는 Metadata 구조체를 통해 제목, 작성자, 작성일 등의 메타데이터를 관리합니다.

Metadata 구조체

use std::collections::BTreeMap;

#[non_exhaustive]
pub struct Metadata {
    pub title: Option<String>,               // 문서 제목
    pub author: Option<String>,              // 작성자
    pub subject: Option<String>,             // 주제/설명
    pub description: Option<String>,         // 자유 서술 요약 (subject와 별개)
    pub last_saved_by: Option<String>,       // 마지막으로 저장한 사람 (author와 별개)
    pub keywords: Vec<String>,               // 검색 키워드
    pub created: Option<String>,             // 작성일 (ISO 8601, 예: "2026-03-06")
    pub modified: Option<String>,            // 수정일 (ISO 8601)
    pub extras: BTreeMap<String, String>,    // 아직 타입 필드로 승격되지 않은 <opf:meta> 등 원본 항목
}

모든 필드는 선택적입니다. Metadata::default()는 모든 필드가 비어 있는 상태를 반환합니다.

Metadata는 #[non_exhaustive]입니다 — 향후 버전에서 필드가 추가될 수 있으므로, 외부 크레이트에서는 ..Default::default()를 붙여도 구조체 리터럴로 생성할 수 없습니다. Metadata::new()에서 시작하는 빌더(with_title, with_author, with_subject, with_description, with_last_saved_by, with_keywords, with_created, with_modified, with_extra)를 사용하세요. 이미 만들어진 값의 필드는 doc.metadata_mut().title = ...처럼 직접 대입할 수 있습니다.

기존 HWPX 파일에서 메타데이터 읽기

HwpxDecoder로 HWPX 파일을 디코딩한 후 document.metadata()로 접근합니다.

use hwpforge::hwpx::HwpxDecoder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = HwpxDecoder::decode_file("document.hwpx")?;
    let meta = result.document.metadata();

    // 개별 필드 접근
    if let Some(title) = &meta.title {
        println!("제목: {}", title);
    }
    if let Some(author) = &meta.author {
        println!("작성자: {}", author);
    }
    if let Some(created) = &meta.created {
        println!("작성일: {}", created);
    }
    if let Some(subject) = &meta.subject {
        println!("주제: {}", subject);
    }
    if !meta.keywords.is_empty() {
        println!("키워드: {}", meta.keywords.join(", "));
    }

    Ok(())
}

Markdown에서 메타데이터 설정

YAML Frontmatter로 메타데이터를 지정하면 MdDecoder가 자동으로 Metadata 필드에 매핑합니다.

#![allow(unused)]
fn main() {
use hwpforge::md::{MdDecoder, MdDocument};

let markdown = r#"---
title: 분기 보고서
author: 김철수
date: 2026-03-06
metadata:
  subject: 2026년 1분기 경영실적 보고
  keywords:
    - 분기실적
    - 경영보고
  modified: 2026-03-10
---

보고서 본문

내용이 여기에 들어갑니다.
"#;

let MdDocument { document, style_registry, .. } = MdDecoder::decode_with_default(markdown).unwrap();

let meta = document.metadata();
assert_eq!(meta.title.as_deref(), Some("분기 보고서"));
assert_eq!(meta.author.as_deref(), Some("김철수"));
assert_eq!(meta.created.as_deref(), Some("2026-03-06"));
assert_eq!(meta.subject.as_deref(), Some("2026년 1분기 경영실적 보고"));
assert_eq!(meta.keywords, vec!["분기실적", "경영보고"]);
assert_eq!(meta.modified.as_deref(), Some("2026-03-10"));
}

Frontmatter 필드 매핑

최상위 필드:

YAML 필드Metadata 필드설명
titletitle문서 제목
authorauthor작성자
datecreated작성일 (ISO 8601)
template(없음)파싱되지만 스타일 선택에는 쓰이지 않습니다(inert)
metadata(중첩 맵)아래 하위 필드를 담는 컨테이너

metadata: 아래의 하위 필드:

하위 필드Metadata 필드설명
subjectsubject주제/설명
keywordskeywords검색 키워드 (배열)
modifiedmodified수정일 (ISO 8601)
format(없음)값이 lossless 이면 lossless 출력 표식이라 디코드가 거부합니다

subject/keywords/modified는 반드시 metadata: 아래에 중첩해야 합니다 — 최상위에 쓰면 조용히 무시됩니다.

프로그래밍으로 메타데이터 설정

Document<Draft> 상태에서 metadata_mut()으로 직접 설정할 수 있습니다.

#![allow(unused)]
fn main() {
use hwpforge::core::{Document, Draft, Metadata, PageSettings, Paragraph, Run, Section};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};

let mut doc = Document::<Draft>::new();

// 메타데이터 설정
doc.metadata_mut().title = Some("제안서".to_string());
doc.metadata_mut().author = Some("홍길동".to_string());
doc.metadata_mut().created = Some("2026-03-06".to_string());
doc.metadata_mut().subject = Some("신규 사업 제안".to_string());
doc.metadata_mut().keywords = vec!["사업".to_string(), "제안".to_string()];

// 또는 빌더로 Metadata를 만들어 한 번에 설정
let meta = Metadata::new()
    .with_title("제안서")
    .with_author("홍길동")
    .with_created("2026-03-06");
doc.set_metadata(meta);

// 섹션 추가 후 검증/인코딩
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("본문 내용", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));
let validated = doc.validate().unwrap();
}

CLI에서 메타데이터 확인

hwpforge inspect 명령으로 HWPX 파일의 메타데이터를 확인합니다.

# 사람이 읽기 좋은 출력
hwpforge inspect document.hwpx

# 출력 예시:
# Document: document.hwpx
#   Title:  분기 보고서
#   Author: 김철수
#   Sections: 1
#     [0] 2 paras (deep 2), 0 tables, 0 images, 0 charts | header=false footer=false pagenum=false
# JSON 출력 (AI 에이전트용)
hwpforge inspect document.hwpx --json

# 출력 예시:
# {
#   "status": "ok",
#   "metadata": {
#     "title": "분기 보고서",
#     "author": "김철수"
#   },
#   "sections": [
#     {
#       "index": 0,
#       "paragraphs": 2,
#       "deep_paragraphs": 2,
#       "tables": 0,
#       "images": 0,
#       "charts": 0,
#       "has_header": false,
#       "has_footer": false,
#       "has_page_number": false,
#       ...
#     }
#   ]
# }

JSON 라운드트립에서 메타데이터

to-json으로 내보내면 메타데이터가 JSON에 포함됩니다.

hwpforge to-json document.hwpx -o doc.json
{
  "document": {
    "sections": [...],
    "metadata": {
      "title": "분기 보고서",
      "author": "김철수",
      "subject": null,
      "description": null,
      "last_saved_by": null,
      "keywords": [],
      "created": "2026-03-06",
      "modified": null,
      "extras": {}
    }
  },
  "styles": {...}
}

AI 에이전트가 JSON에서 메타데이터를 수정한 후 from-json으로 HWPX를 재생성할 수 있습니다.

# JSON 편집 후 HWPX로 변환
hwpforge from-json doc.json -o updated.hwpx

MCP 도구에서 메타데이터 확인

hwpforge_inspect MCP 도구로 메타데이터를 포함한 문서 구조를 확인합니다.

{
  "tool": "hwpforge_inspect",
  "arguments": {
    "file_path": "/path/to/document.hwpx"
  }
}

현재 제한사항

  • HWPX 네이티브 메타데이터: 디코더는 한글 프로그램이 저장한 HWPX의 Contents/content.hpf (<opf:metadata>)를 읽어 제목(<opf:title>)과 <opf:meta name="..."> 항목 중 작성자(creator)·주제(subject)·설명(description)·마지막 저장자(lastsaveby)·작성일(CreatedDate)·수정일(ModifiedDate)·키워드(keyword, 세미콜론 구분)를 Metadata에 채웁니다. 아직 타입 필드가 없는 <opf:meta> 항목은 extras에 보존됩니다.
  • 타임스탬프 형식: created/modified는 Option<String> (ISO 8601 문자열)입니다. chrono 등 날짜 라이브러리와 연동 시 직접 파싱이 필요합니다.

Markdown에서 HWPX로

HwpForge는 Markdown을 HWPX로 변환하는 완전한 파이프라인을 제공합니다. LLM이 Markdown을 생성하면 HwpForge가 이를 한글 문서로 자동 변환합니다.

MD → Core → HWPX 파이프라인

Markdown 문자열
    |
    v (MdDecoder::decode)
Document<Draft> + StyleRegistry
    |
    v (doc.validate())
Document<Validated>
    |
    v (HwpxEncoder::encode)
HWPX 바이트 → .hwpx 파일

각 단계는 독립적이므로, 중간 Core DOM을 직접 조작하거나 검사할 수 있습니다.

MdDecoder::decode() 사용법

#![allow(unused)]
fn main() {
use hwpforge::md::{MdDecoder, MdDocument};

let markdown = r#"
---
title: 사업 제안서
author: 홍길동
date: 2026-03-06
---

개요

본 제안서는 신규 사업 기회를 설명합니다.

# 배경

시장 분석에 따르면 성장 가능성이 높습니다.
"#;

let MdDocument { document, style_registry, .. } = MdDecoder::decode_with_default(markdown).unwrap();

println!("섹션 수: {}", document.sections().len());
}

MdDocument에는 document: Document<Draft>, style_registry: StyleRegistry, warnings: Vec<MdWarning>이 포함됩니다. warnings에는 대상이 빈 이미지(![x]())처럼 문서에 넣지 않은 것이 남습니다. 필드가 늘 수 있으므로 구조 분해에는 ..을 붙입니다.

YAML Frontmatter

Markdown 파일 상단에 --- 블록으로 문서 메타데이터를 지정합니다.

---
title: 문서 제목          # Metadata.title
author: 작성자 이름        # Metadata.author
date: 2026-03-06          # Metadata.created (ISO 8601)
template: government      # 파싱되지만 스타일 선택에는 쓰이지 않습니다 (inert)
metadata:                 # 아래 하위 필드를 담는 중첩 맵
  subject: 신규 사업 제안   # Metadata.subject
  keywords:                # Metadata.keywords (YAML 배열)
    - 사업
    - 제안
  modified: 2026-03-10     # Metadata.modified (ISO 8601)
---

최상위 필드:

필드Metadata 필드설명
titletitle문서 제목
authorauthor작성자
datecreated작성일 (ISO 8601)
template(없음)파싱되지만 스타일 선택에는 쓰이지 않습니다(inert)
metadata(중첩 맵)아래 하위 필드를 담는 컨테이너

metadata: 아래의 하위 필드:

하위 필드Metadata 필드설명
subjectsubject주제/설명
keywordskeywords검색 키워드 (YAML 배열)
modifiedmodified수정일 (ISO 8601)
format(없음)값이 lossless 이면 lossless 출력 표식이라 디코드가 거부합니다

subject/keywords/modified는 반드시 metadata: 아래에 중첩해야 합니다 — 최상위에 쓰면 조용히 무시됩니다(Frontmatter 구조체가 이 키들을 최상위 필드로 갖지 않고, 모르는 키를 에러로 거부하지도 않기 때문입니다).

Frontmatter 없이도 디코딩이 가능하며, 메타데이터 필드는 빈 값으로 처리됩니다.

디코딩 후 메타데이터 확인

#![allow(unused)]
fn main() {
use hwpforge::md::{MdDecoder, MdDocument};

let markdown = "---\ntitle: 보고서\nauthor: 홍길동\ndate: 2026-03-06\n---\n\n# 본문\n";
let MdDocument { document, .. } = MdDecoder::decode_with_default(markdown).unwrap();

let meta = document.metadata();
assert_eq!(meta.title.as_deref(), Some("보고서"));
assert_eq!(meta.author.as_deref(), Some("홍길동"));
assert_eq!(meta.created.as_deref(), Some("2026-03-06"));
}

전체 메타데이터 필드와 프로그래밍 설정 방법은 메타데이터 가이드를 참고하세요.

섹션 마커

<!-- hwpforge:section --> 주석으로 HWPX 섹션을 분리합니다. 한 Markdown 파일에서 여러 섹션(페이지 설정이 다른 구역)을 만들 때 유용합니다.

# 1장 개요

첫 번째 섹션 내용.

<!-- hwpforge:section -->

# 2장 본론

두 번째 섹션 — 다른 페이지 설정 가능.

각주 (Footnote) / 미주 (Endnote)

GFM 각주 문법으로 각주와 미주를 표현합니다.

본문에 각주를 답니다.[^1] 미주도 답니다.[^e1]

[^1]: 각주 본문입니다.

[^e1]: 미주 본문입니다.
  • [^라벨]: 각주 — 관례적으로 숫자를 씁니다([^1]), 하지만 규칙 자체는 아래 미주 형태(e[0-9]+)가 아니면 어떤 라벨도 각주로 인정됩니다(예: [^note]도 유효한 각주 라벨입니다).
  • [^eN] (e + 숫자 1개 이상): 미주 — HwpForge dialect의 예약 네임스페이스입니다. 각주 의도로 [^e1]을 써도 미주로 정규화됩니다 (lossy 변환입니다).
  • 정의는 여러 문단으로 이어갈 수 있습니다. 첫 문단 다음에 빈 줄을 두고, 이어지는 문단의 모든 줄을 4-space 들여씁니다.
[^1]: 첫 번째 문단.

    두 번째 문단 (4-space 들여쓰기).

hwpforge to-md(기본 styled 모드)로 HWPX → Markdown 역방향 변환할 때도 각주는 [^N], 미주는 [^eN]으로 방출되어 왕복이 보존됩니다. lossy 모드는 대신 (footnote: ...)/(endnote: ...) 형태의 인라인 텍스트로 펼쳐서 출력하므로 이 왕복 규약의 대상이 아닙니다.

표 (Table)

GFM 표 문법을 지원합니다.

| 항목 | 값     |
| ---- | ------ |
| 이름 | 홍길동 |
| 부서 | 기획팀 |

표 셀 안에는 링크, 이미지, 각주/미주 참조 등 인라인 요소도 담을 수 있습니다. 셀 안의 <br> 는 셀 문단을 나눕니다.

Markdown 안의 HTML

디코더는 to-md 의 styled·lossy 보기가 쓰는 HTML 만 읽습니다(읽기 보기가 쓰는 HTML 의 목록은 아래 “읽기 보기(styled·lossy)가 escape 하는 것과 쓰는 HTML” 절). 그 밖의 HTML, 대문자 태그, 표에 없는 속성은 MD_DECODE_FAILED 오류입니다.

아래 표의 태그 이름은 문법 개요입니다. 실제 입력은 보기가 쓰는 모양 그대로여야 합니다. 태그 이름은 소문자로 쓰고, 속성 값은 큰따옴표로 감싸며, <br> 는 닫지 않고, <img> 는 /> 로 끝냅니다. 예: <a href="https://example.com">링크</a>, <img src="images/a.png" alt="a"/>, <td colspan="2">칸</td>.

HTML읽는 방식
<strong>·<em>·<del>·<u>·<sup>·<sub>글자 모양(굵게·기울임·취소선·밑줄·위첨자·아래첨자). 열고 닫는 순서가 맞아야 하고, 문단·셀 안에서 닫혀야 합니다. 위첨자와 아래첨자를 함께 쓰면 오류입니다
<a href>·<img src alt>Markdown 링크·그림과 같습니다(같은 URL 규칙, 같은 그림 파일 규칙)
<br>본문·각주에서는 줄바꿈, 표 셀에서는 셀 문단 경계, 링크 안에서는 링크 글의 줄바꿈
<table>·<tbody>·<tr>·<td colspan rowspan>표. <table><tbody> 안에 <tr> 행과 <td> 셀이 오는 순서를 지켜야 합니다. 셀 안에는 글·서식·링크·그림·<br>·주석과 표(32단계까지)가 옵니다. span 은 1–65535 입니다. 행과 셀은 쓴 그대로 읽고, 표가 맞는지는 문서 검증이 판정합니다
<!-- hwpforge:section -->구역 경계(본문에서만)
<!-- chart -->·<!-- memo: … -->읽지 않고 건너뜁니다. 주석마다 경고 CONTENT_LOST(MdWarning::ContentLost)가 하나씩 나옵니다

각주·미주 정의 안에서는 서식, <br>, chart·memo 주석만 읽습니다. 링크·그림·표는 같은 자리의 Markdown 링크·그림·표처럼 오류이고, 구역 표지도 오류입니다. chart·memo 주석을 건너뛰어 정의에 글이 남지 않아도 오류가 아닙니다. 각주는 남은 문단 그대로(빈 서식 문단도 그대로, 문단이 없으면 빈 문단 하나) 남고 CONTENT_LOST 가 나옵니다.

HTML 표 안의 글은 HTML 글로 한 번만 읽습니다. **굵게** 같은 Markdown 은 셀 안에서 글자 그대로 남습니다. 예외는 각주·미주 참조 하나입니다. styled 보기는 셀 글의 [ 를 &#91; 로 쓰므로, 셀 안의 날 [^1] 은 보기가 쓴 참조이고 문서 끝 정의와 이어집니다. &#91;^1] 은 글자 [^1] 입니다.

이미지

![대체 텍스트](images/photo.png)
  • 지원 포맷: PNG, JPEG, GIF, BMP, WMF, EMF (SVG는 지원하지 않습니다) — 확장자가 아니라 실제 바이트를 스니핑해 포맷을 확인합니다.
  • 경로(상대·절대 모두)는 정규화한 뒤 Markdown 파일이 있는 디렉터리 하위에 있는지 검사합니다. ../로 그 디렉터리를 벗어나는 경로는 거부되지만, 그 디렉터리 안을 가리키는 절대 경로는 허용됩니다 — 거부되는 것은 “절대 경로“가 아니라 “벗어나는 경로“입니다.
  • data: URI(base64)도 지원합니다 — 네트워크 접근 없이 로컬에서 바로 디코드됩니다. 기준 디렉터리가 없는 인라인 텍스트/stdin 입력에서는 data: URI만 임베드할 수 있습니다.
  • http(s) 원격 URL은 네트워크 접근을 금지하는 정책상 거부됩니다.
  • 실패한 참조(파일 없음·경로 탈출·원격 URL·미지 포맷 등)는 경고와 함께 이미지 run이 드롭됩니다 — 결과 문서에 깨진 참조가 남지 않습니다.
  • 파일 크기 상한은 50MB입니다.

구분선과 섹션 구분자

Markdown의 ---(frontmatter 블록 밖에서 단독으로 쓴 thematic break)는 리터럴 "---" 문단으로 변환됩니다 — 페이지나 섹션을 나누는 구분자가 아닙니다. HWPX 섹션(다른 페이지 설정 구역)을 나누려면 반드시 <!-- hwpforge:section --> 주석을 사용하세요 (앞의 섹션 마커 참고).

H1-H6 → 개요 1-6 자동 매핑

Markdown 헤딩은 한글의 개요 스타일로 자동 변환됩니다.

Markdown한글 스타일
# H1개요 1 (style ID 2)
## H2개요 2 (style ID 3)
### H3개요 3 (style ID 4)
#### H4개요 4 (style ID 5)
##### H5개요 5 (style ID 6)
###### H6개요 6 (style ID 7)
일반 문단본문 (style ID 0)

목록 → 한컴 글머리표·번호 문단

Markdown 목록은 한컴의 글머리표·번호·체크 문단으로 바뀝니다. 표지(-, 1., [x])는 글자로 남지 않고 문단 모양의 목록 설정이 됩니다. 한컴에서 문단을 고치면 기호와 번호가 그 설정대로 따라옵니다.

Markdown한컴 문단(기본 템플릿)
- 항목글머리표 문단. 수준 0·1·2 의 기호는 •·◦·▪, 그 뒤 수준은 이 셋을 되풀이
1. 항목번호 문단. 수준 0–5 는 1.·가.·1)·가)·(1)·(가), 수준 6·7 은 원문자 숫자·한글, 수준 8·9 는 1.
- [ ] 할 일·- [x] 끝난 일체크 문단(☐·☑). 번호 목록 안의 체크 항목(1. [x] …)도 체크 문단
  • 수준: 중첩 깊이가 수준입니다(0부터). 수준마다 왼쪽 여백이 20pt 씩 깊어지고, 첫 줄 내어쓰기는 없습니다(한컴이 둘째 줄을 기호 뒤 글이 시작하는 자리에 맞춥니다). 9 보다 깊은 목록은 수준 9 로 쓰고 LIST_LEVEL_CLAMPED 를 냅니다.
  • 번호 형식과 Markdown: 번호 형식은 한컴에서 보이는 모양입니다. HWPX 를 Markdown 으로 다시 쓰면 번호 형식과 상관없이 1. 표지로 나오고, 나란히 놓인 두 번호 목록을 가를 때만 1) 을 씁니다.
  • 항목 안의 블록: 항목의 둘째 문단, 항목 안의 표·코드 블록은 그 항목의 이어지는 문단(기호 없음, 왼쪽 여백은 항목 여백에 기호 폭 20pt 를 더한 값)입니다. 한컴에서 기호 폭은 번호 값과 상관없이 글자 크기의 2배로 고정해 쓰므로, 기본 글자 크기 10pt 에서는 항목 글과 이어지는 문단이 같은 자리에서 시작합니다. 글자 크기가 다르면 항목 글과 어긋날 수 있습니다. 기호 폭 고정은 그 수준의 숫자·한글·원문자 번호 하나에 ASCII 문자만 붙고 글자 크기의 2배 안에 드는 번호 형식에만 적용하고, 그 밖의 형식은 번호 값을 따릅니다. 표는 항목 글이 시작하는 자리에서 시작하고, 본문 표처럼 오른쪽 여백에서 끝나도록 열 폭을 그만큼 줄입니다. 항목 여백이 쪽 폭을 다 차지해 남는 폭이 없으면 열마다 최대 40mm 로 써서 오른쪽 여백을 넘을 수 있습니다. Markdown 표는 본문과 항목 안 모두 다음 줄과 붙어 보이지 않도록 아래에 10pt 를 비웁니다. 코드는 공백·탭·빈 줄을 그대로 두고, 마지막 줄 끝의 줄바꿈 하나만 뺍니다. 그래서 빈 줄 하나뿐인 코드 블록은 빈 코드 블록과 같은 문단이 됩니다. 글이 없는 항목(- 만 있는 줄, 표나 하위 목록으로 시작하는 항목)도 기호만 있는 빈 문단으로 남습니다.
  • 항목 안의 제목·구분선: 항목 밖의 제목·--- 문단이 됩니다(항목 머리는 남음). 문단마다 LIST_SEMANTICS_LOST 를 냅니다.
  • 번호 목록마다 다시 시작: 번호 목록 하나(같은 Start(List) 의 항목들)마다 번호 정의를 하나씩 씁니다. 본문 뒤의 두 번째 1. 목록, 같은 부모 아래 나란히 놓인 두 하위 목록(1. 다음 1))은 각각 1 부터 다시 셉니다. 한컴도 번호를 다시 시작할 때 새 번호 정의를 만듭니다. 한 문서는 번호 정의를 1024 번까지 복제합니다. 첫 번호 목록은 템플릿의 번호 정의가 Markdown 처럼 시작하면(번호 정의의 시작 0, 모든 수준의 시작 1. 기본 템플릿이 그렇습니다) 그 정의를 그대로 쓰므로, 1025 번째 목록까지 각자 셉니다. 그렇지 않은 템플릿은 첫 목록부터 복제하므로 1024 번째 목록까지입니다. 그 뒤의 목록은 템플릿의 번호 정의를 함께 써서 번호가 이어질 수 있고, NUMBERING_PRESENTATION_LOST 를 한 번 냅니다.
  • 시작 번호: 1 이 아닌 수로 시작하는 목록(3. 항목)은 1 부터 쓰고 LIST_START_NORMALIZED 를 냅니다(한컴이 시작 번호를 어느 값으로 보이는지 아직 확인하지 않았습니다). 체크 항목만 있는 목록은 번호를 쓰지 않으므로 경고가 없습니다.
  • 상위 수준 번호를 쓰는 서식: 템플릿의 번호 서식이 더 얕은 수준의 번호를 가리키면(^1.^2), 하위 목록은 자기 번호 정의 안의 그 수준을 세므로 바깥 목록의 번호가 보이지 않습니다. 그 정의에 NUMBERING_PRESENTATION_LOST 를 한 번 냅니다. 자기 수준만 쓰는 서식((^2))은 그대로 됩니다.
  • 목록 정의가 없는 템플릿: 템플릿에 그 종류의 목록 역할이 없으면(스타일 템플릿) 그 항목은 목록이 아닌 문단으로 글과 순서만 남고, 종류마다 LIST_DEFINITION_MISSING 을 한 번 냅니다.

반대로 HWPX 를 Markdown 으로 읽을 때(styled·lossy)는 한컴의 글머리표·번호·체크 문단을 -, 1., - [x] 항목으로 씁니다. 번호는 늘 1. 로 시작합니다(한컴이 계산한 번호를 다시 세지 않습니다). 나란히 놓인 서로 다른 번호 정의의 목록은 1. 와 1) 를 번갈아 써서 따로 읽히게 합니다. 항목의 코드 문단에 한컴에서 표·그림·컨트롤을 넣으면 그 문단은 코드 블록으로 쓸 수 없어 항목의 일반 이어지는 문단으로 쓰고, 코드의 공백 보존은 적용되지 않습니다. 한컴 문서에서 같은 번호 정의가 다른 블록 뒤에서 이어지면 Markdown 은 다시 1 부터 쓰므로 NUMBERING_PRESENTATION_LOST 를 냅니다. 표 칸·글상자·각주·캡션 안의 목록 문단은 그 보기가 글로 쓰므로 목록 의미가 빠지고, 문단마다 LIST_SEMANTICS_LOST 를 냅니다. lossy 보기가 원본 목록을 읽으려면 원본 스타일이 필요합니다. CLI 의 to-md, Python 의 to_md, MCP 의 hwpforge_to_md(styled 만)는 늘 원본 스타일로 읽습니다. Rust 에서 lossy 로 읽을 때는 MdEncoder::encode_lossy_with_styles 가 그 경로이고, 스타일을 받지 않는 encode_lossy 는 목록을 알지 못합니다.

lossy 보기는 본문 글자 1. 항목 을 escape 하지 않습니다(아래 “읽기 보기가 escape 하는 것” 절). 그래서 lossy Markdown 을 다시 convert 하면 그런 본문 문단이 번호 문단이 됩니다. 시작 번호가 1 이 아니면 LIST_START_NORMALIZED 가 그 사실을 알립니다.

MdEncoder — Core → Markdown

반대 방향(HWPX → Markdown) 변환도 지원합니다. 두 가지 모드가 있습니다.

#![allow(unused)]
fn main() {
use hwpforge::md::MdEncoder;
use hwpforge::hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let validated = result.document.validate().unwrap();

// Lossy 모드: 읽기 좋은 GFM (표, 이미지 등 일부 정보 손실)
let gfm = MdEncoder::encode_lossy(&validated).unwrap();

// Lossless 모드: YAML frontmatter + HTML-like 마크업 (보존 범위 확인용 기계 보기)
let lossless = MdEncoder::encode_lossless(&validated).unwrap();
}
모드특징용도
encode_lossy읽기 좋은 GFM사람이 읽는 문서 미리보기
encode_lossless아래 보존 범위 안에서 보존, 못 담으면 거부보존 범위 확인(기계용 보기)

Markdown으로 HWPX를 재생성할 때 원본 패키지의 서명·암호화 상태는 승계되지 않습니다.

Lossless 출력은 Markdown 변환의 입력이 아닙니다. 프론트매터에 늘 metadata.format: lossless 를 담고, 일반 Markdown 디코드(CLI·MCP 의 convert, Python convert_md, Rust MdDecoder::decode)는 이 표식을 보면 MD_DECODE_FAILED(Rust 는 MdError::UnsupportedStructure)로 거부합니다. 문서를 고쳐 다시 HWPX 로 만들려면 JSON 왕복(to-json → 편집 → from-json)을 사용하세요. JSON 은 이미지를 담지 않으므로, from-json --base 로 기준 HWPX 의 이미지를 물려받습니다.

전체 파이프라인 예제 (MD string → HWPX file)

use hwpforge::md::{MdDecoder, MdDocument};
use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};

fn markdown_to_hwpx(markdown: &str, output_path: &str) {
    // 1. Markdown 파싱 → Core DOM
    let MdDocument { document, .. } = MdDecoder::decode_with_default(markdown).unwrap();

    // 2. 문서 검증
    let validated = document.validate().unwrap();

    // 3. 한컴 기본 스타일 적용 후 HWPX 인코딩
    let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
    let image_store = Default::default();
    let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap();

    // 4. 파일 저장
    std::fs::write(output_path, &bytes).unwrap();
    println!("저장 완료: {output_path}");
}

fn main() {
    let md = r#"
---
title: AI 활용 정책 제안서
author: 정책팀
date: 2026-03-06
---

제안 배경

인공지능 기술의 급속한 발전에 대응하여 정책 수립이 필요합니다.

# 현황 분석

국내외 AI 활용 사례를 분석하였습니다.

# 정책 방향

단계적 도입과 윤리적 기준 마련을 제안합니다.
"#;

    markdown_to_hwpx(md, "proposal.hwpx");
}

HWPX → Markdown 변환 (RAG/LLM 활용)

HWPX 문서를 Markdown으로 변환하면 LLM이나 RAG(Retrieval-Augmented Generation) 시스템에서 직접 활용할 수 있습니다.

의존성 설정

Cargo.toml에 md 기능을 활성화합니다:

[dependencies]
hwpforge = { version = "0.20", features = ["md"] }

Lossy vs Lossless 모드 선택

기준Lossy (encode_lossy)Lossless (encode_lossless)
출력 형식표준 GFM MarkdownYAML frontmatter + HTML 마크업
가독성높음 (사람/LLM 모두)낮음 (기계 파싱용)
정보 손실스타일/레이아웃 일부 손실보존 범위 안에서 보존
RAG 추천추천 — 청크 분할에 적합쓰지 않음
LLM 추천추천 — 토큰 효율적보존 범위 확인 시(편집은 JSON 왕복)

Lossless 모드는 그림·도형·묶음의 개체 틀(원래 크기와 크기 고정)을 data-original-width-unit·data-original-height-unit·data-size-protect 속성으로, 표의 크기 고정을 data-size-protect 로 담고, Rust MdDecoder::decode_lossless 가 이를 되읽습니다(표에는 원래 크기가 없습니다). 이 속성들은 이전 버전의 디코더가 무시하므로, 이전 버전으로 되읽으면 개체 틀은 기본값이 됩니다.

Lossless 보존 범위

Lossless 모드는 표 칸·행의 제목 속성(아래 문법)과 아래 “보존하는 것“을 Rust MdDecoder::decode_lossless 가 그대로 되읽을 수 있게 쓰고, “거부하는 것“이 있으면 일부를 버리는 대신 문서 전체를 거부합니다(ENCODE_FAILED, Rust 는 MdError::UnsupportedStructure). 두 목록 밖의 값은 모두 거부 없이 빠집니다.

구분내용
보존하는 것구역의 쪽 크기·여백, 문단·run 구조와 글자, 문단 모양·글자 모양 번호(para_shape_id·char_shape_id — 문단 스타일 style_ref 는 아님), 표의 행·칸(병합·너비·배경·줄 나눔 방식)·행 높이·표 너비·크기 고정·칸 크기 고정·셀 영역, 표 캡션의 글자·위치(측)·전체 폭 여부·저장된 너비, 링크(글자 링크와 그림 링크), 각주 본문, 그림·도형의 개체 틀(원래 크기·크기 고정), 그림(본문·묶음 안 모두: 배치와 위치·바깥 여백, 크기, 자르기, 이미지 크기, 링크, 개체 번호, 그림 형식 이름 원문)과 본문 그림의 캡션(위치·간격·너비·전체 폭 여부·저장된 너비와 문단), 도형(글상자·선·타원·다각형·사각형·호·곡선·연결선, 본문·묶음 안 모두: 정의점, 크기, 배치와 위치·바깥 여백, 선 색·두께·종류, 채우기(단색·그러데이션·무늬·없음), 회전·뒤집기·화살표·문단 첫 글자 장식·둥근 모서리, 글자의 세로 정렬, 글상자 안쪽 여백, 안의 문단), 묶음 개체와 중첩 묶음
빠지는 것(예)문단의 쪽·단 나눔·개요 수준·style_ref·줄 배치 캐시, 탭 정보, 칸 여백·칸 세로 정렬, 표 캡션의 간격·너비와 글자가 아닌 내용, 구역의 단·쪽 번호 등 쪽 설정 밖의 값, 머리말·꼬리말·바탕쪽과 그 안의 개체, 각주·미주 번호
거부하는 것묶음 안의 수식·차트·글맵시, 도형의 캡션, 그림 채우기, 예약 비트가 켜진 도형 색·칸 배경색, 문단 없는 글상자·점 세 개 미만 다각형(어디에 있든), 32 겹을 넘는 중첩, 회전값 NaN·무한대, 묶음 안 그림의 캡션, 표 캡션 안의 그림·묶음·도형, 그림 캡션과 도형 글 안의 내용이 빈 문단·표·칸·각주, 그 밖에 이 형식이 표현하지 못하는 컨트롤
쓰지만 되읽지 못하는 것<endnote>·<dutmal>·<compose> — 이 요소가 든 Markdown 은 decode_lossless 가 오류를 냅니다
되읽기Rust API MdDecoder::decode_lossless 만 읽습니다. CLI·MCP 의 convert·Python convert_md 는 프론트매터의 metadata.format: lossless 표식을 보고 MD_DECODE_FAILED 로 거부합니다

<group>·<img>·<caption> 과 도형 요소(<textbox>·<line>·<ellipse>·<polygon>·<rect>·<arc>·<curve>·<connectline>)는 정해진 속성만 받습니다 — 모르는 속성이나 같은 속성이 두 번 나오면 디코드가 실패합니다. 속성 값 안의 제어 문자(탭·줄바꿈 등)는 &#9; 같은 문자 참조로 써서 그대로 되읽습니다.

표의 제목 속성은 <td data-header="true|false">와 <tr data-is-header="true|false">로 보존합니다. 값은 소문자 true 또는 false만 허용하며 잘못된 값·중복 속성은 오류입니다.

  • td의 data-header="true"·"false"는 칸의 명시값(Some)입니다. 생략하면 None으로 행 값을 상속합니다. 명시적 false를 생략하면 의미가 바뀔 수 있습니다.
  • tr의 data-is-header는 옛 문서·생성 코드의 상속 기준이자 파생된 제목행 편의값입니다. 생략은 false이고 출력도 false를 생략합니다. 모든 칸의 실효값이 참인 비어 있지 않은 선두 연속 행만 제목행입니다. 빈 물리 행은 rowspan으로 덮여 있어도 이 블록을 끝냅니다.
  • 검증 시 칸 실효값에서 행 값을 정규화합니다. 행 값이 바뀌면 그 행의 None 칸은 이전 실효값의 명시값으로 고정합니다. 따라서 encode_lossless → decode_lossless 는 검증된 문서의 None/Some을 보존하며, 검증 전의 모순된 행 플래그를 그대로 보존하는 계약은 아닙니다.
  • 두 속성을 모르는 이전 lossless 독자는 속성을 무시하므로 칸·행 제목 정보가 사라집니다. 일반 Markdown 독자는 HTML 사용자 정의 속성을 화면에 표시하지 않습니다. styled·lossy는 기존처럼 첫 물리 행을 GFM 머리 행으로 쓰며 칸별 제목값을 보존하지 않습니다.
  • PDF는 공용 제목행 규칙과 표의 repeat_header가 참일 때만 선두 블록을 반복합니다. 혼합 행의 일부 제목칸·비선두 제목칸은 보존되지만 반복 대상으로 승격되지 않습니다. 제목행 경계를 가로지르는 rowspan은 PDF에서 거부합니다. 혼합 제목칸의 한컴 반복 배치와 같다는 보장은 없습니다.

컨테이너(표·묶음·그림·캡션·도형·각주)는 32 겹까지 중첩할 수 있습니다. 더 깊은 문서는 인코드가, 더 깊은 Markdown 은 디코드가 오류로 거부합니다.

필드 경계는 본문 run 사이의 <field-start>·<field-end/>로 보존합니다. 시작·끝 ID, 종류, 이름, 플래그의 원문 문자열, 파라미터의 종류·순서·이름·값·공백 속성은 정확히 되읽습니다. 주석 문단은 시작 요소의 <field-annotation> 안에 담으며, 그 안의 문단·표에는 위의 투영 범위가 적용됩니다. None과 빈 주석 목록, 파라미터 그룹 이름 없음과 빈 이름은 구별합니다. 원문에 끝이 없는 시작은 data-unclosed="true"로 명시합니다(생략 또는 false는 일반 범위이며, 다른 표기는 거부합니다). 끝 경계를 만들지 않으며, Core 검증은 이를 경고로 허용합니다. 표시 없이 짝이 깨지거나 미종결 표시와 끝 경계가 함께 있으면 오류입니다. 미종결 범위의 시작부터 해당 독립 흐름 끝까지는 편집할 수 없습니다. 기존 접힌 Control::Field·Control::Memo에는 별도의 lossless 문법이 없습니다. lossy·styled는 경계를 표시하지 않고 일반 본문을 씁니다.

요소허용 속성부모·자식·빈 형식
<field-start>data-char-shape, data-id, data-kind, data-name, data-editable, data-dirty, data-z-order, data-field-id, data-meta-tag 필수; data-parameter-name, data-unclosed 선택부모 p. field-param 0개 이상 다음 field-annotation 0–1개. 자식 없으면 /> 또는 명시적 닫기
<field-end/>data-char-shape, data-begin-id, data-field-id 필수부모 p. 빈 요소만 허용
<field-param/>data-kind(String·Integer·Boolean), data-name, data-value 필수. data-xml-space는 String에만 필수, 나머지에는 금지부모 field-start. 빈 요소만 허용. 숫자·불리언 값도 원문 문자열로 운반
<field-annotation>없음부모 field-start. p 0개 이상. />도 허용

이 네 요소는 모르는 속성·중복 속성·잘못된 부모·자식·중복 주석을 거부합니다. 속성은 공통 escape_attr 규칙을 따릅니다. field-start는 깊이 한도에서 한 겹이며, 파라미터·주석 래퍼는 추가 깊이로 세지 않습니다. 복구 표시 없이 짝이 깨진 범위는 Core 검증에서 거부하므로 lossless 인코드 입력으로 사용할 수 없습니다. 표 캡션처럼 경계를 버리는 경로도 인코드가 거부합니다.

버전·도구 사이의 호환

이 형식은 보존 범위를 확인하는 기계용 보기이고, 되읽는 것은 Rust MdDecoder::decode_lossless 뿐입니다. 일반 Markdown 미리보기나 HTML 렌더러에서는 구조가 다르게 보일 수 있습니다.

이 버전이 쓴 것이전 버전(v0.16.10) 디코더일반 HTML 렌더러
캡션 없는 <img … />(배치·개체 번호·자르기 등 속성이 늘어남)읽지만 새 속성은 무시해 그 값을 잃음그림으로 보임
캡션 있는 <img …><caption>…</caption></img>오류<img> 는 자식을 가질 수 없어 캡션이 그림 밖으로 나옴. 표 칸 안이면 <caption> 이 칸을 닫아 바깥 표의 캡션으로 옮겨질 수 있음
<group>·<rect>·<arc>·<curve>·<connectline>, 그리고 <line>·<ellipse>·<polygon>오류(<line>·<ellipse>·<polygon> 은 이전 버전이 쓰기는 했으나 읽지 못하던 태그)모르는 요소로 다룸
<textbox> 의 새 속성(스타일·배치·세로 정렬·안쪽 여백)읽지만 새 속성은 무시해 그 값을 잃음—
<td data-line-wrap>무시해 기본 줄 나눔이 됨—
<field-start>·<field-end/>·<field-param/>·<field-annotation>오류(필드 문법 도입 전 디코더는 모르는 태그를 거부)모르는 요소로 다루며 주석 글자가 본문에 보일 수 있음
<field-start data-unclosed="true">필드 문법 도입 전에는 모르는 태그 오류; 미종결 속성 도입 전에는 허용 목록 밖 속성 오류속성을 무시하고 본문 글자를 표시
속성 값의 &#9; 같은 문자 참조원래 글자로 읽음원래 글자로 읽음

반대 방향으로, 이전 버전이 쓴 lossless Markdown 은 이 버전이 읽을 수 있는 범위에서 그대로 읽습니다 — 이전 출력의 속성은 모두 새 디코더가 받는 속성 목록에 들어 있습니다. 다만 <endnote>·<dutmal>·<compose> 는 여전히 읽지 못하고, 컨테이너가 32 겹을 넘게 중첩된 파일은 새 깊이 한도로 이제 오류가 납니다.

묶음 개체는 lossy·styled 모두 자식을 본문과 같은 방식으로 그 자리에 그립니다(그림은 링크, 글상자는 그 글). lossy 는 글상자·도형·각주 글자 안의 그림과 묶음을 그리지 않습니다(그 글은 평문). styled 는 쓴 그림 링크마다 그 그림 파일을 images 에 함께 내며, 메모(<!-- memo: … -->) 안의 그림은 링크 글자만 씁니다. 병합 칸(HTML 표) 안의 글상자 글은 HTML 서식(<strong> 등)으로 씁니다. 각주 안이나 메모 안의 각주는 (주: …) 로 본문에 넣습니다. 중첩 깊이는 보기마다 세는 법이 다릅니다. lossless 와 lossy 는 문서 구조의 깊이를 lossless 디코더와 같은 방식으로 셉니다 — 표·그림(캡션은 한 겹 더)·묶음·도형·각주·메모가 한 겹씩이고, 32 겹을 넘으면 오류를 냅니다. styled 는 그리면서 들어가는 깊이를 셉니다 — 표·캡션·도형 글·각주·메모만 한 겹씩이고 묶음과 그림 자체는 세지 않으므로, 같은 문서라도 lossless·lossy 가 거부하는 깊이를 styled 는 그릴 수 있습니다(예: 묶음 → 글상자 17번 반복은 구조 깊이 34 라 lossy 는 거부, styled 는 글상자 17 겹이라 그림). styled 는 32 겹을 넘는 자리에 오류 대신 (중첩 깊이 초과로 생략) 을 씁니다. lossy 는 표 안의 표가 8 단계를 넘으면 그 자리에 (중첩 표 생략) 을 씁니다. 생략한 자리는 경고로 알립니다 — Rust 는 MdOutput::warnings·encode_lossy_with_report 의 MdWarning::ContainerTooDeep, CLI·MCP·Python 은 경고 코드 CONTAINER_TOO_DEEP. styled 는 수식을 $…$ LaTeX 로 쓰되 Markdown 글에서는 <·> 를 \lt·\gt 로 바꾸고, LaTeX 에 $·]( 가 있거나 \ 로 끝나면 수식 스크립트를 일반 글자로 쓴 뒤 MdWarning::EquationAsText(경고 코드 EQUATION_AS_TEXT)로 알립니다.

styled 의 글자 서식과 문단 스타일

styled 는 글자의 굵게·기울임·취소선·밑줄·위 첨자·아래 첨자를 그 문단 스타일의 기본 글자 모양과 비교해, 스타일이 이미 주는 서식은 강조로 쓰지 않습니다. 굵은 개요 스타일의 제목은 # **제목** 이 아니라 # 제목 으로 씁니다. 비교는 글자 모양 번호가 아니라 이 여섯 속성의 값으로 합니다(글꼴·크기·색은 보지 않습니다). 스타일이 주지 않는 서식만 씁니다. 굵은 제목 안의 기울임은 # *제목* 입니다.

다음 경우에는 전처럼 글자의 서식을 그대로 씁니다.

  • 문단에 스타일이 없거나, 스타일의 기본 글자 모양을 알 수 없을 때. Rust 에서 직접 만든 StyleLookup 은 style_char_shape 를 구현해야 이 비교가 적용됩니다(기본 구현은 None).
  • 문단 안에 스타일 서식을 끈 글자가 있을 때(굵은 스타일 문단의 굵지 않은 글자). Markdown 에는 강조를 끄는 표기가 없으므로, 그 문단은 글자끼리의 대비를 지키도록 절대 서식으로 씁니다.

이 출력은 외형을 보존하는 계약이 아닙니다. 문단 스타일 자체는 Markdown 에 남지 않으므로, convert 하면 스타일이 주던 서식은 쓰는 템플릿의 것이 됩니다. 예를 들어 한컴의 굵지 않은 개요 스타일에 굵은 글자로 쓴 제목은 # **제목** 으로 나옵니다. 이것을 기본 템플릿(굵은 제목)으로 convert 한 뒤 다시 읽으면 # 제목 입니다. 같은 템플릿으로 만든 문서는 두 번째 읽기부터 결과가 같습니다. 스타일과 같은 서식을 원문에서 일부러 표시했는지(# **제목**)는 문서에 남지 않으므로 구별하지 않습니다. 코드 글꼴 문단을 코드 블록으로 쓰는 판정은 이 비교와 따로입니다.

읽기 보기(styled·lossy)가 escape 하는 것과 쓰는 HTML

문서 글자는 그 글자가 놓이는 자리(Markdown 글, GFM 표 칸, HTML 칸, 코드)에 맞게 한 번만 escape 해서 씁니다. 두 보기 모두 다음은 같습니다.

  • 줄 끝: Core 문자열을 Markdown으로 쓸 때 CRLF 쌍, 단독 CR, 단독 LF 는 각각 LF 하나로 정규화합니다. HWPX 본문을 읽을 때는 날 문자·문자 참조·CDATA의 CR과 LF를 각각 LF 하나로 읽습니다. 실제 to-md 의 styled·lossy 출력에서 본문 문단의 a\r\nb 는 a\n\nb 가 되며, Markdown 글에서는 빈 줄로 문단을 나눕니다. styled 제목은 한 줄이라 줄 끝이 공백이 됩니다. GFM 칸과 HTML 칸에서는 각 줄 끝을 <br> 로 씁니다. Core·patch·fill 값으로 직접 준 CRLF는 한 글 조각 안에서 줄바꿈 하나로 쓰는 기존 계약을 유지합니다.
  • 링크: 주소가 http://·https://·mailto:(대소문자 무관)이거나 비어 있고, 공백·제어 문자가 없을 때만 링크로 씁니다. 상대 경로, #앵커, 그 밖의 스킴은 표시 글자만 씁니다. 이전 버전은 이런 링크도 썼으므로 동작이 바뀐 부분입니다.
  • 링크 주소·그림 경로: 다시 읽었을 때 원래 값과 같도록 씁니다. \·(·)·<·>, 그리고 엔티티 앞의 & 는 앞에 \ 를 붙입니다. 공백이 있으면 <…> 형식으로 씁니다. 줄 끝은 주소 안에 둘 수 없어서 %0A·%0D 로 씁니다. 링크 글자와 그림 대체 글자 안의 줄 끝은 공백으로 씁니다.
  • 코드: 코드 블록과 코드 스팬의 울타리는 내용에 있는 가장 긴 백틱 연속보다 깁니다. 그래서 내용이 울타리를 닫지 못합니다.

styled 는 글자에 Markdown escape 를 적용합니다. *·_·`·[·]·~·\·# 앞에 \ 를 붙이고, <·> 는 &lt;·&gt;, 엔티티 앞의 & 는 \& 로 씁니다. 서식 태그(<u> 등) 안의 글자도 같은 방식으로 escape 합니다. Markdown 렌더러는 인라인 HTML 태그 안의 Markdown 도 해석하기 때문입니다. HTML 칸의 글자는 HTML escape 합니다.

수식은 $…$ LaTeX 로 씁니다. 이때 보장하는 범위는 실행 가능한 HTML 과 검사하지 않은 링크를 만들지 않는 것까지입니다. <·> 는 \lt·\gt 로 바꿉니다. LaTeX 에 $·]( 가 있거나 \ 로 끝나면 수식 스크립트를 글자로 쓰고 EQUATION_AS_TEXT 로 알립니다. $ 안의 다른 Markdown(*x* 등)은 수식 렌더러가 먼저 읽는다고 보고 글자로 바꾸지 않습니다. 중첩이 너무 깊어 변환하지 못한 수식도 글자로 쓰지만, 이 경우에는 경고를 내지 않습니다.

lossy 는 문서 글자를 거의 그대로 씁니다. CommonMark 가 글자가 아닌 마크업으로 읽는 자리에만 앞에 \ 를 붙입니다. 판정은 문단 전체를 한 번에, 인코더가 만든 마크업(링크·그림·표)까지 문맥으로 넣어서 합니다. 그래서 여러 run 에 걸친 시퀀스([a] 다음 run 의 (…)), 링크 양옆의 원문이 함께 만드는 태그(<img title=' · 링크 · ' onerror=…>), 원문과 마크업이 맞닿아 생기는 문법(원문 ! 바로 뒤의 링크, 원문 끝의 \ 바로 뒤의 링크)도 잡습니다.

escape 하는 것예
raw HTML 을 여는 < — 완전한 여는 태그(이름, 속성, >·/>), 닫는 태그, 주석, <?, 선언, CDATA, HTML 블록을 여는 태그 이름(div·table·script 등 뒤에 공백·>·줄 끝)<b>, </b>, <The Pulse>, <!-- -->, <div 가
자동 링크를 여는 <<https://…>, <a@b>
엔티티·문자 참조를 여는 &&amp;, &#60;
인라인 링크·그림 이름을 닫는 ](뒤에 ()[현재단계](기관)
링크 참조 정의를 여는 [ — 줄 머리, 인용문 >·목록 표지 뒤 포함, 라벨이 여러 줄이어도[a]: …, > [a]: …, - [a]: …
마크업 앞의 백틱(코드 스팬이 링크를 삼키지 않게), 줄 머리의 코드 울타리(```·~~~ 세 개 이상)—
링크 글자·그림 대체 글자의 \·[·]·`—

위에 해당하지 않는 글자는 그대로 둡니다. 예를 들어 <붙임>, <표 1>, <AI가 바꾼 것>, a < b, [참고], AT&T, *강조*, # 제목, 1. 항목 은 그대로 씁니다. 그래서 *·_·#·-·숫자 목록은 Markdown 서식으로 보일 수 있습니다. lossy 는 읽기 위한 보기라서 이 차이는 받아들였습니다. escape 하는 글자 바로 앞에 원래 있던 역슬래시는 두 배로 써서 글자로 남깁니다.

마지막으로 두 보기 모두 완성된 Markdown 을 다시 파싱해 검사합니다. 인코더가 쓰지 않는 마크업 — 아래 목록 밖의 HTML, 인코더가 만들지 않은 링크·그림, 링크 참조 정의 — 이 나오면, 그 최상위 문단을 모든 구두점을 escape 한 평문으로 다시 쓰고 MdWarning::MarkupWrittenAsText(경고 코드 MARKUP_WRITTEN_AS_TEXT)로 알립니다. 문단 하나로는 문제가 없는데 문단끼리 작용해 생긴 경우(다른 문단의 참조 정의 등)에는 모든 문단을 평문으로 씁니다. 위 규칙들이 제대로 동작하면 이 경고는 나오지 않습니다. 측정 코퍼스(한컴 HWPX·HWP5)에서도 0 건입니다.

두 보기가 직접 쓰는 HTML 은 아래 것뿐입니다. 이 밖의 HTML 은 문서 글자에서 생기지 않습니다(src/encoder/markup_safety_tests.rs 가 공격 문자열을 모든 자리에 넣고 출력을 파싱해 확인합니다).

HTML쓰는 곳
<br>표 칸 안 줄바꿈(GFM 칸·HTML 칸), HTML 칸 캡션
<table>·<tbody>·<tr>·<td colspan rowspan>styled 병합 칸·표 안 표
<strong>·<em>·<del>·<u>·<sup>·<sub>styled 서식
<a href>·<img src alt>styled HTML 칸 링크·그림(속성은 HTML escape, 줄 끝은 문자 참조)
<!-- hwpforge:section -->·<!-- chart -->·<!-- memo: … -->구역 경계·차트 자리·메모(메모 본문은 한 줄, 줄바꿈은 공백, - 는 \-)

styled 의 결과 MdOutput 에는 markdown·images·warnings 세 필드가 있습니다. #[non_exhaustive] 구조체라서 크레이트 밖에서는 구조체 리터럴로 만들 수 없고, MdEncoder::encode_styled 로만 만듭니다. 필드를 읽거나 let MdOutput { markdown, images, .. } = out; 처럼 .. 를 넣어 분해합니다.

RAG 시스템에서는 encode_lossy를 권장합니다. 표준 GFM으로 출력되어 청크 분할기(text splitter)와 호환성이 높고, 불필요한 마크업이 없어 토큰을 절약합니다.

완전한 HWPX → Markdown 예제 (에러 처리 포함)

use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;
use std::path::Path;

fn hwpx_to_markdown(input_path: &str) -> Result<String, Box<dyn std::error::Error>> {
    // 1. 파일 존재 여부 확인
    let path = Path::new(input_path);
    if !path.exists() {
        return Err(format!("파일을 찾을 수 없습니다: {}", input_path).into());
    }

    // 2. HWPX 디코딩
    let result = HwpxDecoder::decode_file(input_path)
        .map_err(|e| format!("HWPX 디코딩 실패: {e}"))?;

    // 3. 메타데이터 확인 (선택)
    let meta = result.document.metadata();
    if let Some(title) = &meta.title {
        eprintln!("문서 제목: {}", title);
    }

    // 4. Draft → Validated 상태 전이
    let validated = result.document.validate()
        .map_err(|e| format!("문서 검증 실패: {e}"))?;

    // 5. Markdown 변환 (RAG용 lossy 모드)
    let markdown = MdEncoder::encode_lossy(&validated)
        .map_err(|e| format!("Markdown 인코딩 실패: {e}"))?;

    Ok(markdown)
}

fn main() {
    match hwpx_to_markdown("document.hwpx") {
        Ok(md) => {
            std::fs::write("output.md", &md).expect("파일 저장 실패");
            println!("변환 완료: {} bytes", md.len());
        }
        Err(e) => eprintln!("오류: {e}"),
    }
}

대량 파일 변환

여러 HWPX 파일을 Markdown으로 일괄 변환합니다:

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;
use std::path::Path;

fn batch_convert(input_dir: &str, output_dir: &str) -> Result<usize, Box<dyn std::error::Error>> {
    std::fs::create_dir_all(output_dir)?;
    let mut count = 0;

    for entry in std::fs::read_dir(input_dir)? {
        let entry = entry?;
        let path = entry.path();

        if path.extension().is_some_and(|ext| ext == "hwpx") {
            let result = HwpxDecoder::decode_file(&path)?;
            let validated = result.document.validate()?;
            let markdown = MdEncoder::encode_lossy(&validated)?;

            let out_name = path.file_stem().unwrap().to_string_lossy();
            let out_path = Path::new(output_dir).join(format!("{}.md", out_name));
            std::fs::write(&out_path, &markdown)?;

            eprintln!("변환: {} → {}", path.display(), out_path.display());
            count += 1;
        }
    }

    Ok(count)
}
}

CLI로 변환

# Markdown → HWPX
hwpforge convert report.md -o report.hwpx

# HWPX → Markdown
hwpforge to-md report.hwpx -o report.md

# 변환 모드 선택 (기본값: styled)
hwpforge to-md report.hwpx -o report.md --mode lossy
hwpforge to-md report.hwpx -o report.md --mode lossless

# HWPX 구조 확인 후 JSON으로 추출 (Markdown 변환 대안)
hwpforge inspect document.hwpx --json
hwpforge to-json document.hwpx -o document.json

참고: CLI의 convert 명령은 Markdown → HWPX 방향만 지원합니다. HWPX → Markdown 변환은 hwpforge to-md 명령(모드 styled/lossy/lossless) 또는 Rust API(MdEncoder)를 사용하세요. lossless 출력은 convert 입력으로 쓸 수 없으므로, 왕복 편집에는 to-json/from-json 을 사용하세요.

스타일 템플릿 (YAML)

Blueprint 개념: 구조와 스타일 분리

HwpForge는 HTML+CSS와 동일한 철학으로 **구조(Core)**와 **스타일(Blueprint)**을 분리합니다.

Core (Document, Section, Paragraph, Run)
    = HTML — "무엇이 있는가"

Blueprint (Template, StyleRegistry, CharShape, ParaShape)
    = CSS  — "어떻게 보이는가"

Core의 문단과 런은 스타일 인덱스(ParaShapeIndex, CharShapeIndex)만 참조합니다. 실제 폰트 이름이나 크기는 Blueprint에 정의됩니다. 덕분에 동일한 문서 구조에 다른 템플릿을 적용해 전혀 다른 외관의 HWPX를 생성할 수 있습니다.

Template YAML 구조

meta:
  name: my-template
  version: "1.0"
  description: "커스텀 스타일 템플릿"

styles:
  body:
    font: "한컴바탕"
    size: 10pt
    line_spacing: 160%
    alignment: justify

  heading1:
    inherits: body        # body에서 상속
    font: "한컴고딕"
    size: 16pt
    bold: true

  heading2:
    inherits: heading1
    size: 14pt

상속 (Inheritance)

inherits 키로 다른 스타일을 상속받습니다. 상속 체인은 DFS로 해결되며, 자식 스타일의 값이 부모를 덮어씁니다. Option 필드(PartialCharShape, PartialParaShape)를 병합하는 two-type 패턴으로 구현됩니다.

글자 그림자 (shadow)

char_shape.shadow 는 종류만 적는 문자열이나, 종류·색·간격을 적는 맵으로 씁니다. 간격은 글자 크기 대비 % 로 −100 이상 100 이하, 색은 "#RRGGBB" 또는 색 없음 none 입니다.

# parent.yaml
meta:
  name: parent
styles:
  heading1:
    char_shape:
      font: 한컴바탕
      size: 16pt
      shadow:                 # 맵: 종류·색·간격
        kind: continuous
        color: '#123456'
        offset_x: -3
        offset_y: 4
  body:
    char_shape:
      font: 한컴바탕
      size: 10pt
      shadow: drop            # 문자열: 종류만 (drop · continuous · none)

# child.yaml
meta:
  name: child
  extends: parent
styles:
  heading1:
    char_shape:
      shadow: { color: '#00FF00' }   # 색만 바꿈 — 종류·간격은 parent 의 것

extends 로 이어진 템플릿 사이의 상속은 칸별입니다. 자식이 shadow: { color: '#00FF00' } 만 적으면 부모의 종류·간격은 그대로이고 색만 바뀝니다(위 예의 child heading1 = 연속 #00FF00 −3·4). color: none 은 색을 지우는 명시 값이고, 키를 적지 않으면 부모 값을 물려받습니다. 끝까지 정해지지 않은 칸은 한컴 새 문서의 값(종류 없음·#C0C0C0·10·10)이 됩니다 — 위 예의 body 는 비연속 #C0C0C0 10·10. color: null, 모르는 키, 범위 밖 간격은 오류입니다.

옛 템플릿의 shadow: drop 은 그대로 읽힙니다. 다만 색을 적지 않고 그림자를 켜면 0.17.0 부터 한컴 새 문서와 같은 #C0C0C0 으로 그려져, 이전(#B2B2B2)보다 밝게 보입니다. 이전 색이 필요하면 shadow: {kind: drop, color: '#B2B2B2'} 처럼 색을 적습니다.

Rust API 에서 결정값 CharShape.shadow 는 ShadowType 이 아니라 hwpforge_foundation::CharShadow(종류·색·간격), 부분값 PartialCharShape.shadow 는 Option<PartialCharShadow> 입니다(0.17.0 breaking).

다단 템플릿 상속의 우선순위

extends 체인은 root → parent → leaf 순서로 병합합니다. 같은 필드나 markdown_mapping 키를 여러 조상이 정의하면 가장 가까운 명시값이 이기며, leaf가 적은 값은 항상 우선합니다. root의 글자 크기가 12pt, parent가 20pt이고 leaf가 생략하면 결과는 20pt입니다.

이 동작은 먼 조상의 값이 먼저 채워지던 이전 다단 상속 결과를 교정합니다. 이전 결과가 필요하면 leaf에 크기와 mapping을 명시하세요. 스타일 entry도 root의 선언 순서부터 누적하므로 첫 entry를 쓰던 본문 폴백 결과가 달라질 수 있습니다. 종전 선택을 유지하려면 markdown_mapping.body를 명시하세요.

Markdown 목록 역할

Markdown 목록(Markdown에서 HWPX로의 “목록 → 한컴 글머리표·번호 문단” 절)은 markdown_mapping 의 목록 역할이 가리키는 스타일과 템플릿의 numberings·bullets 정의로 씁니다. 내장 default 템플릿(과 그것을 상속하는 gov_proposal)의 선언은 다음과 같습니다(글자·여백 외형은 줄였습니다).

styles:
  list_item:      # 글머리표 항목, 그리고 모든 목록의 공통 여백
    para_shape:
      indent: { left: 20pt }
      list: { kind: bullet, bullet_id: 1, level: 0 }
  numbered_item:  # 번호 항목
    para_shape:
      list: { kind: number, numbering_id: 2, level: 0 }
  check_item:     # 체크 항목
    para_shape:
      list: { kind: check_bullet, bullet_id: 11, level: 0, checked: false }

numberings:
  - id: 1         # 첫 번호 정의 = 제목(개요)용
    start: 0
    levels: [...]  # 수준 1–10
  - id: 2         # 번호 항목용: 수준 1–8 은 한컴 기본 형식, 수준 9·10 은 Digit '^9.'·'^:.'
    start: 0
    levels: [...]

bullets:          # id 1–10: 수준 0–9 의 기호(• ◦ ▪ 되풀이), id 11: ☐/☑
  - { id: 1, bullet_char: '•', use_image: false, para_head: { start: 0, level: 1, num_format: Digit, text: '', checkable: false } }
  # …
  - { id: 11, bullet_char: '☐', checked_char: '☑', use_image: false, para_head: { start: 0, level: 1, num_format: Digit, text: '', checkable: true } }

markdown_mapping:
  list_item: list_item
  numbered_item: numbered_item
  check_item: check_item
  bullet_levels: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
키뜻
list_item모든 목록의 공통 외형. 수준 n 의 왼쪽 여백은 이 스타일의 왼쪽 여백 + n × 한 단계(이 스타일의 왼쪽 여백, 없으면 20pt), 첫 줄 내어쓰기는 이 스타일의 값. 이 스타일에 글머리표 목록(kind: bullet)이 있으면 글머리표 항목도 이 스타일로 씁니다
numbered_item번호 항목. 번호 목록(kind: number)이 있어야 하고, 그 번호 정의는 첫 번호 정의(제목이 쓰는 개요)가 아니어야 하며, 수준 1–10 을 차례대로 모두 선언해야 합니다
check_item체크 항목. 체크 글머리표 목록(kind: check_bullet, checked_char 와 checkable: true 를 가진 정의)이 있어야 합니다
bullet_levels수준 0–9 의 글머리표 정의 id 10 개(체크 글머리표는 안 됨). 없으면 list_item 의 글머리표를 모든 수준에서 씁니다

내장 템플릿의 목록 스타일은 첫 줄 내어쓰기를 두지 않습니다. 한컴이 항목의 둘째 줄을 기호 뒤 글이 시작하는 자리에 맞추고 내어쓰기를 그 위에 더하므로, 음수를 주면 둘째 줄이 그만큼 글 시작보다 오른쪽으로 갑니다. 템플릿이 list_item 에 first_line 을 적으면 모든 목록 항목에 그 값을 그대로 씁니다.

numbered_item·check_item 은 이름을 적었거나 같은 이름의 스타일이 있을 때만 정해집니다. 다른 스타일로 대신하지 않으므로, 둘 다 없는 템플릿은 번호·체크 항목을 목록이 아닌 문단으로 쓰고 LIST_DEFINITION_MISSING 을 냅니다. 정의 id 는 YAML 의 숫자 그대로가 아니라, 상속을 합친 뒤 그 id 의 정의가 놓인 자리로 찾습니다.

다음 경우는 템플릿 오류(BlueprintError::StyleResolution·InvalidListReference·InvalidPlainBulletDefinition)로 거절합니다.

  • numbered_item 에 번호 목록이 없거나, 첫 번호 정의를 가리키거나, 그 번호 정의가 수준 1–10 을 차례대로 갖지 않을 때
  • check_item 에 체크 글머리표 목록이 없을 때
  • bullet_levels 가 10 개가 아니거나, 없는 id·체크 글머리표 id 를 담을 때
  • bullet_levels 가 있는데 list_item 에 글머리표 목록이 없을 때

마지막 규칙은 상속에도 적용됩니다. 자식 템플릿이 bullet_levels 를 적지 않으면 부모의 값을 물려받고(빈 배열로 끌 수 없습니다), 자식의 값은 배열 전체를 바꿉니다. 그래서 default 를 상속하면서 list_item 을 글머리표 목록이 없는 스타일로 바꾸면, 물려받은 bullet_levels 때문에 템플릿이 거절됩니다. 그 스타일에 list: { kind: bullet, … } 를 더하세요.

StyleRegistry: from_template() 사용법

#![allow(unused)]
fn main() {
use hwpforge_blueprint::template::Template;
use hwpforge_blueprint::registry::StyleRegistry;

let yaml = r#"
meta:
  name: custom
  version: "1.0"
styles:
  body:
    font: "나눔명조"
    size: 11pt
"#;

// YAML → Template → StyleRegistry
let template = Template::from_yaml(yaml).unwrap();
let registry = StyleRegistry::from_template(&template).unwrap();

// 인덱스 기반 접근 (브랜드 타입으로 혼용 방지)
let body_entry = registry.get_style("body").unwrap();
let char_shape = registry.char_shape(body_entry.char_shape_id).unwrap();
println!("폰트: {}", char_shape.font);       // "나눔명조"
println!("크기: {:?}", char_shape.size);     // HwpUnit
}

내장 템플릿: builtin_default()

별도 YAML 없이 즉시 사용 가능한 기본 템플릿입니다.

#![allow(unused)]
fn main() {
use hwpforge_blueprint::builtins::builtin_default;
use hwpforge_blueprint::registry::StyleRegistry;

let template = builtin_default().unwrap();
assert_eq!(template.meta.name, "default");

let registry = StyleRegistry::from_template(&template).unwrap();
let body = registry.get_style("body").unwrap();
let cs = registry.char_shape(body.char_shape_id).unwrap();
assert_eq!(cs.font, "한컴바탕");
}

HwpxRegistryBridge 변환: from_registry()

Blueprint의 StyleRegistry를 HWPX 인코더 경계에서 안전하게 쓰기 위한 bridge를 만듭니다. 이 bridge는 두 가지를 함께 맡습니다.

  • HwpxStyleStore 생성
  • registry-local CharShapeIndex / ParaShapeIndex를 store-local HWPX id로 rebinding
#![allow(unused)]
fn main() {
use hwpforge_blueprint::builtins::builtin_default;
use hwpforge_blueprint::registry::StyleRegistry;
use hwpforge_smithy_hwpx::HwpxRegistryBridge;

let template = builtin_default().unwrap();
let registry = StyleRegistry::from_template(&template).unwrap();

// Blueprint StyleRegistry → HWPX encode bridge
let bridge = HwpxRegistryBridge::from_registry(&registry).unwrap();
let style_store = bridge.style_store();
}

한컴 스타일셋: Classic / Modern / Latest

한글 프로그램은 버전에 따라 다른 기본 스타일 구성을 사용합니다.

스타일셋스타일 수설명
Classic18개한글 2014–2020
Modern22개기본값 (한글 2022 이후)
Latest23개한글 2025 이후

Modern은 개요 8/9/10을 스타일 ID 9-11에 삽입하므로 인덱스가 Classic과 다릅니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwpx::{HwpxStyleStore, HancomStyleSet};

// 기본값 (간단한 방법)
let modern = HwpxStyleStore::with_default_fonts("함초롬바탕");

// 특정 스타일셋 지정
// from_registry_with()로 커스텀 레지스트리 + 스타일셋 조합 가능
}

예제: 커스텀 스타일로 문서 생성

#![allow(unused)]
fn main() {
use hwpforge_blueprint::template::Template;
use hwpforge_blueprint::registry::StyleRegistry;
use hwpforge_smithy_hwpx::{HwpxEncoder, HwpxRegistryBridge};
use hwpforge_core::{Document, Section, Paragraph, PageSettings};
use hwpforge_core::run::Run;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

let yaml = r#"
meta:
  name: report
  version: "1.0"
styles:
  body:
    font: "맑은 고딕"
    size: 10pt
    line_spacing: 150%
  title:
    inherits: body
    font: "맑은 고딕"
    size: 20pt
    bold: true
    alignment: center
"#;

// 스타일 빌드
let template = Template::from_yaml(yaml).unwrap();
let registry = StyleRegistry::from_template(&template).unwrap();
let bridge = HwpxRegistryBridge::from_registry(&registry).unwrap();

// 문서 구성 (스타일 인덱스는 레지스트리에서 조회)
let mut doc = Document::new();
doc.add_section(Section::with_paragraphs(
    vec![
        // 제목 문단 (ParaShapeIndex 0 = title)
        Paragraph::with_runs(
            vec![Run::text("분기 보고서", CharShapeIndex::new(0))],
            ParaShapeIndex::new(0),
        ),
        // 본문 문단 (ParaShapeIndex 1 = body)
        Paragraph::with_runs(
            vec![Run::text("1분기 실적은 목표를 초과 달성했습니다.", CharShapeIndex::new(1))],
            ParaShapeIndex::new(1),
        ),
    ],
    PageSettings::a4(),
));

let rebound = bridge.rebind_draft_document(doc).unwrap();
let validated = rebound.validate().unwrap();
let image_store = Default::default();
let bytes = HwpxEncoder::encode(&validated, bridge.style_store(), &image_store).unwrap();
std::fs::write("report.hwpx", &bytes).unwrap();
}

차트 생성

HwpForge는 OOXML 차트 형식(xmlns:c)을 사용해 18종의 차트를 HWPX 문서에 삽입할 수 있습니다.

지원 차트 종류 (18종)

변형설명
Bar가로 막대 차트
Column세로 막대 차트
Bar3D / Column3D3D 막대/세로 막대
Line / Line3D꺾은선 / 3D 꺾은선
Pie / Pie3D원형 / 3D 원형
Doughnut도넛 차트
OfPie원형-of-원형 / 막대-of-원형
Area / Area3D영역 / 3D 영역
Scatter분산형 (XY)
Bubble버블 차트
Radar방사형 차트
Surface / Surface3D표면 / 3D 표면
Stock주식 차트 (HLC/OHLC/VHLC/VOHLC)

Control::Chart 생성 방법

차트는 Control::Chart 변형으로 표현됩니다. Run::control()로 런에 삽입하고, 그 런을 문단에 넣습니다.

#![allow(unused)]
fn main() {
use hwpforge_core::control::Control;
use hwpforge_core::chart::{ChartType, ChartData, ChartGrouping, LegendPosition};
use hwpforge_foundation::HwpUnit;

let chart = Control::Chart {
    chart_type: ChartType::Column,
    data: ChartData::category(
        &["1월", "2월", "3월", "4월"],
        &[("매출", &[1200.0, 1500.0, 1350.0, 1800.0])],
    ),
    title: Some("월별 매출".to_string()),
    legend: LegendPosition::Bottom,
    grouping: ChartGrouping::Clustered,
    width: HwpUnit::from_mm(120.0).unwrap(),
    height: HwpUnit::from_mm(80.0).unwrap(),
    bar_shape: None,
    explosion: None,
    of_pie_type: None,
    radar_style: None,
    wireframe: None,
    bubble_3d: None,
    scatter_style: None,
    show_markers: None,
    stock_variant: None,
};
}

Control::Chart에는 위 7개 외에 차트 종류별 옵션 필드 9개(bar_shape, explosion, of_pie_type, radar_style, wireframe, bubble_3d, scatter_style, show_markers, stock_variant)가 있습니다. 모두 Option이며 None이면 해당 차트의 기본 모양입니다. 제목·크기 등을 바꿀 필요가 없다면 기본값 생성자 Control::chart(chart_type, data)가 더 간단합니다(너비 약 114mm, 높이 약 66mm, 제목 없음, 범례 오른쪽, 그룹 방식 ChartGrouping::Clustered(기본값, 계열을 나란히 배치)).

ChartData: Category vs Xy 방식

Category 방식 (막대, 꺾은선, 원형, 영역, 방사형 등)

카테고리 레이블(X축)과 여러 시리즈로 구성됩니다. 대부분의 차트 종류에 사용합니다.

#![allow(unused)]
fn main() {
use hwpforge_core::chart::ChartData;

// 편의 생성자: cats 슬라이스 + (이름, 값 슬라이스) 튜플 배열
let data = ChartData::category(
    &["1분기", "2분기", "3분기", "4분기"],
    &[
        ("매출액", &[4200.0, 5100.0, 4800.0, 6200.0]),
        ("비용", &[3100.0, 3400.0, 3200.0, 3900.0]),
    ],
);
}

Xy 방식 (분산형, 버블)

X값과 Y값 쌍으로 구성됩니다. 두 변수 간의 관계를 나타낼 때 사용합니다.

#![allow(unused)]
fn main() {
use hwpforge_core::chart::ChartData;

// (이름, x값 슬라이스, y값 슬라이스) 튜플 배열
let data = ChartData::xy(&[
    ("데이터셋 A", &[1.0, 2.0, 3.0, 4.0], &[2.1, 3.9, 6.2, 7.8]),
    ("데이터셋 B", &[1.0, 2.0, 3.0, 4.0], &[1.5, 3.0, 5.0, 6.5]),
]);
}

ChartSeries, XySeries 구조

시리즈를 직접 구성할 때는 구조체를 사용합니다.

#![allow(unused)]
fn main() {
use hwpforge_core::chart::{ChartData, ChartSeries, XySeries};

// Category용 시리즈
let series = ChartSeries {
    name: "판매량".to_string(),
    values: vec![100.0, 150.0, 200.0],
};

let data = ChartData::Category {
    categories: vec!["A".to_string(), "B".to_string(), "C".to_string()],
    series: vec![series],
};

// XY용 시리즈
let xy_series = XySeries {
    name: "측정값".to_string(),
    x_values: vec![0.0, 1.0, 2.0],
    y_values: vec![0.0, 1.0, 4.0],
};
}

차트를 문단에 삽입하는 패턴

차트 Control을 Run::control()로 감싼 뒤, Paragraph::with_runs()에 포함시킵니다.

#![allow(unused)]
fn main() {
use hwpforge_core::control::Control;
use hwpforge_core::chart::{ChartType, ChartData};
use hwpforge_core::run::Run;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex};

let chart_control = Control::chart(
    ChartType::Column,
    ChartData::category(
        &["A", "B", "C"],
        &[("값", &[10.0, 20.0, 30.0])],
    ),
);

let para = Paragraph::with_runs(
    vec![Run::control(chart_control, CharShapeIndex::new(0))],
    ParaShapeIndex::new(0),
);
}

예제: 막대 차트 (Column)

#![allow(unused)]
fn main() {
use hwpforge_core::control::Control;
use hwpforge_core::chart::{ChartType, ChartData, ChartGrouping, LegendPosition};
use hwpforge_core::run::Run;
use hwpforge_core::paragraph::Paragraph;
use hwpforge_core::{Document, Section, PageSettings};
use hwpforge_smithy_hwpx::{HwpxEncoder, HwpxStyleStore};
use hwpforge_foundation::{CharShapeIndex, ParaShapeIndex, HwpUnit};

let data = ChartData::category(
    &["2022", "2023", "2024", "2025"],
    &[
        ("국내 매출", &[3200.0, 4100.0, 5300.0, 6800.0]),
        ("해외 매출", &[1100.0, 1800.0, 2700.0, 3900.0]),
    ],
);

let chart = Control::Chart {
    chart_type: ChartType::Column,
    data,
    title: Some("연도별 매출 현황 (단위: 백만원)".to_string()),
    legend: LegendPosition::Bottom,
    grouping: ChartGrouping::Clustered,
    width: HwpUnit::from_mm(140.0).unwrap(),
    height: HwpUnit::from_mm(90.0).unwrap(),
    bar_shape: None,
    explosion: None,
    of_pie_type: None,
    radar_style: None,
    wireframe: None,
    bubble_3d: None,
    scatter_style: None,
    show_markers: None,
    stock_variant: None,
};

let mut doc = Document::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::control(chart, CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

let validated = doc.validate().unwrap();
let bytes = HwpxEncoder::encode(
    &validated,
    &HwpxStyleStore::with_default_fonts("함초롬바탕"),
    &Default::default(),
).unwrap();
std::fs::write("bar_chart.hwpx", &bytes).unwrap();
}

예제: 원형 차트 (Pie)

#![allow(unused)]
fn main() {
use hwpforge_core::control::Control;
use hwpforge_core::chart::{ChartType, ChartData, ChartGrouping, LegendPosition};
use hwpforge_foundation::{HwpUnit};

// 원형 차트는 단일 시리즈 사용
let chart = Control::Chart {
    chart_type: ChartType::Pie,
    data: ChartData::category(
        &["서울", "경기", "부산", "기타"],
        &[("비율", &[38.5, 25.2, 12.8, 23.5])],
    ),
    title: Some("지역별 매출 비중".to_string()),
    legend: LegendPosition::Right,
    grouping: ChartGrouping::Standard, // Pie는 Standard 사용
    width: HwpUnit::from_mm(100.0).unwrap(),
    height: HwpUnit::from_mm(80.0).unwrap(),
    bar_shape: None,
    explosion: None,
    of_pie_type: None,
    radar_style: None,
    wireframe: None,
    bubble_3d: None,
    scatter_style: None,
    show_markers: None,
    stock_variant: None,
};
}

주의: 차트 XML은 ZIP에 포함되지만 content.hpf 매니페스트에는 등록하지 않습니다. 매니페스트에 등록하면 한글이 크래시합니다.

텍스트 추출 (Text Extraction)

HwpForge의 Core DOM을 활용하여 문서에서 텍스트를 추출하고, 문서 구조(섹션, 문단, 표, 각주 등)를 보존하는 방법을 설명합니다.

포맷 지원 현황: CLI·Python의 지원 읽기 연산은 HWPX(.hwpx)와 HWP5(.hwp) 입력을 받습니다. HWP5는 메모리에서 HWPX로 자동 변환하며 변환 경고를 보고합니다. 아래 Rust 예제는 HWPX·Markdown 경로를 사용하며, HWP5의 전용 디코더 예제는 레거시 파일 처리에 있습니다.

문서 구조 개요

HwpForge 문서는 다음과 같은 트리 구조를 가집니다:

Document
├── Metadata (title, author, created, ...)
├── Section 0
│   ├── PageSettings (용지 크기, 여백)
│   ├── headers / footers (Vec, 비어 있을 수 있음) / PageNumber (선택)
│   ├── Paragraph 0
│   │   ├── para_shape (문단 스타일 인덱스)
│   │   └── Run[]
│   │       ├── Run { content: Text("본문 텍스트"), char_shape }
│       ├── Run { content: InlineText(...), char_shape }   (탭 등 속성이 있는 텍스트)
│   │       ├── Run { content: Table(...), char_shape }
│   │       ├── Run { content: Image(...), char_shape }
│   │       └── Run { content: Control(Footnote/TextBox/...), char_shape }
│   ├── Paragraph 1
│   │   └── ...
│   └── ...
├── Section 1
│   └── ...
└── ...

RunContent는 #[non_exhaustive]라서 match에는 마지막에 _ => {} 팔이 필요합니다. 텍스트만 필요하다면 Text와 InlineText를 모두 처리하는 run.content.plain_text()(Option<Cow<str>>) 또는 문단 단위의 paragraph.text_content()를 쓰는 것이 안전합니다. RunContent::Text만 읽으면 InlineText 런의 텍스트가 조용히 빠집니다.

핵심 타입:

타입설명
RunContent::Text(String)일반 텍스트
RunContent::InlineText(InlineText)탭처럼 속성이 있는 텍스트 (plain_text()로 문자열화)
RunContent::Table(Box<Table>)인라인 표
RunContent::Image(Image)인라인 이미지
RunContent::Control(Box<Control>)컨트롤 (글상자, 하이퍼링크, 각주, 도형 등)

기본 텍스트 추출

가장 간단한 패턴: 모든 섹션의 모든 문단에서 텍스트만 추출합니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let doc = &result.document;

for section in doc.sections() {
    for paragraph in &section.paragraphs {
        // Text 와 InlineText 런의 텍스트를 이어 붙인 문자열
        println!("{}", paragraph.text_content());
    }
}
}

구조 보존 텍스트 추출

문서 구조(섹션, 문단, 표, 각주 등)를 보존하면서 텍스트를 추출합니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::core::run::RunContent;
use hwpforge::core::control::Control;
use hwpforge::core::paragraph::Paragraph;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let doc = &result.document;

// 메타데이터 출력
let meta = doc.metadata();
if let Some(title) = &meta.title {
    println!("=== {} ===", title);
}

for (sec_idx, section) in doc.sections().iter().enumerate() {
    println!("\n--- 섹션 {} ---", sec_idx + 1);

    // 머리글 텍스트 (적용 쪽 종류별로 여러 개일 수 있음)
    for header in &section.headers {
        print!("[머리글] ");
        extract_paragraphs(&header.paragraphs);
        println!();
    }

    // 본문 문단
    for paragraph in &section.paragraphs {
        extract_paragraph(paragraph, 0);
    }

    // 바닥글 텍스트
    for footer in &section.footers {
        print!("[바닥글] ");
        extract_paragraphs(&footer.paragraphs);
        println!();
    }
}

/// 단일 문단에서 텍스트 추출 (들여쓰기 레벨 지원)
fn extract_paragraph(para: &Paragraph, indent: usize) {
    let prefix = "  ".repeat(indent);
    print!("{}", prefix);

    for run in &para.runs {
        match &run.content {
            RunContent::Text(text) => print!("{}", text),
            RunContent::InlineText(inline) => print!("{}", inline.plain_text()),
            RunContent::Table(table) => {
                println!("\n{}[표 {}x{}]", prefix, table.row_count(), table.col_count());
                for (r, row) in table.rows.iter().enumerate() {
                    for (c, cell) in row.cells.iter().enumerate() {
                        print!("{}  [{},{}] ", prefix, r, c);
                        extract_paragraphs(&cell.paragraphs);
                    }
                }
            }
            RunContent::Image(img) => {
                print!("[이미지: {}]", img.path);
            }
            RunContent::Control(ctrl) => {
                extract_control(ctrl);
            }
            // RunContent 는 #[non_exhaustive] — 이후 추가될 변형은 건너뜀
            _ => {}
        }
    }
    println!();
}

/// 컨트롤 요소에서 텍스트 추출
fn extract_control(ctrl: &Control) {
    match ctrl {
        Control::TextBox { paragraphs, .. } => {
            print!("[글상자] ");
            extract_paragraphs(paragraphs);
        }
        Control::Hyperlink { text, url, .. } => {
            print!("[링크: {} → {}]", text, url);
        }
        Control::Footnote { paragraphs, .. } => {
            print!("[각주: ");
            extract_paragraphs(paragraphs);
            print!("]");
        }
        Control::Endnote { paragraphs, .. } => {
            print!("[미주: ");
            extract_paragraphs(paragraphs);
            print!("]");
        }
        // 도형 (Line, Ellipse, Polygon 등)은 텍스트 없음 — 건너뜀
        _ => {}
    }
}

/// 문단 목록에서 텍스트 추출 (헬퍼)
fn extract_paragraphs(paragraphs: &[Paragraph]) {
    for para in paragraphs {
        print!("{}", para.text_content());
    }
}
}

콘텐츠 요약 (빠른 분석)

문서의 구조적 특성을 빠르게 파악하려면 content_counts()를 사용합니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();

for (i, section) in result.document.sections().iter().enumerate() {
    let counts = section.content_counts();
    println!(
        "섹션 {}: {} 문단, {} 표, {} 이미지, {} 차트",
        i, section.paragraphs.len(), counts.tables, counts.images, counts.charts
    );
    println!(
        "  머리글={}개 바닥글={}개 쪽번호={}",
        section.headers.len(),
        section.footers.len(),
        section.page_number.is_some()
    );
}
}

CLI로 텍스트 추출

inspect — 구조 요약

hwpforge inspect document.hwpx --json

to-json — 전체 DOM을 JSON으로 내보내기

JSON 출력에는 모든 텍스트와 구조 정보가 포함됩니다.

hwpforge to-json document.hwpx -o doc.json

Markdown 변환 — 읽기 쉬운 텍스트 추출

Rust API를 통해 HWPX를 Markdown으로 변환하면 구조를 보존한 텍스트를 얻을 수 있습니다.

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let validated = result.document.validate().unwrap();

// 사람이 읽기 좋은 GFM (헤딩, 표, 목록 구조 보존)
let markdown = MdEncoder::encode_lossy(&validated).unwrap();
println!("{}", markdown);
}

이 방법은 문서 구조(헤딩 계층, 표, 목록, 인용 등)를 Markdown 형식으로 자연스럽게 보존합니다.

레거시 HWP5 파일 처리

CLI에서는 hwpforge read legacy.hwp --section 0, hwpforge to-md legacy.hwp -o extracted처럼 HWP5를 직접 전달합니다. Python에서도 Document.open("legacy.hwp").read(section=0)으로 읽습니다. 자동 변환 경고와 보류 연산은 입력 정책을 참고합니다.

현재 선택지는 이렇습니다.

  1. CLI·Python 자동 변환: outline, read, to-md, to-json 등 지원 연산에 HWP5를 직접 전달합니다
  2. 전용 crate 사용: hwpforge-smithy-hwp5의 Hwp5Decoder
  3. HWPX로 재출력 후 기존 guide 재사용: 변환 결과를 HWPX guide와 같은 방식으로 처리

전용 crate 경로 예시는 다음과 같습니다.

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwp5::Hwp5Decoder;

let result = Hwp5Decoder::decode_file("legacy.hwp").unwrap();
let doc = &result.document;

for section in doc.sections() {
    for paragraph in &section.paragraphs {
        println!("{}", paragraph.text_content());
    }
}
}

주의:

  • HWP5 경로는 warning-first가 기본입니다.
  • visual parity나 layout fidelity는 HWPX path보다 더 까다롭습니다.
  • Rust의 hwpforge::ops와 MCP는 HWP5를 자동 변환하지 않습니다. 전용 디코더를 사용하거나 명시적으로 변환한 HWPX를 전달합니다.

HWP5와 HWPX: 이중 포맷 파이프라인

HwpForge는 한국의 두 가지 주요 문서 포맷 — 바이너리 OLE 기반 HWP5와 XML 기반 HWPX — 을 하나의 통합 파이프라인으로 처리할 수 있도록 설계되었습니다.

포맷 비교

특성HWP5 (.hwp)HWPX (.hwpx)
컨테이너OLE2/CFB (Compound File Binary)ZIP
내부 데이터바이너리 레코드 스트림XML 파일 (KS X 6101 OWPML)
표준한컴 독자 포맷 (공개 스펙)국가 표준 KS X 6101
역사1990년대~현재 (레거시)2014년~ (현대)
파일 시그니처D0 CF 11 E0 A1 B1 1A E1 (OLE)50 4B 03 04 (ZIP/PK)
스트림 구조FileHeader, DocInfo, BodyText/Section0 등mimetype, Contents/header.xml, Contents/section0.xml 등
압축zlib (스트림 단위)ZIP deflate (파일 단위)
암호화지원 (스트림 암호화)지원 (ZIP 암호화)
한글 호환성한글 97~최신한글 2014~최신

Core DOM: 포맷 독립 중간 표현 (IR)

HwpForge의 핵심 설계 원칙은 Core DOM이 포맷에 독립적이라는 것입니다. Document<Draft>는 HWP5든 HWPX든 Markdown이든 동일한 구조체로 표현됩니다.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  HWP5 파일  │     │  HWPX 파일  │     │  Markdown   │
│ (OLE/CFB)   │     │ (ZIP/XML)   │     │ (GFM+YAML)  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │ decode            │ decode            │ decode
       ▼                   ▼                   ▼
┌──────────────────────────────────────────────────────┐
│              Document<Draft>  (Core DOM)              │
│  ┌──────────────────────────────────────────────┐    │
│  │ Sections → Paragraphs → Runs → Text/Control  │    │
│  │ + Metadata (title, author, created, ...)      │    │
│  │ + Tables, Images, Shapes, Charts, ...         │    │
│  └──────────────────────────────────────────────┘    │
│              포맷 독립 중간 표현 (IR)                  │
└──────────┬───────────────┬───────────────┬───────────┘
           │ encode        │ encode        │ encode
           ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ HWP5     │    │ HWPX     │    │ Markdown │
    │ 미지원   │    │ ✅ 구현   │    │ ✅ 구현   │
    └──────────┘    └──────────┘    └──────────┘

이 설계 덕분에:

  • 하나의 문서 모델로 모든 포맷을 처리합니다
  • 포맷 간 변환이 Core DOM을 경유하여 자연스럽게 이루어집니다
  • 새 포맷 추가 시 기존 코드 수정 없이 Smithy 크레이트만 추가하면 됩니다
  • 비즈니스 로직은 Core DOM에만 의존하므로 포맷 변경에 영향을 받지 않습니다

포맷 감지

다음은 매직 바이트로 후보 형식을 분류하는 단순 예제입니다. CLI·Python의 자동 입력 변환은 확장자를 사용하지 않으며, CFB 시그니처가 있어도 정상 ZIP으로 열리면 HWPX로 처리합니다. 이 예제는 그 입력 판별 계약을 대체하지 않습니다.

#![allow(unused)]
fn main() {
/// 파일 포맷 감지
enum DocumentFormat {
    Hwp5,     // OLE2/CFB 바이너리
    Hwpx,     // ZIP + XML
    Markdown, // 텍스트
    Unknown,
}

fn detect_format(bytes: &[u8]) -> DocumentFormat {
    if bytes.len() < 4 {
        return DocumentFormat::Unknown;
    }

    // OLE2 Compound File Binary: D0 CF 11 E0
    if bytes.starts_with(&[0xD0, 0xCF, 0x11, 0xE0]) {
        return DocumentFormat::Hwp5;
    }

    // ZIP (PK\x03\x04)
    if bytes.starts_with(&[0x50, 0x4B, 0x03, 0x04]) {
        return DocumentFormat::Hwpx;
    }

    // UTF-8 텍스트로 시작하면 Markdown 후보
    if std::str::from_utf8(bytes).is_ok() {
        return DocumentFormat::Markdown;
    }

    DocumentFormat::Unknown
}
}

포맷 독립 문서 처리

Core DOM을 활용하면 입력 포맷에 관계없이 동일한 코드로 문서를 처리할 수 있습니다.

현재 지원되는 파이프라인

#![allow(unused)]
fn main() {
use hwpforge::hwpx::{HwpxDecoder, HwpxEncoder, HwpxRegistryBridge};
use hwpforge::md::{MdDecoder, MdDocument, MdEncoder};
use hwpforge::core::{Document, Draft, ImageStore};

// === 1. HWPX → Core DOM ===
let hwpx_result = HwpxDecoder::decode_file("input.hwpx").unwrap();
let doc_from_hwpx: Document<Draft> = hwpx_result.document;

// === 2. Markdown → Core DOM ===
let markdown = "# 제목\n\n본문 내용입니다.";
let MdDocument { document: doc_from_md, style_registry, .. } =
    MdDecoder::decode_with_default(markdown).unwrap();

// === 3. 포맷 독립 처리 (어느 소스에서 왔든 동일) ===
fn process_document(doc: &Document<Draft>) {
    // 메타데이터 접근
    let meta = doc.metadata();
    println!("제목: {:?}", meta.title);
    println!("작성자: {:?}", meta.author);

    // 섹션/문단 순회
    for section in doc.sections() {
        println!("문단 수: {}", section.paragraphs.len());
        let counts = section.content_counts();
        println!("표: {}, 이미지: {}", counts.tables, counts.images);
    }
}

process_document(&doc_from_hwpx);
process_document(&doc_from_md);

// === 4. Core DOM → 다른 포맷으로 출력 ===
// HWPX로 저장
let bridge = HwpxRegistryBridge::from_registry(&style_registry).unwrap();
let rebound = bridge.rebind_draft_document(doc_from_md).unwrap();
let validated = rebound.validate().unwrap();
let bytes = HwpxEncoder::encode(&validated, bridge.style_store(), &ImageStore::new()).unwrap();
std::fs::write("output.hwpx", &bytes).unwrap();

// Markdown으로 저장
let markdown_out = MdEncoder::encode_lossy(&validated).unwrap();
std::fs::write("output.md", &markdown_out).unwrap();
}

HWP5 입력 경로

#![allow(unused)]
fn main() {
use hwpforge_smithy_hwp5::Hwp5Decoder;
use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};
use hwpforge::core::{Document, Draft, ImageStore};

let hwp5_result = Hwp5Decoder::decode_file("legacy.hwp").unwrap();
let doc: Document<Draft> = hwp5_result.document;

// Core DOM을 경유하여 HWP5 → HWPX 변환
let validated = doc.validate().unwrap();
let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
let bytes = HwpxEncoder::encode(&validated, &style_store, &ImageStore::new()).unwrap();
std::fs::write("converted.hwpx", &bytes).unwrap();
}

CLI만 필요하다면 전용 명령도 이미 있습니다.

hwpforge convert-hwp5 legacy.hwp -o converted.hwpx
hwpforge audit-hwp5 legacy.hwp converted.hwpx
hwpforge census-hwp5 legacy.hwp --json

CLI에서 포맷 처리

CLI(hwpforge)는 변환·검사·편집·검증용 23개 명령을 제공합니다. 전체 목록은 hwpforge --help로 확인하세요. 이 장에서 다루는 포맷 변환 명령은 다음과 같습니다.

# Markdown → HWPX 변환
hwpforge convert report.md -o report.hwpx

# HWPX 문서 검사 (메타데이터 포함)
hwpforge inspect report.hwpx --json

# HWPX → JSON → 편집 → HWPX 라운드트립
hwpforge to-json report.hwpx -o report.json
# (AI 에이전트가 JSON 편집)
hwpforge from-json report.json --base report.hwpx -o updated.hwpx

# HWPX → Markdown (읽기용)
hwpforge to-md report.hwpx

# HWPX/HWP5 → PDF
hwpforge to-pdf report.hwpx -o report.pdf

from-json --base는 원본 이미지와 미편집 문단의 줄 캐시를 보존합니다. base가 편집 가능 검사를 통과하고 캐시를 제외한 Core 문서 전체와 스타일·이미지 바이트가 모두 원본과 같으면 원본 ZIP을 바이트 그대로 반환합니다. Core에 표현되지 않는 내용도 함께 유지하며, 원본 캐시의 유효성을 새로 인증하거나 수리하는 동작은 아닙니다. 실제 편집으로 문서를 재생성할 때에는 다음의 지문·흐름 검증을 적용합니다. Core의 문단 내용·참조 스타일·쪽/컨테이너 설정이 바뀌면 해당 문단과 같은 흐름의 후속 문단, 이를 담는 host 사슬의 캐시를 무효화합니다. 스타일은 명시적 ID로 해석하며 미해결·중복 참조는 보존하지 않습니다. 각주·미주·개요/목록·캡션 자동 번호가 있는 문서의 편집과 시작 번호 변경은 뒤 구역까지 보수적으로 무효화합니다. 쪽 번호·전체 쪽 수·상호참조가 있으면 앞 구역도 영향받을 수 있어 문서 전체를 무효화합니다. 떠 있는 개체가 있는 구역의 편집은 앞 문단에 미치는 영향을 계산할 수 없으므로 구역 전체를 무효화합니다. 배치가 생략된 표도 떠 있는 개체입니다. 문단 추가·삭제 시에는 영향받은 목록에서 동일한 앞부분만 대응시키며, 재배열된 문단을 텍스트로 찾아 다시 연결하지 않습니다. JSON의 layout_cache를 직접 수정하거나 삭제해도 그 값을 신뢰하지 않고 base 캐시를 사용합니다. 대응 불가·의도적 무효화·좌표 검증 실패는 각각 경고로 보고합니다. --base가 없으면 기존처럼 캐시를 생략하고 경고합니다.

HWPX → Markdown은 Rust API(MdEncoder::encode_lossy(&validated))로도 할 수 있습니다.

크레이트 역할 분담

크레이트역할포맷 의존성
hwpforge-foundation원시 타입 (HwpUnit, Color, Index)없음
hwpforge-core포맷 독립 문서 모델 (IR)없음
hwpforge-blueprintYAML 스타일 템플릿없음
hwpforge-smithy-hwpxHWPX ↔ Core 코덱HWPX (ZIP+XML)
hwpforge-smithy-hwp5HWP5 decode/projectionHWP5 (OLE/CFB)
hwpforge-smithy-mdMarkdown ↔ Core 코덱Markdown (텍스트)
hwpforge-smithy-pdfPDF 렌더러 (쓰기 전용, 코덱 아님)PDF (출력만)
hwpforge-convertHWP5 → HWPX 변환 오케스트레이터 + audit helpers + PDF 렌더 연산HWP5 + HWPX + PDF (smithy 경유)
hwpforge-bindings-cli / -mcp / -pyCLI / MCP / Python 진입점 (공유 연산 계층 hwpforge::ops 호출)직접 의존: CLI는 smithy 4종, MCP는 smithy-hwpx·smithy-md, Python은 smithy-pdf와 convert

핵심 원칙: Core 이하 계층은 어떤 파일 포맷도 모릅니다. 특정 포맷을 이해하는 것은 Smithy 계층이고(바인딩 크레이트는 그 Smithy에 직접 의존하기도 합니다), convert는 두 Smithy를 엮어 포맷 간 변환을 지휘합니다(자체 포맷 파싱 없음).

HWP5 포맷 구조 (참고)

HWP5 파일은 OLE2 Compound File Binary (CFB) 컨테이너 안에 바이너리 레코드 스트림을 저장합니다.

HWP5 파일 (OLE2 CFB)
├── FileHeader          — 파일 인식 정보, 버전, 플래그
├── DocInfo             — 문서 설정 (스타일, 폰트, 탭, 번호)
├── BodyText/
│   ├── Section0        — 첫 번째 섹션 (바이너리 레코드)
│   ├── Section1        — 두 번째 섹션
│   └── ...
├── BinData/            — 이미지 등 바이너리 데이터
├── DocOptions/         — 추가 옵션
├── Scripts/            — 매크로 스크립트
└── PrvText             — 미리보기 텍스트

각 섹션은 Tag-Length-Value (TLV) 구조의 레코드 체인으로 구성됩니다:

레코드 = TagID (10bit) + Level (10bit) + Size (12bit) + Data (Size bytes)

주의: HWP5의 TagID에는 +16 오프셋이 있습니다. PARA_HEADER = 0x42 (66), 공식 스펙의 0x32 (50)가 아닙니다.

현재 지원 상태

기능HWPXHWP5Markdown
읽기 (Decode)✅ 완전 지원🟡 CLI·Python 자동 변환 / 전용 crate✅ 완전 지원
쓰기 (Encode)✅ 완전 지원—✅ 완전 지원
메타데이터 추출✅ Core DOM🟡 inspect/census summary✅ YAML Frontmatter
이미지 추출✅ ImageStore🟡 decode/projection path—
스타일 보존✅ HwpxStyleStore🟡 warning-first projection + HWPX re-emission✅ StyleRegistry
JSON 라운드트립✅ to-json/from-json——

CLI·Python의 지원 읽기·편집 연산은 HWP5를 HWPX로 자동 변환합니다. 편집 결과는 .hwpx이며 .hwp 저장은 지원하지 않습니다. 의미 손실은 기본 거부하며 CLI --accept-conversion-loss 또는 Python accept_conversion_loss=True로 변환 손실만 허용합니다. MCP와 Rust의 hwpforge::ops는 자동 변환하지 않습니다. 대상 연산과 보류 경로는 CLI 입력 정책을 참고합니다.

대규모 HWP 아카이브 마이그레이션

레거시 HWP/HWPX 문서 아카이브를 검색 가능한 Markdown으로 마이그레이션하는 전략을 설명합니다.

마이그레이션 파이프라인 개요

┌────────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│ 1. 스캔        │ ──▶ │ 2. 분류      │ ──▶ │ 3. 변환     │ ──▶ │ 4. 검증      │
│ 파일 목록 수집 │     │ 포맷 감지    │     │ Core → MD   │     │ 무결성 확인  │
│                │     │ HWP5/HWPX    │     │ lossy 모드  │     │ 결과 기록    │
└────────────────┘     └──────────────┘     └─────────────┘     └──────────────┘

1단계: 파일 스캔 및 포맷 분류

파일 확장자와 매직 바이트로 포맷을 감지합니다.

이 장의 예제는 디렉터리 순회에 walkdir 크레이트를 씁니다. 따라 하려면 cargo add walkdir로 의존성을 추가하세요.

#![allow(unused)]
fn main() {
use std::path::{Path, PathBuf};

#[derive(Debug)]
enum DocFormat {
    Hwpx,         // ZIP + XML (PK 시그니처)
    Hwp5,         // OLE2/CFB (D0 CF 시그니처)
    Unknown(String),
}

#[derive(Debug)]
struct ScanResult {
    path: PathBuf,
    format: DocFormat,
    size_bytes: u64,
}

fn scan_archive(dir: &Path) -> Vec<ScanResult> {
    let mut results = Vec::new();

    let walker = walkdir::WalkDir::new(dir)
        .into_iter()
        .filter_map(|e| e.ok());

    for entry in walker {
        let path = entry.path();
        let ext = path.extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase();

        if ext != "hwp" && ext != "hwpx" {
            continue;
        }

        let size_bytes = entry.metadata().map(|m| m.len()).unwrap_or(0);
        let format = detect_format(path);

        results.push(ScanResult {
            path: path.to_path_buf(),
            format,
            size_bytes,
        });
    }

    results
}

fn detect_format(path: &Path) -> DocFormat {
    let Ok(bytes) = std::fs::read(path) else {
        return DocFormat::Unknown("읽기 실패".into());
    };

    if bytes.len() < 4 {
        return DocFormat::Unknown("파일이 너무 작음".into());
    }

    // ZIP (HWPX): PK\x03\x04
    if bytes.starts_with(&[0x50, 0x4B, 0x03, 0x04]) {
        return DocFormat::Hwpx;
    }

    // OLE2/CFB (HWP5): D0 CF 11 E0
    if bytes.starts_with(&[0xD0, 0xCF, 0x11, 0xE0]) {
        return DocFormat::Hwp5;
    }

    DocFormat::Unknown(format!("알 수 없는 시그니처: {:02X} {:02X}", bytes[0], bytes[1]))
}
}

2단계: 변환 (HWPX 중심 + HWP5 별도 경로)

이 배치 예제는 HWPX를 중심으로 HWP5를 별도 큐에 분류합니다. CLI·Python의 지원 읽기·편집 연산은 HWP5를 자동 변환할 수 있으므로, 별도 큐는 제품의 입력 제한이 아닌 예제의 운영 선택입니다. 대상 명령과 손실 정책은 CLI 입력 정책을 참고합니다.

HWPX 파일 변환

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;
use std::path::Path;

#[derive(Debug)]
struct ConvertResult {
    source: String,
    status: ConvertStatus,
    markdown_len: usize,
    title: Option<String>,
}

#[derive(Debug)]
enum ConvertStatus {
    Success,
    DecodeError(String),
    ValidationError(String),
    EncodeError(String),
}

fn convert_hwpx(input: &Path) -> ConvertResult {
    let source = input.display().to_string();

    // 1. 디코딩 (손상 파일 처리)
    let result = match HwpxDecoder::decode_file(input) {
        Ok(r) => r,
        Err(e) => {
            return ConvertResult {
                source,
                status: ConvertStatus::DecodeError(e.to_string()),
                markdown_len: 0,
                title: None,
            };
        }
    };

    let title = result.document.metadata().title.clone();

    // 2. 검증
    let validated = match result.document.validate() {
        Ok(v) => v,
        Err(e) => {
            return ConvertResult {
                source,
                status: ConvertStatus::ValidationError(e.to_string()),
                markdown_len: 0,
                title,
            };
        }
    };

    // 3. Markdown 변환 (RAG/검색용 lossy 모드)
    match MdEncoder::encode_lossy(&validated) {
        Ok(md) => ConvertResult {
            source,
            status: ConvertStatus::Success,
            markdown_len: md.len(),
            title,
        },
        Err(e) => ConvertResult {
            source,
            status: ConvertStatus::EncodeError(e.to_string()),
            markdown_len: 0,
            title,
        },
    }
}
}

HWP5 파일 처리

레거시 HWP5(.hwp) 파일은 CLI·Python의 지원 연산에 직접 전달할 수 있습니다. 편집 출력은 .hwpx이며 .hwp 저장은 지원하지 않습니다. 아래 배치 예제는 변환 경고를 따로 검토하도록 HWP5 큐를 분리합니다.

전략설명자동화
HwpForge CLI지원 읽기·편집의 자동 변환, convert-hwp5·audit-hwp5·census-hwp5의 명시적 변환·점검완전 자동
전용 cratehwpforge-smithy-hwp5로 HWP5 decode 후 Core/HWPX 경로 재사용자동
별도 분류HWP5 파일만 분리해 별도 queue로 처리수동
// 현재 — HWP5 직접 decode 후 기존 pipeline에 연결
// use hwpforge_smithy_hwp5::Hwp5Decoder;
//
// let result = Hwp5Decoder::decode_file("legacy.hwp")?;
// let validated = result.document.validate()?;
// let markdown = MdEncoder::encode_lossy(&validated)?;

3단계: 배치 처리 아키텍처

대규모 아카이브(수천~수만 파일)를 안정적으로 처리하는 패턴입니다.

#![allow(unused)]
fn main() {
use std::path::{Path, PathBuf};
use std::fs;

use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;

struct MigrationConfig {
    input_dir: PathBuf,
    output_dir: PathBuf,
    error_dir: PathBuf,
    /// 개별 파일 처리 제한 시간 (초)
    timeout_secs: u64,
    /// 최대 파일 크기 (바이트, 기본 100MB)
    max_file_size: u64,
}

struct MigrationReport {
    total: usize,
    success: usize,
    failed: usize,
    skipped_hwp5: usize,
    skipped_too_large: usize,
    errors: Vec<(String, String)>,
}

fn run_migration(config: &MigrationConfig) -> MigrationReport {
    fs::create_dir_all(&config.output_dir).expect("출력 디렉토리 생성 실패");
    fs::create_dir_all(&config.error_dir).expect("오류 디렉토리 생성 실패");

    let mut report = MigrationReport {
        total: 0, success: 0, failed: 0,
        skipped_hwp5: 0, skipped_too_large: 0,
        errors: Vec::new(),
    };

    let files: Vec<_> = walkdir::WalkDir::new(&config.input_dir)
        .into_iter()
        .filter_map(|e| e.ok())
        .filter(|e| {
            e.path().extension()
                .is_some_and(|ext| ext == "hwpx" || ext == "hwp")
        })
        .collect();

    report.total = files.len();
    eprintln!("총 {} 파일 발견", report.total);

    for (i, entry) in files.iter().enumerate() {
        let path = entry.path();
        let rel_path = path.strip_prefix(&config.input_dir).unwrap_or(path);

        // 진행률 표시
        if (i + 1) % 100 == 0 || i + 1 == report.total {
            eprintln!("[{}/{}] 처리 중...", i + 1, report.total);
        }

        // 예시 단순화를 위해 HWP5는 별도 queue로 분리
        if path.extension().is_some_and(|ext| ext == "hwp") {
            report.skipped_hwp5 += 1;
            continue;
        }

        // 파일 크기 제한
        let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
        if size > config.max_file_size {
            report.skipped_too_large += 1;
            continue;
        }

        // 변환 시도
        match convert_single(path, &config.output_dir, rel_path) {
            Ok(_) => report.success += 1,
            Err(e) => {
                report.failed += 1;
                report.errors.push((path.display().to_string(), e.clone()));

                // 실패 파일을 오류 디렉토리에 복사
                let err_dest = config.error_dir.join(rel_path);
                if let Some(parent) = err_dest.parent() {
                    let _ = fs::create_dir_all(parent);
                }
                let _ = fs::copy(path, err_dest);
            }
        }
    }

    report
}

fn convert_single(
    input: &Path,
    output_dir: &Path,
    rel_path: &Path,
) -> Result<(), String> {
    let result = HwpxDecoder::decode_file(input)
        .map_err(|e| format!("디코딩 실패: {e}"))?;

    let validated = result.document.validate()
        .map_err(|e| format!("검증 실패: {e}"))?;

    let markdown = MdEncoder::encode_lossy(&validated)
        .map_err(|e| format!("MD 인코딩 실패: {e}"))?;

    // 출력 경로: .hwpx → .md
    let out_name = rel_path.with_extension("md");
    let out_path = output_dir.join(out_name);

    if let Some(parent) = out_path.parent() {
        fs::create_dir_all(parent).map_err(|e| format!("디렉토리 생성 실패: {e}"))?;
    }

    fs::write(&out_path, &markdown).map_err(|e| format!("파일 쓰기 실패: {e}"))?;

    Ok(())
}
}

4단계: 무결성 검증

변환 결과의 품질을 검증합니다.

기본 검증 항목

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;
use std::path::Path;

struct IntegrityCheck {
    source_sections: usize,
    source_paragraphs: usize,
    source_tables: usize,
    markdown_lines: usize,
    markdown_bytes: usize,
    has_title: bool,
}

fn verify_conversion(hwpx_path: &Path, markdown: &str) -> Option<IntegrityCheck> {
    let result = HwpxDecoder::decode_file(hwpx_path).ok()?;
    let doc = &result.document;

    let mut total_paragraphs = 0;
    let mut total_tables = 0;
    for section in doc.sections() {
        total_paragraphs += section.paragraphs.len();
        total_tables += section.content_counts().tables;
    }

    Some(IntegrityCheck {
        source_sections: doc.sections().len(),
        source_paragraphs: total_paragraphs,
        source_tables: total_tables,
        markdown_lines: markdown.lines().count(),
        markdown_bytes: markdown.len(),
        has_title: doc.metadata().title.is_some(),
    })
}
}

검증 체크리스트

항목방법허용 기준
텍스트 보존원본 문단 수 vs Markdown 비어있지 않은 줄 수손실 < 10%
표 구조원본 표 수 vs Markdown | 테이블 수동일
메타데이터YAML frontmatter에 title/author 존재원본과 일치
파일 크기Markdown 바이트 > 0빈 파일 없음
인코딩UTF-8 유효성깨진 문자 없음

손상 파일 처리 전략

대규모 아카이브에서는 손상되거나 비표준 파일이 불가피합니다.

일반적인 오류 유형과 대응

오류원인대응
ZIP 파싱 실패파일 손상, 불완전 다운로드오류 목록에 기록, 원본 보존
XML 파싱 실패비표준 네임스페이스, 잘못된 인코딩오류 목록에 기록, 수동 검토
검증 실패빈 섹션, 유효하지 않은 인덱스경고 후 계속 진행
OOM (메모리 부족)매우 큰 임베디드 이미지파일 크기 제한으로 사전 필터링
암호화된 파일비밀번호 보호별도 목록으로 분류

에러 리포트 생성

#![allow(unused)]
fn main() {
use std::fs;

struct MigrationReport {
    total: usize,
    success: usize,
    failed: usize,
    skipped_hwp5: usize,
    skipped_too_large: usize,
    errors: Vec<(String, String)>,
}

fn write_report(report: &MigrationReport, path: &str) {
    let mut lines = Vec::new();
    lines.push(format!("# 마이그레이션 리포트\n"));
    lines.push(format!("- 총 파일: {}", report.total));
    lines.push(format!("- 성공: {}", report.success));
    lines.push(format!("- 실패: {}", report.failed));
    lines.push(format!("- HWP5 별도 처리: {}", report.skipped_hwp5));
    lines.push(format!("- 크기 초과: {}", report.skipped_too_large));

    if !report.errors.is_empty() {
        lines.push(format!("\n## 실패 목록\n"));
        lines.push(format!("| 파일 | 오류 |"));
        lines.push(format!("| --- | --- |"));
        for (file, err) in &report.errors {
            lines.push(format!("| `{}` | {} |", file, err));
        }
    }

    fs::write(path, lines.join("\n")).expect("리포트 저장 실패");
}
}

Lossy vs Lossless 모드 선택

목적권장 모드이유
RAG/검색 인덱싱encode_lossy표준 GFM, 청크 분할 호환, 토큰 절약
보존 범위 확인encode_lossless변환이 담는 구조를 기계로 확인
하이브리드둘 다 생성lossy는 검색용, lossless는 보존 범위 확인용

Lossless 출력은 원본 복원용 백업이 아니고 convert 입력으로도 쓸 수 없습니다. 원본은 HWPX 파일 그대로 보관하고, 고쳐서 되돌릴 때는 to-json/from-json 을 사용하세요.

하이브리드 전략이 이상적입니다:

#![allow(unused)]
fn main() {
use hwpforge::hwpx::HwpxDecoder;
use hwpforge::md::MdEncoder;

let result = HwpxDecoder::decode_file("document.hwpx").unwrap();
let validated = result.document.validate().unwrap();

// 검색/RAG용
let lossy = MdEncoder::encode_lossy(&validated).unwrap();
std::fs::write("output/search/document.md", &lossy).unwrap();

// 보존 범위 확인용
let lossless = MdEncoder::encode_lossless(&validated).unwrap();
std::fs::write("output/inspect/document.lossless.md", &lossless).unwrap();
}

관련 문서

CLI 레퍼런스

hwpforge(Hammer)는 HwpForge의 명령줄 도구입니다. 이 장은 hwpforge --help와 hwpforge <명령> --help가 보여 주는 23개 명령을 정리합니다. 플래그 이름과 기본값은 clap 정의(crates/hwpforge-bindings-cli/src/main.rs)를 그대로 옮겼으므로, 버전이 올라 의심스러우면 --help가 우선입니다.

설치

hwpforge-bindings-cli는 crates.io에 배포하지 않으므로(publish = false) git 또는 로컬 경로에서 설치합니다. hwpforge-smithy-pdf(krilla) 의존 때문에 워크스페이스 MSRV(1.89)보다 높은 Rust 1.92 이상이 필요합니다(rust-version = "1.92").

cargo install --git https://github.com/ai-screams/HwpForge hwpforge-bindings-cli

# 또는 clone 후 로컬 경로에서
git clone https://github.com/ai-screams/HwpForge && cd HwpForge
cargo install --path crates/hwpforge-bindings-cli

설치되는 바이너리 이름은 hwpforge입니다([[bin]] name = "hwpforge").

전역 옵션

옵션설명
--json결과를 machine-readable JSON으로 출력합니다
-h, --help도움말
-V, --version버전

--json은 모든 명령이 받습니다. 에이전트가 결과를 파싱할 때는 이 플래그를 붙이세요.

명령 한눈에 보기

--help는 HWP5·PDF 명령을 먼저 나열하고 그 뒤에 HWPX 명령을 나열합니다. 아래 표는 용도별로 다시 묶었습니다.

용도명령
HWP5 · PDFaudit-hwp5, census-hwp5, convert-hwp5, to-pdf
만들기 · 변환convert, to-json, from-json, to-md
읽기 · 검사inspect, outline, fields, read, diff, validate
편집fill, set-cell, patch, insert-para, delete-para, stamp-plan, stamp
부가templates, schema

HWP 입력과 HWPX 출력

다음 14개 명령은 HWPX와 HWP5(.hwp) 입력을 받습니다. HWP5는 메모리에서 HWPX로 변환한 뒤 기존 연산에 전달합니다. 확장자가 아니라 내용으로 판별하며, 정상 ZIP으로 열리는 접두사 HWPX는 그대로 처리합니다.

용도명령
읽기·검사inspect, outline, read, fields, to-md, to-json, validate, diff(양쪽 입력), stamp-plan
편집fill, set-cell, insert-para, delete-para, stamp

편집 문서 결과는 **.hwpx**입니다. .hwp 저장은 지원하지 않으며, 편집 5개 명령은 .hwp 출력 확장자를 대소문자 구분 없이 INVALID_EXTENSION으로 거부합니다. 읽기 명령의 JSON·Markdown 출력 형식은 그대로입니다.

hwpforge inspect form.hwp --json
hwpforge fill form.hwp --set name=홍길동 -o form.filled.hwpx --json

변환 손실 정책

읽기 명령은 변환 경고를 보고합니다. 편집 5개 명령은 의미 손실이 있으면 쓰기 전에 HWP5_CONVERSION_LOSS로 거부합니다. 거부된 경고를 확인한 뒤 --accept-conversion-loss로 변환 손실을 명시적으로 허용합니다. 이 옵션은 편집 자체의 admission 검사나 인코드 의미 손실 거부(ENCODE_SEMANTIC_LOSS)를 해제하지 않습니다.

글꼴 분류 정보(style.font.type_info)와 메모 모양 정의(header.memo_shape_definition)의 생략은 정책상 비손실이며 경고는 남습니다. 시각적으로 차이가 없다는 보장은 아닙니다. 조판 캐시 생략도 의미 손실 거부 대상이 아닙니다. 개요 번호 모양 참조(section.outlineShapeIDRef), 변경 추적 정의, 중첩 구역 설정, 언어별 장평, 자동 간격과 미분류 경고는 손실로 취급합니다.

변환 메타데이터

HWP5_CONVERSION_LOSS의 JSON details.warnings는 거부된 경고만 담으며, 각 항목은 stage, code, message와 선택적인 location을 갖습니다. 성공 JSON은 기존 warnings의 형과 내용을 유지하고, HWP5 입력일 때만 별도 conversion: {source_format: "hwp5", warnings: [...]}를 더합니다. 변환 경고가 없어도 conversion.warnings는 빈 배열입니다.

diff는 conversion.base·conversion.revised에 변환된 입력의 메타데이터만 담습니다. diff -o 보고서 본문과 to-json·to-md의 문서 본문에는 변환 메타데이터를 섞지 않습니다. 사람용 모드는 표준 오류로 변환 사실과 경고를 알리고, --json 모드는 결과 메타데이터로 전달합니다.

HWP 원본 보호

HWP5 입력을 자동 변환한 경우, 이미 있는 출력 파일이 입력과 같은 파일이면 INVALID_OUTPUT_PATH(종료 1)로 쓰기 전에 거부합니다. 편집 5개 명령의 문서 출력과 stamp의 manifest뿐 아니라 diff -o(양쪽 입력), to-json -o, to-md의 Markdown·추출 이미지 출력에도 적용합니다. 상대·절대 경로, 심볼릭 링크, 하드 링크와 대소문자를 구분하지 않는 파일 시스템의 별칭도 파일 정체성으로 비교합니다.

아직 없는 출력은 이 비교로 거부하지 않습니다. 정체성 확인 실패는 FILE_WRITE_FAILED이며 insert-para·delete-para는 종료 2, 나머지 자동 변환 대상 명령은 종료 1입니다. HWPX 입력의 제자리 편집은 계속 허용합니다. 실행 도중 다른 프로세스가 경로를 바꾸는 경우는 보호 범위에 포함하지 않습니다.

자동 변환 제외 경로

CLI from-json --base·patch, Python from_json(base=...)·patch·restyle과 MCP의 문서 입력(restyle 포함)은 HWP5를 자동 변환하지 않으며 HWP5_INPUT으로 거부합니다. 이 경로에는 convert-hwp5 또는 Python convert_hwp5로 명시적으로 변환한 HWPX를 전달합니다. Python의 지원 연산과 저장 보호는 Python 입력 정책을 참고합니다.

자동 변환 도입은 오류 코드 계약의 breaking change입니다. 대상 명령의 HWP5 입력은 기존 HWP5_INPUT 대신 변환 결과 또는 HWP5_DECODE_FAILED, HWP5_CONVERT_FAILED, VALIDATION_FAILED, ENCODE_FAILED를 반환합니다. 변환 실패는 기존 연산의 인자 검사보다 먼저이며, 변환 손실 거부는 기존 편집 검사 다음이면서 쓰기 전입니다. 기존 코드의 명령별 종료 값은 유지합니다(set-cell의 validation/encode 오류는 1, 나머지 변환 오류는 2). .hwp 출력 거부도 기존 동작의 변경입니다.

HWP5 · PDF

convert-hwp5

HWP5(.hwp)를 HWPX로 변환합니다.

hwpforge convert-hwp5 [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
-o, --output출력 HWPX 경로(필수)
--no-layout-cacheHWP5의 조판 캐시(PARA_LINE_SEG)를 싣지 않습니다. 줄 나눔은 여는 쪽이 다시 계산합니다

기본값은 조판 캐시를 HWPX <hp:linesegarray>로 싣습니다. 그래서 결과가 원본의 줄 나눔 자리를 담고 to-pdf의 렌더 대상이 됩니다. 줄 시작 자리를 정확히 옮길 수 없는 문단(차트, 알 수 없는 컨트롤, 경계로 가를 수 없는 줄 시작)은 잘못된 데이터를 싣는 대신 LAYOUT_CACHE_DROPPED 경고와 함께 캐시를 버립니다. 예전 옵션 --carry-layout-cache는 계속 받지만 기본값과 같은 출력을 내며, --no-layout-cache와 함께 줄 수 없습니다.

to-pdf

HWPX 또는 HWP5 문서를 조판 캐시 재생 방식으로 PDF로 렌더합니다. 입력 형식은 확장자가 아니라 내용으로 판별합니다.

hwpforge to-pdf [OPTIONS] <INPUT>
옵션설명
-o, --output출력 PDF 경로(기본값: 입력 경로의 확장자를 .pdf로 바꾼 것)
--font-dir <FONT_DIRS>폰트를 찾을 디렉터리(반복 가능)
--discovery <DISCOVERY>폰트 자동 탐색: explicit(결정적, 기본값) | hancom | platform
--degraded렌더 실패를 오류 대신 경고로 낮춥니다. 없는 스타일·축 폰트는 regular로 그리고, 렌더할 수 없는 이미지는 건너뜁니다
--partial-cache-reject조판 캐시가 없는 문단이 하나라도 있으면 문서를 거부합니다(기본값: 경고 후 그 문단을 건너뜀)

조판 캐시가 있는 문서만 렌더할 수 있습니다. convert나 --base 없는 from-json이 새로 만든 문서에는 캐시가 없어 거부됩니다. from-json --base는 믿을 수 있는 바뀌지 않은 캐시만 이어받습니다.

audit-hwp5

HWP5 원본과 변환된 HWPX 결과의 구조·의미 동등성을 점검합니다. 픽셀 단위 시각·쪽 나눔 동등성은 보장하지 않으며, 후속 시각 검증용 체크리스트를 보고서에 담습니다.

hwpforge audit-hwp5 [OPTIONS] <SOURCE> <RESULT>

<SOURCE>는 원본 .hwp, <RESULT>는 변환된 .hwpx입니다.

census-hwp5

HWP5 파일(과 선택적 HWPX 짝 파일)의 원시 fixture census를 만듭니다.

hwpforge census-hwp5 [OPTIONS] <INPUT>
옵션설명
--companion <COMPANION>중첩 XML·경로 census용 HWPX 짝 fixture(선택)
-o, --outputcensus 데이터셋을 JSON으로 저장할 경로(선택)

만들기 · 변환

convert

Markdown을 HWPX로 변환합니다.

hwpforge convert [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
<INPUT>Markdown 파일. -를 주면 stdin에서 읽습니다
-o, --output출력 HWPX 경로(필수)
--preset <PRESET>스타일 프리셋 이름(기본값: default)

사용 가능한 프리셋은 templates list로 확인합니다.

to-json

HWPX 또는 HWP5를 편집 가능한 JSON으로 내보냅니다.

hwpforge to-json [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
-o, --output출력 JSON 경로(필수, stdout 내보내기는 없습니다)
--section <SECTION>특정 섹션만 추출(0부터 시작하는 인덱스)
--no-styles스타일 정보를 제외합니다

--section 없이 내보낸 문서 전체 JSON은 from-json이, --section N으로 내보낸 섹션 JSON은 patch가 읽습니다. 두 JSON은 서로 다른 형식입니다.

두 JSON 모두 맨 위에 "format_version": 3 를 쓰고, 문단 여백 다섯 가지(margin_left, margin_right, indent, spacing_before, spacing_after)와 탭 위치(position)를 단위와 값으로 씁니다. hwpunit 은 1/100 pt, char 는 1/500 글자입니다.

"margin_left": { "unit": "hwpunit", "value": 2000 },
"indent": { "unit": "char", "value": -1000 }

from-json 과 patch 는 이전 판이 쓴 버전 없는 JSON 을 이렇게 다룹니다.

  • 탭 위치가 하나라도 있으면 LEGACY_JSON_TABS 로 거부합니다. 옛 JSON 에는 탭 단위가 남아 있지 않아 추측하지 않습니다.
  • 탭 위치가 없으면 문단 여백을 옛 표현에서 풀어 읽고 LEGACY_PARAGRAPH_MEASURES 경고를 냅니다. 옛 JSON 이 이미 잃은 단위는 되살리지 못합니다.
  • 명시 v2는 문단 style_id를 정의 배열 위치로 해석해 v3로 이행합니다. 그 밖의 버전 번호나 정수가 아닌 format_version 은 거부합니다.

어느 경우든 원본 HWPX 또는 HWP5 에서 새 판의 to-json 을 다시 실행하는 것이 가장 정확합니다.

스타일 글자 모양의 그림자는 0.17.0 부터 shadow 객체로 나옵니다(이전 키 shadow_type 은 종류만 담았습니다).

"shadow": { "kind": "Continuous", "color": "#123456", "offset_x": -3, "offset_y": 4 }

color 는 "#RRGGBB" 또는 "none" 입니다. 이전 판이 쓴 "shadow_type": "Drop" JSON 도 from-json 이 읽고, 이때 색·간격은 기본값 #C0C0C0·10·10 이 됩니다(이전 출력 #B2B2B2 보다 밝음).

from-json

JSON을 HWPX로 되돌립니다.

hwpforge from-json [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
-o, --output출력 HWPX 경로(필수)
--base <BASE>이미지를 물려받을 기준 HWPX(왕복 충실도용)

to-md

HWPX 또는 HWP5를 Markdown으로 변환합니다.

hwpforge to-md [OPTIONS] <INPUT>
옵션설명
-o, --output출력 디렉터리(기본값: 입력과 같은 디렉터리)
--mode <MODE>styled(기본값, 스타일을 따르고 이미지 포함) | lossy(스타일 정보 없는 읽기용) | lossless(보존 범위를 확인하는 기계용 보기. 보존 범위의 보존 목록은 보존, 거부 목록에 든 개체가 있으면 오류, 그 밖의 값은 빠질 수 있음. 프론트매터에 metadata.format: lossless 가 붙고 convert 는 이 출력을 MD_DECODE_FAILED 로 거부하므로, 왕복 편집에는 to-json/from-json 을 사용)

읽기 · 검사

inspect

HWPX 또는 HWP5 문서를 디코드한 구조를 보여 줍니다. HWP5 입력의 변환 경고는 별도로 보고합니다.

hwpforge inspect [OPTIONS] <FILE>
옵션설명
--styles스타일 상세(문자·문단 모양)를 포함합니다

outline

문서의 내비게이션 맵(제목, 표, 이름 있는 누름틀, 책갈피)을 보여 줍니다. 이름 앵커(제목 텍스트, 표 순번, 필드·책갈피 이름)가 1차 키이고 {section, para} 위치는 구조 편집 뒤에 낡을 수 있으므로, 읽기·편집 전에 한 번 받아 두는 용도입니다.

hwpforge outline [OPTIONS] <FILE>

fields

이름 있는 누름틀(click-here field)과 각각이 채울 수 있는 필드인지 나열합니다.

hwpforge fields [OPTIONS] <FILE>

read

문서 전체를 내보내지 않고 목표 하나만 텍스트로 읽습니다. 목표는 정확히 하나만 지정합니다.

hwpforge read [OPTIONS] <FILE>
옵션설명
--section <SECTION>문단을 읽을 섹션 인덱스
--paras <PARAS>닫힌 문단 범위 "A..B" 또는 단일 "N"(--section 필요)
--table <TABLE>표 순번. 논리 격자 텍스트 행렬로 읽습니다(병합 영역은 앵커에 한 번, span과 함께)
--field <FIELD>이름 있는 누름틀 하나

텍스트가 아닌 내용(표, 이미지, 컨트롤)은 조용히 버려지지 않고 명시적인 표지로 드러납니다. 읽기 전용입니다.

diff

HWPX 또는 HWP5 입력 둘을 두 채널로 비교해 편집이 실제로 무엇을 바꿨는지 확인합니다.

hwpforge diff [OPTIONS] <BASE> <REVISED>
옵션설명
-o, --output전체 JSON 보고서를 이 경로에도 씁니다

semantic 채널은 디코드한 Core 구조를 필드 값, 표 셀 텍스트 {table, row, col}, 문단 텍스트 {section, para}, 구조 개수, 상한이 있는 미분류 잔여로 분류합니다. package 채널은 ZIP 엔트리를 바이트로 비교합니다. 바뀐 엔트리 안의 wire 내용(예: hp:linesegarray 조판 캐시)은 항목별로 나열하지 않으며 보고서가 그렇게 밝힙니다. fill·set-cell·stamp·patch 뒤에 돌려 의도한 변경만 반영됐는지 확인하세요.

validate

HWPX 또는 HWP5가 디코드되고 Core의 구조 불변식(Document::validate)을 만족하는지 편집 없이 검사합니다.

hwpforge validate [OPTIONS] <FILE>

종료 코드는 --help에 다음과 같이 정의돼 있습니다.

종료 코드의미
0문서가 유효합니다
1파일을 읽을 수 없음(없거나 읽을 수 없거나 크기 상한을 넘는 파일)
2명령행 인자가 잘못됐거나 디코드·HWP5 변환에 실패합니다
3디코드는 되지만 검증에 실패합니다(오류가 아니라 판정이며, --json 출력의 errors를 보세요). 파서는 통과하고 Core 중첩 깊이가 32를 넘는 문서는 디코드에서 거부되므로 3이 아니라 DECODE_FAILED(종료 2)입니다

인자를 잘못 준 경우(필수 인자 누락, 알 수 없는 옵션)는 clap이 종료 코드 2로 끝냅니다. 아래 오류 계약은 다른 명령의 종료 정책도 함께 설명합니다.

편집

fill·set-cell·insert-para·delete-para·stamp는 HWP5 입력의 의미 손실을 기본 거부합니다. 공통 옵션 --accept-conversion-loss는 변환 손실만 허용하며 편집 문서 출력은 .hwpx입니다. 자세한 내용은 입력 정책을 참고합니다.

fill·set-cell·insert-para·delete-para·stamp·patch는 결과를 -o로 지정한 출력 경로에 씁니다(필수 옵션). stamp-plan은 파일을 쓰지 않으므로 -o가 없습니다. 편집 뒤에는 diff로 변경 범위를 확인하세요.

fill

이름 있는 누름틀을 값으로 채웁니다. 기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기(Preview)를 지우고 PREVIEW_REMOVED 경고를 냅니다. 한컴에서 다시 저장하면 미리보기가 다시 만들어집니다. 내용이 같으면 원본 파일을 돌려줍니다. 머리글 정규화·스타일 정의 변경 등 문서 재인코드가 필요하거나 이전 형식의 문서 전체 JSON을 쓰는 경우는 이 보장 밖입니다.

hwpforge fill [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
--set <NAME=VALUE>채울 이름=값 쌍(반복 가능). 하나 이상 필수
-o, --output출력 HWPX 경로(필수)

요청한 값을 모두 먼저 검증(알 수 없는·중복된·채울 수 없는 이름, 빈 값)하고, 하나라도 실패하면 아무것도 쓰지 않습니다. 누름틀이 들어 있는 서식 문서에서만 동작하므로 convert로 막 만든 문서에는 필드가 없습니다. 이름은 fields로 먼저 확인하세요.

set-cell

요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.

표 셀을 논리 격자 주소로 편집하며, batch는 전부 성공하거나 아무것도 쓰지 않습니다.

hwpforge set-cell [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
--table <TABLE>표 순번(문서 순서, 0부터). 단일 편집에는 필수(--map 일괄 편집에서는 쓰지 않음)
--at <R,C>격자 좌표 "row,col"(덮인 위치는 병합 앵커로 해석)
--right-of <LABEL>유일하게 라벨된 셀의 오른쪽 셀을 대상으로 합니다
--below <LABEL>유일하게 라벨된 셀의 아래쪽 셀을 대상으로 합니다
--text <TEXT>바꿀 텍스트(빈 문자열은 셀을 비웁니다). 단일 편집에는 필수
--map <MAP_JSON>일괄 편집용 명세 맵(CellSpec JSON 배열). 위 플래그들과 함께 쓸 수 없습니다
-o, --output출력 HWPX 경로(필수)

patch

기존 HWPX의 섹션 하나를 교체합니다.

hwpforge patch [OPTIONS] --section <SECTION> --output <OUTPUT> <BASE> <SECTION_JSON>

<SECTION_JSON>은 to-json --section N으로 내보낸 섹션 JSON이며, <BASE>가 이미지와 나머지 패키지의 기준입니다. 문서 전체 JSON을 넣으면 스키마 불일치로 거부됩니다. 구조(문단 수)를 바꾸려면 insert-para·delete-para나 from-json을 쓰세요.

insert-para

기준 문단 앞이나 뒤에 새 최상위 문단을 삽입합니다. 관련 없는 내용을 유지하며, 영향을 받는 조판 캐시를 고칩니다. 한컴 저장 문서는 아래 사전 검사에서 거부됩니다.

hwpforge insert-para [OPTIONS] --section <SECTION> --anchor <ANCHOR> --text <TEXTS> --output <OUTPUT> <FILE>
옵션설명
--section <SECTION>섹션 인덱스
--anchor <ANCHOR>기준 문단 인덱스(새 문단이 이 문단의 문단·문자 모양을 그대로 물려받습니다)
--before기준 앞에 삽입합니다(기본값은 뒤)
--text <TEXTS>새 문단의 한 줄 일반 텍스트. 반복하면 연속된 블록을 한 번의 검증된 편집으로 삽입합니다
-o, --output출력 HWPX 경로(필수)

섹션의 첫 문단(secPr를 담은 문단) 앞 삽입은 거부됩니다. 왕복 안전한 입력만 편집할 수 있습니다.

delete-para

최상위 본문 문단을 인덱스로 삭제합니다. 전부 성공하거나 전부 취소됩니다. 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.

CONTENT_LOST는 입력을 Core로 읽을 때 표현하지 못한 정보가 있다는 경고입니다. 원문 보존 삭제는 그 정보가 출력 원문에 보존되고 삭제 판정에 영향을 주지 않음을 별도로 확인한 경우에만 성공하며, 입력 decode 경고는 순서와 횟수 그대로 남습니다. 이는 원문 XML에 정보가 남는 일부 손실(예: 언어별 글자 값)에만 해당하며, 그 밖의 CONTENT_LOST 입력은 기존 거부를 유지합니다. 전체 재인코드 편집의 입력 손실 거부는 유지됩니다.

hwpforge delete-para [OPTIONS] --section <SECTION> --output <OUTPUT> <FILE>
옵션설명
--section <SECTION>섹션 인덱스
--index <INDICES>...삭제할 최상위 문단 인덱스(일괄 삭제는 반복). 하나 이상 필수
-o, --output출력 HWPX 경로(필수)

참조(책갈피·상호참조·각주 등)를 담은 문단, 강제 쪽·단 나눔이 있는 문단, 섹션 속성(secPr)을 담은 첫 문단, 삭제하면 섹션이 비게 되는 경우는 거부합니다(fail-closed).

stamp-plan

산문 속 자리표시자(체크박스, 괄호 빈칸, 날짜 빈칸, 단독 @, 도장 토큰) 후보를 찾아 템플릿 스탬핑 계획을 만듭니다.

hwpforge stamp-plan [OPTIONS] <FILE>

출력의 각 후보에 {"field":{"name":"…"}} 또는 "ignore" 액션을 붙여 명세 맵을 만든 뒤 stamp --map을 실행합니다. 지침 문맥의 후보(guarded)는 자동 적용되지 않습니다.

stamp

명세 맵을 적용해 자리표시자를 이름 있는 누름틀로 승격합니다. 전부 성공하거나 전부 취소되며, 스탬프된 HWPX와 매니페스트를 씁니다.

hwpforge stamp [OPTIONS] --map <MAP_JSON> --output <OUTPUT> <FILE>
옵션설명
--map <MAP_JSON>StampSpec JSON 배열(필수)
-o, --output출력 HWPX 경로(필수)
--manifest <MANIFEST>매니페스트 JSON 경로(기본값: <output>.manifest.json)

실패 시 아무것도 쓰지 않는 admission 게이트(무변경 왕복 + ZIP 닫힌 세계 검사) 뒤에서 동작하고, 결과물은 곧바로 fields·fill에 쓸 수 있습니다.

부가

templates

스타일 프리셋을 관리합니다. 하위 명령은 두 개입니다.

hwpforge templates list            # 사용 가능한 프리셋 목록
hwpforge templates show <NAME>     # 프리셋 상세

schema

문서·스타일 타입의 JSON Schema를 출력합니다.

hwpforge schema [OPTIONS] [TYPE_NAME]

TYPE_NAME은 document(기본값), exported-document, exported-section 중 하나입니다. exported-document가 to-json의 전체 JSON, exported-section이 --section JSON의 형식입니다.

다음 단계

0.18 오류 코드와 종료 상태

CLI JSON의 code, MCP 도구 오류의 code, Python HwpForgeError.code는 같은 실패 단계와 도메인 거부 사유에 같은 OpsCode 문자열을 사용합니다. 여러 결함이 있으면 실제로 먼저 실패한 검사로 분류하며, 메시지·힌트·응답 봉투까지 같다는 뜻은 아닙니다. 퇴역 별명과 옛 문자열 lookup은 제공하지 않습니다.

실패 단계·원인코드
보류 명령의 HWPX 입력에 HWP5(.hwp)를 전달HWP5_INPUT (종료 2)
HWP5 변환의 의미 손실로 편집 거부HWP5_CONVERSION_LOSS (종료 1)
편집 문서 출력이 .hwpINVALID_EXTENSION (종료 1)
편집 문서·manifest 또는 diff·to-json·to-md 출력이 HWP5 입력과 같은 파일INVALID_OUTPUT_PATH (종료 1)
입력 HWPX / Markdown / HWP5 해석DECODE_FAILED / MD_DECODE_FAILED / HWP5_DECODE_FAILED
편집 전 no-op 검증·인코드·재디코드 또는 의미 왕복 불일치INPUT_NOT_ROUNDTRIP_SAFE
입력 ZIP 엔트리 미보존INPUT_ENTRIES_NOT_CARRIED
명시적 문서 검증·메모리 문서 깊이 검사VALIDATION_FAILED
출력 생성 / 의미 손실 때문에 출력 거부ENCODE_FAILED / ENCODE_SEMANTIC_LOSS
생성 산출물 읽기·재디코드·대조SELF_VERIFY_FAILED
보호 필드 침범 / 내부 불변식 파손PROTECTED_FIELD_RANGE / INTERNAL_INVARIANT
보존 patch의 변경·metadata 거부 / fill 고유 거부PATCH_FAILED / FILL_FAILED
아직 분류하지 않은 상류 variantUPSTREAM_UNMAPPED

HWP5_INPUT이면 먼저 hwpforge convert-hwp5 <in.hwp> -o <out.hwpx>로 변환하세요. 확장자가 아닌 내용으로 판정하며, ZIP으로 열리는 접두사 HWPX는 이 코드로 재분류하지 않습니다.

전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.

INPUT_NOT_ROUNDTRIP_SAFE는 현재 코덱으로 무변경 왕복을 확인하지 못했다는 뜻입니다. 원문을 보존하는 to-json --section N → patch, 누름틀 fill, 보존 가능한 한 문단·한 Text run 칸의 set-cell 경로를 검토하세요. 입력 바이트의 깊이 초과는 DECODE_FAILED이고, Rust Draft 셀 편집의 깊이 초과는 VALIDATION_FAILED입니다.

종료 상태는 (명령, 코드)로 결정합니다. 같은 명령·코드는 오류 payload나 발생 경로에 따라 달라지지 않습니다. 0은 성공이고, validate의 3은 디코드된 문서가 유효하지 않다는 판정입니다(Core 중첩 깊이 32 초과는 디코드 거부라 DECODE_FAILED입니다). 오류의 1·2만으로 원인을 구분하지 말고 code를 확인하세요.

I/O 코드종료 상태
FILE_NOT_FOUND, FILE_READ_FAILEDto-md·convert-hwp5는 2, 나머지는 1
INPUT_TOO_LARGE일반 파일 사전 검사·FIFO 모두 1
FILE_WRITE_FAILEDdelete-para·insert-para·convert-hwp5는 2, 나머지는 1

0.18에서 바뀌는 종료 값은 다음 일곱 변경군입니다.

delete-para의 사전 validate·encode·재decode 실패도 INPUT_NOT_ROUNDTRIP_SAFE / 1입니다. 마지막 의미 왕복 비교 또는 ZIP carry 호출의 실패만 원문 보존 삭제를 시도하며, 그 시도에서 어느 검증이든 실패하면 원래 오류를 그대로 반환합니다.

명령·실패이전0.18 코드·종료
insert-para: no-op validate·encode·재decode2INPUT_NOT_ROUNDTRIP_SAFE / 1
stamp: no-op validate·encode·재decode2INPUT_NOT_ROUNDTRIP_SAFE / 1
set-cell: 입력 decode·원본 패키지 읽기1DECODE_FAILED / 2
delete-para·insert-para: 출력 decode·생성 산출물 읽기·fragment 파싱2SELF_VERIFY_FAILED / 1
to-md·convert-hwp5: 크기 한도를 넘는 FIFO 입력2INPUT_TOO_LARGE / 1
convert-hwp5: 쓰기 성공 직후 stat 실패1FILE_WRITE_FAILED / 2
validate: 파서는 통과하고 Core 중첩 깊이가 32를 넘는 HWPX3(판정)DECODE_FAILED / 2

CLI 전용 INVALID_SET·DUPLICATE_SET과 진단용 네 코드는 유지합니다. 잘못된 명령행 문법은 기존 파서의 종료 2와 사용법 텍스트를 유지합니다. PDF의 cause.code는 별도 렌더러 코드 체계입니다.

이전 코드로 분기하던 소비자는 다음 이행표를 참고하세요. 아래 왼쪽 열은 과거 이름이며 0.18 출력이나 lookup 별명이 아닙니다.

이전 코드·용도0.18 코드
DECODE_ERROR, HWPX_DECODE_FAILEDDECODE_FAILED
ENCODE_ERRORENCODE_FAILED
VALIDATION_ERROR, VALIDATE_FAILEDVALIDATION_FAILED
MD_DECODE_ERROR, JSON_PARSE_ERRORMD_DECODE_FAILED, JSON_PARSE_FAILED
SERIALIZE_ERROR, STAMP_MANIFEST_SERIALIZEJSON_SERIALIZE_FAILED
UNKNOWN_PRESETPRESET_NOT_FOUND
STYLE_STORE_ERROR, STYLE_REBIND_ERRORSTYLE_STORE_FAILED, STYLE_REBIND_FAILED
FILL_ERROR, 포괄 FILL_FAILED고유 fill 거부는 FILL_FAILED, 나머지는 실패 단계·patch·불변식 코드
PATCH_ERROR, 포괄 PATCH_FAILED보존 정책 거부는 PATCH_FAILED, 나머지는 실패 단계·보호 필드·불변식·구역 범위 코드
SET_CELL_CODEC_FAILED, STAMP_CODEC_FAILED, STRUCTURAL_CODEC해당 단계 코드, PROTECTED_FIELD_RANGE, INTERNAL_INVARIANT; 의미 손실은 ENCODE_SEMANTIC_LOSS
READ_SECTION_OUT_OF_RANGE, READ_TABLE_OUT_OF_RANGE, READ_FIELD_NOT_FOUNDSECTION_OUT_OF_RANGE, TABLE_NOT_FOUND, FIELD_NOT_FOUND
STAMP_DELTA_MISMATCH, STAMP_CELL_TARGET_DUPLICATESELF_VERIFY_FAILED, CELL_TARGET_DUPLICATE
INDEX_OUT_OF_RANGESECTION_OUT_OF_RANGE 또는 PARAGRAPH_OUT_OF_RANGE
UNCARRIED_ZIP_ENTRIESINPUT_ENTRIES_NOT_CARRIED
MCP 앞 삽입 거부의 SECTION_PROPERTIES_PARAGRAPHINSERT_BEFORE_SECTION_PROPERTIES; 원래 구역 속성 문단 보호에는 기존 코드 유지
STRUCTURAL_EDIT_FAILED정밀 도메인 코드 또는 UPSTREAM_UNMAPPED
SECTION_WORKFLOW_FAILED, SECTION_WORKFLOW_ERROR, SET_CELL_FAILED, STAMP_FAILED fallbackUPSTREAM_UNMAPPED
포괄 HWP5_CONVERT_FAILEDdecode는 HWP5_DECODE_FAILED, 직접 검증은 VALIDATION_FAILED, 출력 생성은 ENCODE_FAILED; layout replay는 기존 코드 유지
READ_ERROR, METADATA_ERROR, STDIN_READ_FAILEDFILE_READ_FAILED; 입력 부재는 FILE_NOT_FOUND
WRITE_ERROR, DIR_CREATE_ERROR, DIR_CREATE_FAILED출력 I/O는 FILE_WRITE_FAILED, 출력 경로 정책은 INVALID_OUTPUT_PATH

과거 로그의 포괄 코드는 당시 실패 단계를 모르면 새 코드 하나로 자동 변환할 수 없습니다.

MCP의 도구 필드 역직렬화 실패는 필드 경로를 메시지에 포함한 INVALID_PARAMS입니다. 경고가 있는 18개 도구는 {code, message, hint?} 객체 배열을 반환하며, 빈 경고는 생략합니다. templates에는 경고 필드가 없습니다. 전송·JSON-RPC·알 수 없는 도구·worker 실패는 기존 프로토콜 경계를 유지합니다.

Python 파일 I/O는 HwpForgeError와 OSError로 포착할 수 있고, 입력 부재는 FileNotFoundError로도 포착할 수 있습니다. 정확한 타입 비교나 PermissionError 같은 세부 포착은 달라집니다. Python 호출 규약·인자 변환의 TypeError·ValueError는 유지합니다.

스타일 참조와 JSON 이행

v3 문단의 style_ref는 문서 내부 참조입니다. styles.style_positions[ref]가 styles.styles 정의 배열의 위치를 가리킵니다. 숫자 ref 0은 wire 0과 다를 수 있으며, null은 출력에서 wire 0을 사용합니다. 대응표는 모든 정의를 정확히 한 번 포함해야 합니다. schema의 Document는 Core 구조이고 ExportedDocument/ExportedSection은 이 교환 envelope를 설명합니다.

독립 from-json은 non-null 참조가 있으면 styles를 요구합니다(base 제공 여부와 무관). styles 없는 구역 patch는 제출한 base의 참조 공간으로 해석합니다. 동일 section과 다른 header를 가진 파일의 출처 차이까지 검출하지는 않습니다. 완전 왕복에는 styles를 포함하세요. v2는 위치 참조를 단방향 이행하며, styles 없는 v2 문서 작성은 default preset을 사용합니다. 버전 없는 JSON은 기존 여백 단위 이행을 먼저 수행합니다.

MCP from-json의 문자열 인자 안 JSON도 같은 계약입니다. 별도 MCP schema 도구는 없으며 CLI schema를 사용합니다. Python의 dict 반환 타입과 callable은 그대로이고, 그 내부 데이터 계약만 v3로 바뀝니다.

v3에서 Core JSON의 style_id는 style_ref로 바뀌었으며, 교환에는 envelope를 사용하세요. to-json --no-styles로 내보낸 v3 문서는 non-null 참조에 필요한 styles가 없어 그대로 from-json에 넣으면 거절됩니다.

MCP 서버 레퍼런스

hwpforge-mcp는 HwpForge의 MCP 서버입니다. Claude Code 같은 MCP 지원 AI 도구가 한글 문서를 직접 만들고 읽고 편집할 수 있도록 도구 19개, 리소스 4개, 프롬프트 3개를 노출합니다. 이 장의 이름과 매개변수는 crates/hwpforge-bindings-mcp/src의 정의에서 옮겼습니다.

모든 도구는 { data, summary, next } 3층 출력 형식을 씁니다. 파일은 대부분 경로로 주고받으며(예외: hwpforge_convert는 is_file: false로 Markdown을 인라인으로 받고, hwpforge_to_json은 output_path 없이 JSON을 인라인으로 돌려주고, hwpforge_diff는 output_path 없이 보고서를 인라인으로 돌려주며, hwpforge_from_json은 JSON을 structure 문자열로 받습니다), 실패는 오류 응답(CallToolResult::error)으로 돌아옵니다.

등록

npm (권장, Rust 툴체인 불필요)

npx -y가 플랫폼에 맞는 바이너리를 내려받습니다.

# 현재 프로젝트에서만
claude mcp add hwpforge -- npx -y @hwpforge/mcp

# 모든 프로젝트에서 (user 범위)
claude mcp add --scope user hwpforge -- npx -y @hwpforge/mcp

프로젝트 루트의 .mcp.json에 직접 적어도 됩니다.

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

Claude Code의 MCP 서버는 claude mcp add 또는 .mcp.json으로 등록합니다. .claude/settings.json에 적어도 MCP 서버로 읽히지 않습니다.

Cargo

cargo install hwpforge-bindings-mcp
claude mcp add hwpforge hwpforge-mcp

crates.io 패키지 이름은 hwpforge-bindings-mcp이고 설치되는 바이너리 이름은 hwpforge-mcp입니다([[bin]] name = "hwpforge-mcp").

npm 패키지 구성

@hwpforge/mcp는 플랫폼별 패키지를 optionalDependencies로 가진 기본 패키지입니다. 플랫폼 패키지는 .github/workflows/npm-publish.yml의 빌드 매트릭스와 같은 다섯 개입니다.

플랫폼 패키지 접미사Rust 타깃
darwin-arm64aarch64-apple-darwin
darwin-x64x86_64-apple-darwin
linux-x64x86_64-unknown-linux-gnu
linux-arm64aarch64-unknown-linux-gnu
win32-x64x86_64-pc-windows-msvc

패키지 이름은 @hwpforge/mcp-<접미사> 형태입니다. 게시는 npm Trusted Publishing(OIDC)만 씁니다.

도구

표의 (.hwpx)는 그 output_path가 .hwpx로 끝나야 한다는 표시입니다. 이 확장자 검사는 hwpforge_convert·hwpforge_from_json·hwpforge_restyle·hwpforge_fill·hwpforge_set_cell·hwpforge_patch·hwpforge_stamp에 있고, hwpforge_insert_para·hwpforge_delete_para에는 없습니다. hwpforge_to_json의 output_path는 .json으로 끝나야 합니다.

만들기 · 변환

도구용도매개변수
hwpforge_convertMarkdown을 HWPX로 변환합니다markdown(파일 경로 또는 인라인 내용), is_file(기본 true), output_path(.hwpx), preset(기본 default)
hwpforge_to_jsonHWPX를 편집용 JSON으로 내보냅니다file_path, section(선택, 0부터), output_path(선택, .json으로 끝나야 함, 없으면 JSON을 응답에 인라인으로 돌려줌)
hwpforge_from_jsonJSON(ExportedDocument 스키마)으로 HWPX를 직접 만듭니다structure(JSON 문자열), output_path(.hwpx)
hwpforge_to_mdHWPX를 Markdown으로 변환합니다file_path, output_dir(선택, 기본값은 입력과 같은 디렉터리)
hwpforge_restyle기존 HWPX에 다른 스타일 프리셋을 적용합니다file_path, preset, output_path(.hwpx)
hwpforge_templates스타일 프리셋 목록을 돌려줍니다name(선택, 프리셋 이름 필터)

hwpforge_to_json의 인라인 응답은 직렬화된 응답이 1 MB 미만일 때만 가능하며, 더 큰 내보내기는 OUTPUT_TOO_LARGE로 거부되므로 output_path를 주세요. 전체 문서 내보내기는 hwpforge_from_json이, section을 준 내보내기는 hwpforge_patch가 읽습니다.

MCP hwpforge_from_json이나 Markdown으로 HWPX를 재생성할 때 원본 패키지의 서명·암호화 상태는 승계되지 않습니다.

읽기 · 검사

도구용도매개변수
hwpforge_inspect섹션·문단·표·이미지·차트·머리글/바닥글·쪽번호 개수와 디코드 경고를 돌려줍니다file_path, styles(예약 필드, 현재 무시됨)
hwpforge_outline제목, 표, 이름 있는 누름틀, 책갈피의 내비게이션 맵file_path
hwpforge_fields누름틀의 이름, 힌트, 현재 값, 채울 수 있는지 여부file_path
hwpforge_read문단 범위, 표 격자, 필드 중 하나만 텍스트로 읽습니다file_path, section, paras("A..B" 또는 "N"), table, field — section/table/field 중 정확히 하나
hwpforge_diff두 HWPX를 semantic·package 두 채널로 비교합니다base_path, revised_path, output_path(선택, 보고서가 인라인 1 MB를 넘으면 필수)
hwpforge_validateHWPX 구조와 무결성을 검사합니다file_path

hwpforge_validate는 디코드할 수 없는 HWPX를 “유효하지 않은 문서” 판정이 아니라 DECODE_FAILED 오류로 알립니다. HWP5(.hwp)는 HWP5_INPUT입니다. MCP는 자동 변환하지 않으므로 CLI hwpforge convert-hwp5 <in.hwp> -o <out.hwpx> 또는 Python convert_hwp5로 먼저 변환하세요.

편집

도구용도매개변수
hwpforge_fill이름 있는 누름틀을 이름→값 맵으로 채웁니다(전부 성공하거나 전부 취소)file_path, values(이름→값 맵), output_path(.hwpx)
hwpforge_set_cell표 셀을 논리 격자 주소로 편집합니다file_path, specs(셀 명세 배열: 표 순번 + at {row,col} / right_of / below + text), output_path(.hwpx)
hwpforge_patch섹션 하나를 편집한 JSON으로 교체합니다(텍스트 전용)base_path, section, section_json_path, output_path(.hwpx)
hwpforge_insert_para기준 문단 앞뒤에 새 최상위 문단을 삽입합니다file_path, section, anchor, before(기본 false), text 또는 texts 중 정확히 하나, output_path
hwpforge_delete_para최상위 본문 문단을 인덱스로 삭제합니다file_path, section, indices, output_path
hwpforge_stamp_plan자리표시자 후보를 찾습니다file_path
hwpforge_stamp승인된 명세로 자리표시자를 누름틀로 승격합니다file_path, specs(텍스트 명세), cells(셀 명세), source_sha256(cells를 쓰면 필수), output_path(.hwpx), manifest_path(기본 <output>.manifest.json)

전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.

편집 도구의 동작 규칙은 CLI 레퍼런스의 대응하는 명령(예: hwpforge_insert_para는 insert-para)과 같습니다. 주의할 점은 다음과 같습니다.

  • hwpforge_patch는 문단 구조를 바꾸지 못합니다. 의미 텍스트 슬롯의 개수나 경로가 다르면 거부되며, 문단 추가·삭제는 hwpforge_insert_para·hwpforge_delete_para, 표 셀은 hwpforge_set_cell, 구조가 바뀐 문서 재구성은 hwpforge_from_json을 씁니다.
  • hwpforge_delete_para: 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.
  • hwpforge_insert_para·hwpforge_stamp와 보존 범위 밖 hwpforge_set_cell은 왕복 안전한 입력만 편집합니다. 인코더가 ZIP 엔트리를 모두 실어 보낼 수 없는 문서, 곧 한컴이 저장하며 Preview/*와 META-INF/container.rdf를 더한 문서는 거부됩니다. 이런 문서에도 hwpforge_to_json + hwpforge_patch(텍스트)와 hwpforge_fill(누름틀)은 쓸 수 있습니다.
  • hwpforge_stamp는 hwpforge_stamp_plan이 준 후보 객체를 그대로 복사해 action({"field":{"name":"…"}} 또는 "ignore")만 더합니다. 지침 문맥의 후보는 자동 적용되지 않습니다.

요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.

리소스

스타일 템플릿을 YAML(application/x-yaml)로 읽는 리소스 4개입니다. 프리셋 이름과 일치합니다(crates/hwpforge-bindings-mcp/src/resources/mod.rs).

URI이름
hwpforge://templates/defaultDefault Template
hwpforge://templates/modernModern Template
hwpforge://templates/classicClassic Template
hwpforge://templates/latestLatest Template

프롬프트

워크플로 안내 프롬프트 3개입니다(crates/hwpforge-bindings-mcp/src/prompts/mod.rs).

이름제목인자
generate_proposal정부 제안서 생성topic(필수), organization(선택), deadline(선택, YYYY-MM-DD)
generate_report보고서 생성topic(필수), author(선택), report_type(선택: research / progress / analysis, 기본 research)
convert_and_review문서 편집 워크플로우file_path(필수), edit_instructions(선택)

참고

  • MCP 서버는 베타이며 HWP5 경로는 MCP가 아니라 CLI(convert-hwp5, audit-hwp5, to-pdf)를 우선합니다. 이 서버의 19개 도구에는 HWP5와 PDF 관련 도구가 없습니다.
  • CLI 명령은 CLI 레퍼런스, Python 사용법은 Python 가이드를 보세요.

API 레퍼런스 (rustdoc)

HwpForge의 전체 공개 API 문서는 docs.rs에서 확인할 수 있습니다.

참고

  • 이 mdBook는 개념 설명과 사용 가이드 중심입니다.
  • trait, struct, enum, function의 상세 시그니처는 rustdoc이 진실입니다.
  • docs.rs와 저장소 문서가 어긋나면, 공개 API 계약은 rustdoc 쪽을 먼저 확인하십시오.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

릴리스 노트 위치 (0.10.0 이후)

0.10.0 이후 릴리스 노트는 release-plz 가 크레이트별로 생성한다 — 이 루트 파일은 갱신을 멈췄다. 최신 이력은 다음에서 확인:

아래는 0.6.0~0.9.0 수동 관리 이전 이력이다.

[0.6.0 – 0.9.0] — 2026-05-29 … 2026-06-28 (released)

아래 항목들은 이미 crates.io 로 릴리스된 v0.6.0~v0.9.0 누적분이다 (루트 CHANGELOG 를 버전별 섹션으로 컷하지 못해 오랫동안 [Unreleased] 에 쌓여 있던 것 — E6 IR 와이어-누출 상환 A/B/C/M2, Wave 11/12 HWP5→HWPX carry, 문서 메타데이터 등). 정확한 버전별 대응은 release-plz 가 소유하는 per-crate CHANGELOG (crates/*/CHANGELOG.md) 를 참조.

Changed — BREAKING — cross-ref inst_id 누출을 ObjectId 로 (E6/M2, ADR-010)

크로스레퍼런스 링크가 두 무관한 정수 필드(타깃 inst_id: Option<u64/u32> ↔ 참조자 RefTarget::SystemId(u64))의 값-우연-일치였던 것을, 공유 newtype hwpforge_core::ObjectId(u64) 로 묶어 타입 수준 링크로 격상 (ADR-010, ADR-005 supersede). 리팩토링이 링크를 조용히 깨면 byte-diff 로도 안 잡히던 취약성 제거 + notes(u32)/shapes(u64) 폭 불일치 해소.

  • 신규 public 타입 hwpforge_core::ObjectId (#[serde(transparent)] → JSON/YAML 에서 bare integer).
  • 타깃 inst_id 필드 타입 변경 (필드명 유지): Image/Table/ Control::{Equation,Group,TextArt,Footnote,Endnote} 의 inst_id → Option<ObjectId>. Footnote/Endnote 는 u32→u64 승격. 패턴 매칭에서 값을 꺼내 쓰면 ObjectId 로 받게 됨(Some(42) → Some(ObjectId::new(42))).
  • RefTarget::SystemId(u64) → RefTarget::Object(ObjectId) (variant 리네임
    • payload 타입). FromStr/Display 출력 wire 문자열(#<id>)은 불변.
  • Control::{footnote,endnote}_with_id 인자 u32 → u64 (정수 리터럴 호출은 무변경).
  • JSON 영향: 타깃 inst_id 값은 정수 그대로(byte-동일). RefTarget 직렬화 태그가 "SystemId" → "Object" 로 변경 (CLI to-json/from-json, MCP). wire(HWPX) 출력은 전(全) 구간 byte-중립.
  • 와이어 스키마 HxFootNote.inst_id u32→u64 (in-range byte-중립, truncation 제거).

Fixed — Markdown(GFM) 표 헤더 행 손실 (사용자 흐름 점검)

convert(Markdown → HWPX) 에서 GFM 표의 헤더 행이 통째로 사라지던 data-loss 버그. | A | B | 헤더 + | 1 | 2 | 데이터 → HWPX 에 1|2 1행만 남고 A|B 소실.

  • 원인: md 디코더가 pulldown-cmark 의 Tag::TableHead/TagEnd::TableHead 를 no-op({}) 처리 → 헤더 셀이 어느 행에도 안 붙고 드롭. 본문 행(TableRow)만 캡처.
  • 수정: TableHead 를 TableRow 처럼 처리해 헤더 셀을 표 행 0 으로 캡처 (Core/HWPX 는 행 0 을 헤더로 렌더 — to-md 가 행 0 을 md 헤더로 출력하는 것과 정합).
  • 검증: convert → HWPX 에 2행(A,B / 1,2) + to-md 라운드트립이 헤더 완전 복원.
  • 테스트: pipeline_table_roundtrip 을 2행·헤더 셀 내용 단언으로 강화(기존엔 버그를 주석으로 박제하고 있었음), 표 셀 image/link 디코더 테스트 2건 행 인덱스 정정.

Changed — BREAKING (이전 wave 누락분 명시, API audit)

코드 audit 에서 발견한, 이미 발생했으나 Breaking 으로 명시되지 않았던 public API 변경 (downstream 마이그레이션 누락 방지):

  • Control::memo(content, author, date) → Control::memo(content) 로 시그니처 축소. anchor run 이 필요하면 Control::memo_with_anchor(content, anchor_runs) 사용 (Wave 12e/f).
  • Control::Memo 에서 author: String / date: String 필드 제거 → anchor_runs: Vec<Run> + metadata: MemoMetadata 로 대체. 패턴 매칭에서 해당 필드 바인딩 제거 필요 (Wave 12e/f).
  • RefType: TryFrom<u8> public trait impl 제거 (Wave 12m Phase 2). raw HWP5 바이트 → RefType 변환은 smithy-hwp5 경계 함수로 이동. downstream 의 직접 byte 변환 코드는 깨짐.
  • blueprint::style::{CharShape, PartialCharShape} 에 #[non_exhaustive] 추가 (B3). 외부 크레이트의 struct-literal 생성 차단 — CharShape 는 PartialCharShape::resolve(), PartialCharShape 는 default() + 필드 설정으로 생성. 향후 필드 추가가 더는 breaking 이 되지 않도록 한 번에 고정 (underline_shape 추가가 이미 깨뜨린 김에).
  • blueprint::style::{ParaShape, PartialParaShape, PartialStyle} 에도 #[non_exhaustive] 추가 (B 일관화) — CharShape 쌍과 동일한 style/shape 패밀리. ParaShape 는 #[derive(Default)] 추가(가산적, 합리적 기본값) + resolve() 또는 default()+필드설정 으로 생성. (성장형이나 외부 구성이 많은 core::{Section, Paragraph} 등은 builder/Default 선행이 필요해 후속 슬라이스로 보류 — backlog 기록.)

Fixed — HWP5→HWPX 채우기 “색 없음” → faceColor="none" (P1-5, 옵션 전수조사)

HWP5 는 “배경색 없음” 을 None fill 이 아니라 Color fill + background_color = 0xFFFFFFFF (Windows COLORREF null sentinel)로 인코딩한다. colorref_to_hwpx_color 가 (raw>>24)!=0 검사를 먼저 통과시켜 faceColor="#FFFFFFFF" (흰색)을 emit했고, 한컴 native 는 faceColor="none" 을 쓴다.

  • 신규 fill 전용 헬퍼 colorref_to_hwpx_fill_color: 0xFFFFFFFF → "none", 그 외는 기존 매핑. face/hatch 색에만 적용 — 테두리 선 색은 native 가 실제 #RRGGBB 를 쓰므로 공유 함수 그대로 둠 (검증 안 된 거동 도입 방지).
  • 검증: 기존 native sample-cell-diagonal (borderFill id=2 background=0xFFFFFFFF) 변환 결과가 faceColor="none" 으로 일치, 출력에서 #FFFFFFFF 완전 제거.
  • 테스트: fill_color_maps_no_color_sentinel_to_none.

Changed — 미상 무늬/그러데이션 type warning-first (P1-3/4, 옵션 전수조사)

border_fill 의 채우기 무늬·그러데이션 type 이 알 수 없는 raw 값일 때 조용히 기본값(무늬→솔리드, 그러데이션→LINEAR)으로 떨어지던 것을 ProjectionFallback 경고로 노출. (알려진 6개 무늬·4개 그러데이션 type 은 정상 carry 되며, 무늬 None=무늬 없음 은 경고 대상 아님.)

  • 신규 경고 subject: style.border_fill.fill_pattern, style.border_fill.gradation_type (각각 border_fill_id + raw 값 포함).
  • 정상 저작으론 도달하지 않는 방어적 경로라 native fixture 불필요.
  • 테스트: unknown_hatch_pattern_warns_but_known_and_none_stay_silent, unknown_gradation_type_warns_but_known_stays_silent.

Fixed — HWP5→HWPX 이미지 채우기 모드 12종 (P1-2, 옵션 전수조사)

배경 그림 채우기(<hc:imgBrush mode>)의 16개 모드 중 4개(TILE/TOTAL/CENTER/ ZOOM)만 매핑되고 나머지 12개가 무음으로 투명 처리(fill 드롭) 되던 문제. 바둑판 가로/세로, 가운데 위/아래, 좌/우 정렬 채우기가 전부 사라졌다.

  • hwp5_image_fill_mode_to_hwpx 를 16개 모드 전부로 완성. HWP5 raw 0-15 는 OWPML ImageBrushMode enum 과 동일 순서 1:1 (raw 1=TILE_HORZ_TOP, 7= CENTER_TOP, 10=LEFT_TOP, 14=RIGHT_BOTTOM, *Middle→*_CENTER 등).
  • 검증: 사용자 작성 native sample-cell-image-fill (4 family 대표 모드 TILE_HORZ_TOP/CENTER_TOP/LEFT_TOP/RIGHT_BOTTOM) 변환 결과가 한컴 native 와 일치, 변환 경고 4→0.
  • 테스트: image_fill_mode_maps_all_16_ks_x_6101_modes (전 모드 단위).

Fixed — HWP5→HWPX 쪽 번호 형식 carry (P0-3, 옵션 전수조사)

pgnp(쪽 번호 위치) 컨트롤의 번호 모양 바이트를 전혀 읽지 않아 모든 쪽 번호가 formatType="DIGIT" 로만 나가던 문제. 로마자/한글/알파벳 쪽 번호가 조용히 아라비아 숫자로 변환됨.

  • parse_page_number_control 이 property bits 0-7 (header_data[4]) = 번호 모양(HWPNumberShape)을 읽어 NumberFormatType::try_from 으로 매핑 (위치는 기존대로 bits 8-11 = header_data[5]). HWP5 shape 코드는 NumberFormatType 과 1:1 (0=Digit, 2=RomanCapital, …).
  • 검증: 사용자 작성 native sample-pagenu-roman (로마자 대문자) 변환 결과가 한컴 native 와 byte-identical — <hp:pageNum pos="INSIDE_TOP" formatType="ROMAN_CAPITAL" sideChar="-"/>.
  • 테스트: parse_page_number_control_reads_number_shape_from_property (단위), ..._user_sample_page_number_format_matches_native (native e2e).

Fixed — HWP5→HWPX 문단 번호매기기 형식 5종 (P0-1, 옵션 전수조사)

문단 번호 형식(<hh:paraHead numFormat>) 디코딩 매핑이 KS X 6101 OWPML NumberType1 enum 과 어긋나 일부 형식이 손실/오변환됐다. 옵션 단위 전수조사 중 발견.

  • code 11: "HANJA_DIGIT" (OWPML 에 없는 무효 문자열) → CIRCLED_HANGUL_JAMO (원 ㄱ,ㄴ,ㄷ) 로 정정. 한자 숫자는 실제로 code 13 = IDEOGRAPH.
  • code 6 (CIRCLED_LATIN_CAPTION, 원 알파벳 대문자 Ⓐ), code 12 (HANGUL_PHONETIC 일,이,삼), code 13 (IDEOGRAPH 한자), code 14 (CIRCLED_IDEOGRAPH) 추가 — 이전엔 전부 무음으로 DIGIT 로 붕괴.
  • code 0~10 은 사용자 작성 native fixture sample-numbering-hangul(10수준, 9형식)로 byte 단위 일치 확인 — 가/나/다(HANGUL_SYLLABLE), ㄱ/ㄴ/ㄷ (HANGUL_JAMO) 등 정상 carry 회귀 잠금. (audit 의 “가/나/다가 아라비아로 나간다” 주장은 거짓이었음 — 코드 정독 한계, fixture 로 반증.)
  • 테스트: numbering_num_format_covers_full_ks_x_6101_enum (전 코드 단위), ..._user_sample_numbering_formats_match_native (native e2e 게이트).

Verified — HWP5→HWPX 빗금무늬(hatch fill) carry + gotcha #21 방향 스왑

빗금/역빗금 등 무늬 채우기(<hc:winBrush hatchStyle>)의 HWP5→HWPX carry 를 native 한컴 fixture 로 실측 검증. 코드 변경 없음 — 디코드/projection/인코더 경로는 이미 완성돼 있었고, 한컴 HWPX writer 의 빗금↔역빗금 문자열 스왑 (gotcha #21: 시각 빗금(/) → "BACK_SLASH", 시각 역빗금() → "SLASH") 도 이미 올바르게 반영돼 있었음.

  • fixture: 사용자 작성 native sample-charbg-hatch-{slash,backslash}.{hwp,hwpx} (글자 배경 무늬 — hatch fill 은 page/char/table border fill 에 공유되므로 동일 코드 경로를 검증). 우리 출력 winBrush 가 한컴 native 와 byte-identical (faceColor="#E5E5E5" hatchColor="#CA56A7" hatchStyle="BACK_SLASH"/"SLASH").
  • 회귀 게이트: ..._charbg_hatch_carries_swapped_pattern_direction.
  • Windows-deferred: 쪽 테두리/배경(페이지) 무늬 fixture 는 macOS 한글 [쪽] 메뉴에 항목 자체가 없어 작성 불가 → Windows 한글 fixture 대기 (masterPage gap C / non-chart OLE 와 동일 차단). 단 hatch fill 자체는 위에서 공유 검증됨.

Added — HWP5→HWPX 다단(multi-column / <hp:colPr>) carry

한 구역을 2단/3단 신문형으로 나눈 다단을 HWP5→HWPX 변환에서 보존; 이전엔 cold ctrl 을 마커로만 필터하고 단 개수를 항상 colCount="1" 로 하드코딩해 단 정보가 손실됐다.

  • HWP5 디코더: cold(CTRL_ID_COLUMN_DEF) ctrl payload 파싱 — [4..6] u16 property (bits 2-9 = 단 개수), [6..8] u16 단 간격(HWPUNIT). secd 사이드카 캡처 패턴 미러로 SectionResult.column_def 에 저장.
  • Projection: col_count >= 2 면 Section.column_settings = ColumnSettings::equal_columns(count, gap). 단일 단은 None 유지(인코더 기본값).
  • 인코더/Core: 변경 없음 — Section.column_settings 와 build_col_pr_xml 가 이미 multi-column emit + HWPX round-trip 지원. HWP5 leg 만 비어 있던 것.
  • 검증: 사용자 작성 sample-multicolumn.hwp (2단) 변환 결과 colPr 가 native 와 byte-identical (colCount="2" sameSz="1" sameGap="2268"), 0 warnings. 디코더 단위 테스트(ctrl_header_cold_captures_column_def) 추가. nextest/clippy clean, 한컴 시각 게이트 PASS.

Fixed — Blueprint 저작 시 밑줄 선종류(underline shape) 손실

Blueprint(YAML 템플릿 / 빌더 API)로 만든 문서의 밑줄이 선종류와 무관하게 항상 SOLID 로 나가던 문제. Core breaking (additive): CharShape / PartialCharShape 에 underline_shape 필드 추가 (strikeout_shape 는 이미 있었으나 underline_shape 만 누락돼 있었음).

  • 근본 원인: style_store.rs 의 Blueprint→HwpxCharShape 브리지가 underline_shape: UnderlineShape::Solid 를 하드코딩 — Blueprint 에 읽을 필드가 없었기 때문.
  • 수정: blueprint/style.rs 에 underline_shape 추가 (PartialCharShape 은 Option, CharShape 는 UnderlineShape 기본 Solid) + merge() / resolve() thread, 하드코딩을 cs.underline_shape 로 교체.
  • 범위 메모: HWP5→HWPX 변환과 HWPX→HWPX round-trip 경로는 이미 밑줄/취소선 12종 선종류를 완전히 carry 하고 있었음 (Foundation UnderlineShape/StrikeoutShape + HWP5 decoder + HWPX encoder/decoder 모두 완비). 이번 수정은 Blueprint 저작 경로 전용.
  • 검증: nextest 통과 (+ 비-Solid 밑줄 carry 회귀 테스트 + serde round-trip 테스트). 생성기 examples/underline_shapes.rs 산출물이 SOLID/DASH/DOT/DASH_DOT/DASH_DOT_DOT/LONG_DASH/DOUBLE_SLIM/WAVE 밑줄 + SOLID/DASH/DOUBLE_SLIM/WAVE 취소선을 distinct 하게 emit, 한컴 시각 게이트 PASS (이중선 2줄, 물결 곡선 정상 렌더링).

Added — HWP5↔HWPX TextArt(글맵시 / <hp:textart>) carry

한컴 글맵시(워프된 장식 문자)를 HWP5→HWPX 변환에서 보존 (이전엔 통째로 drop). Core breaking (additive): Control::TextArt { text, shape, font_name, font_style, align, line_spacing, char_spacing, width, height, horz_offset, vert_offset, fill_color, inst_id } 신설 + validate.rs 가 TextArt 를 도형 family 로 검증/그룹 자식 허용.

  • Wire 발견: TextArt 는 gso ShapeComponent(0x4C) 의 comp_type 판별자 "$tat" 가 ShapeTextArt(0x5A) sub-record 를 감싸는 구조 (0x5A 는 dead 가 아니라 TextArt 전용으로 사용됨 — WIRE_SPEC §10 정정). 0x5A 레이아웃: pt0..3 (32B) + BSTR text/fontName/fontStyle + u32 fontType(1=TTF)/textShape(0..54)/lineSpacing/charSpacing/align(0=LEFT) + 20B shadow tail.
  • textShape enum (55종): HWP5 정수 = 글맵시 모양 그리드 위치, HWPX 문자열은 native 출력에서 추출. 사용자가 작성한 56-textart fixture 로 전체 테이블 (PARALLELOGRAM=0 … WAVE2=17 … DOUBLE_LINE_CIRCLE=54) 을 한 번에 확정 (TEXTART_SHAPE_NAMES).
  • HWP5 디코더: Hwp5ShapeTextArt 스키마 + $tat/0x5A 를 4개 gso 컨텍스트에 ellipse 미러로 thread, classify_gso_control 에서 Hwp5Control::TextArt 조기 분류.
  • Projection → Control::TextArt (textart_shape_name/textart_align_name 으로 정수→문자열, 범위 밖이면 경고+fallback).
  • HWPX 인코더: <hp:textart> 직접 emit (renderingInfo scaMatrix = curSz/orgSz 계산, lineShape NONE, fillBrush, pt0-3, textartPr, shapeComment).
  • HWPX 디코더: <hp:textart> → Control::TextArt round-trip (HxTextArt).
  • 검증: workspace nextest 통과(+신규 textart 스키마/인코더/테이블 테스트), clippy -D warnings clean. 사용자 작성 sample-gso-textart-all.hwp (56 글맵시, 55 distinct shape) 변환 결과 textShape 55종 전부 보존, 0 drop, HWP5→HWPX→JSON round-trip 56개 유지. scaMatrix/orgSz/curSz native 일치.

Added — HWP5↔HWPX 묶음 객체(group / <hp:container>) carry (Wave A, flat groups)

한컴 “개체 묶기“로 묶인 그리기 객체(group)를 HWP5→HWPX 변환에서 보존 (이전엔 통째로 drop). Core breaking (additive): 재귀 Control::Group { children: Vec<Control>, width, height, horz_offset, vert_offset, inst_id } 신설 + validate.rs 가 비-도형 자식을 ValidationError::InvalidGroupChild 로 거부.

  • Wire 발견: container 는 별도 TagId(0x56) 가 아니라 gso ShapeComponent(0x4C) 의 comp_type 판별자 "$con" (line "$col" / rect "$rec" / ellipse "$ell" 와 동일 메커니즘). 자식은 한 단계 깊은 ShapeComponent 들이고 각자 기존 shape sub-record(0x4F/0x50/…) 보유.
  • HWP5 디코더: gso 스코프를 단일-Option flat 상태머신에서 GsoGroupBuilder/GsoChildBuilder 스택으로 재구성 (기존 table_stack 패턴, architect 리뷰 P0). 자식 geometry 는 자식 ShapeComponent common header 에서 파싱 (Hwp5ShapeComponentGeometry::parse_from_shape_component: x=[4..8], y=[8..12], w=[16..20], h=[20..24] — native 바이트 대조로 도출). Wave A 는 flat 만; 중첩 $con 은 depth cap(GSO_GROUP_MAX_DEPTH) 으로 warn+degrade.
  • HWPX 인코더: <hp:container> 재귀 emit. 자식 위치는 한컴이 <hc:transMatrix> translation(e3=x, e6=y)으로 잡으므로 그것을 설정 (identity matrix 면 전부 원점에 겹침 — 시각 검증으로 확인); <hp:offset> 도 동일 값으로 mirror, top-level <hp:sz>/<hp:pos> 는 자식에서 제거, <hp:curSz> 는 0×0 (native 일치).
  • HWPX 디코더: <hp:container> → Control::Group round-trip.
  • 검증: workspace nextest 통과, clippy clean, 변환 산출물 geometry 가 native sample-gso-group.hwpx 와 byte 일치 (offset/transMatrix/orgSz/ curSz/container sz·pos), 한컴 시각 게이트 PASS (직사각형+타원 나란히, 텍스트 “사각형”/“타원” 보존, 겹침 없음). 중첩 그룹 재귀는 Wave B.

Added — HWP5↔HWPX 중첩 묶음 객체($con-in-$con) 재귀 carry (Wave B)

Wave A 가 flat 그룹만 보존한 데 이어, 그룹 안의 그룹($con 이 $con 을 다시 품는 구조)을 재귀적으로 보존. Core 변경 없음(Control::Group 가 이미 재귀형 Vec<Control>); 4개 레이어가 재귀를 타도록 확장.

  • HWP5 디코더: GsoGroupBuilder.current_child 를 Option<GsoChildBuilder> → Option<GsoActiveChild> 로 교체. GsoActiveChild::{Leaf(GsoChildBuilder), Nested(Box<GsoGroupBuilder>)} 로 중첩 $con 은 자식 GsoGroupBuilder 를 열어 재귀 (Box 로 GsoGroupBuilder → GsoActiveChild → GsoGroupBuilder 타입 cycle 차단). GSO_GROUP_MAX_DEPTH 초과 시에만 leaf 로 degrade → Unknown(경고).
  • Projection: project_group_child 에 Hwp5Control::Group(nested) => project_group_run(...) arm 추가 (중첩 그룹 자식 재귀).
  • 레이아웃 힌트: collect_group_child_layout_hints 가 자식이 중첩 그룹이면 재귀 — 그러지 않으면 inner 그룹의 텍스트 자식 <hp:p> 가 hint 없이 emit 되어 paragraph layout hint count underflow 발생.
  • HWPX 인코더: encode_group_child_xml 에 Control::Group early-return 추가 — encode_group_to_xml 로 재귀 후 transMatrix/offset/curSz/sz·pos 를 다른 자식과 동일하게 처리 (groupLevel 은 재귀 내부에서 +1 baked).
  • HWPX 디코더: HxContainer.containers: Vec<HxContainer> 필드 + decode_container 가 중첩 container 재귀, MAX_NESTING_DEPTH(32) depth guard.
  • 검증: workspace nextest 통과, clippy clean. 변환 산출물이 native sample-gso-group-nested.hwpx 와 구조·geometry byte 일치 (groupLevel 0/1/2/2/1, inner container identity matrix, ellipse e3=1164/e6=6512, line e3=525/e6=13422, 전 자식 curSz 0×0 + top-level sz/pos 없음). 한컴 시각 게이트 PASS.

Fixed — SUMMERY/PATH 필드 빈 본문 → 한컴 “낮은 보안 수준 복구” 경고 (#120/#136)

HWP5 → HWPX 변환 시 문서정보(SUMMERY: $author/$title/$createtime/ $modifiedtime/$lastsaveby)·경로(PATH: $P$F) 필드의 <hp:fieldBegin>…<hp:fieldEnd> 본문이 빈 <hp:t/> 로 나가 한컴이 필드를 미해결로 보고 “낮은 보안 수준으로 복구” 경고 + 첫 열기 빈 placeholder 를 남기던 문제.

  • 진단: byte-diff 로 빈 본문이 유일 구조 차이임을 확인하고, 우리 출력에 native 값만 주입한 격리 파일로 한컴 실측 (경고 없음) 하여 본문 값이 원인임을 확정. 한컴 native HWPX 는 본문에 resolved 값을 캐싱하며 그 값은 HWP5 원본 BodyText/Section0 ParaText 의 FieldBegin..FieldEnd span 에 이미 존재. Wave 12n Step 6.6 이 “빈 본문이 경고를 회피한다” 던 주석은 틀렸음 — 당시 거부된 건 합성 ISO 날짜 (locale 불일치) 였지 verbatim 값이 아니었다.
  • Core (breaking, additive): Control::Field/UnknownSummery/ DateCodeField/PathField 에 display_text: String 추가 (CrossRef::display_text 와 동일 형태/의미, 빈 문자열 = 없음). ClickHere 는 빈 값 유지 (visible placeholder 는 hint_text).
  • HWP5 projection: FieldBegin..FieldEnd span 을 display_text 로 누적 (Hyperlink/CrossRef 와 동일 경로) + DoS cap (MAX_FIELD_DISPLAY_TEXT_UNITS = 4096, body 가 BSTR command cap 우회).
  • HWPX encoder/decoder: 본문에 캐싱값 emit + round-trip 복원 (디코더가 run body 텍스트를 display_text 로 환원).
  • 검증: workspace nextest 2,469 통과, 변환 산출물 field body 가 native 안정값과 일치 (날짜/경로는 출처 파일 차이만), 한컴 시각 게이트 (경고 없음 + 첫 열기 값 표시) PASS.

Fixed — HWP5→HWPX 차트 편집 시나리오 (크기 + custom title)

HWP5 → HWPX 변환본의 차트를 to-json → 값 편집 → from-json 으로 재생성하는 체인을 end-to-end 검증하며 발견된 2건:

  • 차트 표시 크기: projection 이 ShapeComponentOle extent (내부 캔버스, 상수 7200×7200) 를 hp:sz 로 사용해 변환 차트가 ≈2.5cm 로 축소되던 버그. 표시 프레임은 gso CtrlHeader geometry [16..24] (HWPUNIT) — 한컴 native HWPX 쌍의 hp:sz 32250×18750 과 byte 일치 (probe_chart_geometry 로 확정). geometry 우선 + extent fallback 으로 수정; encoder 의 orgSz/extent 7200 hardcode 는 native 와 일치라 유지. e2e 게이트에 native 크기 단언 추가.
  • custom title 형태: write_title 의 최소형 (<a:bodyPr/><a:lstStyle/> + 빈 <a:rPr lang="ko-KR"/>) 은 표준 OOXML 로는 유효하지만 한컴 native 형태와 다름. 사용자 작성 sample-chart-title.hwpx fixture 에서 한컴의 실제 custom title 형태를 probe 해 byte-convention 미러링으로 교체: fully-attributed bodyPr, lstStyle 제거, pPr/defRPr+rPr 에 sz=1400+함초롬돋움 4종, trailing endParaRPr. 단위 게이트 write_title_mirrors_hancom_native_form 추가.

시각 검증: 변환 → 판매 값 [10,3.5,1.5,1.2]→[1,2,3,4] 편집 + 제목 추가 → 재생성본이 한컴에서 정상 크기 프레임 + 제목 + 분리형 파이 (explosion 25% 보존) 로 렌더링 확인.

Refactor (tasks #88/#89/#90/#91/#92/#94/#95) — Wave 12 누적 부채 정리

기능 영향 0 (모든 step 에서 workspace nextest 전체 통과로 검증), 코드 구조만 개선:

  • #94 CTRL_ID 상수 33개 선언 (4개 파일, 9개 중복 그룹) → smithy-hwp5/src/ctrl_ids.rs 단일 모듈 25개 canonical 상수. drift 이름 정리: SECTION_DEF→SECD, CROSSREF→FIELD_CROSSREF, FIELD_INLINE_PAGE/INLINE_AUTONUM→ATNO, INDEXMARK_INLINE→INDEXMARK.
  • #95 Wave 12i/12k 공유 split-leader / length-prefixed UTF-16 BSTR 파서를 parse_split_leader_utf16 / parse_length_prefixed_utf16 helper 로 통합 (Dutmal main/sub, IndexMark primary/secondary). Compose (12j) 는 length prefix 가 없는 다른 wire 라 의도적으로 제외.
  • #88 parse_name_subrecord 의 Option<Option<String>> → ClickHereNameSubrecord { Named / Unnamed / Malformed } named enum.
  • #89 Hwp5ClickHereControl::parse → Result<_, ClickHereParseError> (TruncatedHeader / CommandTooLong / TruncatedCommand / CommandSyntax) — DroppedControl warning 에 구체 사유 표기.
  • #90 handle_top_level_record ~425줄 → 71줄 dispatcher + 4 helper (try_intercept_memo_cluster, try_attach_clickhere_name, handle_ctrl_header, handle_eqedit_record).
  • #91 project_paragraph_with_images_structural ~225줄 → 135줄 + 3 helper (project_visible_text_segment, start_field_from_marker, drain_unconsumed_paragraph_queues).
  • #92 smithy-hwpx/encoder/section.rs 5,481줄 → 3,765줄 (잔여 중 ~2,760줄은 root 테스트 모듈). 기존 section/table.rs 선례 패턴 (mod X; + use super::*; + pub(super) fn) 으로 8개 family 모듈 신설: field(694) / section_pr(280) / header_footer(245) / memo(169) / chart(152) / picture(139) / equation(66) / typography(64). root 재수입으로 호출처/테스트 무변경, 본문 verbatim 이동. 같은 crate 내 모듈 분리라 runtime 성능 영향 0.

Docs (task #72) — HWP5 wire spec (HwpForge-internal)

Added crates/hwpforge-smithy-hwp5/HWP5_WIRE_SPEC.md — code-grounded HWP5 binary format documentation capturing Wave 12 series discoveries that the public KS X 6101 / Hancom spec omits:

  • ParaHeader [18..22] instance_id field (Wave 12p Step 1)
  • Family-aware CtrlHeader instance_id offsets (fn/en at 16, gso/tbl/eqed at 36, Wave 12p Step 5)
  • ParaShape property1 bits 25-27 are zero-based ordinal cap=6 (Wave 12p #121)
  • Style “개요 N” / “Outline N” outline-level override for levels 7~9 (Wave 12q #122)
  • Default linesegarray synthesis values for paragraphs lacking ParaLineSeg (Wave 12p #123)
  • editable attribute per FieldType (Wave 12p #124)
  • BSTR length-prefix allocation caps (MAX_*_UNITS family, Wave 12 + task #86)
  • CTRL_ID magic constant inventory across 24 entries (3 source files, prelude to task #94 consolidation)
  • SummaryInformation OLE2 PropertySet layout incl. Hancom custom PIDs 0x14/0x15 (Wave 12o)
  • Cross-reference Command 8-parameter Hancom-canonical wire (Wave 12m, ADR-004)

Each topic links back to the canonical source file/symbol so future contributors can grep this file before re-running probes.

Linked from crates/hwpforge-smithy-hwp5/AGENTS.md for discoverability.

Wave 12q (task #122) — outline level 7~9 recovery via Style “개요 N” linkage

HWP5 ParaShape.property1 bit 25-27 은 3 bits 만 표현 가능 (cap=6). 한컴 native 는 outline level 7~9 를 Style record 의 한국어 이름 “개요 N” (N-1 = HWPX level) 으로 표현. 변환 후 paraPr 의 heading_level 을 Style “개요 N” 매핑으로 override 하여 native parity 달성.

Fixed

  • hwpforge-smithy-hwp5: apply_outline_style_level_overrides() — ParaShape 변환 후 Style 테이블에서 “개요 N” / “Outline N” 패턴 매칭 → para_shape_id 가 가리키는 paraPr 의 heading_level 을 N-1 로 override. 한컴이 wire cap=6 으로 저장한 level 7/8/9 가 정확히 emit.
  • override 는 silent (warning 없음) — semantic loss 가 아닌 lossless level recovery 이므로 audit warning_count 에 영향 없음.

Added — hwpforge-smithy-hwpx

  • HwpxStyleStore::para_shape_mut() — Wave 12q level override 용 mutable accessor.

검증

  • sample-outline-9levels.hwp (사용자 작성 native fixture) 변환 결과:
    • paraPr id 2~8 level 0~6: native parity ✅
    • paraPr id 18/16/17 level 7/8/9: hp10 namespace switch wrap 없이도 한컴이 정상 인식 ✅
  • 한컴 시각 검증: 1~7수준 1./가./1)/가)/(1)/(가)/①, 8수준 ㉠, 9~10수준 marker 없음 (native 와 byte-identical 매칭).
  • Codex(architect) 검토 반영: paraPr id 자체에 의존 안 함, heading_type 이 Outline 인 paraPr 만 override.

ADR 참조: .docs/architecture/adr/ADR-006-wave12p-task122-outline-level-7-9-diagnostics.md

Wave 12p tasks #121/#123/#124 — outline/linesegarray/editable fidelity

Fixed (#121) — hwpforge-smithy-hwp5

  • Hwp5RawParaShape::heading_level() 이 saturating_sub(1) 로 wire 를 1-based 로 잘못 가정 → 0-based 그대로 사용. HWP5 spec bit 25-27 (3 bits) 가 zero-based ordinal 0~7. HWPX <hh:heading level> 도 zero-based. Codex(architect) 검토 확인.
  • 검증: native sample-outline-9levels.hwpx 의 paraPr id 2~8 level 0~6 가 우리 emit 와 완전 일치.

Fixed (#123) — hwpforge-smithy-hwp5

  • layout_hint_patch::write_linesegarray(): HWP5 source 의 ParaLineSeg (tag 0x45) record 가 없는 paragraph 도 default lineseg 로 <hp:linesegarray> 항상 emit. 이전엔 누락 → 한컴이 “낮은 보안 수준 복구” 경고.
  • Default 값 (native fixture 도출): vertsize=1000, textheight=1000, baseline=850, spacing=600, horzsize=42520 (A4 content width), flags=393216. vertpos=0 — 한컴이 paragraph 순서 따라 재계산.

Fixed (#124) — hwpforge-foundation + hwpforge-smithy-hwpx

  • FieldType::hwpx_editable() 신규 method — Author/Title → false, LastSavedBy/CreatedTime/ModifiedTime → true (한컴 native fixture 도출). 이전엔 모든 SUMMERY field 가 editable="1" 강제됨.
  • build_summery_run_xml_raw() 시그니처 확장 (editable: bool 파라미터).
  • 검증: sample-field-docsummary.hwp 변환 결과 8/8 SUMMERY field 가 native editable 값과 일치.

Wave 12p — cross-ref target element instance ID carry (BREAKING, partial)

Wave 12m 시각 검증의 잔존 이슈 (HWP5 변환본의 footnote/endnote/figure/ table/equation cross-ref 가 한컴에서 ? 표시) 해소 작업. Steps 1-4 완료, Step 5 (HWP5 → HWPX target ID 매칭 알고리즘) 는 후속 작업.

ADR 참조: .docs/architecture/adr/ADR-005-wave12p-target-element-instance-id-carry.md

Breaking — hwpforge-foundation

  • RefContentType::BookmarkName variant 부활 (Wave 12m fixup regression revert). Bookmark N2 매핑 native 일치 보정:
    • N2=0 → Page, N2=1 → Number (책갈피 본문/번호)
    • N2=2 → BookmarkName (책갈피 이름), N2=3 → UpDownPos
  • Display 는 Contents 와 BookmarkName 모두 OBJECT_TYPE_CONTENTS emit (한컴 wire 일치, 의미는 RefType + N2 wire code 에서 결정).

Breaking — hwpforge-core

  • Image 에 pub inst_id: Option<u64> 신규.
  • Table 에 pub inst_id: Option<u64> 신규.
  • Control::Equation variant 에 inst_id: Option<u64> 신규.
  • 모두 #[non_exhaustive] + Default::default() 호환이라 builder 사용 시 caller 코드 변경 불필요.

Added — hwpforge-smithy-hwp5

  • Hwp5ParaHeader.instance_id: u32 (Step 1a) — HWP5 ParaHeader [18..22] 의 u32 LE 추출. outline cross-ref target ID source.
  • Hwp5NestedSubtree.instance_id: u32 (Step 1b) — Header/Footer/Footnote/ Endnote CtrlHeader trailer.
  • Hwp5Table.instance_id: u32 (Step 1c-1) — Table CtrlHeader trailer.
  • Hwp5EquationControl.instance_id: u32 (Step 1c-2) — eqed CtrlHeader trailer.
  • Hwp5ImageControl.instance_id: u32 (Step 1c-3) — gso CtrlHeader trailer (via NestedSubtreeContext + InlineGsoContext).
  • Helper extract_ctrl_header_trailer_instance_id(&[u8]) -> u32 — 마지막 8 bytes 중 first 4 의 u32 LE.

Changed — projection / encoder

  • HWP5 projection: 6종 target element 의 instance_id 를 Core inst_id 로 통과 (0 은 unset 으로 None 정규화).
  • HWPX encoder: <hp:footNote instId="N">, <hp:endNote instId="N">, <hp:equation id="N">, <hp:tbl id="N">, <hp:pic id="N"> 모두 Core inst_id 가 있으면 사용, 없으면 sequential generate_instid fallback.

Deferred (Step 5, 후속 작업)

Probe 결과 (crates/hwpforge-smithy-hwp5/examples/probe_instance_id.rs): HWP5 binary 의 footnote/endnote CtrlHeader payload 는 자기 자신의 instance ID 를 carry 하지 않음 (한컴이 save 시 session counter 로 synthesize). cross-ref Command 는 target ID 를 carry 하지만 target element 의 ID 는 wire 에 없음.

결과:

  • Forged HWPX path (caller 가 Image::new(...).inst_id = Some(N) 설정): ✅ 정상 동작 (encoder 가 wire 에 emit)
  • HWP5 → HWPX 변환 path: ❌ cross-ref 가 여전히 ? 표시 (target element inst_id = None, encoder skip)

Step 5 알고리즘 (ADR-005 §“Step 5 Algorithm” 에 plan 상세):

  1. Section 별 cross-ref Command target_id 들을 pre-scan + RefType 별 grouping
  2. Doc 순서대로 target element 에 그 IDs 할당 (1:N dedup 처리)
  3. cross-ref Command 는 as-is (HWP5 wire 그대로)

Step 5 land 시 HWP5 conversion path 도 cross-ref 정상 동작.

신규 examples / probe

  • crates/hwpforge-smithy-hwp5/examples/probe_instance_id.rs — debug: HWP5 fixture 의 projection inst_id 확인

검증

  • cargo nextest run --workspace --all-features: 2,463 passed, 2 skipped
  • cargo clippy --workspace --all-features --all-targets -D warnings: clean
  • 한컴 시각 검증: forged path 만 동작 확인 (HWP5 conversion path 는 Step 5 대기)

Wave 12m fixup — fieldid %xrf magic constant + RefContentType::BookmarkName 폐기 (BREAKING)

Wave 12m Phase 2 시각 검증 (한컴오피스 한글) 에서 cross-ref body 가 ? 로 표시되는 회귀 발견 → 2단계 research (1차 + 재검증) 후 두 결정적 차이 fix.

Breaking — hwpforge-foundation

  • RefContentType::BookmarkName variant 폐기. OWPML 표 156 은 ContentType 을 4종 (PAGE / NUMBER / CONTENTS / UPDOWNPOS) 만 정의 하며, 책갈피의 경우 Contents 가 “책갈피 내용/이름” 의미를 내포함 (spec 명시: “참조 대상의 제시 내용 또는 책갈피의 경우, 책갈피 내용”). Wave 12m Phase 2 Step 3 의 BookmarkName enum + OBJECT_TYPE_BOOKMARK_NAME emit 은 spec 외 invented string 으로 한컴 인식 실패. HWP5 N2 code 2 for Bookmark → RefContentType::Contents 로 매핑.

Fixed — hwpforge-smithy-hwpx

  • build_crossref_run_xml 의 fieldid 가 sequential counter (1_828_000_000 + N) 가 아니라 Hancom %xrf ASCII magic constant (0x25787266 = 628_650_598) 로 emit. native HanCom-authored HWPX 11 sample 전수 분석 (n=11) 에서 모든 CROSSREF 가 동일 magic constant 사용 확인. per-instance identity 는 id (begin_id) 가 carry. HwpForge 다른 native byte-identical 검증된 field 와 일관: ClickHere=%clk, SummeryField=%smr, PathField=%pat.
  • HWP5 projection boundary decode_hwp5_crossref_content_type: Bookmark
    • N2=2 → Contents (이전 BookmarkName). 의미는 RefType-상대적 (“책갈피 이름”).
  • HWPX encoder reverse boundary ref_content_type_wire_code: Contents → 모든 RefType 에서 N2=2 (Bookmark=“책갈피 이름”, Figure/Table/Eq/ Outline=“캡션 내용”).

Regression gates

  • crossref_builders_emit_nonzero_matching_fieldid: fieldid 기댓값 1828000000 → 628650598 변경. assertion 메시지 “non-zero derived” → “%xrf magic constant” 로 강화.

시각 검증 결과 (한컴오피스 한글 직접 열기)

케이스이전현재
Bookmark+Page (Point)?1 ✅
Bookmark+Page+Hyperlink (Point)?1 ✅
Bookmark+Contents (Span)(미검증)본문 표시 ✅
Bookmark+Contents (Point)?? (정상 — 본문 없음)

Point bookmark 의 Contents reference 는 본문이 없어 한컴이 ? 표시 — 우리 wire 형식은 정상. caller 가 SpanStart/SpanEnd 책갈피를 만들면 한컴 이 범위 안 본문을 표시.

추가 발견 (별도 task)

  • <hp:endNote> / <hp:footNote> / <hp:figure> / <hp:table> 등 cross-ref target 이 될 수 있는 elements 에 instId attribute 가 emit 되지 않음. 한컴 cross-ref Command 의 ?#<id> target lookup 이 실패하여 endnote/footnote/caption cross-ref 가 ? 표시. Wave 12m 범위 밖 — task #134 로 분리.

새 examples (시각 검증용)

  • crossref_matrix.rs — RefType × ContentType 8-permutation HWPX
  • crossref_with_target.rs — Point bookmark + cross-ref 4종
  • crossref_span_bookmark.rs — Span bookmark + Contents reference 검증

검증

  • cargo nextest run --workspace --all-features: 2,463 passed, 2 skipped
  • cargo clippy --workspace --all-features --all-targets -D warnings: clean

Wave 12m Phase 2 — Control::CrossRef HWP5 leg structured upgrade (BREAKING)

HWP5 %xrf 상호참조 필드를 Control::Unknown(tag="hwp5.crossref") surrogate (Wave 12 이전 lossy 경로) 대신 typed Hwp5CrossRefControl schema → boundary functions → native Control::CrossRef 로 end-to-end carry. 사용자 시각 검증 가능한 12 한컴 native fixture (tests/fixtures/hwp5/crossref/) e2e 회귀 게이트 동반.

ADR 참조: .docs/architecture/adr/ADR-004-wave12m-crossref-structured-upgrade.md (내부 문서).

Breaking — hwpforge-foundation

  • RefType (enum) — #[repr(u8)] 제거 + #[non_exhaustive] 추가. 신규 variants: Footnote, Endnote, Outline, Unknown(u8). 기존 TryFrom<u8> impl 제거 (boundary 책임을 smithy-hwp5 로 이동). RefType 크기 1 byte → 2 bytes (variant + discriminant).
  • RefContentType (enum) — #[repr(u8)] 제거 + #[non_exhaustive] 추가. 신규 variants: BookmarkName, Unknown(u8). 동일 크기 변화.

Breaking — hwpforge-core

  • Control::CrossRef — target_name: String 필드를 type-safe target: RefTarget 로 교체. 신규 RefTarget 열거형 (Name(String) for Bookmark, SystemId(u64) for #<id> refs, Raw(String) for unparseable fallback). Control::cross_ref(...) 생성자 시그니처도 연동 변경.
  • Control::CrossRef 에 display_text: String 필드 추가. HWPX wire 는 <hp:fieldBegin> / <hp:fieldEnd> 사이 visible run 으로 display text 를 embedding 한다. HWP5 %xrf wire 는 display text 를 직접 carry 하지 않고 ParaText 본문에 풀어 두지만, projection 이 FieldBegin..FieldEnd span 을 읽어 이 필드에 채워 넣는다. 빈 문자열은 “display text 없음” 의미.
  • JSON 호환성: 의도된 clean break. 기존 target_name / surrogate JSON 도 마이그레이션 없이 변경.

Added — hwpforge-smithy-hwp5

  • schema::section::Hwp5CrossRefControl — 9-field wire-fidelity 구조 (ctrl_id, command_raw, target_raw, ref_type_code, content_type_code, hyperlink_code, param4_raw, header_flag_raw, trailer_begin_id, trailer_field_id). MAX_CROSSREF_COMMAND_UNITS = 1024 cap 으로 할당 전 차단. 13 unit tests (security gates 포함).
  • decoder::section::Hwp5Control::CrossRef(Hwp5CrossRefControl) variant
    • CTRL_ID_FIELD_CROSSREF = 0x2578_7266 (“%xrf”) dispatch. malformed payload 는 Hwp5Warning::DroppedControl{control: "crossref"} 로 떨어진다 (silent skip 금지).
  • projection:: Boundary functions: decode_hwp5_crossref_ref_type (0~6 + Unknown(u8)), decode_hwp5_crossref_content_type (RefType-relative: Bookmark=1→Contents/2→BookmarkName, 그 외는 1→Number/2→Contents, 3→UpDownPos), decode_hwp5_crossref_target (Bookmark→Name, #<u64>→SystemId, 실패→Raw).
  • semantic::Hwp5SemanticControlKind::CrossRef 신규 variant + semantic_adapter 매핑.

Added — hwpforge-smithy-hwpx

  • Reverse boundary helpers: ref_type_wire_code(&RefType) -> u8, ref_content_type_wire_code(&RefType, &RefContentType) -> u8, crossref_target_for_command(&RefTarget, &RefType) -> String.
  • build_crossref_run_xml 가 Hancom-canonical 8-parameter form (Fiexde=1 / Prop=0 / Command=?{target};N1;N2;N3;0; / RefPath=?{target}; / RefType / RefContentType / RefHyperLink / RefOpenType=HWPHYPERLINK_JUMP_CURRENTTAB) 직접 emit. 시그니처: 1번 인자 target_name: &str → target: &RefTarget (target 종류별 정확한 emit).

Changed — hwpforge-smithy-md

  • Markdown encoder 의 Control::CrossRef arm 이 display_text 가 비어 있지 않으면 그대로 emit (사용자가 본 visible 문자열). 비어 있을 때만 target.as_display() 로 fallback (Name → “bookmark1”, SystemId → “#5”) 하고 [...] anchor brackets 로 wrap.

Removed (clean break)

  • hwpforge-smithy-hwp5::projection::HWP5_CROSSREF_UNKNOWN_TAG constant ("hwp5.crossref")
  • parse_crossref_target_name, encode_hwp5_crossref_unknown_data (smithy-hwp5 projection)
  • parse_hwp5_crossref_unknown_data, Hwp5CrossRefUnknownPayload (smithy-hwpx encoder), HWP5_CROSSREF_UNKNOWN_TAG const
  • HWPX encoder 의 Control::Unknown { tag == HWP5_CROSSREF_UNKNOWN_TAG } branch — projection 이 더 이상 emit 하지 않음.
  • build_hwp5_crossref_run_xml 는 fieldid 회귀 게이트 목적으로 #[cfg(test)] 유지.

Decoder — HWPX (Wave 12m Phase 2 Step 4)

  • <hp:fieldBegin type="CROSSREF"> 가 RefPath 의 #<u64> 를 RefTarget::SystemId 로 정규화, Bookmark refs (ref_type == Bookmark) 는 RefTarget::Name, 그 외는 RefTarget::Raw fallback. display_text capture 는 후속 wave (FieldBegin/FieldEnd 사이 sibling run 누적).

Regression gates

  • 신규 (Step 2): 12 fixture parse 회귀 게이트 (schema::section::tests::crossref_parse_*) — 모든 wire 변형의 Command 파싱 검증.
  • 신규 (Step 6): hwp5_to_hwpx_crossref_12_fixture_matrix_emits_typed_control_and_canonical_wire — 12 한컴 native fixture 의 end-to-end 변환 검증 (RefType / Hancom-canonical 8-param form / fieldid 양수).

검증

  • cargo nextest run --workspace --all-features: 2,463 passed, 2 skipped (Wave 12n Step 6 baseline 2,445 → 2,463, Wave 12m Phase 2 +18 신규 게이트).
  • cargo clippy --workspace --all-features --all-targets -D warnings: clean.

Wave 12n Step 6 — %pat PATH 필드 lossless HWPX carry

Wave 12n Step 3 에서 placeholder 로 남겨두었던 Control::PathField 의 HWPX wire 매핑을 native 형식으로 완성. #120 (한컴 “낮은 보안수준 복구” 경고의 가장 강한 트리거) 해소.

Fixed — HWPX encoder

  • Control::PathField { command } arm 이 더 이상 LOSSY SUMMERY surrogate 를 emit 하지 않고 <hp:fieldBegin type="PATH" name="" editable="0" dirty="0" zorder="-1" fieldid="628121972" metaTag="">
    • <hp:stringParam name="Format">$P|$F|$P$F</hp:stringParam> 를 직접 emit. 한컴 native 와 byte-identical (단 id 카운터 제외). Body 는 empty — 한컴이 저장 시 $P / $F / $P$F 를 실제 on-disk 경로 / 파일명으로 재평가.

Added — HWPX decoder

  • <hp:fieldBegin type="PATH"> 인식 분기 신설. Format param 우선, 없으면 Command 로 fallback. PathFieldCommand::from_wire(&cmd) 로 typed variant (Path / FileName / PathAndFileName) 또는 Unknown(s) 로 carry.

Regression gates (+2, -1)

  • 신규: pathfield_emits_native_path_wire — encoder wire 형식 검증 (type="PATH" / fieldid="628121972" / editable="0" / Format 사용 / Property 미사용)
  • 신규: pathfield_roundtrip_preserves_command_lossless — PathAndFileName / Path / FileName 세 variant 모두 lossless round-trip 검증
  • 신규: pathfield_unknown_command_roundtrips_as_unknown — 비표준 $X Command 도 PathFieldCommand::Unknown("$X") 로 carry
  • 제거: 기존 lossy_roundtrip_pathfield_becomes_unknown_summery — 이제 lossless 이므로 의도 상충. lossy 사실을 확정하던 단언이 모두 lossless 단언으로 대체됨.
  • 제거: 기존 lossy_pathfield_emits_summery_with_raw_command — 마찬가지 이유.

검증:

  • workspace nextest: 2,444 → 2,445 passed + 2 skipped (+3 신규, -2 폐기)
  • end-to-end: sample-field-docsummary.hwp 변환 결과의 PATH 필드 wire 가 한컴 native sample-field-docsummary.hwpx 와 byte-identical (single field id 카운터 차이만 존재).

Note — #120 보안 경고 보조 트리거 잔존

PATH 필드 오분류는 #120 의 가장 강한 트리거이나 #121 (outline level off-by-1), #123 (linesegarray 누락), #124 (editable bit 강제) 등 다른 트리거가 잔존. Step 6 만으로 보안 경고가 완전 사라지는지는 사용자 시각 검증 (한컴 열기 후 확인) 에 의존.

Known Issues — Wave 12p/12q 종료 후 잔존

#120 — “낮은 보안 수준 복구” 경고 (HWP5 → HWPX SUMMERY 필드)

증상 (2026-06-09 시각 검증, converted-field-docsummary-wave12p-final.hwpx):

  1. 한컴에서 변환 결과 파일을 열 때 “현재의 낮은 보안 수준으로 문서에 손상을 줄 수 있는 내용을 복구하였습니다” 경고 dialog 표시.
  2. 처음 열 때 모든 SUMMERY 필드 ($author, $title, $modifiedtime, $lastsaveby, $createtime) 의 body 가 빈 placeholder ([문서 정보 시작][문서 정보 끝]) 로 표시.
  3. 사용자가 저장하면 한컴이 자체적으로 metadata 를 evaluate 해서 hanyul / 날짜 등 실제 값으로 채워 다시 표시.

Native fixture (sample-field-docsummary.hwpx) 와의 차이:

  • native: 경고 없음 + 처음 열 때부터 SUMMERY 값 표시.
  • ours: 경고 + 처음 열 때 빈 표시 → 저장 후 update.

Wire 비교 결과 (/tmp/docsum_diff 의 grep):

native 와 우리 emit 모두 <hp:fieldBegin> 와 <hp:fieldEnd> 사이의 <hp:t> body 에 실제 값을 채움 (예: native field #2 hanyul, ours field #2 hanyul). body 자체에는 차이 없음. 그럼에도 한컴이 우리 파일은 빈 placeholder 로 표시 — 한컴이 다른 구조적 차이를 트리거로 잡는 듯.

알려지지 않은 추가 트리거 (Wave 12p/12q 후 잔존):

  • <hp:fieldBegin> 의 id/fieldid/metaTag attribute 의 값/조합이 native 와 미세하게 다른가? (예: hardcoded fieldid="628321650" vs native 의 paragraph-별 다른 값)
  • ParaText (paragraph 본문 text) 의 byte sequence 가 다른가?
  • dirty="0" 이지만 한컴이 dirty 로 인식하는 다른 signal?
  • 단일 paragraph 안에 여러 SUMMERY field 가 연속될 때 우리 emit 의 paragraph 구조가 다른가? (native field #5 는 paragraph 안에 여러 <hp:t> 가 split 되어 있음)

완화책 — 후속 wave 에서 진단 필요:

  1. native sample-field-docsummary.hwpx 와 우리 emit 의 section0.xml byte-level diff 로 트리거 specific 식별.
  2. 한컴 “낮은 보안 수준” warning 의 정확한 트리거 조건 reverse-engineering.
  3. ZIP container 의 file 순서 / mimetype 처리 차이 가능성도 검토.

user impact: 사용자가 변환 결과를 저장 한 번 하면 모든 값이 올바르게 표시되므로 functional impact 는 크지 않음. 단 첫 인상이 “빈 필드 + 경고” 라 confusing — 후속 wave 에서 trigger specific 한 fix 필요.

상태: investigation deferred — 후속 wave 에서 byte-level diff 진단 필요.

#33 — Wave 5 gap C: 별도 <hm:masterPage> element carry

상태: investigation deferred — Windows 한컴 fixture 필요.

컨텍스트 (2026-06-09 macOS 한컴 fixture 진단):

macOS 한컴은 페이지 테두리 / 머리말 / 꼬리말 / 쪽 배경 등을 모두 <hp:secPr> 안에 <hp:pageBorderFill> + <hp:header> + <hp:footer> 로 inline emit. 별도 <hm:masterPage> element 는 만들지 못함 (masterPageCnt="0", 별도 MasterPage/ 디렉토리 / Contents/masterPageN.xml 파일 없음).

진단 결과: 현재 HwpForge 변환이 이미 macOS 한컴 시나리오 (페이지 테두리 + 머리말/꼬리말) 를 정확히 처리 — <hp:pageBorderFill> 3종 (BOTH/EVEN/ODD), <hp:header applyPageType="BOTH">, <hp:footer ...> 모두 native parity (id 번호만 +1 차이).

#33 의 진짜 scope 인 별도 <hm:masterPage> element (페이지별로 다른 master template 같은 advanced 기능) 는 macOS 한컴이 만들지 못해 fixture 확보 불가. Windows 한컴 환경에서 <hm:masterPage> 정의된 .hwp + native .hwpx fixture 확보 후 진단/구현 가능.

user impact 작음: 일반 사용자가 사용하는 페이지 테두리/머리말/꼬리말 시나리오는 이미 동작. advanced <hm:masterPage> 시나리오는 한컴 자체 가 흔한 use case 가 아닌 듯 (macOS 빌드에서 누락 가능).

Wave 12o-fixup — Codex(architect) Top-5 리뷰 4건 + 종료 정직성

Codex(architect) Wave 12o post-completion 리뷰에서 발견된 P0/P1 4건의 fast-follow fix + 종료 노트 정직성 보정. Wave 12o 종료 commit (8aa47f9) 은 revert/amend 하지 않음 (감사 추적성 보존).

Security (Top-1 P0)

  • hwpforge-smithy-hwp5::schema::summary_info::parse_summary_information 의 sec_start + 8 unchecked usize add 가 32-bit / wasm 타깃에서 u32-derived sec_start >= 0xFFFFFFF8 일 때 wrap 후 panicking 슬라이스 인덱스로 진입할 수 있었음. checked_add + bytes.get(..) 패턴으로 항상 Hwp5Error::RecordParse 경로 보장. 악성 .hwp 만으로 트리거 가능한 DoS 봉쇄.

Fixed (Top-2 P0 — data carry)

  • HWPX decoder 가 한컴 emit <opf:meta name="date">2026년 …</opf:meta> 값을 extras["date"] 로 carry 하지만 HWPX encoder 의 typed-collision guard 가 이를 drop 해서 HWPX → HwpForge → HWPX 1-cycle round-trip 에서 silent data loss 발생. typed-collision 리스트에서 date 만 예외 처리하고 9-slot canonical 위치에서 extras["date"] 값을 그대로 emit. creator / subject 등 진짜 typed slot 은 계속 drop.

Fixed (Top-4 P1 — API 일관성)

  • Hwp5Decoder::decode (canonical public entry) 가 decode_intermediate 에서 생성한 intermediate.metadata 를 받았지만 projection 결과 document 에 set_metadata 하지 않아 silently drop. 한 줄 추가로 decode_hwp5_with_images / hwp5_to_hwpx_bytes 와 일관성 확보.

Fixed (S3 namespace guard — P1 신규 발견)

  • hwpforge-smithy-hwpx::decoder::metadata::enforce_namespace 가 if let Some(p) = name.prefix() 패턴이어서 unprefixed <title> / <meta> (prefix 누락) 가 S3 (namespace confusion) 가드를 통과. match 표현으로 변환해서 prefix 누락 케이스도 reject. 하스타일 metadata 슬롯 shadow 가능성 차단.

Regression gates (+3 tests)

  • summary_info::section_start_past_eof_rejected — Top-1
  • decoder::metadata::date_extras_roundtrip_preserves_value — Top-2
  • decoder::metadata::unprefixed_element_inside_metadata_rejected — S3

Workspace nextest: 2,441 → 2,444 passed + 2 skipped.

Process integrity (Top-5)

  • Wave 12o 종료 commit 의 G6/G7 PASS 표기 뒤에 G2 (native byte-parity xmllint diff), G4 (HWP5→HWPX e2e 자동 게이트), G8b (저장 후 fallback 거동) 가 미평가 상태로 묻혀 있던 사실을 CLAUDE.md 종료 노트에 명시. 후속 wave 에서 자동 게이트로 승격 약속.

Visual verification example

  • 신규 crates/hwpforge-smithy-hwpx/examples/probe_date_carry_wave12o_fixup.rs — 한컴 저장본 HWPX 를 HwpForge 가 decode → encode → 재decode 한 결과 metadata 가 동일한지 자동 검증 + content.hpf 비교 명령 출력.

Wave 12o Phase 3 — HWP5 SummaryInformation OLE2 PropertySet decoder

Added — HWP5 decoder

  • New module crate::schema::summary_info parses the \x05HwpSummaryInformation OLE2 PropertySet stream (standard MS Office layout) into a populated [Metadata](Phase 0) struct.
  • PackageReader now reads the summary stream alongside the other OLE2 sub-streams. Missing or undecodable summary downgrades to Metadata::default() with a ParserFallback warning (never fatal).
  • DecodedHwp5Intermediate gains a metadata field; both decode_hwp5_with_images and hwp5_to_hwpx_bytes forward it into the projected Document via Document::set_metadata.

Wire mapping (PropertySet PIDs → Core Metadata)

  • PID 2 (TITLE) → title
  • PID 3 (SUBJECT) → subject
  • PID 4 (AUTHOR) → author
  • PID 5 (KEYWORDS) → keywords (semicolon-split)
  • PID 6 (COMMENTS) → description
  • PID 8 (LASTAUTHOR) → last_saved_by
  • PID 0x0C (LASTSAVEDTIME, VT_FILETIME) → modified (ISO 8601)
  • PID 0x0D (CREATEDTIME, VT_FILETIME) → created (ISO 8601)
  • PID 0x14 (Hancom custom date display string) → extras["date"]
  • PID 0x15 (Hancom custom app name) → extras["appname"]
  • Unknown PIDs → extras["pid_<hex>"] (preserves wire bytes)

Security (Wave 12o architect review §11.2 M3/M4 + §11.4 S2/S7)

  • M3 — slots into Schema stage (no new pipeline stage).
  • M4 — FILETIME → ISO 8601 hand-rolled (no chrono dependency added). Sub-second precision discarded to match Hancom wire (seconds). Year > 9999 and FILETIME = 0 yield None.
  • S2 — property table monotonic-offset enforcement rejects classic PropertySet payload-cycle DoS.
  • S7 — explicit UTF-16LE BOM strip from VT_LPWSTR payloads.
  • Allocation caps: per-property body ≤ 64 KiB, property count ≤ 256.

Wave 12o Phase 2 — HWPX decoder content.hpf metadata parser + XXE/DoS defenses

Added — HWPX decoder

  • New module crate::decoder::metadata parses Contents/content.hpf <opf:metadata> into the Core [Metadata](Phase 0) struct, symmetric with Phase 1’s encoder output.
  • HwpxDecoder::decode now reads metadata before constructing the Document, so a Hancom-emitted file’s $title/$author/etc. values resolve correctly on the next encode.
  • Missing or malformed content.hpf metadata downgrades to Metadata::default() (third-party HWPX authors may omit the block).

Security (Wave 12o architect review §11.1 B3 / §11.4 S1–S3)

  • <!DOCTYPE> events are rejected explicitly — defeats XXE and billion-laughs vectors before quick-xml’s default parser path.
  • CDATA inside <opf:metadata> is rejected.
  • Allocation caps: depth ≤ 16, <opf:meta> count ≤ 256, per-text body ≤ 64 KiB, attribute value ≤ 64 KiB.
  • S3 namespace confusion guard: any child of <opf:metadata> must use the opf prefix; <hp:title> and friends are rejected.
  • S1 illegal-XML-char sanitizer is applied to all decoded text before it enters Metadata.

Wave 12o Phase 1 — HWPX encoder content.hpf metadata emit

Changed (BREAKING — public API)

  • HwpxEncoder::encode now consults document.metadata() and forwards it to the package writer.
  • package::generate_content_hpf / PackageWriter::write_hwpx signatures gain a leading metadata: &Metadata parameter (internal pub(crate); not part of the public surface).

Added — wire format

  • content.hpf <opf:metadata> is always emitted with the full nine-slot Hancom byte-parity layout (title/language/creator/subject/description/lastsaveby/ CreatedDate/ModifiedDate/date/keyword) plus alphabetical extras. None slots self-close; populated slots use the content="text" attribute.
  • date always self-closes (Hancom recomputes on save — Wave 12o §11.3 Q2). keywords are joined with ; into a single element (§11.3 Q3).
  • Defense in depth: every text body flows through sanitize_xml_text (Wave 12o §11.4 S1) before escape_xml.

Wave 12o Phase 0 — Document Metadata Core breaking

Changed (BREAKING — public API)

  • core::metadata::Metadata gains three new fields and is now annotated #[non_exhaustive]. This is ADR-003 in the 0.7.0 break window. External callers can no longer construct Metadata with a struct literal; use the new Metadata::new() seed plus the chainable .with_title()/.with_author()/.with_subject()/.with_description()/ .with_last_saved_by()/.with_keywords()/.with_created()/ .with_modified()/.with_extra() builder methods.
  • New Metadata::description: Option<String> — corresponds to HWPX <opf:meta name="description">. Distinct from subject (Hancom stores them in separate slots).
  • New Metadata::last_saved_by: Option<String> — corresponds to HWPX <opf:meta name="lastsaveby"> and the $lastsaveby SUMMERY auto-field (Wave 12n). Distinct from author (creator).
  • New Metadata::extras: BTreeMap<String, String> — lossless carry slot for <opf:meta> keys not yet promoted to typed fields. Deterministic ordering for byte-stable encoder output.
  • Rationale: HwpForge-emitted content.hpf had hardcoded <opf:title/> with all other metadata fields empty, causing Hancom Office to overwrite SUMMERY auto-field values (e.g. $title) with fallback text on save. Wave 12n’s Control::Field (Author/LastSavedBy/CreatedTime/ ModifiedTime/Title) auto-fields need a populated metadata source to resolve to user-intended values. Phases 1–4 (HWPX encoder/decoder, HWP5 SummaryInformation) wire the carry end-to-end.

Phase 12l — Control::Field name carry (Core + HWPX + HWP5)

Changed (BREAKING — public API)

  • Control::Field gains a name: Option<String> field carrying the form-mode identifier (HWPX <hp:fieldBegin name="...">). Existing callers that construct Control::Field with a field-record literal must add name: None. Pattern matches with .. are unaffected. Required because the prior model silently dropped the form-mode identifier on every HWPX↔Core↔HWP5 roundtrip.
  • Control::field() convenience constructor unchanged in signature; the produced Control::Field now has name: None.
  • Display impl for Control::Field now prints name="…" only when present.
  • Serialize/Deserialize/JsonSchema representations of Control::Field gain the new field; consumers that round-trip JSON of Control::Field must accept the new key (it is optional / defaults to null).

Fixed — HWPX encoder

  • build_field_run_xml now emits the real name attribute on <hp:fieldBegin> for both CLICK_HERE and SUMMERY (automatic) fields instead of the hardcoded name="".
  • Clickhere:set:N: now uses a fixed-point computed N (self-referential UTF-16 code unit count) instead of the literal 43 that did not match the real command string length and was a wire-truth lie even before name carry.
  • build_field_run_xml signature gains name: &str.

Fixed — HWPX decoder

  • Both CLICK_HERE/automatic-field branches and the SUMMERY branch in decode_field_control now carry fb.name into Control::Field.name (with Some("") -> None normalisation, matching the indexmark/dutmal pattern).

Added — HWP5 leg

  • HWP5 %clk CtrlHeader parser (Hwp5ClickHereControl::parse) carries the press-field’s hint_text / help_text / field_unique_id from the wire’s UTF-16LE Command string. Parser is length-driven (no :-delimiter split) and UTF-16 code unit cursor based, so embedded colons in hint/help and surrogate-pair input do not corrupt decoding.
  • HWP5 0x57 (TagId::CtrlData) sub-record parser (Hwp5ClickHereControl::parse_name_subrecord) carries the form-mode name. The %clk → 0x57 pairing is held by BodyTextParserState.pending_clickhere (mirrors the eqed → EqEdit pattern used in Wave 12d) and flushed at orphan boundaries with a targeted ProjectionFallback warning.
  • Projection has a dedicated clickhere_controls queue + new ActiveField::ClickHere variant. start_active_field / finish_active_field emit a single Control::Field Run with all four metadata fields populated; the HWPX encoder rebuilds the visible placeholder from hint_text, so the span between the FIELD_BEGIN / FIELD_END markers is intentionally not double-emitted.
  • Audit semantic model gains Hwp5SemanticControlKind::ClickHere so press-field counts attribute correctly in the audit-batch output.

Fixed — HWPX encoder Command N

  • Clickhere:set:43: was a wire-truth lie (the literal 43 did not match any real-fixture command length, even before name carry). Replaced by clickhere_command_string, which uses the empirically-derived formula N = utf16_len(rest_of_command) - 1 (verified against the seven press-field instances across five fixtures). The formula is digits(N)-independent, so no fixed-point iteration is required.

Notes

  • See .docs/algorithms/2026-06-02_clickhere_field_carry.md for the full algorithm + Codex review resolution table.
  • See .docs/research/2026-06-02_clickhere_wire_dump.md for the wire layout derivation.

Phase 12 (HWP5 drawing-object carry)

Continues the Phase 11 line: HWP5 drawing objects the decoder previously skipped now carry through Core to HWPX instead of silently emptying their host paragraph. No Core or HWPX API changes — these shape variants already existed in the shared model; only the HWP5 leg was missing.

Added — Wave 12a (GSO ellipse / arc / curve)

  • Decode gso ShapeComponentEllipse (0x50) and ShapeComponentCurve (0x53) sub-records and project them to Control::Ellipse, Control::Arc, and Control::Curve. Previously these fell through to Hwp5Control::Unknown and were dropped, emptying the host paragraph.
  • 한컴 stores arcs inside the ellipse (0x50) record with arc fields set — it does not emit a separate ShapeComponentArc (0x51). An arc is now distinguished by content and carried as Control::Arc → <hp:ellipse hasArcPr="1">.
  • Classify ellipse/arc/curve in the audit semantic model (Hwp5SemanticControlKind::{Ellipse, Arc, Curve}) so source-side control counts match converted output.
  • Binary layouts confirmed empirically from 한컴 truth fixtures (sample-gso-{ellipse,arc,curve}); golden tests assert end-to-end carry.
  • Known limitation: arcs carry as the Normal arc type sized from the bounding box. Pie/chord arc types and exact arc-sweep endpoints are deferred until dedicated fixtures exist.

Added — Wave 12b (GSO connect line)

  • Carry connectors as Control::ConnectLine → <hp:connectLine> instead of demoting them to a plain <hp:line>. 한컴 stores a connector in the same ShapeComponentLine (0x4E) sub-record as a plain line; the only discriminator is the ShapeComponent (0x4C) type tag "$col" (confirmed against $rec/$ell/$cur). A conservative guard upgrades only an exact "$col" match, so plain lines are never reclassified.
  • Classify connectors in the audit semantic model (Hwp5SemanticControlKind::ConnectLine).
  • Confirmed end to end against a natively-drawn 한컴 connector fixture (sample-gso-connectline-native: two rectangles + one connector).
  • Known limitation: only a straight connector with its endpoints is carried; the source connector’s object-link references have no <hp:connectLine> representation and are dropped.

Fixed — floating ellipse/arc/curve/connect-line positioning (HWPX encoder)

  • <hp:ellipse>, <hp:curve>, and <hp:connectLine> hardcoded inline positioning (numberingType="NONE", textWrap="TOP_AND_BOTTOM", vertRelTo/horzRelTo="PARA") instead of using the shared offset-aware helpers that <hp:line>/<hp:rect> already used. A floating shape (non-zero offset) was therefore mis-anchored to the paragraph and rendered in the wrong place in 한컴. They now route through shape_position / shape_numbering_type / shape_text_wrap, so a floating shape anchors to PAPER as PICTURE/IN_FRONT_OF_TEXT (matching 한컴) while inline shapes (zero offset) are unchanged. Exposed by Wave 12b’s first floating connector.

Added — Wave 12d (equation)

  • Carry equations as Control::Equation → <hp:equation> with the HancomEQN script preserved. The eqed ctrl used to fall through to Hwp5Control::Unknown and was dropped. The decoder now recognizes the eqed ctrl, parses the script from its child HWPTAG_EQEDIT (0x58) record (UINT32 property, then a UINT16 WCHAR-count length prefix + UTF-16 script), and projects it to Control::Equation sized from the ctrl-header geometry.
  • Classify equations in the audit semantic model (Hwp5SemanticControlKind::Equation).
  • Confirmed end to end against a 한컴 equation fixture (sample-equation-basic: {a + b} over {c + d}); golden test asserts both <hp:equation> emission and verbatim <hp:script> carry.

Added — Wave 12e-Memo (memo annotation carry + body corruption fix)

  • Carry memo annotations as Control::Memo → HWPX <hp:fieldBegin type="MEMO"> with the body paragraphs in <hp:subList>. The HWP5 %unk ctrl with command "MEMO/{shapeId}/{memo_id}/{instId}" used to fall through to Hwp5Control::Unknown, so the matching HWPTAG_MEMO_LIST (0x5D) cluster’s level-2 ParaText records would fall into the body-paragraph ParaText arm and overwrite the body text — the visible “memo content replaces body text” corpus bug.
  • Decoder now recognises the %unk MEMO/... placeholder, captures the matching cluster region at the end of the section’s last body paragraph (records at level 1/2: MemoList, ListHeader, content ParaHeader, ParaText, CharShape, …), and joins clusters back to placeholders by memo_id (not by document position) during BodyTextParserState::finish. Multi-memo fixtures confirmed both happy path and id-keyed matching.
  • Projection adds an ActiveField::MemoAnchor so the anchor text inside the FieldBegin %unk MEMO / FieldEnd span flows into runs (no drop) and the memo Run is emitted at the anchor’s start position.
  • layout_hint_patch now folds memo body paragraphs into the body scope so the HWPX patcher does not underflow the paragraph-hint queue.
  • Classify memos in the audit semantic model (Hwp5SemanticControlKind::Memo).
  • Golden tests confirmed against two 한컴 fixtures: sample-memo-basic (one memo, body anchor + body content preservation) and sample-memo-multiple (two memos, id-keyed cluster matching).

Changed — Wave 12e-Memo (Core API breaking, semver-deliberate)

  • Control::Memo no longer carries author / date — the variant is now Control::Memo { content: Vec<Paragraph> }. Neither field was actually populated by any wire path: the HWPX <hp:fieldBegin type="MEMO"> only exposes MemoShapeID / MemoType parameters, and HWP5’s %unk MEMO/... command exposes no author/date metadata. Holding the fields encouraged callers to pass dummy values that never round-tripped.
  • Control::memo(content) helper drops the corresponding author/date parameters; call sites in smithy-hwpx examples (shapes_and_references, hwpx_complete_guide_parts/section2) and tests (smithy-hwpx/src/registry_bridge.rs, smithy-hwpx/src/encoder/section.rs) updated.
  • smithy-md markdown encoder emits <!-- memo: body --> instead of <!-- memo(author): body --> (the author segment was always blank in practice).

Fixed — Wave 12f (memo anchor position)

  • HWP5 stores the memo inline FieldBegin marker with extra[0..4] = %%me (0x2525_6D65), which is not the same id as the CtrlHeader ctrl_id %unk (0x2575_6E6B). Wave 12e matched only the latter, so the inline anchor was never recognised and the memo Run ended up drained at the end of the paragraph as a point-anchored field — 한컴 rendered it as 메모 대상 문장입니다.[메모 시작][필드 끝].
  • projection.rs::start_active_field now recognises both ids: the inline marker activates ActiveField::MemoAnchor, which positions the memo Run at the correct anchor offset (vis=2 in the basic fixture).

Changed — Wave 12g (Core API breaking, semver-deliberate)

  • Control::Memo gains anchor_runs: Vec<Run>. The anchor body sits inside the same <hp:run> as fieldBegin/fieldEnd in 한컴 truth fixtures; the previous Wave-12f layout placed the anchor as a separate Run before the memo and 한컴 mis-rendered the end marker as generic [필드 끝].
  • HWPX encoder now serializes memos as a flat [fieldBegin][anchor_xml][fieldEnd] <hp:run> via build_memo_anchor_xml. See .docs/algorithms/2026-06-01_memo_anchor_serialization.md for the anchor-body collapse heuristic (single <hp:t> per anchor) and why we accept the per-run char-shape fidelity loss.
  • Control::memo_with_anchor(content, anchor_runs) helper added.

Added / Changed — Wave 12h (full <hp:parameters> carry)

  • HWPX <hp:parameters> now emits the full 한컴-standard cnt="7" block (Prop, Command, ID, Number, Author, MemoShapeIDRef, CreateDateTime) plus editable="1" dirty="1" zorder="1". The pre-12h cnt="2" block (MemoShapeID + MemoType only) made 한컴 mis-classify the field — the memo body rendered correctly, but the end marker fell back to generic [필드 끝] in 조판부호 view.
  • New schema struct Hwp5MemoCommand parses the wire’s "MEMO/{shape_id}/{memo_id}/{hancom_inst_a}/{hancom_inst_b}/{author}/{terminator}" command string. Reusable wire-string utilities (parse_ctrl_header_command_string, split_slash_command) added to schema/section.rs for future %hlk / %xrf / %bmk work.
  • New Control::Memo { metadata: MemoMetadata, … } field (Core API breaking, semver-deliberate). MemoMetadata carries shape_id_ref, number, id, author, create_datetime, command — wire values flow through projection.rs verbatim.
  • CreateDateTime has no HWP5 wire source (verified via DOC_PROPERTIES 0x10, TRACKCHANGE 0x20, MemoShape 0x5E dumps). Encoder fills it with iso8601_utc_now() (std-only Howard-Hinnant civil-from-days) at write time — matching 한컴’s own behaviour on fresh saves.
  • build_memo_parameters_xml extracted as a re-usable HWPX <hp:parameters> builder for future field types that need the same structure (hyperlink / cross-reference fidelity work).

Added / Changed — Wave 12i (dutmal carry + flat-path control filter)

  • Carry dutmal (덧말) annotations as Control::Dutmal → <hp:dutmal> with main_text / sub_text / posType / option. The decoder now reads option_raw from tail[8..12] of the tdut ctrl payload (Hwp5DutmalControl); the HWPX encoder previously hard-coded option="0" and the HWPX decoder discarded the value, so any non-default option=4 한컴 fixture lost fidelity end to end. Both legs now mirror the integer verbatim. Semantics of option are intentionally not pinned — the bit/enum meaning is undocumented and produces no visible rendering difference in our truth fixture; see .docs/algorithms/2026-06-01_dutmal_carry.md.
  • New Control::Dutmal { metadata: DutmalMetadata, … } field (Core API breaking, semver-deliberate). DutmalMetadata carries option: u32 and is #[non_exhaustive] so future sz_ratio / align / style_id_ref decode work is additive.

Fixed — Wave 12i flat-path projection control_iter filter

  • project_paragraph_with_images_flat used to iterate every control in Hwp5Paragraph.controls (including the secd / cold / %bmk / %hlk / %xrf / bokm / pgnp Unknown markers that lead a first-section paragraph) when matching inline \u{FFFC} ControlRef positions to runs. Each FFFC popped the wrong control — the marker-header Unknowns returned None from project_control_run and got dropped, while the real inline controls leaked to the end-of-paragraph drain. The observable symptom on Wave 12i’s two-dutmals-with-space fixture was the body space <hp:t> </hp:t> getting pulled in front of both dutmals (한국어 韓字 → 한국어韓字). The structural projection path was unaffected because it already separated those controls into marker_headers vs. object_controls queues. The flat path now applies the same filter so its FFFC iterator only sees object controls. Any first-section paragraph that combines secd / cold with any inline shape (rect, polygon, ellipse, image, table, equation, dutmal) is covered, not just dutmal. See .docs/algorithms/2026-06-01_dutmal_carry.md (companion-fix section) for the full root-cause + rationale.

Added / Changed — Wave 12j (compose carry + char_pr_ids fidelity)

  • Carry compose (글자겹침) annotations end-to-end through the HWP5 leg — Hwp5ComposeControl schema struct, tcps CtrlHeader decode, Hwp5Control::Compose variant, and a project_compose_run that emits Control::Compose with circleType / composeType mapped from raw enum bytes to the OWPML attribute strings (14 SHAPECIRCLETYPE values + 2 COMPOSETYPE values, including the spec-typo SHAPE_REVERSAL_TIRANGLE). HWPX→Core and Core→HWPX both already existed prior to this wave; only HWP5→Core was missing and tcps was silently dropped to Hwp5Control::Unknown.
  • New Control::Compose { char_pr_ids: Vec<u32>, … } field (Core API breaking, semver-deliberate). HWPX schema fixes <hp:compose charPrCnt> at 10, but the existing encoder hard-coded all 10 slots to u32::MAX (“no override” sentinel) and the existing decoder discarded <hp:charPr prIDRef> children entirely. The new field threads the 10 LE u32 charPr IDs verbatim through Core so a HWPX → Core → HWPX round-trip preserves which slots carry a real prIDRef override (e.g. 7) vs. the u32::MAX placeholder. Encoder pads / truncates to 10 slots.
  • Compose wire layout discriminator. The tcps CtrlHeader payload has two empirically-observed forms, discriminated by the low half of properties (data[4..6] as LE u16):
    • 0x0003 (unpacked) — composeText is fully in data[8..], body trailer carries the 4 metadata bytes + 10 × u32 charPrs. 27 of 28 round-tripped variants and every native 한컴 fixture use this layout.
    • 0x0002 (packed) — composeText[0] is in properties[2..4], composeText[1..N] is at the start of the body; the body trailer layout is unchanged. Observed exclusively on the CHAR + OVERLAP combination when 한컴 saved an HWPX → HWP5. The parser detects this via properties.low == 0x0002 and prepends the packed char to the body region before decoding.
  • Any other properties.low value falls through to Hwp5Control::Unknown. No clamp; no guessing. See .docs/algorithms/2026-06-01_compose_carry.md for the full discriminator table, the shape-glyph table for properties.high, and the validation policy rationale (Codex-reviewed).
  • The packed variant was discovered only through a 14 × 2 = 28 circleType × composeType combinatorial fixture (gen_compose_variants example) — single-shape native fixtures never trigger it. The lesson is captured in .docs/learnings/2026-06-01_hwp5_ctrl_header_properties_overloaded.md: HWP5’s CtrlHeader properties word is not a generic bitfield — each ctrl_id can repurpose it for ctrl-specific data, and the same ctrl can switch layouts within a single document.

Added — Wave 12k (IndexMark carry + 0x16 inline marker promotion)

  • Carry IndexMark (찾아보기 표시) annotations end-to-end through the HWP5 leg — Hwp5IndexMarkControl schema struct, idxm CtrlHeader decode, Hwp5Control::IndexMark variant, and a project_indexmark_run that emits Control::IndexMark { primary, secondary }. The HWPX encoder + decoder + Core variant all existed prior to Wave 12k; only the HWP5 leg was missing and idxm was silently dropped to Hwp5Control::Unknown.
  • 0x16 ParaText inline-marker promotion (Codex 🟠 HIGH). Hwp5ParaText::parse used to consume the entire 0x0E..=0x16 byte range silently. Adding a CtrlHeader dispatch alone would have left every IndexMark Run drained to end-of-paragraph instead of anchored at the inline marker. The fix carves 0x16 out of the silent-consume range and promotes it to TextSegment::ControlRef only when extra[0..4] matches the LE-stored ctrl_id for idxm. The discrimination keeps every unknown 0x16 owner falling through the silent path so we don’t alias unrelated control families.
  • Targeted parser warning. Malformed idxm payloads emit Hwp5Warning::DroppedControl { control: "indexmark", … } rather than the generic UnsupportedTag(0x47) fallback — audit baselines can attribute the loss to the IndexMark code path specifically.
  • Trailer 4 bytes deliberately discarded. The trailer is 0xFFFF_FFFF on native 한컴 authoring and 0x00000000 on HWPX→ HWP5 round-trip via 한컴 save; HWPX has no corresponding attribute, so carrying it into Core would be a format leak. The 4 bytes are still required to be present — a truncated trailer means the record boundary is no longer trustworthy.
  • Empty-secondary normalization. The source Some("") for one fixture entry comes back from 한컴 as secondary_units_len = 0; the decoder reflects 한컴’s intent by returning None. HWP5 wire cannot distinguish the two states once 한컴 has saved.
  • Golden tests cover (a) the native two-IndexMark fixture, (b) the 8-IndexMark combinatorial fixture (every primary-only and primary+secondary combination + the CPU / GPU same-paragraph order regression gate that Codex specifically called out). The schema layer adds five focused unit tests (real native bytes, real multi bytes with secondary, primary_units_len == 1 edge case, primary_units_len == 0 rejection, truncated-trailer rejection). See .docs/algorithms/2026-06-02_indexmark_carry.md for the full layout table, Codex-review rationale, and validation policy notes.

Phase 11 (HWP5 → HWPX silent-gap closure)

This release closes the largest batch of “HWP5 decoder has the bytes, but projection or shared model can’t carry them” gaps measured against truth HWPX fixtures from 한컴 Office. All work is HWP5-leg only — HWPX encode/decode paths were already verified by existing golden tests.

Added — Wave 0 (audit infrastructure)

  • audit-hwp5 warning taxonomy (SilentGap, DroppedControl, …) and --strict mode so silently dropped semantics are surfaced as build signals instead of accumulating as invisible technical debt.

Added — Wave 1 (character style line family + word break)

  • Carry underline (1b) and strikeout (1c) line family (DOT, DASH, DOT_DASH, etc.) through HwpxCharShape instead of collapsing to SOLID.
  • Carry breakLatinWord = HYPHENATION (1d) through WordBreakType and HWP5 projection so HWPX breakLatinWord is no longer always KEEP_WORD.
  • Surface silent shadow decode gap as warning (1a) until carry lands.

Added — Wave 2 (paragraph layout fidelity)

  • Carry lineSpacingType = AtLeast (2a).
  • Verify all 6 alignment variants (2b), indent + pageBreakBefore (2cd), and border + shading (2e) carry against truth HWPX fixtures.

Added — Wave 3 (paragraph-level checked decode)

  • HWP5 paragraph-level paraPr.checked decode so the third location of checkable-bullet truth (the per-item checked state) is no longer lost. Closes the legacy R1 line.

Added — Wave 4 (Field / Object parity)

  • Wave 4a: carry HWP5 Rect control through Core → HWPX.
  • Wave 4b: carry HWP5 footnote control through Core → HWPX.
  • Wave 4c: carry HWP5 chart (OLE-backed BinData) end-to-end as Control::EmbeddedChart passthrough — emits Chart/chartN.xml + BinData/oleN.ole + <hp:switch> block. Closes the DroppedControl:ole_object measurement.
  • Carry HWP5 fixed-width space and non-breaking space through Core to HWPX inline text.
  • Carry HWP5 checkable bullet checkedChar + paraHead.checkable through bullet conversion.
  • Tab fidelity end-to-end: carry inline <hp:tab width / leader / type> attributes through a new RunContent::InlineText variant; HWPX encoder/decoder updated symmetrically; fill-type → leader mapping rebuilt against openhwp truth. See debug doc .docs/debug/2026-05-26_tab_fidelity_bugs.md and .docs/debug/2026-05-27_hwpx_decoder_inline_tab_attrs_lost.md.
  • Field controls: emit non-zero fieldid for CROSSREF and keep fieldBegin id within signed 32-bit range.

Added — Wave 5 (page-level features)

  • Wave 5 gap A: carry per-ctrl applyPageType (BOTH / ODD / EVEN) through HWP5 head / foot ctrl property word into multiple <hp:header> / <hp:footer> elements. Verified against sample-header-footer-odd-even truth fixture.
  • Wave 5 gap B: carry secd ctrl property bits (0/1/2/5/19) into Section.visibility.hide_first_header / footer / page_num / empty_line / master_page. Verified against sample-header-footer-hide-first truth fixture. New crates/hwpforge-smithy-hwp5/examples/probe_secd.rs reusable probe.
  • Wave 5 gap C (masterPage carry): deferred. Diagnosed as fixture-asymmetric on macOS 한컴 (truth HWPX has masterpage0.xml but the paired HWP5 has no master-page sub-records). See debug doc .docs/debug/2026-05-27_hwp5_page_features_lost.md for full probe results. Resume when a PC-한컴 fixture is available.

Fixed — Wave 6 (corpus-driven conversion robustness)

Measured by extending the audit-hwp5 signal source from synthetic fixtures to the real government-document corpus and clustering the pre-categorized conversion failures. The two real bugs recovered all 29 hwp5_convert_failed documents (plus one more from 탈락); the remaining failures are inputs that are genuinely not HWP5.

  • Schemeless hyperlink URLs (e.g. www.motie.go.kr) are normalized to http:// instead of aborting the whole conversion. The HWPX encoder previously rejected any URL outside the http:// / https:// / mailto: allowlist; explicit unsafe schemes (javascript:, data:, file:, …) are still rejected. (16 corpus docs)
  • Non-leading table header rows are demoted to normal rows (with a warning) in HWP5 projection instead of failing Core validation with NonLeadingTableHeaderRow. Real 한글 tables sometimes restate a header row mid-table; the leading header block is preserved and the stray header row is demoted so the document still converts. (14 corpus docs)
  • .hwp inputs that are actually ZIP (PK.., i.e. an HWPX saved with a .hwp extension) or a Hancom secured/DRM container (SCDS..) now fail with an actionable message instead of a raw CFB byte dump.

Changed — Breaking

  • ADR-002: hwpforge_core::Section.header: Option<HeaderFooter> → Section.headers: Vec<HeaderFooter> (and footer → footers). This changes the public Section shape so that multiple page-type-scoped headers (ODD / EVEN / BOTH) can coexist as required by HWPX wire format. Empty Vec means “no header”. JSON dump now emits a list instead of an object (or omits when empty). Patch / MD encoder / CLI / MCP consumers updated to iterate the slot. See .docs/architecture/adr/ADR-002-section-multi-header-footer-cardinality.md.

Added — Public API

  • hwpforge_core::RunContent::InlineText(InlineText) variant for mixed-content runs that include <hp:tab> (and is forward-compatible with <hp:lineBreak> / <hp:nbSpace> / <hp:fwSpace>). InlineText / InlineSegment / InlineTabAttr are #[non_exhaustive].
  • Section constructors continue to be new() / with_paragraphs(); push headers/footers via section.headers.push(HeaderFooter::…).

Migration

  • Replace section.header = Some(hf) with section.headers.push(hf).
  • Replace section.header.as_ref() with section.headers.first() (single-slot consumers) or iterate section.headers (general).
  • serde shape now uses headers / footers arrays; persisted JSON using the old keys must be migrated.
  • Match arms on RunContent may need a new InlineText(_) arm. Use RunContent::carries_text() / plain_text() for read-only consumers that don’t care about inline attribute fidelity.

[0.5.2] - 2026-05-13

Added

  • hwpforge CLI gains to-md lossy / lossless modes for HWPX → Markdown export choice.
  • HWP5 → HWPX projection preserves field controls and checkable state (precursor to Phase 11 Wave 3/4 closure).

Fixed

  • Dependency hygiene updates (sha2, GitHub Actions pinning, suppress RUSTSEC-2026-0097 non-applicable advisory).

[0.5.1] - 2026-04-13

Added

  • HWP5 → HWPX style fidelity bridge improvements (more char/para style surface preserved end-to-end).
  • HWPX char effects: preserve emboss, engrave, superscript, subscript (also covered later under Wave 1 audit).

Fixed

  • Warn on conflicting vertical-position bits instead of silently normalizing.
  • HWP5 paragraph layout hints (linesegarray, safe table height) carried to HWPX so visual diff matches truth better.
  • convert-hwp5 / audit-hwp5 / inspect summary share the same style-projection warning source.

[0.5.0] - 2026-03-20

Changed — Breaking

  • Adopt shared ordered / bullet / outline list semantics across core, blueprint, and smithy-hwpx. Markdown bridge integrated.
  • Add checkable bullet semantics (HWPX heading(type="BULLET") + bullet.checkedChar + bullet.paraHead.checkable + paraPr.checked). Markdown task lists normalize to this shared HWP semantic; ordered task lists intentionally drop numbering on the way in.
  • Tighten bullet semantics: paragraph heading_level is no longer a catch-all for list semantics (see gotcha #7 in CLAUDE.md).

Added

  • Markdown bridge: preserve task list continuation paragraphs; normalize ordered task lists.
  • Fixtures: reorganized under examples/ and tests/fixtures/.

Fixed

  • HWPX style id bridging for registry-local style ids.
  • Outline contract hardening (golden tests).

[0.4.0] - 2026-03-20

Changed

  • Promote the workspace release line to 0.4.0 for the breaking tab semantics contract in hwpforge-core and hwpforge-blueprint.
  • Add shared tab-stop semantics across the IR stack so HWPX/HWP5 codecs can preserve explicit tab definitions and paragraph tab references.

Migration

  • hwpforge_core::TabDef now includes explicit stops; downstream struct literals must initialize the new field.
  • hwpforge_blueprint::Template, ParaShape, and PartialParaShape now carry tab definition references/collections directly.
  • Consumers matching on BlueprintErrorCode should handle the new tab-related error codes explicitly.

[0.3.0] - 2026-03-19

Changed

  • Promote the workspace release line to 0.3.0 for the breaking HWPX section editing contract update.
  • Preserve-first section editing now requires preservation metadata on ExportedSection and rejects stale or legacy section exports explicitly.

[0.2.0] - 2026-03-17

Changed

  • Adopt the hwpforge-core v0.2.0 public DOM contract for richer table and image semantics.
  • Align the workspace release line and internal crate pins on 0.2.0.

Migration

  • Table, TableRow, TableCell, and Image are now #[non_exhaustive] and should be constructed via new/with_* builders instead of struct literals.
  • Table DOM now carries page-break, repeat-header, cell-spacing, border/fill, header-row, cell margin, and vertical-alignment semantics directly in hwpforge-core.
  • Image DOM now carries placement metadata directly in hwpforge-core.
  • Validation now exposes CoreErrorCode::NonLeadingTableHeaderRow; downstream code that inspects validation codes should handle it explicitly.

0.1.0 - 2026-03-06

Added

  • hwpforge: Umbrella crate with feature flags (hwpx, md, full)
  • hwpforge-foundation: Primitive types (HwpUnit, Color BGR, branded Index, enums, error codes)
  • hwpforge-core: Format-independent document model with typestate validation (Draft/Validated)
    • Document, Section, Paragraph, Run, Table, Image
    • Controls: TextBox, Footnote, Endnote, Equation, Chart (18 types)
    • Shapes: Line, Ellipse, Polygon, Arc, Curve, ConnectLine
    • References: Bookmark, CrossRef, Field, Memo, IndexMark
    • Layout: Multi-column, captions, headers/footers, page numbers, master pages
    • Annotations: Dutmal, compose characters
  • hwpforge-blueprint: YAML-based style template system
    • Template inheritance with DFS merge
    • StyleRegistry with deduplicated fonts, char shapes, para shapes
    • Built-in default template (Hancom 한컴바탕)
    • BorderFill support
  • hwpforge-smithy-hwpx: Full HWPX codec (KS X 6101)
    • Decoder: HWPX ZIP+XML -> Core Document
    • Encoder: Core Document -> HWPX ZIP+XML
    • Lossless roundtrip for all supported content
    • HancomStyleSet support (Classic/Modern/Latest)
    • 22 default styles with per-style charPr/paraPr
    • ZIP bomb defense (50MB/500MB/10k limits)
    • OOXML chart generation (18 chart types)
    • Golden fixture tests with real Hancom 한글 files
  • hwpforge-smithy-md: Markdown codec
    • GFM decoder (pulldown-cmark) with YAML frontmatter
    • Lossy encoder (readable GFM) and lossless encoder (HTML+YAML)
    • Full pipeline: MD -> Core -> HWPX verified in Hancom 한글

by Ai-Scream