hwp-convert 1.0.0

package/dist/lib/hwp/byteReader.js

@@ -0,0 +1,116 @@
+/**
+ * 바이너리 데이터 읽기 유틸리티 (커서 기반).
+ * HWP 5.0 스트림은 모두 little-endian, 문자열은 UTF-16LE.
+ *
+ * 원작: rhwp/src/parser/byte_reader.rs (MIT, Copyright (c) 2025-2026 Edward Kim)
+ */
+const UTF16_LE = new TextDecoder("utf-16le");
+export class ByteReader {
+    view;
+    offset;
+    end;
+    constructor(data, offset = 0, length) {
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        this.offset = offset;
+        this.end = length === undefined ? data.byteLength : offset + length;
+    }
+    /** 현재 위치 (바이트 오프셋, 시작점 기준) */
+    position() {
+        return this.offset;
+    }
+    /** 남은 바이트 */
+    remaining() {
+        return Math.max(0, this.end - this.offset);
+    }
+    isEmpty() {
+        return this.remaining() === 0;
+    }
+    setPosition(pos) {
+        if (pos < 0 || pos > this.end) {
+            throw new RangeError(`setPosition out of range: ${pos} (end=${this.end})`);
+        }
+        this.offset = pos;
+    }
+    skip(n) {
+        if (this.offset + n > this.end) {
+            throw new RangeError(`skip exceeds end: pos=${this.offset}+${n} > ${this.end}`);
+        }
+        this.offset += n;
+    }
+    readU8() {
+        this.ensure(1);
+        return this.view.getUint8(this.offset++);
+    }
+    readU16() {
+        this.ensure(2);
+        const v = this.view.getUint16(this.offset, true);
+        this.offset += 2;
+        return v;
+    }
+    readU32() {
+        this.ensure(4);
+        const v = this.view.getUint32(this.offset, true);
+        this.offset += 4;
+        return v;
+    }
+    readI8() {
+        this.ensure(1);
+        return this.view.getInt8(this.offset++);
+    }
+    readI16() {
+        this.ensure(2);
+        const v = this.view.getInt16(this.offset, true);
+        this.offset += 2;
+        return v;
+    }
+    readI32() {
+        this.ensure(4);
+        const v = this.view.getInt32(this.offset, true);
+        this.offset += 4;
+        return v;
+    }
+    /** i64 (BigInt). HWP에서는 거의 등장하지 않지만 호환을 위해. */
+    readI64() {
+        this.ensure(8);
+        const v = this.view.getBigInt64(this.offset, true);
+        this.offset += 8;
+        return v;
+    }
+    /** 지정 길이 바이트를 복사하지 않고 sub-view 반환 (Uint8Array) */
+    readBytes(len) {
+        this.ensure(len);
+        const out = new Uint8Array(this.view.buffer, this.view.byteOffset + this.offset, len);
+        this.offset += len;
+        return new Uint8Array(out); // 복사본 — 호출자가 외부 라이프사이클을 신경 쓸 필요 없게
+    }
+    /** 남은 전부 */
+    readRemaining() {
+        return this.readBytes(this.remaining());
+    }
+    /**
+     * HWP 문자열: [u16 charCount] + [UTF-16LE bytes * charCount].
+     */
+    readHwpString() {
+        const charCount = this.readU16();
+        if (charCount === 0)
+            return "";
+        return this.readUtf16(charCount);
+    }
+    /** 지정 글자 수의 UTF-16LE 문자열 */
+    readUtf16(charCount) {
+        const byteLen = charCount * 2;
+        this.ensure(byteLen);
+        const slice = new Uint8Array(this.view.buffer, this.view.byteOffset + this.offset, byteLen);
+        this.offset += byteLen;
+        return UTF16_LE.decode(slice);
+    }
+    /** ColorRef (0x00BBGGRR) — u32 그대로 */
+    readColorRef() {
+        return this.readU32();
+    }
+    ensure(n) {
+        if (this.offset + n > this.end) {
+            throw new RangeError(`ByteReader: not enough bytes. need=${n}, have=${this.end - this.offset}, pos=${this.offset}`);
+        }
+    }
+}

package/dist/lib/hwp/cfbReader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HWP 5.0 CFB(OLE2) 컨테이너 리더.
+ * SheetJS 'cfb' 패키지를 감싸 HWP 친화적 API 제공.
+ *
+ * HWP CFB 구조:
+ *   /FileHeader              (256B, 비압축)
+ *   /DocInfo                 (압축 가능 — 비밀 stream에서 raw deflate)
+ *   /BodyText/Section{N}     (압축 가능)
+ *   /ViewText/Section{N}     (배포용 문서; 암호화)
+ *   /BinData/BIN{XXXX}.{ext} (이미지/임베디드)
+ *   /PrvImage, /PrvText      (미리보기)
+ *   /Scripts/..., /DocOptions/...
+ *
+ * 원작 참고: rhwp/src/parser/cfb_reader.rs (MIT, Edward Kim)
+ */
+export declare class CfbError extends Error {
+    constructor(msg: string);
+}
+export declare class HwpCfbReader {
+    private container;
+    constructor(data: Uint8Array);
+    /** path 정확히 일치하는 stream 의 raw bytes (압축/암호화 그대로) */
+    readStreamRaw(path: string): Uint8Array | null;
+    /** 디플레이트 압축 해제. raw deflate (zlib 헤더 없음). */
+    static decompress(data: Uint8Array): Uint8Array;
+    /** FileHeader (256바이트, 비압축) */
+    readFileHeader(): Uint8Array;
+    /** DocInfo (compressed 플래그에 따라 자동 해제) */
+    readDocInfo(compressed: boolean): Uint8Array;
+    /** /BodyText/SectionN 또는 /ViewText/SectionN (배포용) */
+    readBodySection(index: number, compressed: boolean, distribution: boolean): Uint8Array | null;
+    /** BodyText 섹션 개수 (Section0 ~ SectionN-1) */
+    sectionCount(distribution?: boolean): number;
+    /** /BinData/BIN{XXXX}.{ext} 모두 나열 */
+    listBinData(): {
+        name: string;
+        storageId: number;
+        extension: string;
+    }[];
+    /** /BinData/BIN{XXXX}.{ext} 의 데이터 (압축되어 있으면 해제 시도) */
+    readBinData(path: string): Uint8Array | null;
+    /** 디버그 — 모든 stream 경로 */
+    listStreams(): string[];
+}

package/dist/lib/hwp/cfbReader.js

@@ -0,0 +1,134 @@
+/**
+ * HWP 5.0 CFB(OLE2) 컨테이너 리더.
+ * SheetJS 'cfb' 패키지를 감싸 HWP 친화적 API 제공.
+ *
+ * HWP CFB 구조:
+ *   /FileHeader              (256B, 비압축)
+ *   /DocInfo                 (압축 가능 — 비밀 stream에서 raw deflate)
+ *   /BodyText/Section{N}     (압축 가능)
+ *   /ViewText/Section{N}     (배포용 문서; 암호화)
+ *   /BinData/BIN{XXXX}.{ext} (이미지/임베디드)
+ *   /PrvImage, /PrvText      (미리보기)
+ *   /Scripts/..., /DocOptions/...
+ *
+ * 원작 참고: rhwp/src/parser/cfb_reader.rs (MIT, Edward Kim)
+ */
+import * as CFB from "cfb";
+import { inflateRaw } from "pako";
+export class CfbError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "CfbError";
+    }
+}
+export class HwpCfbReader {
+    container;
+    constructor(data) {
+        try {
+            this.container = CFB.read(data, { type: "buffer" });
+        }
+        catch (e) {
+            throw new CfbError(`CFB 파싱 실패: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /** path 정확히 일치하는 stream 의 raw bytes (압축/암호화 그대로) */
+    readStreamRaw(path) {
+        const norm = path.startsWith("/") ? path : `/${path}`;
+        const entry = CFB.find(this.container, norm);
+        if (!entry || entry.type !== 2 /* stream */)
+            return null;
+        return toUint8Array(entry.content);
+    }
+    /** 디플레이트 압축 해제. raw deflate (zlib 헤더 없음). */
+    static decompress(data) {
+        if (data.byteLength === 0)
+            return data;
+        try {
+            return inflateRaw(data);
+        }
+        catch (e) {
+            throw new CfbError(`deflate 해제 실패: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /** FileHeader (256바이트, 비압축) */
+    readFileHeader() {
+        const data = this.readStreamRaw("/FileHeader");
+        if (!data)
+            throw new CfbError("/FileHeader 스트림이 없습니다");
+        return data;
+    }
+    /** DocInfo (compressed 플래그에 따라 자동 해제) */
+    readDocInfo(compressed) {
+        const raw = this.readStreamRaw("/DocInfo");
+        if (!raw)
+            throw new CfbError("/DocInfo 스트림이 없습니다");
+        return compressed ? HwpCfbReader.decompress(raw) : raw;
+    }
+    /** /BodyText/SectionN 또는 /ViewText/SectionN (배포용) */
+    readBodySection(index, compressed, distribution) {
+        const folder = distribution ? "ViewText" : "BodyText";
+        const raw = this.readStreamRaw(`/${folder}/Section${index}`);
+        if (!raw)
+            return null;
+        if (distribution) {
+            // ViewText 는 암호화되어 있어 v1 미지원: 호출자가 raw 처리
+            return raw;
+        }
+        return compressed ? HwpCfbReader.decompress(raw) : raw;
+    }
+    /** BodyText 섹션 개수 (Section0 ~ SectionN-1) */
+    sectionCount(distribution = false) {
+        const folder = distribution ? "ViewText" : "BodyText";
+        const re = new RegExp(`(?:^|/)${folder}/Section\\d+$`);
+        let n = 0;
+        for (const path of this.container.FullPaths) {
+            if (re.test(path))
+                n++;
+        }
+        return n;
+    }
+    /** /BinData/BIN{XXXX}.{ext} 모두 나열 */
+    listBinData() {
+        const result = [];
+        const re = /(?:^|\/)BinData\/BIN([0-9A-Fa-f]{4})\.([^/]+)$/;
+        for (const path of this.container.FullPaths) {
+            const m = re.exec(path);
+            if (!m)
+                continue;
+            result.push({
+                name: path,
+                storageId: parseInt(m[1], 16),
+                extension: m[2].toLowerCase(),
+            });
+        }
+        return result;
+    }
+    /** /BinData/BIN{XXXX}.{ext} 의 데이터 (압축되어 있으면 해제 시도) */
+    readBinData(path) {
+        const raw = this.readStreamRaw(path);
+        if (!raw)
+            return null;
+        // BinData 도 일반적으로 압축됨
+        try {
+            return HwpCfbReader.decompress(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    /** 디버그 — 모든 stream 경로 */
+    listStreams() {
+        const out = [];
+        for (let i = 0; i < this.container.FileIndex.length; i++) {
+            if (this.container.FileIndex[i].type === 2)
+                out.push(this.container.FullPaths[i]);
+        }
+        return out;
+    }
+}
+function toUint8Array(content) {
+    if (content instanceof Uint8Array)
+        return content;
+    // number[]
+    return Uint8Array.from(content);
+}

package/dist/lib/hwp/control.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 컨트롤 파싱 (CTRL_HEADER 의 ctrl_id 별 분기).
+ *
+ * 1차 포팅 범위: 표(tbl) / 그림(gso+pic) / 머리말(head) / 꼬리말(foot) / 각주(fn)
+ *
+ * 원작: rhwp/src/parser/control.rs (MIT, Edward Kim)
+ */
+import type { Record } from "./record.js";
+import type { HwpControl, HwpParagraph } from "./types.js";
+/**
+ * CTRL_HEADER 레코드와 그 자식 레코드들을 받아 HwpControl 로 변환.
+ *
+ * @param ctrlHeader CTRL_HEADER 레코드 자체
+ * @param children CTRL_HEADER 의 자식 레코드들 (level > ctrlHeader.level). subtree 의 후손까지 포함.
+ * @param parseParagraphList 재귀 파싱용 콜백 — 셀/머리말 등 내부 문단 추출
+ */
+export declare function parseCtrlHeader(ctrlHeader: Record, children: Record[], parseParagraphList: (records: Record[], baseLevel: number) => HwpParagraph[]): HwpControl;

package/dist/lib/hwp/control.js

@@ -0,0 +1,290 @@
+/**
+ * 컨트롤 파싱 (CTRL_HEADER 의 ctrl_id 별 분기).
+ *
+ * 1차 포팅 범위: 표(tbl) / 그림(gso+pic) / 머리말(head) / 꼬리말(foot) / 각주(fn)
+ *
+ * 원작: rhwp/src/parser/control.rs (MIT, Edward Kim)
+ */
+import { ByteReader } from "./byteReader.js";
+import { CTRL_TABLE, CTRL_GEN_SHAPE, CTRL_HEADER, CTRL_FOOTER, CTRL_FOOTNOTE, CTRL_EQUATION, HWPTAG_TABLE, HWPTAG_LIST_HEADER, HWPTAG_SHAPE_COMPONENT_PICTURE, HWPTAG_SHAPE_COMPONENT_LINE, HWPTAG_SHAPE_COMPONENT_RECTANGLE, HWPTAG_SHAPE_COMPONENT_ELLIPSE, HWPTAG_SHAPE_COMPONENT_ARC, HWPTAG_SHAPE_COMPONENT_POLYGON, HWPTAG_SHAPE_COMPONENT_CURVE, HWPTAG_EQEDIT, ctrlIdToString, isFieldCtrlId, } from "./tags.js";
+/**
+ * CTRL_HEADER 레코드와 그 자식 레코드들을 받아 HwpControl 로 변환.
+ *
+ * @param ctrlHeader CTRL_HEADER 레코드 자체
+ * @param children CTRL_HEADER 의 자식 레코드들 (level > ctrlHeader.level). subtree 의 후손까지 포함.
+ * @param parseParagraphList 재귀 파싱용 콜백 — 셀/머리말 등 내부 문단 추출
+ */
+export function parseCtrlHeader(ctrlHeader, children, parseParagraphList) {
+    if (ctrlHeader.data.byteLength < 4) {
+        return { kind: "unknown", ctrlId: "" };
+    }
+    // ctrl_id 는 첫 4바이트의 u32(LE) 값. tags.ts 의 ctrlId() 와 동일한 big-endian 표기 정수를 반환하도록 변환.
+    // 파일에는 "secd" 가 [0x64, 0x63, 0x65, 0x73] 순서(LE u32)로 저장되며, 같은 4글자를 BE u32 로 인코딩한 값과 동일.
+    const r = new ByteReader(ctrlHeader.data);
+    const ctrlIdRaw = r.readU32(); // LE u32 → 그대로 BE 인코딩한 ctrl_id 와 일치
+    const ctrlData = ctrlHeader.data.subarray(4);
+    switch (ctrlIdRaw) {
+        case CTRL_TABLE:
+            return parseTableControl(ctrlHeader, children, parseParagraphList);
+        case CTRL_GEN_SHAPE:
+            return parseGsoControl(ctrlHeader, children);
+        case CTRL_HEADER:
+            return {
+                kind: "header",
+                paragraphs: collectListHeaderParagraphs(ctrlHeader, children, parseParagraphList),
+            };
+        case CTRL_FOOTER:
+            return {
+                kind: "footer",
+                paragraphs: collectListHeaderParagraphs(ctrlHeader, children, parseParagraphList),
+            };
+        case CTRL_FOOTNOTE:
+            return {
+                kind: "footnote",
+                paragraphs: collectListHeaderParagraphs(ctrlHeader, children, parseParagraphList),
+            };
+        case CTRL_EQUATION:
+            return parseEquationControl(ctrlHeader, children);
+        default:
+            if (isFieldCtrlId(ctrlIdRaw)) {
+                return parseFieldControl(ctrlIdRaw, ctrlData);
+            }
+            return { kind: "unknown", ctrlId: ctrlIdToString(ctrlIdRaw) };
+    }
+}
+// ============================================================
+// 표
+// ============================================================
+function parseTableControl(ctrlHeader, children, parseParagraphList) {
+    const baseLevel = ctrlHeader.level;
+    let rowCount = 0;
+    let colCount = 0;
+    const cells = [];
+    // 자식 중 직접 자식(level == baseLevel + 1) 만 처리.
+    // - HWPTAG_TABLE: 표 메타데이터 (행/열)
+    // - HWPTAG_LIST_HEADER: 셀 (그 자체는 레벨 baseLevel+1)
+    //   각 셀의 내부 문단 PARA_HEADER 는 level baseLevel+2
+    let tableSeen = false;
+    for (let i = 0; i < children.length; i++) {
+        const r = children[i];
+        if (r.level !== baseLevel + 1)
+            continue;
+        if (r.tagId === HWPTAG_TABLE) {
+            tableSeen = true;
+            const meta = parseTableMeta(r.data);
+            rowCount = meta.rowCount;
+            colCount = meta.colCount;
+        }
+        else if (r.tagId === HWPTAG_LIST_HEADER) {
+            // TABLE 레코드 이전의 LIST_HEADER 는 캡션 — 1차 포팅에서는 무시
+            if (!tableSeen)
+                continue;
+            // 셀 메타데이터 파싱 (LIST_HEADER 의 데이터)
+            const cellMeta = parseCellMeta(r.data);
+            // HWP 셀 구조 특이점: LIST_HEADER 와 그 셀의 PARA_HEADER 가 같은 level 이다.
+            // 따라서 셀 범위는 다음 LIST_HEADER 또는 TABLE (같은 level) 까지.
+            // PARA_HEADER 는 같은 level 이라도 셀 내용이므로 포함시킨다.
+            const cellChildren = [];
+            for (let j = i + 1; j < children.length; j++) {
+                const cr = children[j];
+                if (cr.level < baseLevel + 1)
+                    break; // 서브트리 탈출
+                if (cr.level === baseLevel + 1) {
+                    if (cr.tagId === HWPTAG_LIST_HEADER || cr.tagId === HWPTAG_TABLE)
+                        break;
+                }
+                cellChildren.push(cr);
+            }
+            // 셀 문단은 LIST_HEADER 와 같은 level (baseLevel + 1)
+            const cellParagraphs = parseParagraphList(cellChildren, baseLevel + 1);
+            cells.push({
+                col: cellMeta.col,
+                row: cellMeta.row,
+                colSpan: cellMeta.colSpan,
+                rowSpan: cellMeta.rowSpan,
+                paragraphs: cellParagraphs,
+            });
+        }
+    }
+    return { kind: "table", rowCount, colCount, cells };
+}
+function parseTableMeta(data) {
+    const r = new ByteReader(data);
+    if (r.remaining() < 8)
+        return { rowCount: 0, colCount: 0 };
+    r.readU32(); // attr
+    const rowCount = r.readU16();
+    const colCount = r.readU16();
+    return { rowCount, colCount };
+}
+function parseCellMeta(data) {
+    const r = new ByteReader(data);
+    // LIST_HEADER 공통: nParagraphs(u16) + listAttr(u32) + listHeaderWidthRef(u16)
+    if (r.remaining() < 8)
+        return { col: 0, row: 0, colSpan: 1, rowSpan: 1 };
+    r.readU16();
+    r.readU32();
+    r.readU16();
+    // 셀 메타: col(u16) row(u16) colSpan(u16) rowSpan(u16)
+    if (r.remaining() < 8)
+        return { col: 0, row: 0, colSpan: 1, rowSpan: 1 };
+    const col = r.readU16();
+    const row = r.readU16();
+    const colSpan = r.readU16();
+    const rowSpan = r.readU16();
+    return {
+        col,
+        row,
+        colSpan: colSpan === 0 ? 1 : colSpan,
+        rowSpan: rowSpan === 0 ? 1 : rowSpan,
+    };
+}
+// ============================================================
+// 그리기 개체 (gso) — 1차 포팅: PICTURE 만 추출
+// ============================================================
+function parseGsoControl(ctrlHeader, children) {
+    const baseLevel = ctrlHeader.level;
+    // 그림이 우선 — SHAPE_COMPONENT_PICTURE 레코드 검색
+    for (const r of children) {
+        if (r.tagId === HWPTAG_SHAPE_COMPONENT_PICTURE && r.level <= baseLevel + 3) {
+            const binDataId = parsePictureBinDataId(r.data);
+            if (binDataId !== undefined) {
+                return { kind: "picture", binDataId };
+            }
+        }
+    }
+    // 도형 (line/rect/ellipse/arc/polygon/curve)
+    for (const r of children) {
+        if (r.level > baseLevel + 3)
+            continue;
+        switch (r.tagId) {
+            case HWPTAG_SHAPE_COMPONENT_LINE:
+                return parseLineShape(r.data);
+            case HWPTAG_SHAPE_COMPONENT_RECTANGLE:
+                return { kind: "shape", shapeType: "rectangle" };
+            case HWPTAG_SHAPE_COMPONENT_ELLIPSE:
+                return { kind: "shape", shapeType: "ellipse" };
+            case HWPTAG_SHAPE_COMPONENT_ARC:
+                return { kind: "shape", shapeType: "arc" };
+            case HWPTAG_SHAPE_COMPONENT_POLYGON:
+                return { kind: "shape", shapeType: "polygon" };
+            case HWPTAG_SHAPE_COMPONENT_CURVE:
+                return { kind: "shape", shapeType: "curve" };
+        }
+    }
+    return { kind: "unknown", ctrlId: "gso " };
+}
+function parseLineShape(data) {
+    // SHAPE_LINE: x1(i32), y1(i32), x2(i32), y2(i32) + 추가 속성
+    if (data.byteLength < 16)
+        return { kind: "shape", shapeType: "line" };
+    const r = new ByteReader(data);
+    const x1 = r.readI32();
+    const y1 = r.readI32();
+    const x2 = r.readI32();
+    const y2 = r.readI32();
+    return { kind: "shape", shapeType: "line", x1, y1, x2, y2 };
+}
+// ============================================================
+// 수식
+// ============================================================
+function parseEquationControl(ctrlHeader, children) {
+    // EQEDIT 레코드를 자식에서 찾는다.
+    // EQEDIT 레이아웃: u32 attr + u16 width + u16 height + u32 charCount(?) + WCHAR script + ...
+    // 여기서는 단순히 UTF-16 문자열을 추출해서 반환.
+    for (const r of children) {
+        if (r.tagId === HWPTAG_EQEDIT) {
+            return { kind: "equation", script: extractEquationScript(r.data) };
+        }
+    }
+    return { kind: "equation", script: "" };
+}
+function extractEquationScript(data) {
+    // 보수적으로 파싱: u32 attr 다음 가변. HWP 스펙상:
+    // u32 attr | i16 nLine | i16 lineHeight | u8 charScale | u32 baseUnit |
+    // u16 strLen | WCHAR script[strLen] | u16 charSet | i32 fontSize ...
+    // strLen 이 어디인지 찾기 위해 처음 몇 u16 의 패턴을 검사.
+    const r = new ByteReader(data);
+    if (r.remaining() < 4)
+        return "";
+    r.readU32(); // attr
+    // nLine, lineHeight (i16 x 2), charScale (u8), baseUnit (u32) — 11바이트
+    if (r.remaining() < 11)
+        return "";
+    r.skip(11);
+    if (r.remaining() < 2)
+        return "";
+    const strLen = r.readU16();
+    if (strLen === 0 || strLen > 10000)
+        return "";
+    const need = strLen * 2;
+    if (r.remaining() < need)
+        return "";
+    try {
+        return r.readUtf16(strLen);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * SHAPE_COMPONENT_PICTURE 레코드에서 bin_data_id 추출.
+ * 레이아웃 (rhwp 기준):
+ *   border_color  u32       (4)
+ *   border_width  i32       (4)
+ *   border_attr   u32       (4)
+ *   border_x[4]   i32 each (16)
+ *   border_y[4]   i32 each (16)
+ *   crop          4x i32   (16)
+ *   padding       4x i16    (8)
+ *   brightness    i8        (1)
+ *   contrast      i8        (1)
+ *   effect        u8        (1)
+ *   bin_data_id   u16       (2) ← offset 71
+ */
+function parsePictureBinDataId(data) {
+    const OFFSET = 4 + 4 + 4 + 16 + 16 + 16 + 8 + 1 + 1 + 1; // 71
+    if (data.byteLength < OFFSET + 2)
+        return undefined;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return view.getUint16(OFFSET, true);
+}
+// ============================================================
+// LIST_HEADER 기반 컨트롤 (head/foot/fn)
+// ============================================================
+function collectListHeaderParagraphs(ctrlHeader, children, parseParagraphList) {
+    const baseLevel = ctrlHeader.level;
+    // 첫 LIST_HEADER (level baseLevel+1) 의 자식 PARA_HEADER (level baseLevel+2) 수집
+    const lhIdx = children.findIndex((r) => r.tagId === HWPTAG_LIST_HEADER && r.level === baseLevel + 1);
+    if (lhIdx < 0)
+        return [];
+    const subtree = [];
+    for (let j = lhIdx + 1; j < children.length; j++) {
+        if (children[j].level <= baseLevel + 1)
+            break;
+        subtree.push(children[j]);
+    }
+    return parseParagraphList(subtree, baseLevel + 2);
+}
+// ============================================================
+// 필드 컨트롤
+// ============================================================
+function parseFieldControl(ctrlIdRaw, ctrlData) {
+    const id = ctrlIdToString(ctrlIdRaw);
+    if (ctrlData.byteLength < 7)
+        return { kind: "field", ctrlId: id };
+    const r = new ByteReader(ctrlData);
+    r.readU32(); // properties
+    r.readU8(); // extra
+    const commandLen = r.readU16();
+    let command;
+    if (commandLen > 0 && r.remaining() >= commandLen * 2) {
+        try {
+            command = r.readUtf16(commandLen);
+        }
+        catch {
+            command = undefined;
+        }
+    }
+    return { kind: "field", ctrlId: id, command };
+}

package/dist/lib/hwp/converter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HwpDocument IR → HWPX/Text 변환기.
+ *
+ * - hwpToText: 모든 섹션의 문단 텍스트를 평탄화 (표 셀, 헤더/푸터 등 포함).
+ * - hwpToHwpx: hwpxBuilder 로 풍부한 HWPX 패키지 생성 (표/이미지 포함).
+ */
+import { hwpDocumentToMarkdown, type MarkdownWriteOptions } from "./mdWriter.js";
+import { markdownToHwpDocument } from "./mdReader.js";
+import { htmlToHwpDocument } from "./htmlReader.js";
+import type { HwpDocument } from "./types.js";
+export { hwpDocumentToMarkdown, markdownToHwpDocument, htmlToHwpDocument };
+export type { MarkdownWriteOptions };
+export interface HwpToTextOptions {
+    paragraphSeparator?: string;
+    sectionSeparator?: string;
+}
+export declare function hwpDocumentToText(doc: HwpDocument, options?: HwpToTextOptions): string;
+export interface HwpToHwpxOptions {
+    title?: string;
+    creator?: string;
+}
+export declare function hwpDocumentToHwpx(doc: HwpDocument, options?: HwpToHwpxOptions): Promise<Uint8Array>;

package/dist/lib/hwp/converter.js

@@ -0,0 +1,41 @@
+/**
+ * HwpDocument IR → HWPX/Text 변환기.
+ *
+ * - hwpToText: 모든 섹션의 문단 텍스트를 평탄화 (표 셀, 헤더/푸터 등 포함).
+ * - hwpToHwpx: hwpxBuilder 로 풍부한 HWPX 패키지 생성 (표/이미지 포함).
+ */
+import { buildHwpxFromDocument } from "./hwpxBuilder.js";
+import { hwpDocumentToMarkdown } from "./mdWriter.js";
+import { markdownToHwpDocument } from "./mdReader.js";
+import { htmlToHwpDocument } from "./htmlReader.js";
+export { hwpDocumentToMarkdown, markdownToHwpDocument, htmlToHwpDocument };
+export function hwpDocumentToText(doc, options) {
+    const paraSep = options?.paragraphSeparator ?? "\n";
+    const sectSep = options?.sectionSeparator ?? "\n\n";
+    return doc.sections
+        .map((s) => s.paragraphs.map((p) => flattenParagraphText(p)).join(paraSep))
+        .join(sectSep);
+}
+function flattenParagraphText(p) {
+    const parts = [];
+    if (p.text.length > 0)
+        parts.push(p.text);
+    for (const ctrl of p.controls) {
+        if (ctrl.kind === "table") {
+            const cellTexts = ctrl.cells.map((cell) => cell.paragraphs.map((q) => flattenParagraphText(q)).join("\n"));
+            parts.push(cellTexts.join("\n"));
+        }
+        else if (ctrl.kind === "header" ||
+            ctrl.kind === "footer" ||
+            ctrl.kind === "footnote") {
+            parts.push(ctrl.paragraphs.map((q) => flattenParagraphText(q)).join("\n"));
+        }
+        else if (ctrl.kind === "equation" && ctrl.script.length > 0) {
+            parts.push(ctrl.script);
+        }
+    }
+    return parts.join("\n");
+}
+export async function hwpDocumentToHwpx(doc, options) {
+    return await buildHwpxFromDocument(doc, options);
+}