hwpkit-dev 0.0.2 → 0.0.3

package/src/encoders/hwpx/constants.ts

@@ -0,0 +1,148 @@
+/**
+ * HWPX 인코더 관련 상수
+ *
+ * HWPX 파일 생성에 필요한 모든 설정값을 한곳에 모아 관리합니다.
+ * 초중급 개발자도 쉽게 수정할 수 있도록 명확한 주석을 포함했습니다.
+ */
+
+// ==================== 파일 형식 관련 ====================
+
+/** HWPX 파일의 MIME 타입 (ZIP 파일 내 mimetype 파일에 저장됨) */
+export const HWPX_MIME_TYPE = "application/hwp+zip";
+
+/** HWPX 파일의 버전 */
+export const HWPX_VERSION = "1.2";
+
+// ==================== XML 네임스페이스 ====================
+
+/** HWPX XML 문서에서 사용되는 네임스페이스 */
+export const NAMESPACES = {
+  /** Hancom 문서 네임스페이스 */
+  HANCOM: "http://www.hancom.co.kr/hwp/xml",
+  /** Hancom 공통 네임스페이스 */
+  HANCOM_COMMON: "http://www.hancom.co.kr/hwp/xml/common",
+  /** Hancom 버전 네임스페이스 */
+  HANCOM_VERSION: "http://www.hancom.co.kr/hwp/xml/version",
+  /** Hancom 속성 네임스페이스 */
+  HANCOM_PROP: "http://www.hancom.co.kr/hwp/xml/property",
+} as const;
+
+/** XML 헤더에 포함될 네임스페이스 선언 문자열 */
+export const NAMESPACE_DECLARATIONS = {
+  HEAD: `xmlns:hh="${NAMESPACES.HANCOM}" xmlns:hc="${NAMESPACES.HANCOM_COMMON}" xmlns:hv="${NAMESPACES.HANCOM_VERSION}" xmlns:hp="${NAMESPACES.HANCOM_PROP}"`,
+  SECTION: `xmlns:hs="${NAMESPACES.HANCOM}" xmlns:hp="${NAMESPACES.HANCOM_PROP}"`,
+} as const;
+
+// ==================== 단위 변환 ====================
+
+/** 1 포인트 (pt) 를 HWPUNIT 으로 변환한 값 (HWPX 내부 단위) */
+export const HWPUNIT_PER_PT = 1000;
+
+/** 1 인치 (inch) 를 포인트 (pt) 로 변환한 값 */
+export const PT_PER_INCH = 72;
+
+/** 1 인치 (inch) 를 픽셀로 변환한 값 (표준 96 DPI 기준) */
+export const PIXELS_PER_INCH = 96;
+
+/** 픽셀을 포인트로 변환하는 계수 */
+export const PT_PER_PIXEL = PT_PER_INCH / PIXELS_PER_INCH; // 0.75
+
+// ==================== 페이지 크기 (A4 기준) ====================
+
+/** A4 용지 너비 (포인트) */
+export const A4_WIDTH_PT = 794;
+
+/** A4 용지 높이 (포인트) */
+export const A4_HEIGHT_PT = 1123;
+
+/** A4 용지 상단 여백 (포인트) */
+export const A4_TOP_MARGIN_PT = 72;
+
+/** A4 용지 하단 여백 (포인트) */
+export const A4_BOTTOM_MARGIN_PT = 72;
+
+/** A4 용지 왼쪽 여백 (포인트) */
+export const A4_LEFT_MARGIN_PT = 83;
+
+/** A4 용지 오른쪽 여백 (포인트) */
+export const A4_RIGHT_MARGIN_PT = 83;
+
+/** A4 용지 상단 머리글 영역 (포인트) */
+export const A4_HEADER_MARGIN_PT = 40;
+
+/** A4 용지 하단 바닥글 영역 (포인트) */
+export const A4_FOOTER_MARGIN_PT = 40;
+
+// ==================== 폰트 관련 ====================
+
+/** 기본 한글 폰트 */
+export const DEFAULT_KOREAN_FONT = "Batang";
+
+/** 기본 영문 폰트 */
+export const DEFAULT_LATIN_FONT = "Arial";
+
+/** 기본 폰트 크기 (포인트) */
+export const DEFAULT_FONT_SIZE_PT = 10;
+
+// ==================== 줄 간격 ====================
+
+/** 기본 줄 간격 (폰트 크기의 %) */
+export const DEFAULT_LINE_SPACING_PERCENT = 160;
+
+/** 최소 줄 간격 (HWPUNIT) */
+export const MIN_LINE_SPACING_HWPUNIT = 1000;
+
+// ==================== 스타일 ID ====================
+
+/** 바탕글 스타일 ID */
+export const STYLE_ID_BATANGGUL = "0";
+
+/** 개요 1 스타일 ID */
+export const STYLE_ID_GYEYOE1 = "1";
+
+/** 개요 2 스타일 ID */
+export const STYLE_ID_GYEYOE2 = "2";
+
+// ==================== 이미지 관련 ====================
+
+/** 이미지 파일이 저장될 디렉토리 경로 (ZIP 내) */
+export const IMAGE_DIR_PATH = "image/";
+
+/** 이미지 파일명 접미사 */
+export const IMAGE_FILE_EXTENSION = ".png";
+
+// ==================== 테이블 관련 ====================
+
+/** 테이블 테두리 기본 두께 (HWPUNIT) */
+export const TABLE_BORDER_WIDTH_HWPUNIT = 500; // 0.5pt
+
+/** 테이블 셀 기본 패딩 (HWPUNIT) */
+export const TABLE_CELL_PADDING_HWPUNIT = 200; // 0.2pt
+
+// ==================== 색상 코드 ====================
+
+/** 검정색 (hex) */
+export const COLOR_BLACK = "#000000";
+
+/** 흰색 (hex) */
+export const COLOR_WHITE = "#FFFFFF";
+
+/** 회색 (워터마크용) */
+export const COLOR_GRAY = "#CCCCCC";
+
+/** 코드 블록 배경색 */
+export const COLOR_CODE_BLOCK_BG = "#f4f4f4";
+
+// ==================== ZIP 파일 구조 ====================
+
+/** HWPX 파일 내 파일 목록 */
+export const HWPX_FILE_STRUCTURE = [
+  { name: "mimetype", mimeType: "" },
+  { name: ".hwpversions/version.xml", mimeType: "application/xml" },
+  { name: "header.xml", mimeType: "application/xml" },
+  { name: "section0.xml", mimeType: "application/xml" },
+  { name: "content.hpf", mimeType: "application/octet-stream" },
+] as const;
+
+/** ZIP 파일 생성 시 사용할 압축 레벨 (0=압축안함, 9=최대압축) */
+export const ZIP_COMPRESSION_LEVEL = 9;

package/src/encoders/hwpx/utils.ts

@@ -0,0 +1,198 @@
+/**
+ * HWPX 인코더 유틸리티 함수
+ *
+ * HWPX 인코딩에 필요한 재사용 가능한 함수들을 모아둔 모듈입니다.
+ */
+
+import {
+  HWPUNIT_PER_PT,
+  PT_PER_PIXEL,
+  PT_PER_INCH,
+} from './constants';
+
+// ==================== 단위 변환 함수 ====================
+
+/**
+ * 포인트 (pt) 를 HWPUNIT 으로 변환합니다.
+ * @param pt - 포인트 값
+ * @returns HWPUNIT 값 (정수)
+ * @example
+ * ptToHwp(10)  // 10000 (10pt × 1000)
+ */
+export function ptToHwp(pt: number): number {
+  return Math.round(pt * HWPUNIT_PER_PT);
+}
+
+/**
+ * HWPUNIT 을 포인트 (pt) 로 변환합니다.
+ * @param hwpunit - HWPUNIT 값
+ * @returns 포인트 값
+ * @example
+ * hwpToPt(10000)  // 10 (10000 ÷ 1000)
+ */
+export function hwpToPt(hwpunit: number): number {
+  return hwpunit / HWPUNIT_PER_PT;
+}
+
+/**
+ * 포인트 (pt) 를 HWP 높이 단위로 변환합니다.
+ * 폰트 높이로 사용되며 ptToHwp 와 동일합니다.
+ * @param pt - 포인트 값
+ * @returns HWP 높이 단위
+ */
+export function ptToHHeight(pt: number): number {
+  return ptToHwp(pt);
+}
+
+/**
+ * 픽셀을 포인트 (pt) 로 변환합니다.
+ * @param pixels - 픽셀 값
+ * @returns 포인트 값
+ * @example
+ * pixelsToPt(96)  // 72 (96px × 72/96)
+ */
+export function pixelsToPt(pixels: number): number {
+  return pixels * PT_PER_PIXEL;
+}
+
+/**
+ * 픽셀을 HWPUNIT 으로 변환합니다.
+ * @param pixels - 픽셀 값
+ * @returns HWPUNIT 값
+ */
+export function pixelsToHwp(pixels: number): number {
+  return ptToHwp(pixelsToPt(pixels));
+}
+
+/**
+ * 인치 (inch) 를 포인트 (pt) 로 변환합니다.
+ * @param inches - 인치 값
+ * @returns 포인트 값
+ * @example
+ * inchesToPt(1)  // 72 (1 인치 × 72)
+ */
+export function inchesToPt(inches: number): number {
+  return inches * PT_PER_INCH;
+}
+
+/**
+ * 인치 (inch) 를 HWPUNIT 으로 변환합니다.
+ * @param inches - 인치 값
+ * @returns HWPUNIT 값
+ */
+export function inchesToHwp(inches: number): number {
+  return ptToHwp(inchesToPt(inches));
+}
+
+// ==================== XML 도우미 함수 ====================
+
+/**
+ * XML 문자열을 이스케이프 처리합니다.
+ * @param str - 이스케이프할 문자열
+ * @returns 이스케이프된 문자열
+ * @example
+ * escapeXml("<hello>&world")  // "&lt;hello&gt;&amp;world"
+ */
+export function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * 속성 문자열을 생성합니다.
+ * @param attributes - 속성 객체 (null/undefined 값은 제외됨)
+ * @returns 속성 문자열
+ * @example
+ * buildAttributes({ id: "1", name: "test", disabled: null })
+ * // 'id="1" name="test"'
+ */
+export function buildAttributes(attributes: Record<string, string | number | null | undefined>): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value != null && value !== "") {
+      const escapedValue = typeof value === "string" ? escapeXml(value) : String(value);
+      parts.push(`${key}="${escapedValue}"`);
+    }
+  }
+  return parts.join(" ");
+}
+
+/**
+ * XML 요소를 생성합니다.
+ * @param tagName - 태그 이름
+ * @param attributes - 속성 객체
+ * @param content - 내용 (문자열 또는 자식 요소 배열)
+ * @returns XML 요소 문자열
+ * @example
+ * createElement("span", { id: "1" }, "내용")
+ * // '<span id="1">내용</span>'
+ */
+export function createElement(
+  tagName: string,
+  attributes: Record<string, string | number | null | undefined> = {},
+  content: string | string[] = "",
+): string {
+  const attrs = buildAttributes(attributes);
+  const attrsStr = attrs ? ` ${attrs}` : "";
+  const contentStr = Array.isArray(content) ? content.join("") : content;
+
+  if (contentStr === "") {
+    return `<${tagName}${attrsStr}/>`;
+  }
+  return `<${tagName}${attrsStr}>${contentStr}</${tagName}>`;
+}
+
+// ==================== 문자열 처리 함수 ====================
+
+/**
+ * 문자열이 한글을 포함하는지 확인합니다.
+ * @param text - 확인할 문자열
+ * @returns 한글이 포함되어 있으면 true
+ */
+export function containsKorean(text: string): boolean {
+  return /[\uAC00-\uD7A3\u3131-\u318E]/.test(text);
+}
+
+/**
+ * 문자열이 영문을 포함하는지 확인합니다.
+ * @param text - 확인할 문자열
+ * @returns 영문이 포함되어 있으면 true
+ */
+export function containsLatin(text: string): boolean {
+  return /[a-zA-Z]/.test(text);
+}
+
+// ==================== 계산 함수 ====================
+
+/**
+ * 두 숫자 중 큰 값을 반환합니다.
+ * @param a - 첫 번째 숫자
+ * @param b - 두 번째 숫자
+ * @returns 큰 값
+ */
+export function max(a: number, b: number): number {
+  return a > b ? a : b;
+}
+
+/**
+ * 두 숫자 중 작은 값을 반환합니다.
+ * @param a - 첫 번째 숫자
+ * @param b - 두 번째 숫자
+ * @returns 작은 값
+ */
+export function min(a: number, b: number): number {
+  return a < b ? a : b;
+}
+
+/**
+ * 숫자를 정수로 반올림합니다.
+ * @param value - 변환할 숫자
+ * @returns 정수
+ */
+export function round(value: number): number {
+  return Math.round(value);
+}

package/src/encoders/md/MdEncoder.ts

@@ -1,40 +1,42 @@
-import type { Encoder } from '../../contract/encoder';
 import type { DocRoot, ParaNode, SpanNode, GridNode, ContentNode, ImgNode } from '../../model/doc-tree';
 import type { Outcome } from '../../contract/result';
 import type { Stroke } from '../../model/doc-props';
+import type { EncoderOptions } from '../../contract/encoder';
 import { succeed, fail } from '../../contract/result';
 import { TextKit } from '../../toolkit/TextKit';
 import { registry } from '../../pipeline/registry';
+import { BaseEncoder } from '../../core/BaseEncoder';
 
-export class MdEncoder implements Encoder {
-  readonly format = 'md';
+export class MdEncoder extends BaseEncoder {
+  protected getFormat(): string { return 'md'; }
 
-  async encode(doc: DocRoot): Promise<Outcome<Uint8Array>> {
+  async encode(doc: DocRoot, options?: EncoderOptions): Promise<Outcome<Uint8Array>> {
+    const includeImages = options?.includeImages !== false;  // default: true
     try {
       const warns: string[] = [];
       const parts: string[] = [];
       for (const sheet of doc.kids) {
         // Warn about header/footer loss
-        if (sheet.header && sheet.header.length > 0) warns.push('[SHIELD] MD: 머리글(header) 표현 불가 — 손실됨');
-        if (sheet.footer && sheet.footer.length > 0) warns.push('[SHIELD] MD: 바닥글(footer) 표현 불가 — 손실됨');
+        if (sheet.headers && sheet.headers.default && sheet.headers.default.length > 0) warns.push('[SHIELD] MD: 머리글(header) 표현 불가 — 손실됨');
+        if (sheet.footers && sheet.footers.default && sheet.footers.default.length > 0) warns.push('[SHIELD] MD: 바닥글(footer) 표현 불가 — 손실됨');
 
-        for (const kid of sheet.kids) parts.push(encodeContent(kid, warns));
+        for (const kid of sheet.kids) parts.push(encodeContent(kid, warns, includeImages));
       }
-      return succeed(TextKit.encode(parts.join('\n\n')), warns);
+      return succeed(this.stringToBytes(parts.join('\n\n')), warns);
     } catch (e: any) {
       return fail(`MD encode error: ${e?.message ?? String(e)}`);
     }
   }
 }
 
-function encodeContent(node: ContentNode, warns: string[]): string {
-  return node.tag === 'grid' ? encodeGrid(node, warns) : encodePara(node, warns);
+function encodeContent(node: ContentNode, warns: string[], includeImages: boolean): string {
+  return node.tag === 'grid' ? encodeGrid(node, warns, includeImages) : encodePara(node, warns, includeImages);
 }
 
-function encodePara(para: ParaNode, warns: string[]): string {
+function encodePara(para: ParaNode, warns: string[], includeImages: boolean): string {
   const text = para.kids.map(k => {
     if (k.tag === 'span') return encodeSpan(k, warns);
-    if (k.tag === 'img') return encodeImage(k);
+    if (k.tag === 'img') return encodeImage(k, includeImages);
     return '';
   }).join('');
 
@@ -112,7 +114,10 @@ function encodeSpan(span: SpanNode, warns: string[]): string {
   return r;
 }
 
-function encodeImage(img: ImgNode): string {
+function encodeImage(img: ImgNode, includeImages: boolean): string {
+  if (!includeImages) {
+    return `![${img.alt ?? ''}]`;  // alt text only, no data URI
+  }
   return `![${img.alt ?? ''}](data:${img.mime};base64,${img.b64})`;
 }
 
@@ -126,7 +131,7 @@ function strokeToCss(s?: Stroke): string | undefined {
   return `${px}px ${style} ${color}`;
 }
 
-function encodeGrid(grid: GridNode, warns: string[]): string {
+function encodeGrid(grid: GridNode, warns: string[], includeImages: boolean): string {
   if (grid.kids.length === 0) return '';
 
   // HTML 테이블로 출력 — 테두리/배경색을 인라인 스타일로 유지
@@ -177,7 +182,7 @@ function encodeGrid(grid: GridNode, warns: string[]): string {
       else if (cell.props.va === 'bot') styles[1] = 'vertical-align:bottom';
 
       const tag = (grid.props.headerRow && ri === 0) || cell.props.isHeader ? 'th' : 'td';
-      const content = cell.kids.map(p => encodePara(p, warns)).join('\n');
+      const content = cell.kids.map(p => p.tag === 'para' ? encodePara(p, warns, includeImages) : encodeGrid(p, warns, includeImages)).join('\n');
       cells += `<${tag}${cs}${rs} style="${styles.join(';')}">${content}</${tag}>`;
       colIdx += cell.cs;
     }

package/src/model/builders.ts

@@ -12,11 +12,11 @@ export function buildRoot(meta: DocMeta = {}, kids: SheetNode[] = []): DocRoot {
 export function buildSheet(
   kids: ContentNode[] = [],
   dims: PageDims = A4,
-  opts?: { header?: ParaNode[]; footer?: ParaNode[] },
+  opts?: { headers?: SheetNode["headers"]; footers?: SheetNode["footers"] },
 ): SheetNode {
   const node: SheetNode = { tag: 'sheet', dims, kids };
-  if (opts?.header) node.header = opts.header;
-  if (opts?.footer) node.footer = opts.footer;
+  if (opts?.headers) node.headers = opts.headers;
+  if (opts?.footers) node.footers = opts.footers;
   return node;
 }
 
@@ -61,7 +61,7 @@ export function buildRow(kids: CellNode[], heightPt?: number): RowNode {
 }
 
 export function buildCell(
-  kids: ParaNode[],
+  kids: (ParaNode | GridNode)[],
   opts: { cs?: number; rs?: number; props?: CellProps } = {},
 ): CellNode {
   return { tag: 'cell', cs: opts.cs ?? 1, rs: opts.rs ?? 1, props: opts.props ?? {}, kids };

package/src/model/doc-props.ts

@@ -1,7 +1,7 @@
 export type Align = 'left' | 'center' | 'right' | 'justify';
 
 // ─── 이미지 배치 ────────────────────────────────────────────
-export type ImgWrap = 'inline' | 'square' | 'tight' | 'through' | 'none' | 'behind' | 'front';
+export type ImgWrap = 'inline' | 'square' | 'tight' | 'through' | 'none' | 'behind' | 'front' | 'topAndBottom';
 export type ImgHorzAlign = 'left' | 'center' | 'right';
 export type ImgVertAlign = 'top' | 'center' | 'bottom';
 export type ImgHorzRelTo = 'margin' | 'column' | 'page' | 'para';
@@ -24,7 +24,7 @@ export interface ImgLayout {
 }
 export type VAlign = 'top' | 'mid' | 'bot';
 export type Heading = 1 | 2 | 3 | 4 | 5 | 6;
-export type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none';
+export type StrokeKind = 'solid' | 'dash' | 'dot' | 'double' | 'none' | 'dashDot' | 'dashDotDot' | 'wave';
 
 export interface TextProps {
   b?: boolean;
@@ -42,10 +42,15 @@ export interface TextProps {
 export interface ParaProps {
   align?: Align;
   heading?: Heading;
-  indentPt?: number;
+  styleId?: string;              // DOCX pStyle styleId (e.g. "Heading1", "TOC1")
+  indentPt?: number;             // 문단 왼쪽 전체 들여쓰기 (pt) — OWPML hc:left
+  indentRightPt?: number;        // 문단 오른쪽 전체 들여쓰기 (pt) — OWPML hc:right
+  firstLineIndentPt?: number;    // 첫 줄 들여쓰기 (pt, 음수=내어쓰기) — OWPML hc:indent
+  leftMargin?: number;           // 문단 왼쪽 여백 (HWP leftMargin, pt)
   spaceBefore?: number;
   spaceAfter?: number;
-  lineHeight?: number;
+  lineHeight?: number;           // 줄 간격 배율 (예: 1.5 = 150%)
+  lineHeightFixed?: number;      // 고정 줄 높이 (pt) — OWPML lineSpacing type="FIXED"
   listLv?: number;
   listOrd?: boolean;
   listMark?: string;
@@ -63,7 +68,11 @@ export interface CellProps {
   left?: Stroke;
   right?: Stroke;
   bg?: string;
-  padPt?: number;
+  padPt?: number;      // 모든 방향 균일 패딩 (하위 호환)
+  padT?: number;       // 상단 패딩 (pt)
+  padB?: number;       // 하단 패딩
+  padL?: number;       // 좌측 패딩
+  padR?: number;       // 우측 패딩
   align?: Align;
   va?: VAlign;
   isHeader?: boolean;
@@ -84,6 +93,7 @@ export interface GridProps {
   defaultStroke?: Stroke;
   look?: TableLook;
   headerRow?: boolean;
+  align?: Align;          // 표 정렬: 'left' | 'center' | 'right' | 'justify'
 }
 
 export interface PageDims {
@@ -94,6 +104,8 @@ export interface PageDims {
   ml: number;
   mr: number;
   orient?: 'portrait' | 'landscape';
+  headerPt?: number;  // distance from paper top to header top (DOCX w:header)
+  footerPt?: number;  // distance from paper bottom to footer bottom (DOCX w:footer)
 }
 
 export interface DocMeta {
@@ -104,6 +116,8 @@ export interface DocMeta {
   keywords?: string;
   created?: string;
   modified?: string;
+  zoom?: number;
+  viewMode?: string;
 }
 
 export const A4: PageDims = {

package/src/model/doc-tree.ts

@@ -44,7 +44,7 @@ export interface LinkNode {
 export interface ParaNode {
   tag: 'para';
   props: ParaProps;
-  kids: (SpanNode | ImgNode | LinkNode)[];
+  kids: (SpanNode | ImgNode | LinkNode | GridNode)[];
 }
 
 // ─── 표(Grid) 노드 ─────────────────────────────────────────
@@ -53,7 +53,7 @@ export interface CellNode {
   cs: number;
   rs: number;
   props: CellProps;
-  kids: ParaNode[];
+  kids: (ParaNode | GridNode)[];
 }
 
 export interface RowNode  { tag: 'row'; kids: CellNode[]; heightPt?: number }
@@ -71,8 +71,16 @@ export interface SheetNode {
   tag: 'sheet';
   dims: PageDims;
   kids: ContentNode[];
-  header?: ParaNode[];
-  footer?: ParaNode[];
+  headers?: {
+    default?: ParaNode[];
+    first?: ParaNode[];
+    even?: ParaNode[];
+  };
+  footers?: {
+    default?: ParaNode[];
+    first?: ParaNode[];
+    even?: ParaNode[];
+  };
 }
 
 // ─── 루트 노드 ─────────────────────────────────────────────

package/src/pipeline/Pipeline.ts

@@ -1,6 +1,7 @@
 import type { DocRoot } from '../model/doc-tree';
 import type { Outcome } from '../contract/result';
-import { fail } from '../contract/result';
+import type { EncoderOptions } from '../contract/encoder';
+import { succeed, fail } from '../contract/result';
 import { registry } from './registry';
 
 // Side-effect imports: auto-register all decoders and encoders
@@ -8,9 +9,12 @@ import '../decoders/hwpx/HwpxDecoder';
 import '../decoders/hwp/HwpScanner';
 import '../decoders/docx/DocxDecoder';
 import '../decoders/md/MdDecoder';
+import '../decoders/html/HtmlDecoder';
 import '../encoders/hwpx/HwpxEncoder';
 import '../encoders/docx/DocxEncoder';
 import '../encoders/md/MdEncoder';
+import '../encoders/html/HtmlEncoder';
+import '../encoders/hwp/HwpEncoder';
 
 export class Pipeline {
   private constructor(private raw: Uint8Array, private srcFmt: string) {}
@@ -35,7 +39,7 @@ export class Pipeline {
   }
 
   /** 목표 포맷으로 변환 */
-  async to(targetFmt: string): Promise<Outcome<Uint8Array>> {
+  async to(targetFmt: string, options?: EncoderOptions): Promise<Outcome<Uint8Array>> {
     const decoder = registry.getDecoder(this.srcFmt);
     const encoder = registry.getEncoder(targetFmt);
 
@@ -45,7 +49,7 @@ export class Pipeline {
     const docResult = await decoder.decode(this.raw);
     if (!docResult.ok) return docResult;
 
-    const encResult = await encoder.encode(docResult.data);
+    const encResult = await encoder.encode(docResult.data, options);
     if (!encResult.ok) return { ...encResult, warns: [...docResult.warns, ...encResult.warns] };
 
     return { ...encResult, warns: [...docResult.warns, ...encResult.warns] };

package/src/pipeline/registry.ts

@@ -5,8 +5,19 @@ class FormatRegistry {
   private decoders = new Map<string, Decoder>();
   private encoders = new Map<string, Encoder>();
 
-  registerDecoder(d: Decoder): void { this.decoders.set(d.format, d); }
-  registerEncoder(e: Encoder): void { this.encoders.set(e.format, e); }
+  registerDecoder(d: Decoder): void {
+    this.decoders.set(d.format, d);
+    if (d.aliases) {
+      for (const alias of d.aliases) this.decoders.set(alias, d);
+    }
+  }
+
+  registerEncoder(e: Encoder): void {
+    this.encoders.set(e.format, e);
+    if (e.aliases) {
+      for (const alias of e.aliases) this.encoders.set(alias, e);
+    }
+  }
 
   getDecoder(fmt: string): Decoder | undefined { return this.decoders.get(fmt); }
   getEncoder(fmt: string): Encoder | undefined { return this.encoders.get(fmt); }