hwpkit-dev 0.0.2 → 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, ImgNode } 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, 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';
@@ -38,10 +39,11 @@ 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 values (UINT32-LE as ASCII)
-const CTRL_TABLE = 0x74626C20;  // ' lbt'
+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
@@ -70,6 +72,7 @@ interface HwpParaShape {
   spaceBefore: number;
   spaceAfter: number;
   lineSpacing: number;
+  leftMargin: number;
   indent: number;
 }
 
@@ -221,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 >> 2) & 0x7] ?? 'left',
-    indent:      d.length >= 16 ? i32(d, 12) : 0,
+    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,
@@ -275,8 +279,13 @@ 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[] = [];
@@ -296,7 +305,7 @@ function parseBody(
       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}`,
       );
@@ -312,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;
@@ -324,7 +333,8 @@ function parseParagraphGroup(
   let text: ParaTextResult | null = null;
   let csPairs: [number, number][] = [];
   const grids: ContentNode[] = [];
-  const ctrlHeaders: { ctrlId: number; objId: number }[] = [];
+  // 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) {
@@ -339,13 +349,23 @@ function parseParagraphGroup(
     } else if (r.tag === TAG_CTRL_HEADER && r.level === lv + 1) {
       if (r.data.length >= 4) {
         const ctrlId = BinaryKit.readU32LE(r.data, 0);
-        // objId at offset 4 (UINT16) - identifies the image/object in BinData
-        const objId = r.data.length >= 6 ? BinaryKit.readU16LE(r.data, 4) : 0;
-        ctrlHeaders.push({ ctrlId, objId });
+
+        // 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),
+            () => parseTableCtrl(recs, i, di, shield, gsoCtx),
             { grid: null, next: skipKids(recs, i) },
             `hwp:tbl@${i}`,
           );
@@ -362,34 +382,29 @@ function parseParagraphGroup(
     }
   }
 
-  // Match extended controls with CTRL_HEADER entries
-  if (text && ctrlHeaders.length > 0) {
-    for (let ci = 0; ci < text.controls.length; ci++) {
-      if (ci < ctrlHeaders.length) {
-        text.controls[ci].ctrlId = ctrlHeaders[ci].ctrlId;
-        text.controls[ci].matched = true;
-      }
-    }
-  }
-
   const nodes: ContentNode[] = [];
 
   // Build paragraph from text and inline controls (images)
   if (text && (text.chars.length > 0 || text.controls.length > 0)) {
     const paraContent: (SpanNode | ContentNode)[] = [];
 
-    // Process text chars and controls together
     if (text.chars.length > 0) {
       const spans = resolveCharShapes(text.chars, csPairs, di);
       paraContent.push(...spans);
     }
 
-    // Add placeholder spans for extended controls (images)
+    // 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++) {
-        // Create placeholder for all extended controls
-        // Image replacement will happen later in injectImagesIntoContent
-        paraContent.push(buildSpan(`__EXT_${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}__`));
       }
     }
 
@@ -511,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;
@@ -567,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);
@@ -602,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;
@@ -624,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 };
 
@@ -659,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;
@@ -670,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);
     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];
@@ -729,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 ───────────────────────────────────────────────── */
@@ -788,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];
@@ -803,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;
 }
 
@@ -813,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();
@@ -834,52 +958,36 @@ export class HwpScanner implements Decoder {
         di = shield.guard(() => parseDocInfo(diRaw, compressed), di, 'hwp:docInfo');
       }
 
-      // Extract images from BinData streams
-      const imageStreams: { path: string; data: Uint8Array }[] = [];
-      for (const [path, data] of streams) {
-        if ((path.includes('BinData') || path.includes('.jpg') || path.includes('.jpeg') || path.includes('.png') || path.includes('.gif') || path.includes('.bmp'))
-            && !path.includes('FileHeader') && !path.includes('DocInfo') && !path.includes('BodyText') && !path.includes('Section')) {
-          imageStreams.push({ path, data });
-          console.log(`[HwpScanner] Image stream found: ${path} (${data.length} bytes)`);
-        }
+      // 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);
 
-      // Create image nodes for each image stream (deduplicated by hash)
       const objectMap = new Map<number, ImgNode>();
-      const seenHashes = new Set<string>();
-      let imgIdx = 0;
-      for (const { path, data } of imageStreams) {
-        // Determine MIME type from extension or signature
-        let mimeType = 'image/jpeg';
-        const lowerPath = path.toLowerCase();
-        if (lowerPath.includes('.png')) mimeType = 'image/png';
-        else if (lowerPath.includes('.gif')) mimeType = 'image/gif';
-        else if (lowerPath.includes('.bmp')) mimeType = 'image/bmp';
-
-        // Also check signature
-        if (data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4E && data[3] === 0x47) mimeType = 'image/png';
-        else if (data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x3538) mimeType = 'image/gif';
-        else if (data[0] === 0x42 && data[1] === 0x4D) mimeType = 'image/bmp';
-
-        const imgData = Buffer.from(data);
-        const base64 = imgData.toString('base64');
-        const hash = base64.slice(0, 20); // Use first 20 chars as simple hash
-        if (!seenHashes.has(hash)) {
-          seenHashes.add(hash);
-          objectMap.set(imgIdx++, buildImg(
-            base64,
-            mimeType as any,
-            0, // w
-            0, // h
-            `Image from ${path}`,
-          ));
-          console.log(`[HwpScanner] Added unique image: ${hash}... (${data.length} bytes)`);
-        } else {
-          console.log(`[HwpScanner] Duplicate image skipped: ${hash}...`);
-        }
+      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));
       }
 
-      console.log(`[HwpScanner] Found ${imageStreams.length} image streams, ${objectMap.size} unique images`);
+      // gsoCtx tracks sequential 'gso' encounter order — must be shared across all sections
+      const gsoCtx: GsoCtx = { count: 0 };
 
       // Body sections
       const allContent: ContentNode[] = [];
@@ -891,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;
             }
@@ -899,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}`,
         );
@@ -907,30 +1015,10 @@ export class HwpScanner implements Decoder {
         if (r.pageDims) pageDims = r.pageDims;
       }
 
-      // Inject images into paragraphs (only if images are available)
-      console.log(`[HwpScanner] Before injection: ${allContent.length} nodes, ${objectMap.size} images available`);
       if (objectMap.size > 0) {
         injectImagesIntoContent(allContent, objectMap);
-        console.log(`[HwpScanner] After injection: ${allContent.length} nodes`);
       }
 
-      // Count images (recursively)
-      const countImages = (nodes: ContentNode[]): number => {
-        let count = 0;
-        for (const node of nodes) {
-          if ((node as any).tag === 'img') count++;
-          if ((node as any).tag === 'para' && (node as any).kids) count += countImages((node as any).kids);
-          if ((node as any).tag === 'grid' && (node as any).kids) {
-            for (const row of (node as any).kids) {
-              if (row.kids) count += countImages(row.kids);
-            }
-          }
-        }
-        return count;
-      };
-      const imgCount = countImages(allContent);
-      console.log(`[HwpScanner] Images in content: ${imgCount}`);
-
       warns.push(...shield.flush());
       const content = allContent.length > 0 ? allContent : [buildPara([buildSpan('')])];
       return succeed(buildRoot({}, [buildSheet(content, pageDims)]), warns);
@@ -947,6 +1035,52 @@ 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)
    ════════════════════════════════════════════════════════════ */
@@ -994,35 +1128,69 @@ function injectImagesIntoContent(
   content: ContentNode[],
   objectMap: Map<number, ImgNode>
 ): void {
-  const imageArray = Array.from(objectMap.values());
-  if (imageArray.length === 0) return;
+  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;
 
-  // Get unique images (deduplicate by base64 content)
-  const uniqueImages = Array.from(new Set(imageArray.map(img => img.b64))).map(b64 => {
-    return imageArray.find(img => img.b64 === b64)!;
-  });
-  if (uniqueImages.length === 0) 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);
+          }
+        }
+      }
+    }
+  };
 
-  let imgIdx = 0;
   for (const node of content) {
     if (node.tag === 'para' && node.kids) {
-      for (let i = 0; i < node.kids.length; i++) {
-        const kid = node.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;
-          // Support both __IMG_N__ and __EXT_N__ patterns
-          const match = text.match?.(/^__(?:IMG|EXT)_(\d+)__$/);
-          if (match) {
-            // Replace placeholder with next available image (round-robin)
-            const imgNode = uniqueImages[imgIdx % uniqueImages.length];
-            if (imgNode) {
-              node.kids[i] = imgNode;
-              imgIdx++;
-            }
-          }
+      // 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);
     }
   }
 }