hwpjs

hwpjs

HWP5·HWPX용 Headless API와 웹 어댑터, 저수준 CFB 읽기·쓰기를 제공하는 JavaScript/WASM 모노레포입니다. 고수준 ESM 진입점은 @ohah/hwpjs와 프레임워크별 subpath입니다.

공개 ESM 사용법

아래는 현재 source/pack 후보의 사용 예입니다. 이 source commit은 신규 npm 버전 발행을 뜻하지 않으며, 배포된 package/demo의 버전은 별도로 확인해야 합니다.

import { createEditor } from '@ohah/hwpjs';
import { createWorkerRuntimeFactory } from '@ohah/hwpjs/runtime';

const editor = createEditor({
  runtimeFactory: createWorkerRuntimeFactory({
    workerURL: '/hwpjs/worker.js',
    wasmURL: '/hwpjs/hwpjs.wasm',
  }),
});

이 예제는 module Worker와 WASM을 제공하는 브라우저 서버 환경을 전제로 합니다. 패키지 dist의 worker.js와 hwpjs.wasm을 해당 URL로 제공하도록 호스트를 구성합니다. React 어댑터는 @ohah/hwpjs/react의 CanvasSurface입니다. 내부 5개 @hwpjs/* 패키지는 private workspace와 dist exports를 사용합니다. 설치·명시 WASM 빌드 순서, 테스트/문서 명령과 Native·skip 제한은 개발·검증 명령을 따릅니다.

저수준 CFB 빌드

Zig 0.17.0과 Node.js 24를 설치한 뒤 저장소 루트에서 실행합니다.

zig build -Doptimize=ReleaseSafe

Node.js에서 읽기

import { readFileSync } from 'node:fs';
import { createCfbReader } from './js/cfb.mjs';

const reader = await createCfbReader(readFileSync('zig-out/bin/hwpjs.wasm'));
try {
  reader.parse(readFileSync('sample.hwp'), { strict: true });
  console.log(reader.findExact('/BodyText/Section0')?.content);
} finally {
  reader.close();
}

이 CFB 예제의 반환값은 컨테이너 스트림의 원시 바이트입니다. 문서 단위 고수준 사용법은 공개 API와 선택·서식을 참고하세요. 아래 저수준 예제는 고수준 편집 API의 지원 범위를 설명하는 예제가 아닙니다.

HWP5 문단 텍스트의 읽기 전용 미리보기는 node tools/hwp5-text-preview.mjs sample.hwp로 확인할 수 있습니다. 먼저 위 빌드를 실행하세요. 제어 토큰을 제외한 텍스트와 문단별 제어 코드가 출력됩니다. HWP5 미리보기 API는 완전한 문서 모델·편집·저장을 제공하지 않습니다.

브라우저에서 읽기

import { createCfbReader } from './js/cfb.mjs';

const wasm = await fetch('./zig-out/bin/hwpjs.wasm');
const reader = await createCfbReader(await wasm.arrayBuffer());
try {
  const file = await fetch('./sample.hwp');
  reader.parse(new Uint8Array(await file.arrayBuffer()), { strict: true });
  console.log(reader.findExact('/FileHeader')?.content);
} finally {
  reader.close();
}

HTML·JS·WASM·입력 파일을 HTTP 서버에서 제공하고 실행합니다.

Canvas 텍스트 미리보기 실행

빌드 후 node tools/serve-preview.mjs를 실행하고 로컬 미리보기에서 .hwp 또는 .hwpx 파일을 선택하세요. 다른 포트는 node tools/serve-preview.mjs 8081처럼 지정합니다.

파일은 브라우저 안에서 처리합니다. 편집 가능한 텍스트 위를 클릭해 caret을 놓고 입력하거나 드래그해 같은 문단을 선택하세요. 한글 조합·삭제·붙여넣기의 입력 경로를 연결한 실험입니다. 편집 세션을 연 뒤 ‘편집본 다운로드’를 누르면 원본과 별도의 파일을 받습니다. HWP5에서 미재조판 저장이 필요하면 별도 허용 체크를 선택하세요. 다운로드 제한을 확인하고 저장 파일의 조판을 한글에서 확인하세요.

실행 취소는 Ctrl/⌘+Z, 다시 실행은 Ctrl/⌘+Shift+Z 또는 Ctrl/⌘+Y입니다. 이력·문단 분할/병합은 문서와 WASM 지원 상태에 따라 사용할 수 있습니다. 원본 글꼴·페이지 조판의 완전한 재현은 보장하지 않습니다. 직접 입력 범위와 검증 제한을 참고하세요. 숫자 인덱스/글자 모양 ID 명령은 접힌 고급 API 폼에 있습니다.

스트림 추가·교체·저장과 옵션·자원 제한은 CFB API를 참고하세요.