hwpkit-dev 0.0.1 → 0.0.3

package/src/decoders/hwp/HwpScanner.ts

@@ -1,11 +1,12 @@
 import type { Decoder } from '../../contract/decoder';
-import type { DocRoot, ContentNode, ParaNode, SpanNode } from '../../model/doc-tree';
+import type { DocRoot, ContentNode, ParaNode, SpanNode, ImgNode, GridNode } from '../../model/doc-tree';
 import type { Outcome } from '../../contract/result';
 import type { Align, Stroke, StrokeKind, PageDims, TextProps, ParaProps, CellProps, GridProps } from '../../model/doc-props';
 import { succeed, fail } from '../../contract/result';
-import { buildRoot, buildSheet, buildPara, buildSpan, buildGrid, buildRow, buildCell } from '../../model/builders';
+import { buildRoot, buildSheet, buildPara, buildSpan, buildGrid, buildRow, buildCell, buildImg } from '../../model/builders';
 import { ShieldedParser } from '../../safety/ShieldedParser';
 import { BinaryKit } from '../../toolkit/BinaryKit';
+import { TextKit } from '../../toolkit/TextKit';
 import { Metric, safeHex, safeFont } from '../../safety/StyleBridge';
 import { registry } from '../../pipeline/registry';
 import { A4 } from '../../model/doc-props';
@@ -37,8 +38,12 @@ const TAG_CELL_B  = HWPTAG_BEGIN + 65;  // 81
 function isTableTag(t: number) { return t === TAG_TABLE_A || t === TAG_TABLE_B; }
 function isCellTag(t: number)  { return t === TAG_CELL_A || t === TAG_CELL_B || t === TAG_LIST_HEADER; }
 
-// CTRL_HEADER ctrlId for table: ' lbt' as UINT32-LE = 0x74626C20
-const CTRL_TABLE = 0x74626C20;
+// CTRL_HEADER ctrlId values (UINT32-LE as ASCII)
+const CTRL_TABLE = 0x74626C20;  // ' lbt' = 표(table)
+const CTRL_IMAGE = 0x696D6720;  // 'img '
+const CTRL_OBJ   = 0x6F626A20;  // 'obj '
+const CTRL_FIG   = 0x66696720;  // 'fig '
+const CTRL_GSO   = 0x67736F20;  // 'gso ' = 그리기 객체 (drawing object, contains embedded images)
 
 /* ═══════════════════════════════════════════════════════════════
    Types
@@ -67,6 +72,7 @@ interface HwpParaShape {
   spaceBefore: number;
   spaceAfter: number;
   lineSpacing: number;
+  leftMargin: number;
   indent: number;
 }
 
@@ -83,7 +89,14 @@ interface DocInfo {
 }
 
 interface ParsedChar { pos: number; ch: string }
-interface ParaTextResult { chars: ParsedChar[]; controlPositions: number[] }
+interface ParsedCtrl { pos: number; ctrlId: number; objId: number; matched: boolean }
+interface ParaTextResult { chars: ParsedChar[]; controls: ParsedCtrl[] }
+
+interface OleObject {
+  id: number;
+  data: Uint8Array;
+  mimeType: string;
+}
 
 /* ═══════════════════════════════════════════════════════════════
    Low-level record parsing
@@ -111,7 +124,9 @@ function parseRecords(data: Uint8Array): HwpRecord[] {
 }
 
 function tryInflate(data: Uint8Array): Uint8Array {
-  try { return pako.inflateRaw(data); } catch { return data; }
+  try { return pako.inflate(data); } catch {
+    try { return pako.inflateRaw(data); } catch { return data; }
+  }
 }
 
 /* ═══════════════════════════════════════════════════════════════
@@ -209,11 +224,12 @@ function parseCharShape(d: Uint8Array): HwpCharShape {
 const ALIGN_TBL: Record<number, Align> = { 0: 'justify', 1: 'left', 2: 'right', 3: 'center', 4: 'justify' };
 
 function parseParaShape(d: Uint8Array): HwpParaShape {
-  if (d.length < 4) return { align: 'left', spaceBefore: 0, spaceAfter: 0, lineSpacing: 160, indent: 0 };
+  if (d.length < 4) return { align: 'left', spaceBefore: 0, spaceAfter: 0, lineSpacing: 160, leftMargin: 0, indent: 0 };
   const attr = BinaryKit.readU32LE(d, 0);
   return {
-    align:       ALIGN_TBL[attr & 0x7] ?? 'left',
-    indent:      d.length >= 16 ? i32(d, 12) : 0,
+    align:       ALIGN_TBL[(attr >> 2) & 0x7] ?? 'left',
+    leftMargin:  d.length >= 8  ? i32(d, 4)  : 0,  // offset 4: leftMargin (들여쓰기)
+    indent:      d.length >= 16 ? i32(d, 12) : 0,  // offset 12: first-line indent
     spaceBefore: d.length >= 20 ? i32(d, 16) : 0,
     spaceAfter:  d.length >= 24 ? i32(d, 20) : 0,
     lineSpacing: d.length >= 28 ? i32(d, 24) : 160,
@@ -228,20 +244,30 @@ function parseParaShape(d: Uint8Array): HwpParaShape {
     [36:4] faceColor (bgColor for solid fill)                        */
 
 const BORDER_W_PT = [0.28, 0.34, 0.43, 0.57, 0.71, 0.85, 1.13, 1.42, 1.70, 1.98, 2.84, 4.25, 5.67, 8.50, 11.34, 14.17];
-const BORDER_KIND: Record<number, StrokeKind> = { 0:'none',1:'solid',2:'dash',3:'dot',4:'dash',5:'dash',6:'dash',7:'dot',8:'double',9:'double',10:'double' };
+const BORDER_KIND: Record<number, StrokeKind> = { 0:'solid',1:'dash',2:'dash',3:'dot',4:'dash',5:'dash',6:'dash',7:'double',8:'double',9:'double',10:'none' };
 
 function parseBorderFill(d: Uint8Array): HwpBorderFill {
+  // Spec grouped format (표 23):
+  //   [0:2]   attr
+  //   [2:4]   4 border types  (left, right, top, bottom) — 1 byte each
+  //   [6:4]   4 border widths (left, right, top, bottom) — 1 byte each (index into BORDER_W_PT)
+  //   [10:16] 4 border colors (left, right, top, bottom) — 4 bytes each (COLORREF)
+  //   [26:3]  diagonal: type(1) + width(1) + color(4) = 6 bytes actually [26:6]
+  //   [32:4]  fillType
+  //   [36:4]  faceColor (bgColor for solid fill)
   const borders: HwpBorderFill['borders'] = [];
+  const BASE_TYPE  = 2;   // 4 type bytes
+  const BASE_WIDTH = 6;   // 4 width bytes
+  const BASE_COLOR = 10;  // 4 × 4-byte colors
   for (let i = 0; i < 4; i++) {
-    const b = 2 + i * 6;
-    if (b + 6 <= d.length) {
-      borders.push({ type: d[b], widthPt: BORDER_W_PT[d[b + 1]] ?? 0.5, color: colorRef(d, b + 2) });
-    } else {
-      borders.push({ type: 0, widthPt: 0.5, color: '000000' });
-    }
+    const type    = BASE_TYPE  + i     < d.length ? d[BASE_TYPE  + i]              : 0;
+    const widthPt = BASE_WIDTH + i     < d.length ? (BORDER_W_PT[d[BASE_WIDTH + i]] ?? 0.5) : 0.5;
+    const color   = BASE_COLOR + i * 4 + 4 <= d.length ? colorRef(d, BASE_COLOR + i * 4) : '000000';
+    borders.push({ type, widthPt, color });
   }
   let bgColor: string | undefined;
-  const fOff = 32;                       // after attr(2) + 5 borders(30)
+  // after attr(2) + 4 types(4) + 4 widths(4) + 4 colors(16) + diagonal(6) = offset 32
+  const fOff = 32;
   if (d.length >= fOff + 8) {
     const ft = BinaryKit.readU32LE(d, fOff);
     if (ft & 1) bgColor = colorRef(d, fOff + 4);
@@ -253,21 +279,33 @@ function parseBorderFill(d: Uint8Array): HwpBorderFill {
    Body section parsing
    ═══════════════════════════════════════════════════════════════ */
 
+// gsoCtx: shared mutable counter for 'gso ' drawing objects.
+// Each 'gso ' CTRL_HEADER encountered increments this counter.
+// objectMap is keyed by 0-based gso order = sequential BinData insertion order.
+interface GsoCtx { count: number }
+
 function parseBody(
-  raw: Uint8Array, compressed: boolean, di: DocInfo, shield: ShieldedParser,
+  raw: Uint8Array, compressed: boolean, di: DocInfo, shield: ShieldedParser, gsoCtx: GsoCtx,
 ): { content: ContentNode[]; pageDims?: PageDims } {
   const recs = parseRecords(compressed ? tryInflate(raw) : raw);
   const content: ContentNode[] = [];
   let pageDims: PageDims | undefined;
-  let i = 0;
 
+  // Pre-scan for PAGE_DEF at any nesting level (real HWP stores it at level 2 inside section ctrl)
+  for (const r of recs) {
+    if (r.tag === TAG_PAGE_DEF) {
+      pageDims = shield.guard(() => parsePageDef(r.data), A4, 'hwp:pageDef');
+      break;
+    }
+  }
+
+  let i = 0;
   while (i < recs.length) {
     if (recs[i].tag === TAG_PAGE_DEF) {
-      pageDims = shield.guard(() => parsePageDef(recs[i].data), A4, 'hwp:pageDef');
-      i++;
+      i++; // already handled above; skip at top level
     } else if (recs[i].tag === TAG_PARA_HEADER) {
       const r = shield.guard(
-        () => parseParagraphGroup(recs, i, di, shield),
+        () => parseParagraphGroup(recs, i, di, shield, gsoCtx),
         { nodes: [] as ContentNode[], next: i + 1 },
         `hwp:para@${i}`,
       );
@@ -283,7 +321,7 @@ function parseBody(
 /* ── Paragraph group ────────────────────────────────────────── */
 
 function parseParagraphGroup(
-  recs: HwpRecord[], start: number, di: DocInfo, shield: ShieldedParser,
+  recs: HwpRecord[], start: number, di: DocInfo, shield: ShieldedParser, gsoCtx: GsoCtx,
 ): { nodes: ContentNode[]; next: number } {
   const hdr = recs[start];
   const lv  = hdr.level;
@@ -295,6 +333,8 @@ function parseParagraphGroup(
   let text: ParaTextResult | null = null;
   let csPairs: [number, number][] = [];
   const grids: ContentNode[] = [];
+  // imgId: for 'gso' uses sequential gsoCtx.count; for others uses flags-based objId
+  const ctrlHeaders: { ctrlId: number; imgId: number; wPt: number; hPt: number }[] = [];
   let i = start + 1;
 
   while (i < recs.length && recs[i].level > lv) {
@@ -307,14 +347,33 @@ function parseParagraphGroup(
       csPairs = parseCharShapePairs(r.data);
       i++;
     } else if (r.tag === TAG_CTRL_HEADER && r.level === lv + 1) {
-      if (r.data.length >= 4 && BinaryKit.readU32LE(r.data, 0) === CTRL_TABLE) {
-        const tr = shield.guard(
-          () => parseTableCtrl(recs, i, di, shield),
-          { grid: null, next: skipKids(recs, i) },
-          `hwp:tbl@${i}`,
-        );
-        if (tr.grid) grids.push(tr.grid);
-        i = tr.next;
+      if (r.data.length >= 4) {
+        const ctrlId = BinaryKit.readU32LE(r.data, 0);
+
+        // HWP 5.0 general-object layout:
+        //   [0:4] ctrlId  [4:4] flags  [8:4] xOff  [12:4] yOff
+        //   [16:4] width(HWPUNIT)  [20:4] height(HWPUNIT)
+        const MAX_HWP = 1_000_000;
+        const rawW = r.data.length >= 24 ? BinaryKit.readU32LE(r.data, 16) : 0;
+        const rawH = r.data.length >= 28 ? BinaryKit.readU32LE(r.data, 20) : 0;
+        const wPt = rawW > 0 && rawW < MAX_HWP ? Metric.hwpToPt(rawW) : 0;
+        const hPt = rawH > 0 && rawH < MAX_HWP ? Metric.hwpToPt(rawH) : 0;
+
+        // 'gso ' (그리기 객체) uses sequential counter; others use flags-based id
+        const imgId = ctrlId === CTRL_GSO ? gsoCtx.count++ : (r.data.length >= 6 ? BinaryKit.readU16LE(r.data, 4) : 0);
+        ctrlHeaders.push({ ctrlId, imgId, wPt, hPt });
+
+        if (ctrlId === CTRL_TABLE) {
+          const tr = shield.guard(
+            () => parseTableCtrl(recs, i, di, shield, gsoCtx),
+            { grid: null, next: skipKids(recs, i) },
+            `hwp:tbl@${i}`,
+          );
+          if (tr.grid) grids.push(tr.grid);
+          i = tr.next;
+        } else {
+          i = skipKids(recs, i);
+        }
       } else {
         i = skipKids(recs, i);
       }
@@ -325,12 +384,32 @@ function parseParagraphGroup(
 
   const nodes: ContentNode[] = [];
 
-  // Build paragraph from text
-  if (text && text.chars.length > 0) {
-    const joined = text.chars.map(c => c.ch).join('');
-    if (joined.trim()) {
+  // Build paragraph from text and inline controls (images)
+  if (text && (text.chars.length > 0 || text.controls.length > 0)) {
+    const paraContent: (SpanNode | ContentNode)[] = [];
+
+    if (text.chars.length > 0) {
       const spans = resolveCharShapes(text.chars, csPairs, di);
-      nodes.push(buildPara(spans, buildParaProps(ps)));
+      paraContent.push(...spans);
+    }
+
+    // Image placeholder spans: only for actual image controls.
+    // Non-image controls (footnotes, TOC entries, etc.) are silently skipped.
+    if (text.controls.length > 0) {
+      for (let ci = 0; ci < text.controls.length; ci++) {
+        const ch = ctrlHeaders[ci];
+        if (!ch) continue; // anchor-only ctrl (gso is sibling, not inline)
+        const isImg = ch.ctrlId === CTRL_IMAGE || ch.ctrlId === CTRL_FIG || ch.ctrlId === CTRL_OBJ || ch.ctrlId === CTRL_GSO;
+        if (!isImg) continue; // skip footnotes, TOC, page num, etc.
+        const dimStr = (ch.wPt > 0 && ch.hPt > 0)
+          ? `_W${Math.round(ch.wPt)}_H${Math.round(ch.hPt)}`
+          : '';
+        paraContent.push(buildSpan(`__EXT_${ch.imgId}${dimStr}__`));
+      }
+    }
+
+    if (paraContent.length > 0) {
+      nodes.push(buildPara(paraContent as any, buildParaProps(ps)));
     }
   }
 
@@ -354,7 +433,7 @@ const INL_CTRL = new Set([4, 5, 6, 7, 8]);
 
 function decodeParaText(d: Uint8Array): ParaTextResult {
   const chars: ParsedChar[] = [];
-  const controlPositions: number[] = [];
+  const controls: ParsedCtrl[] = [];
   let i = 0, pos = 0;
 
   while (i + 1 < d.length) {
@@ -364,8 +443,14 @@ function decodeParaText(d: Uint8Array): ParaTextResult {
     if (c === 10) { chars.push({ pos, ch: '\n' }); i += 2; pos++; continue; }
 
     if (EXT_CTRL.has(c)) {
-      controlPositions.push(pos);
-      i += 16; pos += 8; continue;                       // 8 WORDs
+      // Extended control: 8 WORDs (16 bytes)
+      // WORD 4 contains objId (for images, charts, etc.)
+      let objId = 0;
+      if (i + 16 <= d.length) {
+        objId = BinaryKit.readU16LE(d, i + 8); // 4th WORD (offset 8) contains objId
+      }
+      controls.push({ pos, ctrlId: 0, objId, matched: false });
+      i += 16; pos += 8; continue;
     }
     if (INL_CTRL.has(c)) {
       i += 16; pos += 8; continue;
@@ -379,7 +464,7 @@ function decodeParaText(d: Uint8Array): ParaTextResult {
     chars.push({ pos, ch: String.fromCharCode(c) });
     i += 2; pos++;
   }
-  return { chars, controlPositions };
+  return { chars, controls };
 }
 
 /* ── PARA_CHAR_SHAPE ────────────────────────────────────────── */
@@ -441,7 +526,7 @@ function styledSpan(text: string, shapeId: number, di: DocInfo): SpanNode {
 /* ── Table control parsing ──────────────────────────────────── */
 
 function parseTableCtrl(
-  recs: HwpRecord[], ctrlIdx: number, di: DocInfo, shield: ShieldedParser,
+  recs: HwpRecord[], ctrlIdx: number, di: DocInfo, shield: ShieldedParser, gsoCtx: GsoCtx,
 ): { grid: ContentNode | null; next: number } {
   const ctrlLv = recs[ctrlIdx].level;
   let i = ctrlIdx + 1;
@@ -497,15 +582,15 @@ function parseTableCtrl(
   const rowCnt = tblData.length >= 6 ? BinaryKit.readU16LE(tblData, 4) : 1;
   const colCnt = tblData.length >= 8 ? BinaryKit.readU16LE(tblData, 6) : 1;
 
-  interface PC { row: number; col: number; cs: number; rs: number; widthHwp: number; props: CellProps; paras: ParaNode[] }
+  interface PC { row: number; col: number; cs: number; rs: number; widthHwp: number; heightHwp?: number; props: CellProps; cellChildren: (ParaNode | GridNode)[] }
   const parsed: PC[] = [];
 
   for (let ci = 0; ci < cells.length; ci++) {
     const c = cells[ci];
     const seqIdx = ci;
     const pc = shield.guard(
-      () => parseCellRec(c.data, c.tag, recs, c.cStart, c.cEnd, di, shield, seqIdx, colCnt),
-      { row: Math.floor(ci / (colCnt || 1)), col: ci % (colCnt || 1), cs: 1, rs: 1, widthHwp: 0, props: {}, paras: [buildPara([buildSpan('')])] },
+      () => parseCellRec(c.data, c.tag, recs, c.cStart, c.cEnd, di, shield, seqIdx, colCnt, gsoCtx),
+      { row: Math.floor(ci / (colCnt || 1)), col: ci % (colCnt || 1), cs: 1, rs: 1, widthHwp: 0, heightHwp: undefined, props: {}, cellChildren: [buildPara([buildSpan('')])] },
       `hwp:cell@${c.cStart}`,
     );
     parsed.push(pc);
@@ -532,9 +617,11 @@ function parseTableCtrl(
     }
   }
   // Pass 2: for columns still 0, try to derive from multi-span cells
+  // Sort by span size ascending so smaller, more precise spans fill widths before larger spans
   const zeroColumns = colWidthsPt.filter(w => w === 0).length;
   if (zeroColumns > 0) {
-    for (const c of parsed) {
+    const spanCells = parsed.filter(c => c.cs > 1 && c.widthHwp > 0).sort((a, b) => a.cs - b.cs);
+    for (const c of spanCells) {
       if (c.cs > 1 && c.widthHwp > 0) {
         // Subtract known column widths from the span
         let known = 0;
@@ -554,13 +641,37 @@ function parseTableCtrl(
     }
   }
 
+  // Post-process: clamp near-zero column widths (< 1pt = floating-point artifact) to minimum 1pt
+  for (let i = 0; i < colWidthsPt.length; i++) {
+    if (colWidthsPt[i] > 0 && colWidthsPt[i] < 1) colWidthsPt[i] = 1;
+  }
+
   const rows = [];
   for (let r = 0; r < actualRowCnt; r++) {
     const rc = parsed.filter(c => c.row === r).sort((a, b) => a.col - b.col);
     if (rc.length === 0) continue;
-    rows.push(buildRow(rc.map(c =>
-      buildCell(c.paras.length ? c.paras : [buildPara([buildSpan('')])], { cs: c.cs, rs: c.rs, props: c.props }),
-    )));
+
+    // Calculate row height — prefer rs=1 cells (exact per-row height)
+    let rowHeightPt: number | undefined = undefined;
+    for (const c of rc) {
+      if (c.heightHwp && c.heightHwp > 0 && c.rs === 1) {
+        const hPt = Metric.hwpToPt(c.heightHwp);
+        if (rowHeightPt == null || hPt > rowHeightPt) rowHeightPt = hPt;
+      }
+    }
+    // Fallback: all cells span multiple rows → approximate height per row
+    if (rowHeightPt == null) {
+      for (const c of rc) {
+        if (c.heightHwp && c.heightHwp > 0) {
+          const hPt = Metric.hwpToPt(c.heightHwp) / c.rs;
+          if (rowHeightPt == null || hPt > rowHeightPt) rowHeightPt = hPt;
+        }
+      }
+    }
+
+    rows.push(buildRow(rc.map(c => {
+      return buildCell(c.cellChildren, { cs: c.cs, rs: c.rs, props: c.props });
+    }), rowHeightPt));
   }
   if (rows.length === 0) return { grid: null, next: i };
 
@@ -589,10 +700,11 @@ function parseTableCtrl(
 
 function parseCellRec(
   d: Uint8Array, tag: number, recs: HwpRecord[], cStart: number, cEnd: number,
-  di: DocInfo, shield: ShieldedParser, seqIdx: number, colCnt: number,
+  di: DocInfo, shield: ShieldedParser, seqIdx: number, colCnt: number, gsoCtx: GsoCtx,
 ) {
   let col: number, row: number, cs = 1, rs = 1;
   let widthHwp = 0;
+  let heightHwp = 0;
   const props: CellProps = {};
 
   const attr = d.length >= 6 ? BinaryKit.readU32LE(d, 2) : 0;
@@ -600,57 +712,55 @@ function parseCellRec(
   if (va === 1) props.va = 'mid';
   else if (va === 2) props.va = 'bot';
 
+  const HWP_PAD_LR_DEFAULT = 360;
+  const HWP_PAD_TB_DEFAULT = 141;
+
   if (tag === TAG_LIST_HEADER && d.length >= 22) {
-    // LIST_HEADER with cell-specific fields
-    // offset 8: colAddr, offset 10: rowAddr (HWP 5.0 spec)
     col = BinaryKit.readU16LE(d, 8);
     row = BinaryKit.readU16LE(d, 10);
-    rs  = Math.max(1, BinaryKit.readU16LE(d, 12));
-    cs  = Math.max(1, BinaryKit.readU16LE(d, 14));
+    cs  = Math.max(1, BinaryKit.readU16LE(d, 12));
+    rs  = Math.max(1, BinaryKit.readU16LE(d, 14));
     widthHwp = BinaryKit.readU32LE(d, 16);
-
-    const bfId = d.length >= 34 ? BinaryKit.readU16LE(d, 32) : 0;
-    if (bfId > 0 && bfId <= di.borderFills.length) {
-      const bf = di.borderFills[bfId - 1];
-      if (bf.borders.length >= 4) {
-        props.left  = toStroke(bf.borders[0]);
-        props.right = toStroke(bf.borders[1]);
-        props.top   = toStroke(bf.borders[2]);
-        props.bot   = toStroke(bf.borders[3]);
-      }
-      if (bf.bgColor && bf.bgColor !== 'FFFFFF') props.bg = bf.bgColor;
+    heightHwp = d.length >= 24 ? BinaryKit.readU32LE(d, 20) : 0;
+    if (d.length >= 32) {
+      const pL = BinaryKit.readU16LE(d, 24); const pR = BinaryKit.readU16LE(d, 26);
+      const pT = BinaryKit.readU16LE(d, 28); const pB = BinaryKit.readU16LE(d, 30);
+      if (pL !== HWP_PAD_LR_DEFAULT) props.padL = Metric.hwpToPt(pL);
+      if (pR !== HWP_PAD_LR_DEFAULT) props.padR = Metric.hwpToPt(pR);
+      if (pT !== HWP_PAD_TB_DEFAULT) props.padT = Metric.hwpToPt(pT);
+      if (pB !== HWP_PAD_TB_DEFAULT) props.padB = Metric.hwpToPt(pB);
     }
+    const bfId = d.length >= 34 ? BinaryKit.readU16LE(d, 32) : 0;
+    if (bfId > 0 && bfId <= di.borderFills.length) applyCellBorderFill(di.borderFills[bfId - 1], props);
   } else if (tag !== TAG_LIST_HEADER) {
-    // Full CELL record with position/span/borderFill
     col = d.length >= 8  ? BinaryKit.readU16LE(d, 6) : seqIdx % (colCnt || 1);
     row = d.length >= 10 ? BinaryKit.readU16LE(d, 8) : Math.floor(seqIdx / (colCnt || 1));
     cs  = d.length >= 12 ? Math.max(1, BinaryKit.readU16LE(d, 10)) : 1;
     rs  = d.length >= 14 ? Math.max(1, BinaryKit.readU16LE(d, 12)) : 1;
     widthHwp = d.length >= 18 ? BinaryKit.readU32LE(d, 14) : 0;
-
-    const bfId = d.length >= 32 ? BinaryKit.readU16LE(d, 30) : 0;
-    if (bfId > 0 && bfId <= di.borderFills.length) {
-      const bf = di.borderFills[bfId - 1];
-      if (bf.borders.length >= 4) {
-        props.left  = toStroke(bf.borders[0]);
-        props.right = toStroke(bf.borders[1]);
-        props.top   = toStroke(bf.borders[2]);
-        props.bot   = toStroke(bf.borders[3]);
-      }
-      if (bf.bgColor && bf.bgColor !== 'FFFFFF') props.bg = bf.bgColor;
+    heightHwp = d.length >= 22 ? BinaryKit.readU32LE(d, 18) : 0;
+    if (d.length >= 30) {
+      const pL = BinaryKit.readU16LE(d, 22); const pR = BinaryKit.readU16LE(d, 24);
+      const pT = BinaryKit.readU16LE(d, 26); const pB = BinaryKit.readU16LE(d, 28);
+      if (pL !== HWP_PAD_LR_DEFAULT) props.padL = Metric.hwpToPt(pL);
+      if (pR !== HWP_PAD_LR_DEFAULT) props.padR = Metric.hwpToPt(pR);
+      if (pT !== HWP_PAD_TB_DEFAULT) props.padT = Metric.hwpToPt(pT);
+      if (pB !== HWP_PAD_TB_DEFAULT) props.padB = Metric.hwpToPt(pB);
     }
+    const bfId = d.length >= 32 ? BinaryKit.readU16LE(d, 30) : 0;
+    if (bfId > 0 && bfId <= di.borderFills.length) applyCellBorderFill(di.borderFills[bfId - 1], props);
   } else {
-    // Fallback: LIST_HEADER too short, compute sequentially
     row = Math.floor(seqIdx / (colCnt || 1));
     col = seqIdx % (colCnt || 1);
   }
 
-  // Parse cell content paragraphs
-  const paras: ParaNode[] = [];
+  const cellChildren: (ParaNode | GridNode)[] = [];
+  const MAX_HWP = 1_000_000;
   let k = cStart;
+
   while (k < cEnd) {
     if (recs[k].tag === TAG_PARA_HEADER) {
-      // For cell paragraphs, they might be at various nesting levels
+      // Parse paragraph inside cell — also extracts nested tables within the paragraph
       const r = shield.guard(
         () => {
           const hdr = recs[k];
@@ -659,24 +769,91 @@ function parseCellRec(
           const ps = di.paraShapes[psId];
           let txt: ParaTextResult | null = null;
           let csp: [number, number][] = [];
+          const ctrlHdrs: { ctrlId: number; imgId: number; wPt: number; hPt: number }[] = [];
+          const innerGrids: GridNode[] = [];
           let j = k + 1;
           while (j < cEnd && recs[j].level > lv) {
             if (recs[j].tag === TAG_PARA_TEXT) { txt = decodeParaText(recs[j].data); j++; }
             else if (recs[j].tag === TAG_PARA_CHAR_SHAPE) { csp = parseCharShapePairs(recs[j].data); j++; }
+            else if (recs[j].tag === TAG_CTRL_HEADER && recs[j].level === lv + 1) {
+              if (recs[j].data.length >= 4) {
+                const ctrlId = BinaryKit.readU32LE(recs[j].data, 0);
+                if (ctrlId === CTRL_TABLE) {
+                  // Nested table inside a cell paragraph — recurse into parseTableCtrl
+                  const nestedTr = shield.guard(
+                    () => parseTableCtrl(recs, j, di, shield, gsoCtx),
+                    { grid: null, next: skipKids(recs, j) },
+                    `hwp:innerNestedTbl@${j}`,
+                  );
+                  if (nestedTr.grid) innerGrids.push(nestedTr.grid as GridNode);
+                  j = nestedTr.next;
+                } else {
+                  const rawW = recs[j].data.length >= 24 ? BinaryKit.readU32LE(recs[j].data, 16) : 0;
+                  const rawH = recs[j].data.length >= 28 ? BinaryKit.readU32LE(recs[j].data, 20) : 0;
+                  const wPt = rawW > 0 && rawW < MAX_HWP ? Metric.hwpToPt(rawW) : 0;
+                  const hPt = rawH > 0 && rawH < MAX_HWP ? Metric.hwpToPt(rawH) : 0;
+                  const imgId = ctrlId === CTRL_GSO ? gsoCtx.count++ : (recs[j].data.length >= 6 ? BinaryKit.readU16LE(recs[j].data, 4) : 0);
+                  ctrlHdrs.push({ ctrlId, imgId, wPt, hPt });
+                  j = skipKids(recs, j);
+                }
+              } else {
+                j = skipKids(recs, j);
+              }
+            }
             else j++;
           }
-          const spans = txt && txt.chars.length > 0 ? resolveCharShapes(txt.chars, csp, di) : [buildSpan('')];
-          return { para: buildPara(spans, buildParaProps(ps)), next: j };
+          const paraContent: (SpanNode | ContentNode)[] = [];
+          if (txt && txt.chars.length > 0) paraContent.push(...resolveCharShapes(txt.chars, csp, di));
+          if (txt && txt.controls.length > 0) {
+            for (let ci = 0; ci < txt.controls.length; ci++) {
+              const ch = ctrlHdrs[ci];
+              if (!ch) continue;
+              const isImg = ch.ctrlId === CTRL_IMAGE || ch.ctrlId === CTRL_FIG || ch.ctrlId === CTRL_OBJ || ch.ctrlId === CTRL_GSO;
+              if (!isImg) continue;
+              const dimStr = (ch.wPt > 0 && ch.hPt > 0) ? `_W${Math.round(ch.wPt)}_H${Math.round(ch.hPt)}` : '';
+              paraContent.push(buildSpan(`__EXT_${ch.imgId}${dimStr}__`));
+            }
+          }
+          const kids = paraContent.length > 0 ? paraContent as any : [buildSpan('')];
+          const items: (ParaNode | GridNode)[] = [buildPara(kids, buildParaProps(ps)), ...innerGrids];
+          return { items, next: j };
         },
-        { para: buildPara([buildSpan('')]), next: k + 1 },
+        { items: [buildPara([buildSpan('')])] as (ParaNode | GridNode)[], next: k + 1 },
         `hwp:cellP@${k}`,
       );
-      paras.push(r.para);
+      cellChildren.push(...r.items);
       k = r.next;
+    } else if (recs[k].tag === TAG_CTRL_HEADER && recs[k].data.length >= 4) {
+      // CTRL_HEADER at cell level (sibling of PARA_HEADER) — anchored 'gso' images and outer-level nested tables
+      const cellCtrlId = BinaryKit.readU32LE(recs[k].data, 0);
+      if (cellCtrlId === CTRL_GSO) {
+        const gsoId = gsoCtx.count++;
+        const rawW = recs[k].data.length >= 24 ? BinaryKit.readU32LE(recs[k].data, 16) : 0;
+        const rawH = recs[k].data.length >= 28 ? BinaryKit.readU32LE(recs[k].data, 20) : 0;
+        const wPt = rawW > 0 && rawW < MAX_HWP ? Metric.hwpToPt(rawW) : 0;
+        const hPt = rawH > 0 && rawH < MAX_HWP ? Metric.hwpToPt(rawH) : 0;
+        const dimStr = (wPt > 0 && hPt > 0) ? `_W${Math.round(wPt)}_H${Math.round(hPt)}` : '';
+        cellChildren.push(buildPara([buildSpan(`__EXT_${gsoId}${dimStr}__`)]));
+        k = skipKids(recs, k);
+      } else if (cellCtrlId === CTRL_TABLE) {
+        const tr = shield.guard(
+          () => parseTableCtrl(recs, k, di, shield, gsoCtx),
+          { grid: null, next: skipKids(recs, k) },
+          `hwp:nestedTbl@${k}`,
+        );
+        if (tr.grid) cellChildren.push(tr.grid as GridNode);
+        k = tr.next;
+      } else {
+        k = skipKids(recs, k);
+      }
     } else { k++; }
   }
 
-  return { row, col, cs, rs, props, widthHwp, paras: paras.length ? paras : [buildPara([buildSpan('')])] };
+  return {
+    row, col, cs, rs, props, widthHwp,
+    heightHwp: heightHwp || undefined,
+    cellChildren: cellChildren.length ? cellChildren : [buildPara([buildSpan('')])],
+  };
 }
 
 /* ── PAGE_DEF ───────────────────────────────────────────────── */
@@ -718,6 +895,18 @@ function toStroke(b: { type: number; widthPt: number; color: string }): Stroke {
   return { kind: BORDER_KIND[b.type] ?? 'solid', pt: b.widthPt, color: b.color };
 }
 
+// Apply borderFill to CellProps. Preserve explicit NONE so DOCX tcBorders can
+// override the table-level tblBorders. Filtering NONE would let tblBorders bleed through.
+function applyCellBorderFill(bf: HwpBorderFill, props: CellProps): void {
+  if (bf.borders.length >= 4) {
+    props.left  = toStroke(bf.borders[0]);
+    props.right = toStroke(bf.borders[1]);
+    props.top   = toStroke(bf.borders[2]);
+    props.bot   = toStroke(bf.borders[3]);
+  }
+  if (bf.bgColor && bf.bgColor !== 'FFFFFF') props.bg = bf.bgColor;
+}
+
 function strokeFromBF(bfId: number, di: DocInfo): Stroke | undefined {
   if (bfId <= 0 || bfId > di.borderFills.length) return undefined;
   const bf = di.borderFills[bfId - 1];
@@ -733,7 +922,11 @@ function buildParaProps(ps?: HwpParaShape): ParaProps {
   if (ps.spaceBefore > 0) p.spaceBefore = Metric.hwpToPt(ps.spaceBefore);
   if (ps.spaceAfter > 0)  p.spaceAfter  = Metric.hwpToPt(ps.spaceAfter);
   if (ps.lineSpacing > 0 && ps.lineSpacing !== 160) p.lineHeight = ps.lineSpacing / 100;
-  if (ps.indent > 0) p.indentPt = Metric.hwpToPt(ps.indent);
+  // leftMargin (offset 4) = 문단 몸체 왼쪽 여백 → leftMargin (pt), ensure non-negative
+  const leftMarginPt = Math.max(0, Metric.hwpToPt(ps.leftMargin));
+  if (leftMarginPt > 0) p.leftMargin = leftMarginPt;
+  // indent (offset 12) = 첫 줄 들여쓰기(양수) / 내어쓰기(음수) → firstLineIndentPt
+  if (ps.indent !== 0) p.firstLineIndentPt = Metric.hwpToPt(ps.indent);
   return p;
 }
 
@@ -743,6 +936,7 @@ function buildParaProps(ps?: HwpParaShape): ParaProps {
 
 export class HwpScanner implements Decoder {
   readonly format = 'hwp';
+  readonly aliases = ['application/vnd.hancom.hwp'];
 
   async decode(data: Uint8Array): Promise<Outcome<DocRoot>> {
     const shield = new ShieldedParser();
@@ -764,6 +958,37 @@ export class HwpScanner implements Decoder {
         di = shield.guard(() => parseDocInfo(diRaw, compressed), di, 'hwp:docInfo');
       }
 
+      // Extract images from BinData streams.
+      // HWP duplicates each BinData entry: once as "BinData/BIN0001.jpg" and once as "BIN0001.jpg".
+      // We keep only the "BinData/" prefixed versions, sort by BIN number, then assign 0-based keys
+      // matching the order 'gso' CTRL_HEADER records are encountered during body parsing.
+      const binEntries: { binNum: number; data: Uint8Array }[] = [];
+      for (const [path, streamData] of streams) {
+        // Match "BinData/BIN0001.jpg" style — the canonical form
+        const m = path.match(/^BinData[/\\]BIN(\d+)\.\w+$/i);
+        if (m) binEntries.push({ binNum: parseInt(m[1], 10), data: streamData });
+      }
+      // Sort by BIN number (ascending) so BIN0001→idx0, BIN0002→idx1, …
+      binEntries.sort((a, b) => a.binNum - b.binNum);
+
+      const objectMap = new Map<number, ImgNode>();
+      for (let idx = 0; idx < binEntries.length; idx++) {
+        const { data: imgData } = binEntries[idx];
+
+        // Determine MIME type from binary signature first, then fall back to extension
+        let mimeType: ImgNode['mime'] = 'image/jpeg';
+        if (imgData[0] === 0x89 && imgData[1] === 0x50) mimeType = 'image/png';
+        else if (imgData[0] === 0x47 && imgData[1] === 0x49) mimeType = 'image/gif';
+        else if (imgData[0] === 0x42 && imgData[1] === 0x4D) mimeType = 'image/bmp';
+
+        const base64 = TextKit.base64Encode(imgData);
+        const { wPt, hPt } = getImageDimsPt(imgData, mimeType);
+        objectMap.set(idx, buildImg(base64, mimeType, wPt, hPt));
+      }
+
+      // gsoCtx tracks sequential 'gso' encounter order — must be shared across all sections
+      const gsoCtx: GsoCtx = { count: 0 };
+
       // Body sections
       const allContent: ContentNode[] = [];
       let pageDims: PageDims = A4;
@@ -774,7 +999,7 @@ export class HwpScanner implements Decoder {
           if (s === 0) {
             const fb = findBodySection(streams);
             if (fb) {
-              const r = parseBody(fb, compressed, di, shield);
+              const r = parseBody(fb, compressed, di, shield, gsoCtx);
               allContent.push(...r.content);
               if (r.pageDims) pageDims = r.pageDims;
             }
@@ -782,7 +1007,7 @@ export class HwpScanner implements Decoder {
           break;
         }
         const r = shield.guard(
-          () => parseBody(sec, compressed, di, shield),
+          () => parseBody(sec, compressed, di, shield, gsoCtx),
           { content: [], pageDims: undefined },
           `hwp:sec${s}`,
         );
@@ -790,6 +1015,10 @@ export class HwpScanner implements Decoder {
         if (r.pageDims) pageDims = r.pageDims;
       }
 
+      if (objectMap.size > 0) {
+        injectImagesIntoContent(allContent, objectMap);
+      }
+
       warns.push(...shield.flush());
       const content = allContent.length > 0 ? allContent : [buildPara([buildSpan('')])];
       return succeed(buildRoot({}, [buildSheet(content, pageDims)]), warns);
@@ -806,4 +1035,164 @@ function findBodySection(streams: Map<string, Uint8Array>): Uint8Array | undefin
   return undefined;
 }
 
+/* ═══════════════════════════════════════════════════════════════
+   Image dimension extraction from binary headers
+   ════════════════════════════════════════════════════════════ */
+
+// Returns { wPt, hPt } by parsing image headers; falls back to { wPt: 72, hPt: 72 } (1-inch)
+function getImageDimsPt(data: Uint8Array, mime: string): { wPt: number; hPt: number } {
+  const fallback = { wPt: 72, hPt: 72 };
+  try {
+    if (mime === 'image/png' && data.length >= 24) {
+      // PNG IHDR: sig(8) + length(4) + type(4) + width(4) + height(4) — all big-endian
+      const w = (data[16] << 24 | data[17] << 16 | data[18] << 8 | data[19]) >>> 0;
+      const h = (data[20] << 24 | data[21] << 16 | data[22] << 8 | data[23]) >>> 0;
+      if (w > 0 && h > 0) return { wPt: w * 0.75, hPt: h * 0.75 }; // 96 DPI → pt
+    }
+    if (mime === 'image/jpeg') {
+      // Scan for SOF markers: FF C0 / C1 / C2 / C3
+      let i = 2;
+      while (i + 8 < data.length) {
+        if (data[i] !== 0xFF) { i++; continue; }
+        const marker = data[i + 1];
+        if (marker >= 0xC0 && marker <= 0xC3) {
+          // SOF: 2-byte marker + 2-byte length + 1-byte precision + 2-byte height + 2-byte width
+          const h = (data[i + 5] << 8 | data[i + 6]) >>> 0;
+          const w = (data[i + 7] << 8 | data[i + 8]) >>> 0;
+          if (w > 0 && h > 0) return { wPt: w * 0.75, hPt: h * 0.75 };
+        }
+        const segLen = data[i + 2] << 8 | data[i + 3];
+        i += 2 + (segLen > 0 ? segLen : 2);
+      }
+    }
+    if (mime === 'image/bmp' && data.length >= 26) {
+      // BMP DIB header: width at 18, height at 22 (signed int32 LE; negative = top-down)
+      const w = BinaryKit.readU32LE(data, 18);
+      const h = Math.abs(BinaryKit.readU32LE(data, 22) | 0);
+      if (w > 0 && h > 0) return { wPt: w * 0.75, hPt: h * 0.75 };
+    }
+    if (mime === 'image/gif' && data.length >= 10) {
+      // GIF: width at 6, height at 8 (uint16 LE)
+      const w = data[6] | data[7] << 8;
+      const h = data[8] | data[9] << 8;
+      if (w > 0 && h > 0) return { wPt: w * 0.75, hPt: h * 0.75 };
+    }
+  } catch { /* ignore */ }
+  return fallback;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   OLE Object extraction (images)
+   ════════════════════════════════════════════════════════════ */
+
+function extractImagesFromOleObjectLink(data: Uint8Array): OleObject[] {
+  const objects: OleObject[] = [];
+  let off = 0;
+
+  while (off + 8 <= data.length) {
+    const objId = BinaryKit.readU32LE(data, off);
+    const dataSize = BinaryKit.readU32LE(data, off + 4);
+    const reserved = BinaryKit.readU32LE(data, off + 8);
+
+    if (objId === 0 || dataSize === 0) break;
+
+    const objOff = off + 16;
+    if (objOff + dataSize > data.length) break;
+
+    const objData = data.subarray(objOff, objOff + dataSize);
+
+    // Detect MIME type from signature
+    let mimeType = 'application/octet-stream';
+    if (objData[0] === 0xFF && objData[1] === 0xD8 && objData[2] === 0xFF) {
+      mimeType = 'image/jpeg';
+    } else if (objData[0] === 0x89 && objData[1] === 0x50 && objData[2] === 0x4E && objData[3] === 0x47) {
+      mimeType = 'image/png';
+    } else if (objData[0] === 0x47 && objData[1] === 0x49 && objData[2] === 0x46 && objData[3] === 0x3538) {
+      mimeType = 'image/gif';
+    } else if (objData[0] === 0x42 && objData[1] === 0x4D) {
+      mimeType = 'image/bmp';
+    }
+
+    objects.push({ id: objId, data: objData, mimeType });
+    off = objOff + dataSize;
+  }
+
+  return objects;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Helper to inject images into paragraph content
+   ════════════════════════════════════════════════════════════ */
+
+function injectImagesIntoContent(
+  content: ContentNode[],
+  objectMap: Map<number, ImgNode>
+): void {
+  if (objectMap.size === 0) return;
+
+  // Helper function to process a list of kids (spans, images, etc.)
+  const processKids = (kids: any[]) => {
+    for (let i = 0; i < kids.length; i++) {
+      const kid = kids[i];
+      // Span node structure: { tag: 'span', props, kids: [{ tag: 'txt', content }] }
+      if (kid.tag === 'span' && kid.kids && kid.kids[0]?.tag === 'txt') {
+        const text = kid.kids[0].content;
+        // __EXT_N__ or __EXT_N_W<wPt>_H<hPt>__ (with encoded display size)
+        // N is the objId that matches the index in objectMap
+        const match = text.match?.(/^__(?:IMG|EXT)_(\d+)(?:_W(\d+)_H(\d+))?__$/);
+        if (match) {
+          const objId = parseInt(match[1], 10);
+          const base = objectMap.get(objId);
+          if (base) {
+            const wPt = match[2] ? parseInt(match[2], 10) : 0;
+            const hPt = match[3] ? parseInt(match[3], 10) : 0;
+            // Use encoded display size when valid; otherwise keep pixel-based dims
+            kids[i] = (wPt > 0 && hPt > 0) ? { ...base, w: wPt, h: hPt } : base;
+          }
+        }
+      }
+    }
+  };
+
+  // Recursively process a grid (table): resolves image placeholders in all cells,
+  // including nested grids inside cells.
+  const processGridKids = (grid: any) => {
+    if (!grid.kids || !Array.isArray(grid.kids)) return;
+
+    for (const row of grid.kids) {
+      if (!row.kids || !Array.isArray(row.kids)) continue;
+
+      for (const cell of row.kids) {
+        if (!cell.kids || !Array.isArray(cell.kids)) continue;
+
+        for (const cellKid of cell.kids) {
+          if (cellKid.tag === 'grid') {
+            // Nested table inside cell — recurse
+            processGridKids(cellKid);
+          } else if (cellKid.tag === 'para' && cellKid.kids) {
+            processKids(cellKid.kids);
+          }
+        }
+      }
+    }
+  };
+
+  for (const node of content) {
+    if (node.tag === 'para' && node.kids) {
+      // Process paragraph kids (spans, images, links, grids)
+      processKids(node.kids);
+
+      // Also process any nested grids inside the paragraph
+      for (const kid of node.kids) {
+        if (kid.tag === 'grid') {
+          processGridKids(kid);
+        }
+      }
+    } else if (node.tag === 'grid') {
+      // Process grid nodes (tables)
+      processGridKids(node);
+    }
+  }
+}
+
 registry.registerDecoder(new HwpScanner());