# HWPJS
> HWP5 · HWPX 문서를 위한 헤드리스 API와 Canvas 어댑터
## 시작하기
- [설치와 패키지](/hwpjs/guide/installation.md): HWP5·HWPX용 Zig/WASM 엔진과 CLI·MCP·웹 어댑터는 **@ohah/hwpjs@0.1.0**으로 공개되었습니다. Node.js 24.20.0 이상을 사용하세요. 이전 Rust 기반 0.1.0-rc.10과 현재 공개 API는 다릅니다. 이 가이드에서는 0.1.0의 패키지 root와 subpath를 사용합니다. /react, /svelte 등을 별도 npm 패키지 이름으로 설치하지 않습니다.
## 샘플·데모
- [HWP 샘플과 데모](/hwpjs/guide/demo.md): 전체화면 Canvas 편집기 열기 문서 사이트 안에서 HWP5·HWPX 파일을 열고 편집할 수 있습니다. 예제 열기에서 파일을 선택하거나 내 컴퓨터의 파일을 여세요. 파일 처리와 편집은 브라우저 안에서 수행합니다. noori.hwp 다운로드 예제 파일의 기존 다운로드 주소를 유지합니다. 지원 범위와 제한에서 조판·개체 편집·저장 제한을 확인하세요. 구 Rust JSON·Markdown·HTML 변환기는 이 데모에 포함되지 않습니다.
- [HWPX 샘플과 데모](/hwpjs/guide/demo-hwpx.md): 전체화면 Canvas 편집기 열기 문서 사이트 안에서 HWP5·HWPX 파일을 열고 편집할 수 있습니다. 예제 열기에서 파일을 선택하거나 내 컴퓨터의 파일을 여세요. 파일 처리와 편집은 브라우저 안에서 수행합니다. noori.hwpx 다운로드 예제 파일의 기존 다운로드 주소를 유지합니다. 지원 범위와 제한에서 조판·개체 편집·저장 제한을 확인하세요. 구 Rust JSON·Markdown·HTML 변환기는 이 데모에 포함되지 않습니다.
## 문서 데모
- [공개 API 직접 실행](/hwpjs/api/playground.md): 샘플 API와 JSON 인수를 선택해 실제 반환값·오류·전후 상태를 확인하세요. 문서 열기·선택·입력·실행 취소·저장 흐름을 직접 살펴볼 수 있습니다. 이 도구는 함께 배포한 현재 개발 버전의 패키지·WASM을 사용합니다. 설치한 npm 버전의 지원 범위는 패키지 이름과 게시 상태에서 확인하세요.
- [전체화면 편집 데모](/hwpjs/playground.md)
## CLI · MCP
- [CLI로 원본 읽기·편집·새 문서·변환](/hwpjs/guide/cli.md): HWP5와 HWPX 원본 읽기·정보/개체 조회·그림 추출과 명시 편집을 공통 Native 엔진으로 처리합니다. 새 문서 생성, 명시적인 text-only 교차 변환과 로컬 OCR도 제공합니다. 기본 읽기는 관측한 문서 내용을 텍스트나 Markdown 본문으로 출력합니다. 편집에 필요한 원문 ID·SHA와 진단 상세는 편집 구조 보기에서 확인합니다. 브라우저 체험은 로컬 Node CLI 실행과 별개입니다. 페이지가 사용자의 로컬 파일 시스템이나 설치된 CLI를 대신 실행하지는 않습니다. 현재 실습의 읽기·보기 전환·대표 문자열 편집이 아래 apply/create/convert/OCR 화면을 모두 제공한다는 뜻은 아닙니다.
## 공개 API
- [HeadlessEditor](/hwpjs/api/editor.md): 공개 API 직접 실행에서 실제 코드·JSON 인수·반환값·오류를 확인할 수 있습니다. createEditor({ runtimeFactory, onError? })가 반환하는 객체의 public 소스 계약입니다. 타입 export는 @ohah/hwpjs, runtime 구현은 @ohah/hwpjs/runtime으로 나뉩니다. EditorState는 저장 문서 모델이 아닙니다. content, capabilities, selection은 공개 타입상 unknown인 관측값입니다. 임의 JSON 구조로 수정해서 Native 문서를 바꿀 수 없습니다. state.token은 editor/document/generation/revision 소유권을 검증하며, 저장 bytes를 다시 여는 것과 과거 snapshot을 재주입하는 것은 다릅니다. read()와 state.read() 콜백은 동기 조회만 수행합니다. 이 콜백 안에서 load/dispatch/save를 하거나 async 함수를 넘기지 마세요. 상태 구독은 등록 전에 현재값을 getEditorState()로 읽고, 종료 시 구독을 해제하는 방식으로 구성할 수 있습니다.
## 프레임워크
- [Vanilla](/hwpjs/frameworks/vanilla.md): 먼저 웹 Worker·WASM 배치를 진행하세요. 이 프레임워크의 실행 데모에서 HWP·HWPX 파일을 직접 열 수 있습니다. createCanvasSurface는 현재 렌더러와 직접 입력 구현을 연결합니다. 빈 호스트 요소와 editor를 전달하고 실제 마운트 높이를 지정하세요. 예: 호스트 CSS에 height: 70vh. 호스트의 자식 노드는 surface가 소유하므로 다른 프레임워크로 자식을 동시에 렌더링하지 않습니다. 아래 예제는 브라우저 runtime helper의 createBrowserEditor를 같은 앱 모듈에서 가져옵니다. 호출 앱은 파일 picker에서 받은 File과 배포한 asset URL을 전달합니다. 파일이 열리면 Canvas에서 마우스·키보드·IME로 입력할 수 있습니다. 하나의 editor에는 활성 input surface 하나만 연결합니다. surface.dispose()와 editor.dispose()는 서로 다른 수명을 정리합니다. 언마운트 전에 대기 입력 반영과 오류 처리 정책도 정하세요. 이 패키지는 전체 리본·대화상자·파일 다운로드 UI를 제공하는 완제품 에디터가 아닙니다. 데모 shell은 별도 앱입니다. 저장은 반환된 editor.save()를 사용합니다.
## 지원 범위
- [지원 범위와 제한](/hwpjs/guide/limitations.md): 현재 public 소스 지원과 npm 배포·실제 UI 동작·문서별 저장 검증은 서로 다른 상태입니다. 이 사이트의 타입 검사와 정적 빌드는 제품의 Native/브라우저 E2E를 대신하지 않습니다.
## 로드맵
- [지원 현황과 로드맵](/hwpjs/roadmap.md): 배포 정보 기준일: 2026-10-30. 아래 과거 검증 기록은 각 실행 당시 범위를 유지합니다. 공개 배포와 준비 소스의 상태를 구분합니다. 현재 HWPJS는 Zig 기반 HWP5/HWPX 코어와 freestanding WASM, DOM 없는 헤드리스 API, 이를 사용하는 Canvas 호스트로 구성됩니다. 전체 형식·모든 위치의 편집·한/글과 동일한 조판은 아직 완료되지 않았습니다. HWP3는 사용자 요청으로 대상에서 제외합니다. 이 페이지는 현재 작업 트리의 공개 소스와 기존 검증 기록을 대조한 상태표입니다. 이번 문서 조사에서 Native 빌드나 전수감사를 새로 실행하지 않았습니다. 소스의 public export, 패키지 빌드, npm registry 공개 설치, 실제 브라우저, RN 기기 지원은 서로 다른 증거입니다. 완료 기준이 다른 항목을 합쳐 진행률을 계산하지 않습니다.
## Others
- [페이지를 찾을 수 없습니다](/hwpjs/404.md): 주소가 바뀌었거나 해당 문서가 아직 공개되지 않았을 수 있습니다. 문서 홈에서 현재 제공하는 기능을 확인하세요. CLI 설치와 사용MCP 도구 연결Skill 설치브라우저 Native 체험
- [공개 API 가이드](/hwpjs/api/index.md): @ohah/hwpjs@0.1.1의 헤드리스 API와 이전 0.1.0의 차이를 안내합니다. 아래 실행 페이지는 함께 배포한 실제 패키지·WASM을 사용합니다. 현재 소스에 추가된 기능이 기존 npm 설치본에도 자동으로 포함됐다는 뜻은 아닙니다. 공개 API 직접 실행: 함수·JSON 인수·실제 결과/오류·전후 상태 확인HeadlessEditor: 문서 열기·선택·명령·저장·수명 계약선택과 서식: typed 명령과 지원 경계암호·취소 예제: 암호 후보 재시도·기존 문서 보존·readonly 경계편집·저장 예제: 현재 workspace 예제패키지 이름과 게시 상태: 기존 npm과 새 API의 구분
- [선택과 서식](/hwpjs/api/selection.md)
- [CLI·MCP 브라우저 체험](/hwpjs/cli-simulation.md): 공개 Noori HWP5/HWPX를 실제 Native WASM으로 읽고 한 문단을 수정해 보세요. 미리 저장한 실행 결과를 재생하지 않습니다. CLI 사용법, MCP 도구 계약, Skill 설치를 같은 작업에 연결합니다. 이 페이지는 브라우저에서 공통 CLI engine·model·renderer를 호출합니다. 표시되는 명령·tools/call 요청과 결과는 로컬 실행 흐름을 설명하는 시뮬레이션이며 Node 프로세스나 MCP stdio 서버를 브라우저에서 실행하는 것은 아닙니다. 문서 전체 JSON 변환도 제공하지 않습니다.
- [React Native — experimental](/hwpjs/frameworks/react-native.md): @ohah/hwpjs/react-native의 TypeScript provider/transport 기반과 실제 iOS/Android 에디터의 완성은 다릅니다. Native 코드·플랫폼별 아티팩트·실기기 E2E가 완료되지 않은 상태에서는 experimental로 취급합니다. 웹 Canvas 어댑터를 React Native View로 바로 렌더링할 수 있다고 안내하지 않습니다. 이 사이트는 RN 패키지 설치만으로 네이티브 편집기가 실행된다는 예제를 제공하지 않습니다. Native 호스트와 runtime, 입력·IME, 저장·파일 접근, 수명과 실패 처리를 플랫폼별로 연결하고 검증해야 합니다. 브라우저 Worker/WASM 예제를 기기 동작 증거로 재사용하지 마세요. 현재 바로 연결할 수 있는 브라우저 예제는 Vanilla, React, Svelte를 참고하세요.
- [React](/hwpjs/frameworks/react.md): 먼저 웹 Worker·WASM 배치를 진행하세요. 이 프레임워크의 실행 데모에서 HWP·HWPX 파일을 직접 열 수 있습니다. React 어댑터는 외부에서 소유한 HeadlessEditor를 받아 Canvas 호스트만 관리합니다. 예제는 공개 패키지 0.1.0과 React 19.3.1을 사용합니다. 부모 앱은 Runtime helper로 editor를 만들고, 파일 bytes를 load한 뒤 DocumentPane에 전달합니다. React 렌더마다 새 editor를 만들지 마세요. 한 editor를 여러 surface에 동시에 연결하지 않습니다. environment 객체를 전달할 때는 identity를 안정적으로 유지하세요. CanvasSurface/useCanvasSurface는 effect에서 surface를 생성하고 분리합니다. editor 자체를 load하거나 dispose하지 않으므로 최종 소유자인 부모가 종료해야 합니다. StrictMode의 재마운트를 고려해 자원 생성과 정리를 짝지으세요. useEditorState는 현재 상태를 구독합니다. async mutation을 render나 editor.read() 콜백 안에서 실행하지 않습니다. ref를 쓰면 CanvasSurfaceHandle의 focus/scale/selection/flushComposition에 접근할 수 있습니다. 이는 문서의 typed 명령 전체를 대신하는 API가 아닙니다. SSR에서는 빈 호스트가 렌더링되고 실제 Canvas/Worker는 클라이언트 수명에서 준비합니다.
- [Svelte](/hwpjs/frameworks/svelte.md): 먼저 웹 Worker·WASM 배치를 진행하세요. 이 프레임워크의 실행 데모에서 HWP·HWPX 파일을 직접 열 수 있습니다. @ohah/hwpjs/svelte는 CanvasEditor 컴포넌트와 canvasSurface action을 공개합니다. 예제는 공개 패키지 0.1.0과 Svelte 5.57.3을 사용합니다. 아래는 실제 데모와 같은 mount 경계의 TypeScript 예제이며, 제품 컴포넌트의 public export 타입으로 검사합니다. 부모 앱이 editor의 생성·문서 열기·저장을 소유하고 위 함수에 전달합니다. 반환된 dispose는 Svelte 컴포넌트를 unmount합니다. 컴포넌트 분리 후 editor 소유자가 await editor.dispose()를 수행하세요. 한 editor에 동시에 여러 CanvasEditor를 마운트하지 않습니다. Svelte 템플릿 안에서도 CanvasEditor를 사용할 수 있습니다. 이 페이지는 별도 미검증 템플릿을 중복 제공하지 않고 타입 검사하는 TS 진입점 예제만 제공합니다. 서버 export와 브라우저 export가 분리되어 있어 SSR 모듈 평가 시 DOM 호스트를 만들지 않습니다. 실제 Canvas 생성은 클라이언트 마운트 이후입니다.
- [열기 → 선택 → 입력 → 저장](/hwpjs/guide/editing.md): 파일 선택과 파일 읽기는 호스트 앱의 책임입니다. load는 URL이나 파일 경로가 아니라 Uint8Array 또는 ArrayBuffer를 받습니다. detectDocumentFormat은 컨테이너 구분이며 문서의 모든 내용이 지원된다는 판정은 아닙니다. 호스트가 Reader 또는 Worker runtime factory와 동의 콜백을 주입합니다. replaceFirst는 호출자가 소유한 editor로 편집·저장을 수행하며, 저장 취소나 실패만으로 editor를 종료하지 않습니다. withEditor는 한 번의 작업 수명이 필요한 호스트용 도우미이며 작업을 빠져나갈 때만 finally에서 종료합니다.
- [MCP로 문서 도구 연결](/hwpjs/guide/mcp.md): MCP 클라이언트에 로컬 stdio 서버를 연결하면 HWP5/HWPX 읽기·문서/개체 조회·그림 추출과 문단 편집, 명시 변경 묶음·새 문서·text-only 변환·로컬 OCR을 사용할 수 있습니다. 서버는 공통 CLI의 파일·SHA·네이티브 검증을 호출하며 별도 문서 파서를 두지 않습니다.
- [기존 Rust 문서에서 이동](/hwpjs/guide/migration.md): 과거 legacy/rust/documents 사이트는 역사로 보존합니다. 해당 사이트의 @ohah/hwpjs, napi/WASI 구성, toJson/toHtml/toMarkdown/CLI 예제를 새 @ohah/hwpjs의 public API로 바꾸어 읽지 마세요. 이 문서 사이트는 레거시 사양·개발 검증 기록 전체를 복제하지 않습니다. 사용자 통합에는 설치, Runtime, 편집과 저장, 프레임워크, 제한을 먼저 참고하세요.
- [패키지 이름과 게시 상태](/hwpjs/guide/package-names.md): 공개 배포 이름은 **@ohah/hwpjs**이며, Zig/WASM 공통 엔진을 포함한 0.1.1을 사용합니다. 내부 개발 workspace 이름과 이전 RC의 API를 현재 공개 API와 구분합니다.
- [암호 후보·재시도·취소](/hwpjs/guide/password.md): load와 unlock은 기존 활성 문서를 새 문서 후보와 구분합니다. 암호가 필요한 후보를 열지 못했을 때 기존 문서 A를 버리고 새 editor를 만들 필요는 없습니다. 암호 입력 dialog/CLI와 재시도 횟수는 호스트 콜백으로 주입합니다.
- [Runtime · WASM 설정](/hwpjs/guide/runtime.md): createEditor는 문서마다 Runtime을 주입받습니다. core를 import하는 것과 브라우저 Worker를 실제 생성하는 시점은 다릅니다. factory는 호출마다 새 runtime을 반환해야 하며, 같은 문서 인스턴스를 여러 editor에 공유하지 않습니다.
- [AI 도구용 Skill 설치](/hwpjs/guide/skill.md): hwpjs Skill은 AI 도구가 원본 HWP5/HWPX를 읽고 요청한 문자열만 수정하도록 안내합니다. Skill 자산에는 CLI·MCP 서버·WASM이 함께 포함되며, 실행 시 별도 npm 설치나 임의의 런타임 다운로드를 요구하지 않습니다. 호스트에는 Node.js 24.20 이상이 필요합니다.