@mdgate/hwp 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @mdgate/hwp
+
+Convert Hangul Word Processor files to Markdown. Outputs GitHub-Flavored Markdown. Works in Node,
+Edge, and browsers. No native addons.
+
+Handles: `.hwp`, `.hwpx`, `.hwt`, `.hwtx`
+
+- **HWPX / HWTX** — ZIP + OWPML. Reads `Contents/section*.xml` (and `Contents/header.xml` for
+  outline/heading styles) for paragraphs, line breaks, and tables.
+- **HWP / HWT** — OLE compound files (HWP 5) or the classic `HWP Document File` signature (HWP 3).
+  BodyText section streams are decompressed and scanned for `PARA_TEXT` records when the layout is
+  recognizable. The binary record format is only partially specified publicly; when a stream is too
+  opaque, readable UTF-16 strings (and the `PrvText` preview) are emitted as paragraphs. Tables,
+  drawings, and other controls in binary HWP are not reconstructed.
+
+Encrypted or distribution-locked documents fail with `ConvertError.encrypted`.
+
+## Usage
+
+```ts
+import { toMarkdown } from '@mdgate/hwp';
+
+const markdown = await toMarkdown(bytes);
+```
+
+Compose with other converters:
+
+```ts
+import { create } from '@mdgate/core';
+import { hwp } from '@mdgate/hwp';
+
+const convert = create([hwp()]);
+```
+
+Part of [mdgate converters](https://github.com/mdgate/converters); install
+`@mdgate/converters` for every format at once.

package/dist/hwp.d.ts

@@ -0,0 +1,2 @@
+import type { Converter } from '@mdgate/core';
+export declare function hwp(): Converter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { hwp } from './hwp.js';
+export { toMarkdown } from './to-markdown.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+import{CompoundFile as Fn,detectOleDoc as In,detectZipDoc as Xn,hasOleMagic as k,Package as kn}from"@mdgate/containers";import{ConvertError as p}from"@mdgate/core";import{documentToMarkdown as Mn}from"@mdgate/document";import{fileExtension as On}from"@mdgate/utils";import{hasOleMagic as Wn}from"@mdgate/containers";import{ConvertError as Nn}from"@mdgate/core";import{CompoundFile as Z,hasOleMagic as z,MAX_ENTRY_BYTES as V,MAX_RECORDS as Y}from"@mdgate/containers";import{ConvertError as s}from"@mdgate/core";import{emptyDocument as J,plain as Q}from"@mdgate/document";import{cleanText as C,collapseWs as D,InflateLimitError as j,inflateZlib as q,isAlphanumeric as K}from"@mdgate/utils";var x="HWP Document File",S=2,y=16,b=y+51,nn=new Set([1,2,3,4,5,6,7,8,11,12,13,14,15,16,17,21,22,23,26,27,28,29,30]);function d(n){if(n.length<x.length)return!1;for(let e=0;e<x.length;e+=1)if(n[e]!==x.charCodeAt(e))return!1;return!0}function B(n){if(z(n))return en(n);if(d(n))return L(un(n));throw s.malformed("not an HWP document")}function en(n){let e;try{e=Z.open(n)}catch(i){if(i instanceof s)throw i;throw s.malformed("not an OLE2 compound file")}if(e.exists("EncryptionInfo")||e.exists("EncryptedPackage"))throw s.encrypted();let t=A(e,"FileHeader"),r=t!==void 0?tn(t):void 0;if(r?.encrypted||r?.distribution)throw s.encrypted();let o=[],f=!1;for(let i=0;i<256;i+=1){let c=`BodyText/Section${i}`;if(!e.exists(c)){if(f||i>0)break;continue}f=!0;let m=W(e,c);if(m===void 0)continue;let u=cn(m,r?.compressed);rn(u,o)}if(o.length===0){let i=A(e,"PrvText");if(i!==void 0)an(i,o)}if(o.length===0)for(let i of e.readRootStorage()){if(i.type!==2)continue;let c=A(e,i.name);if(c!==void 0)g(c,o)}return L(o)}function tn(n){if(n.length<40)return;if(!d(n))return;let e=new DataView(n.buffer,n.byteOffset,n.byteLength).getUint32(36,!0);return{compressed:(e&1)!==0,encrypted:(e&2)!==0,distribution:(e&4)!==0}}function rn(n,e){let t=on(n);if(t.length>0){for(let r of t)e.push(r);return}g(n,e)}function on(n){if(n.length<4)return[];let e=new DataView(n.buffer,n.byteOffset,n.byteLength),t=[],r=0,o=0,f=0;while(r+4<=n.length&&o<Y){let i=e.getUint32(r,!0),c=i&1023,m=i>>>20&4095,u=m,l=r+4;if(m===4095){if(l+4>n.length)break;u=e.getUint32(l,!0),l+=4}if(u<0||l+u>n.length)break;if(o+=1,f=l+u,c===b){let a=fn(n.subarray(l,l+u));if(a.length>0)t.push(a)}r=l+u}if(t.length===0&&(o===0||f<n.length/2))return[];return t}function fn(n){let e=n.length&-2,t="",r=0;while(r+1<e){let o=n[r]|n[r+1]<<8;if(r+=2,o<32){if(nn.has(o))r+=14;else if(o===9)t+="\t";else if(o===10)t+=`
+`;else if(o===24||o===25)t+="-";else if(o===31)t+=" ";continue}if(o===65534||o===65535)continue;t+=String.fromCharCode(o)}return t}function cn(n,e){if(n.length>=2&&ln(n)){let t=H(n);if(t!==void 0)return t}if(e===!1)return n;if(e===!0){let t=H(n);if(t!==void 0)return t}return n}function H(n){try{return q(n,V)}catch(e){if(e instanceof j)throw s.resourceLimit("max_entry_bytes",e.message);if(e instanceof s&&e.isFatal())throw e;return}}function ln(n){if(n.length<2)return!1;let e=n[0],t=n[1];if(((e<<8)+t)%31!==0)return!1;return(e&15)===8}function un(n){let e=n.length>32?32:x.length,t=[];if(g(n.subarray(Math.min(e,n.length)),t),t.length===0)g(n,t);return t}function an(n,e){let t=n.length&-2,r=new TextDecoder("utf-16le").decode(n.subarray(0,t));for(let o of r.split(/\0+/)){let f=D(C(o)).trim();if(R(f))e.push(f)}}function g(n,e){let t="",r=()=>{if(t.length>=S)e.push(t);t=""},o=n.length&-2;for(let f=0;f<o;f+=2){let i=n[f]|n[f+1]<<8;if(i!==0&&sn(i))t+=String.fromCharCode(i);else r()}r()}function L(n){let e=new Set,t=J();for(let r of n){let o=D(C(r)).trim();if(!R(o)||e.has(o))continue;e.add(o),t.blocks.push({type:"paragraph",inlines:[Q(o)]})}if(t.blocks.length===0)throw s.malformed("no readable text in HWP document");return t}function sn(n){if(n===9||n===10||n===13||n===32)return!0;if(n<32||n>=127&&n<=159)return!1;return n!==65534&&n!==65535}function R(n){if(n.length<S)return!1;let e=0;for(let r of n)if(K(r))e+=1;if(e<2)return!1;let t=n.toLowerCase();if(t.includes("xmlns")||t.includes("http://schemas.")||t.includes("hwp document file"))return!1;return!0}function A(n,e){if(!n.exists(e))return;return W(n,e)}function W(n,e){try{return n.readStream(e)}catch(t){if(t instanceof s&&t.isFatal())throw t;return}}import{Package as dn}from"@mdgate/containers";import{ConvertError as h}from"@mdgate/core";import{cellSpanning as mn,emptyDocument as hn,GridBuilder as pn,inlinesAreEmpty as xn,plain as w,resolveHeaderRows as gn}from"@mdgate/document";import{cleanText as U}from"@mdgate/utils";function F(n){let e;try{e=dn.open(n)}catch(i){throw Rn(i)}let t=e.optionalXmlPart("Contents/header.xml")??e.optionalXmlPart("Contents/Header.xml"),r={styles:t!==void 0?Pn(t):new Map},o=wn(e);if(o.length===0)throw h.missingPart("Contents/section0.xml");let f=hn();for(let i of o){let c=e.optionalXmlPart(i);if(c===void 0)continue;P(c,f.blocks,r)}if(f.blocks.length===0)Dn(e,f);if(f.blocks.length===0)throw h.malformed("no readable text in HWPX document");return f}function wn(n){let e=[];for(let t of n.partNames())if(/^Contents\/section\d+\.xml$/i.test(t))e.push(t);return e.sort((t,r)=>N(t)-N(r)),e}function N(n){let e=n.match(/section(\d+)/i);return e!==null?Number(e[1]):0}function Pn(n){let e=new Map;for(let t of n.descendantsAny("style")){let r=t.attrAny("id");if(r===void 0)continue;let o=An(t);if(o!==void 0)e.set(r,o)}return e}function An(n){let e=(n.attrAny("type")??"").toLowerCase(),r=`${n.attrAny("name")??""} ${n.attrAny("engName")??""}`.match(/(?:개요|제목|outline|heading)\s*(\d+)/i);if(r!==null)return En(Number(r[1]));if(e==="outline"||e==="heading")return 1;return}function En(n){if(!Number.isFinite(n)||n<1)return 1;return n>6?6:n|0}function P(n,e,t){if(n.local==="tbl"){let r=I(n,t);if(r!==void 0)e.push(r);return}if(n.local==="p"){Un(n,e,t);return}for(let r of n.childElems())P(r,e,t)}function Un(n,e,t){let r=Tn(n,t),o=[],f=!1,i=()=>{if(xn(o)){o=[];return}if(r!==void 0&&!f)e.push({type:"heading",level:r,anchor:void 0,content:o}),f=!0;else e.push({type:"paragraph",inlines:o});o=[]},c=(m)=>{for(let u of m.children){if(u.type==="text"){let a=U(u.text);if(a.length>0)o.push(w(a));continue}let l=u.elem;switch(l.local){case"tbl":{i();let a=I(l,t);if(a!==void 0)e.push(a);break}case"t":{let a=U(l.text());if(a.length>0)o.push(w(a));break}case"lineBreak":case"line-break":o.push({type:"lineBreak"});break;case"tab":o.push(w("\t"));break;default:c(l)}}};c(n),i()}function Tn(n,e){let t=n.attrAny("styleIDRef")??n.attrAny("styleId")??n.attrAny("styleID");if(t===void 0)return;return e.styles.get(t)}function I(n,e){let t=vn(n);if(t.length===0)return;let r=new pn;for(let f of t){r.nextRow();for(let i of Hn(f))r.place(mn(Cn(i,e),_(i,"colSpan"),_(i,"rowSpan")))}let o=r.finish("data");if(o.grid.length===0)return;return o.headerRows=gn(o,0),{type:"table",table:o}}function vn(n){let e=n.childElems().filter((t)=>t.local==="tr");if(e.length>0)return e;return[...n.descendantsAny("tr")]}function Hn(n){let e=n.childElems().filter((t)=>t.local==="tc");if(e.length>0)return e;return[...n.descendantsAny("tc")]}function Cn(n,e){let t=[],r=n.childElems().find((o)=>o.local==="subList");if(r!==void 0)return P(r,t,e),t;for(let o of n.childElems())if(o.local==="p"||o.local==="tbl")P(o,t,e);return t}function _(n,e){let t=n.attrAny(e)??n.childElems().find((o)=>o.local==="cellSpan")?.attrAny(e);if(t===void 0||t.length===0)return 1;let r=Number(t);if(!Number.isFinite(r)||r<1)return 1;return r>1000?1000:r|0}function Dn(n,e){let t=n.optionalPart("Preview/PrvText.txt")??n.optionalPart("Preview/PrvText.dat")??n.optionalPart("Preview/PrvText");if(t===void 0)return;for(let r of Ln(Sn(t)))e.blocks.push({type:"paragraph",inlines:[w(r)]})}function Sn(n){if(n.length>=2&&n[0]===255&&n[1]===254)return new TextDecoder("utf-16le").decode(n);if(n.length>=2&&n[0]===254&&n[1]===255)return new TextDecoder("utf-16be").decode(n);let e=n.length&-2;if(e>=4&&Bn(n.subarray(0,e)))return new TextDecoder("utf-16le").decode(n.subarray(0,e));return new TextDecoder("utf-8",{fatal:!1}).decode(n)}function Bn(n){let e=0;for(let t=1;t<n.length;t+=2)if(n[t]===0)e+=1;return e*2>=n.length/2}function Ln(n){let e=[];for(let t of n.split(/\0+/)){let r=U(t).trim();if(r.length>0)e.push(r)}return e}function Rn(n){if(n instanceof h){if(n.code==="encrypted"||E(n.message)||E(n.detail??""))return h.encrypted();return n}let e=n instanceof Error?n.message:String(n);if(E(e))return h.encrypted();return h.malformed(`not a readable zip archive: ${e}`)}function E(n){let e=n.toLowerCase();return e.includes("encrypted")||e.includes("password")}function X(n){if(_n(n))return F(n);if(Wn(n)||d(n))return B(n);throw Nn.malformed("not an HWP document")}function _n(n){return n.length>=4&&n[0]===80&&n[1]===75&&n[2]===3&&n[3]===4}var Gn=new Set(["hwp","hwpx","hwt","hwtx"]);function v(){return{id:"hwp",sniff(n,e){if(O(n)==="hwpx"||M(n))return 2;if(G(n)==="hwp"||Zn(n))return 2;if(d(n))return 2;if(e?.path!==void 0&&Gn.has(On(e.path)??""))return 1;return 0},convert(n){return $n(n),{markdown:Mn(X(n))}}}}function $n(n){if(Vn(n))throw p.unsupported("pdf");if($(n)){let e=O(n);if(e==="hwpx")return;if(e!==void 0)throw p.unsupported(e);if(M(n))return;throw p.unsupported("zip")}if(k(n)){let e=G(n);if(e==="hwp")return;if(e!==void 0)throw p.unsupported(e);return}if(d(n))return;throw p.unsupported("hwp")}function M(n){if(!$(n))return!1;let e;try{e=kn.open(n)}catch{return!1}for(let r of e.partNames()){let o=r.toLowerCase();if(o==="contents/content.hpf")return!0;if(/^contents\/section\d+\.xml$/.test(o))return!0}let t=e.optionalPart("mimetype");if(t!==void 0){let o=new TextDecoder("utf-8",{fatal:!1}).decode(t).trim().toLowerCase().replace(/-template$/,"");if(o==="application/hwp+zip"||o==="application/vnd.hancom.hwpx")return!0}return!1}function Zn(n){if(!k(n))return!1;try{let e=Fn.open(n);for(let t of e.readRootStorage())if(zn(t.name))return!0}catch{return!1}return!1}function zn(n){let e=n.charCodeAt(0)===5?n.slice(1):n;return T(n,"FileHeader")||T(e,"HwpSummaryInformation")||T(n,"HWPDocumentInfo")}function T(n,e){return n.length===e.length&&n.toLowerCase()===e.toLowerCase()}function O(n){return Xn(n)}function G(n){return In(n)}function $(n){return n.length>=4&&n[0]===80&&n[1]===75&&n[2]===3&&n[3]===4}function Vn(n){let e=Yn(n);return Jn(n,"%PDF-",e)}function Yn(n){let e=0;if(n.length>=3&&n[0]===239&&n[1]===187&&n[2]===191)e=3;while(e<n.length){let t=n[e];if(t!==9&&t!==10&&t!==13&&t!==32)break;e+=1}return e}function Jn(n,e,t){if(t+e.length>n.length)return!1;for(let r=0;r<e.length;r+=1)if(n[t+r]!==e.charCodeAt(r))return!1;return!0}import{create as Qn}from"@mdgate/core";var jn=Qn([v()]);function qn(n,e){return jn(n,e)}export{qn as toMarkdown,v as hwp};

package/dist/to-markdown.d.ts

@@ -0,0 +1,6 @@
+import { type ConvertHint } from '@mdgate/core';
+/**
+ * Convert a single file's bytes to Markdown with the hwp converter.
+ * `hint.path` is only a sniff hint; it is never read from disk.
+ */
+export declare function toMarkdown(bytes: Uint8Array, hint?: ConvertHint): Promise<string>;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mdgate/hwp",
+  "version": "0.1.0",
+  "description": "mdgate Hangul HWP / HWPX converter",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@mdgate/containers": "0.1.0",
+    "@mdgate/core": "0.1.3",
+    "@mdgate/document": "0.1.0",
+    "@mdgate/utils": "0.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mdgate",
+    "markdown",
+    "hwp",
+    "hwpx",
+    "hangul",
+    "hancom"
+  ]
+}