@rhwp/editor 0.7.18 → 0.8.0

package/README.md

@@ -8,6 +8,12 @@
 웹 페이지에 HWP 에디터를 통째로 임베드합니다.
 메뉴, 툴바, 서식, 표 편집 — rhwp-studio의 모든 기능을 그대로 사용할 수 있습니다.
 
+SDK는 지원되는 Studio와 `MessageChannel` v1을 협상해 binary를 transferable로 전송합니다.
+구버전 Studio에는 기존 `postMessage` protocol로 자동 전환되며 기존 공개 API는 유지됩니다.
+`getRendererDiagnostics()`는 `renderer-diagnostics-v1` capability를 협상한 Studio에서만 사용할 수 있습니다.
+호스트와 `studioUrl`은 HTTP(S) origin만 지원합니다. `file:`, `data:`, 브라우저 확장처럼
+origin이 `null`이거나 불투명한 환경의 연결은 SDK와 Studio 양쪽에서 거부합니다.
+
 > **[온라인 데모](https://edwardkim.github.io/rhwp/)** 에서 먼저 체험해보세요.
 
 ## 설치
@@ -72,19 +78,37 @@ const editor = await createEditor(document.getElementById('editor'));
 
 | 옵션 | 기본값 | 설명 |
 |------|--------|------|
-| `studioUrl` | `https://edwardkim.github.io/rhwp/` | rhwp-studio URL |
+| `studioUrl` | `https://edwardkim.github.io/rhwp/` | rhwp-studio HTTP(S) URL. opaque origin은 지원하지 않음 |
 | `width` | `'100%'` | iframe 너비 |
 | `height` | `'100%'` | iframe 높이 |
+| `renderer` | `'canvas2d'` | 문서 단위 renderer 요청. `auto`, `canvas2d`, `canvaskit` 중 하나 |
+| `requestTimeoutMs` | method별 기본값 | 모든 method 제한 시간 override(ms). 일반 10초, load/export 60초 |
+| `handshakeTimeoutMs` | `1000` | v1 협상 후 legacy 전환까지의 제한 시간(ms) |
 
-### editor.loadFile(data, fileName?)
+### editor.loadFile(data, fileName?, options?)
 
 HWP 파일을 로드합니다.
 
 ```javascript
 const result = await editor.loadFile(buffer, 'sample.hwp');
 // result = { pageCount: 5 }
+
+// 안내창에서 사용자가 직접 선택하도록 열기
+await editor.loadFile(buffer, 'sample.hwpx', { suppressDialogs: false });
 ```
 
+**options:**
+
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `skipUnsavedGuard` | `false` | 미저장 변경 확인 없이 문서 교체 |
+| `suppressDialogs` | `true` | 로드 후 안내창(HWPX 검증, 로컬 글꼴 감지) 없이 열기 |
+
+> `suppressDialogs`를 생략하면 검증 경고는 '그대로 열기'로 처리하고 글꼴은 웹 대체 글꼴로
+> 표시하여 `loadFile` 응답을 즉시 반환합니다. 안내창(HWPX 비표준 lineseg 검증, 로컬 글꼴
+> 감지)에서 사용자가 직접 선택해야 하는 대화형 흐름이 필요하면 `suppressDialogs: false`를
+> 명시하세요.
+
 ### editor.pageCount()
 
 현재 문서의 페이지 수를 반환합니다.
@@ -101,6 +125,24 @@ const count = await editor.pageCount();
 const svg = await editor.getPageSvg(0); // 첫 페이지
 ```
 
+### editor.getRendererDiagnostics(page?)
+
+선택된 renderer와 0부터 시작하는 페이지별 readiness 진단을 반환합니다.
+Studio가 `renderer-diagnostics-v1` capability를 제공하지 않으면 명시적으로 실패합니다.
+`auto`에서는 문서 capability preflight, 실제 선택 이유, fallback 이유, 문서 revision과
+resource generation을 `selection`에서 확인할 수 있습니다. 현재 Studio는 `selection`을
+반환하지만, 같은 v1 capability를 제공하는 이전 Studio와의 additive 호환을 위해 이 필드는
+없을 수도 있습니다. `selectionError`는 preflight/리소스/replay 실패를, top-level
+`initializationError`는 Studio 앱 초기화 실패를 나타냅니다. preflight의
+`requiredFontFamilies`는 자동 선택에서 첫 replay 전에 준비해야 하는 문서 폰트 목록입니다.
+기존 v1 소비자 호환을 위해 top-level `request.backend.backend`는 계속 `canvas2d` 또는
+`canvaskit`만 반환하며, `auto` 요청과 실제 선택 과정은 additive `selection`에서 확인합니다.
+
+```javascript
+const diagnostics = await editor.getRendererDiagnostics(0);
+console.log(diagnostics.schemaVersion, diagnostics.effectiveBackend);
+```
+
 ### editor.exportHwp()
 
 현재 편집 중인 문서를 HWP 바이너리로 내보냅니다.
@@ -151,6 +193,89 @@ if (!verify.recovered || verify.pageCountBefore !== verify.pageCountAfter) {
 }
 ```
 
+### editor.exportHml()
+
+현재 편집 중인 문서를 HML(XML) 바이너리로 내보냅니다.
+
+```javascript
+const bytes = await editor.exportHml();
+const blob = new Blob([bytes], { type: 'application/xml' });
+
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'document.hml';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+### editor.getHmlSaveState()
+
+현재 문서의 HML 저장 가능 여부와 blocker 목록을 반환합니다.
+저장 가능 여부는 `hmlSavable`로 판정하고, 실패 원인은 `blockers` 배열로 표시하세요.
+`exportHml()`의 오류 문자열을 파싱하지 마세요.
+
+```javascript
+const state = await editor.getHmlSaveState();
+// {
+//   sourceFormat: 'hwp',
+//   hmlSavable: false,
+//   blockers: [
+//     {
+//       code: 'HML_SOURCE_REQUIRED',
+//       xmlPath: '/HWPML',
+//       message: 'HML source metadata is required',
+//       preserved: false
+//     }
+//   ]
+// }
+
+if (state.hmlSavable) {
+  const bytes = await editor.exportHml();
+  // ... 저장 진행
+} else {
+  for (const item of state.blockers) {
+    console.warn(`HML 저장 불가 [${item.code}] ${item.xmlPath} — ${item.message}`);
+  }
+}
+```
+
+**반환값:**
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `sourceFormat` | `string` | 현재 문서의 원본 형식 — `'hwp'`, `'hwpx'`, `'hml'` |
+| `hmlSavable` | `boolean` | HML로 저장 가능하면 `true` |
+| `blockers` | `HmlSaveBlocker[]` | 저장을 막는 요소 목록. `hmlSavable`이 `true`이면 빈 배열 |
+
+**`HmlSaveBlocker`:**
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `code` | `string` | blocker 종류 코드 |
+| `xmlPath` | `string` | 해당 요소의 XML 경로 |
+| `message` | `string` | 사람이 읽을 수 있는 사유 |
+| `preserved` | `false` | 항상 `false` — 해당 요소가 HML로 보존되지 않음을 뜻함 |
+### editor.notifySaved(fileName?)
+
+내보내기 바이트의 영속화(서버 업로드 또는 호스트 핸드오프) 완료를 스튜디오에
+통지합니다 (#2660). 통지 시 스튜디오는 미저장(dirty) 상태를 해제하고 자동복구
+draft(IndexedDB)를 삭제합니다. **draft 삭제가 완료된 뒤 resolve**되므로, resolve
+이후 창을 닫아도 안전합니다.
+
+```javascript
+const bytes = await editor.exportHwp();
+await uploadToServer(bytes);        // 호스트 저장
+await editor.notifySaved();         // 저장 완료 통지 — dirty 해제 + 복구 draft 삭제
+```
+
+- `fileName` (선택): 호스트가 저장에 사용한 파일 이름. 전달하면 스튜디오의 현재
+  파일 이름이 갱신됩니다.
+- 반환: `{ ok: true, wasDirty: boolean }` — `wasDirty`는 통지 시점에 미저장
+  변경이 있었는지 여부(멱등 호출 관찰용).
+- 스튜디오가 `notify-saved-v1` capability를 광고하지 않으면(구버전 스튜디오 또는
+  legacy 폴백 연결) 요청을 보내지 않고 예외를 던집니다.
+
 ### editor.destroy()
 
 에디터를 제거합니다.
@@ -159,6 +284,43 @@ if (!verify.recovered || verify.pageCountBefore !== verify.pageCountAfter) {
 editor.destroy();
 ```
 
+## 저장 계약 — 내보내기와 저장 완료 통지
+
+`exportHwp()`/`exportHwpx()`/`exportHml()`은 직렬화 바이트만 반환하며 **문서를
+"저장됨"으로 표시하지 않습니다.** 호스트 저장(업로드)이 실패할 수 있으므로,
+스튜디오는 호스트가 `notifySaved()`로 확정하기 전까지 자동복구 draft를
+보존합니다. 통지 없이 종료하면 다음 실행 시 "문서 복구" 안내가 표시됩니다.
+
+**iframe 임베드 (업로드 확정 후 통지):**
+
+```javascript
+const bytes = await editor.exportHwp();
+try {
+  await uploadToServer(bytes);
+  await editor.notifySaved();       // 업로드 "성공 시에만" 호출
+} catch (error) {
+  // 통지하지 않음 — 복구 draft가 보존되어 재시도/복구 가능
+}
+```
+
+**팝업 통합 (핸드오프 즉시 통지 후 닫기):**
+
+스튜디오를 `window.open`으로 띄우고 `window.opener.postMessage`로 바이트를
+넘기는 통합에서는, 핸드오프 시점에 통지하고 닫습니다. 바이트를 수신한 호스트가
+이후 영속화(재시도 포함)를 책임집니다.
+
+```javascript
+window.opener?.postMessage(
+  { action: 'documentExported', content: base64, format: 'hwp' },
+  HOST_ORIGIN,                       // '*' 대신 반드시 명시적 오리진 사용 (문서 유출 방지)
+);
+await editor.notifySaved();          // draft 삭제 완료까지 대기
+window.close();
+```
+
+SDK 없이 스튜디오 페이지 안에서 직접 통합(포크/주입)하는 경우에는 같은 동작의
+`window.rhwpStudio.notifySaved(fileName?)`를 사용할 수 있습니다.
+
 ## 디버깅 도구 — rhwpDev
 
 iframe 안의 rhwp-studio에는 **개발 모드 전용 디버깅 헬퍼** `rhwpDev`가 내장되어 있습니다. 검색, 커서 이동, 문단 ID 점검 등을 콘솔에서 직접 호출할 수 있습니다.
@@ -266,7 +428,9 @@ setInterval(() => {
 
 ### 기본 동작 — 별도 설정 없이 사용 가능
 
-`@rhwp/editor`는 오픈소스 폰트를 내장하고 있어 **별도 폰트 설정 없이 바로 사용**할 수 있습니다.
+`@rhwp/editor`가 기본으로 연결하는 rhwp-studio 배포본은 오픈소스 폰트를 포함하므로
+**별도 폰트 설정 없이 바로 사용**할 수 있습니다. `@rhwp/editor` 패키지 자체에는 폰트 파일이나
+UI runtime dependency가 포함되지 않습니다.
 
 HWP 문서에서 사용된 한컴 전용 폰트(한컴바탕, HY명조 등)는 자동으로 오픈소스 폰트로 폴백됩니다.
 
@@ -290,7 +454,10 @@ HWP 문서에서 사용된 한컴 전용 폰트(한컴바탕, HY명조 등)는
 
 ### 셀프 호스팅 시 폰트
 
-셀프 호스팅 환경에서는 rhwp-studio 빌드에 포함된 `web/fonts/` 폴더의 오픈소스 폰트가 자동으로 사용됩니다. 추가 폰트를 원하면 `web/fonts/`에 woff2 파일을 추가하고 CSS `@font-face`를 등록하면 됩니다.
+저장소의 canonical source는 `assets/fonts/`이고, rhwp-studio build는 이를 배포본의 runtime `fonts/`
+경로로 노출합니다. 셀프 호스팅 서버에서는 이 runtime 경로가 함께 배포되므로 별도 설정 없이
+오픈소스 폰트를 사용합니다. 추가 폰트는 `assets/fonts/`에 WOFF2를 추가하고
+`rhwp-studio/src/core/font-loader.ts`에 `@font-face`와 로딩 정책을 등록해야 합니다.
 
 ## 셀프 호스팅
 

package/index.d.ts

@@ -3,12 +3,18 @@
  */
 
 export interface EditorOptions {
-  /** rhwp-studio URL (기본: https://edwardkim.github.io/rhwp/) */
+  /** rhwp-studio HTTP(S) URL. file:, data:, browser extension 등 opaque origin은 지원하지 않음 */
   studioUrl?: string;
+  /** 문서 단위 renderer 요청. 기본값은 canvas2d이며 auto/CanvasKit 명시 선택도 지원함 */
+  renderer?: 'auto' | 'canvas2d' | 'canvaskit';
   /** iframe 너비 (기본: '100%') */
   width?: string;
   /** iframe 높이 (기본: '100%') */
   height?: string;
+  /** 모든 method 요청 제한 시간 override(ms, 기본: 일반 10000, load/export 60000) */
+  requestTimeoutMs?: number;
+  /** v1 협상 제한 시간(ms, 기본: 1000) */
+  handshakeTimeoutMs?: number;
 }
 
 export interface LoadResult {
@@ -26,19 +32,152 @@ export interface HwpVerifyResult {
   recovered: boolean;
 }
 
+export interface HmlSaveBlocker {
+  code: string;
+  xmlPath: string;
+  message: string;
+  preserved: false;
+}
+
+export interface HmlSaveState {
+  sourceFormat: string;
+  hmlSavable: boolean;
+  blockers: HmlSaveBlocker[];
+}
+
+export interface CanvasKitRendererDiagnostics {
+  mode: 'default' | 'compat';
+  surfacePreference: 'auto' | 'webgpu' | 'webgl' | 'software';
+  surfaceBackend: 'default' | 'software' | null;
+  surfaceFallbackReason: string | null;
+  lastRenderCompleted: boolean;
+  lastUnsupportedOps: string[];
+  lastExpectedUnsupportedOps: string[];
+  lastUnexpectedUnsupportedOps: string[];
+  lastRenderError: string | null;
+  passesRuntimeReadinessGate: boolean;
+  readinessBlockers: Array<'renderNotCompleted' | 'renderError' | 'unexpectedUnsupportedOps' | 'localFontsPending'>;
+  hiddenCanvas2dOverlayUsed: false;
+  lastRenderDurationMs: number | null;
+  renderCount: number;
+  imageCacheEntries: number;
+  imageCacheLimit: number;
+  imageCachePixels: number;
+  imageCachePixelLimit: number;
+  imageCacheHits: number;
+  imageCacheMisses: number;
+  imageCacheEvictions: number;
+  localTypefaceCount: number;
+  localTypefaceLoadFailureCount: number;
+  localTypefacePendingCount: number;
+  bundledTypefaceCount: number;
+  bundledTypefaceLoadFailureCount: number;
+}
+
+export interface CanvasKitDocumentPreflightV1 {
+  schemaVersion: 1;
+  mode: 'default' | 'compat';
+  profile: 'fastPreview' | 'screen' | 'print' | 'highQuality';
+  status: 'eligible' | 'ineligible' | 'incomplete';
+  eligible: boolean;
+  complete: boolean;
+  pageCount: number;
+  scannedPages: number;
+  scannedWorkUnits: number;
+  limits: {
+    maxPages: number;
+    maxWorkUnits: number;
+    maxBlockers: number;
+    maxRequiredFontFamilies: number;
+  };
+  summary: {
+    totalItems: number;
+    directItems: number;
+    directRequiredItems: number;
+    compatOverlayItems: number;
+    textFallbackItems: number;
+    unsupportedItems: number;
+    hiddenOverlayViolations: number;
+  };
+  blockers: Array<{ pageIndex: number; code: string; opType?: string; detail?: string }>;
+  requiredFontFamilies: string[];
+  capabilityDigest: string;
+}
+
+export interface RendererSelectionV1 {
+  schemaVersion: 1;
+  request: { backend: 'auto' | 'canvas2d' | 'canvaskit'; source: 'default' | 'url'; requested?: string; unsupportedReason?: string };
+  requestedBackend: 'auto' | 'canvas2d' | 'canvaskit';
+  effectiveBackend: 'canvas2d' | 'canvaskit';
+  selectionReason: string;
+  fallbackReason: string | null;
+  documentRevision: number;
+  resourceGeneration: number;
+  renderProfile: 'fastPreview' | 'screen' | 'print' | 'highQuality';
+  documentDigest: string | null;
+  decisionKey: string;
+  preflight: CanvasKitDocumentPreflightV1 | null;
+  initializationError: string | null;
+  selectionError: string | null;
+}
+
+export interface RendererDiagnosticsV1 {
+  schemaVersion: 1;
+  request: {
+    /** Legacy v1 request snapshot. Automatic intent is exposed additively through selection. */
+    backend: { backend: 'canvas2d' | 'canvaskit'; source: 'default' | 'url'; requested?: string; unsupportedReason?: string };
+    canvaskitMode: { mode: 'default' | 'compat'; source: 'default' | 'storage' | 'url'; requested?: string; unsupportedReason?: string };
+    canvaskitSurface: { preference: 'auto' | 'webgpu' | 'webgl' | 'software'; requested: string; unsupportedReason?: string };
+    renderProfile: 'fastPreview' | 'screen' | 'print' | 'highQuality';
+  } | null;
+  initialized: boolean;
+  initializationError: string | null;
+  effectiveBackend: 'canvas2d' | 'canvaskit' | null;
+  backendFallbackReason: string | null;
+  /** Added additively to renderer-diagnostics-v1; older Studio builds may omit it. */
+  selection?: RendererSelectionV1 | null;
+  page: { index: number; canvaskit: CanvasKitRendererDiagnostics | null };
+}
+
+export interface LoadFileOptions {
+  /** 미저장 변경 확인 없이 문서 교체 */
+  skipUnsavedGuard?: boolean;
+  /**
+   * 로드 후 안내창(HWPX 검증, 로컬 글꼴 감지) 없이 열기.
+   * 임베드 환경에서 안내창의 사용자 선택을 기다리느라 loadFile 응답이
+   * 지연/교착되는 것을 방지한다. 기본값은 true이며, 안내창을 표시하려면
+   * false를 명시한다.
+   */
+  suppressDialogs?: boolean;
+}
+
 export declare class RhwpEditor {
+  private constructor();
   /** HWP 파일을 로드합니다 */
-  loadFile(data: ArrayBuffer | Uint8Array, fileName?: string): Promise<LoadResult>;
+  loadFile(data: ArrayBuffer | Uint8Array, fileName?: string, options?: LoadFileOptions): Promise<LoadResult>;
   /** 현재 문서의 페이지 수를 반환합니다 */
   pageCount(): Promise<number>;
   /** 특정 페이지를 SVG 문자열로 렌더링합니다 */
   getPageSvg(page?: number): Promise<string>;
+  /** 선택된 renderer와 페이지별 readiness 진단을 반환합니다 */
+  getRendererDiagnostics(page?: number): Promise<RendererDiagnosticsV1>;
   /** 현재 문서를 HWP 바이너리로 내보냅니다 */
   exportHwp(): Promise<Uint8Array>;
   /** 현재 문서를 HWPX(ZIP+XML) 바이너리로 내보냅니다 */
   exportHwpx(): Promise<Uint8Array>;
+  /** 현재 문서를 HML(XML) 바이너리로 내보냅니다 */
+  exportHml(): Promise<Uint8Array>;
+  /** 현재 문서의 HML 저장 가능 여부와 blocker를 반환합니다 */
+  getHmlSaveState(): Promise<HmlSaveState>;
   /** HWP 직렬화 + 자기 재로드 검증 메타데이터 (#178) */
   exportHwpVerify(): Promise<HwpVerifyResult>;
+  /**
+   * 내보내기 바이트의 영속화(업로드/핸드오프) 완료를 스튜디오에 통지합니다 (#2660).
+   * dirty 해제 + 자동복구 draft 삭제 완료 후 resolve — resolve 이후 창을 닫아도 안전.
+   * 업로드 실패 시에는 호출하지 마세요(백업 draft 보존).
+   * 스튜디오가 notify-saved-v1 capability를 광고하지 않으면 요청 없이 실패합니다.
+   */
+  notifySaved(fileName?: string): Promise<{ ok: true; wasDirty: boolean }>;
   /** iframe 엘리먼트를 반환합니다 */
   readonly element: HTMLIFrameElement;
   /** 에디터를 제거합니다 */

package/index.js

@@ -9,9 +9,9 @@
  * 본 제품은 한글과컴퓨터의 한글 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.
  */
 
-const DEFAULT_STUDIO_URL = 'https://edwardkim.github.io/rhwp/';
+import { EditorTransport } from './transport.js';
 
-let requestId = 0;
+const DEFAULT_STUDIO_URL = 'https://edwardkim.github.io/rhwp/';
 
 /**
  * HWP 에디터를 생성하여 지정된 컨테이너에 마운트합니다.
@@ -36,7 +36,15 @@ export async function createEditor(container, options = {}) {
     throw new Error(`Container not found: ${container}`);
   }
 
-  const studioUrl = options.studioUrl || DEFAULT_STUDIO_URL;
+  let studioUrl = options.studioUrl || DEFAULT_STUDIO_URL;
+  if (options.renderer !== undefined) {
+    if (!['auto', 'canvas2d', 'canvaskit'].includes(options.renderer)) {
+      throw new TypeError(`Unsupported renderer: ${options.renderer}`);
+    }
+    const resolvedStudioUrl = new URL(studioUrl, document.baseURI);
+    resolvedStudioUrl.searchParams.set('renderer', options.renderer);
+    studioUrl = resolvedStudioUrl.href;
+  }
 
   // iframe 생성
   const iframe = document.createElement('iframe');
@@ -53,9 +61,21 @@ export async function createEditor(container, options = {}) {
   });
 
   // WASM 초기화 대기 (ready 메서드로 확인)
-  const editor = new RhwpEditor(iframe);
-  await editor._waitReady();
-  return editor;
+  let transport;
+  try {
+    transport = new EditorTransport(iframe, studioUrl, {
+      requestTimeoutMs: options.requestTimeoutMs,
+      handshakeTimeoutMs: options.handshakeTimeoutMs,
+    });
+    await transport.connect();
+    const editor = new RhwpEditor(iframe, transport);
+    await editor._waitReady();
+    return editor;
+  } catch (error) {
+    transport?.destroy();
+    iframe.remove();
+    throw error;
+  }
 }
 
 /**
@@ -63,25 +83,10 @@ export async function createEditor(container, options = {}) {
  *
  * iframe 내부의 rhwp-studio와 postMessage로 통신합니다.
  */
-class RhwpEditor {
-  constructor(iframe) {
+export class RhwpEditor {
+  constructor(iframe, transport) {
     this._iframe = iframe;
-    this._pending = new Map();
-
-    // 응답 수신 리스너
-    window.addEventListener('message', (e) => {
-      if (e.data?.type === 'rhwp-response' && e.data.id != null) {
-        const resolver = this._pending.get(e.data.id);
-        if (resolver) {
-          this._pending.delete(e.data.id);
-          if (e.data.error) {
-            resolver.reject(new Error(e.data.error));
-          } else {
-            resolver.resolve(e.data.result);
-          }
-        }
-      }
-    });
+    this._transport = transport;
   }
 
   /**
@@ -89,21 +94,7 @@ class RhwpEditor {
    * @internal
    */
   _request(method, params = {}) {
-    return new Promise((resolve, reject) => {
-      const id = ++requestId;
-      this._pending.set(id, { resolve, reject });
-      this._iframe.contentWindow.postMessage(
-        { type: 'rhwp-request', id, method, params },
-        '*'
-      );
-      // 10초 타임아웃
-      setTimeout(() => {
-        if (this._pending.has(id)) {
-          this._pending.delete(id);
-          reject(new Error(`Request timeout: ${method}`));
-        }
-      }, 10000);
-    });
+    return this._transport.request(method, params);
   }
 
   /** WASM 초기화 완료 대기 @internal */
@@ -125,6 +116,11 @@ class RhwpEditor {
    *
    * @param data - HWP 파일의 ArrayBuffer 또는 Uint8Array
    * @param fileName - 파일 이름 (선택)
+   * @param options - 로드 옵션 (선택)
+   * @param options.skipUnsavedGuard - 미저장 변경 확인 없이 문서 교체
+   * @param options.suppressDialogs - 로드 후 안내창(HWPX 검증, 로컬 글꼴 감지) 없이 열기.
+   *   임베드 환경에서 안내창의 사용자 선택을 기다리느라 loadFile 응답이 지연/교착되는
+   *   것을 방지한다. 검증 경고는 '그대로 열기'로 처리되고, 글꼴은 웹 대체 글꼴로 표시된다.
    * @returns { pageCount: number }
    *
    * @example
@@ -135,9 +131,13 @@ class RhwpEditor {
    * console.log(`${result.pageCount}페이지`);
    * ```
    */
-  async loadFile(data, fileName = 'document.hwp') {
-    const bytes = data instanceof ArrayBuffer ? Array.from(new Uint8Array(data)) : Array.from(data);
-    return this._request('loadFile', { data: bytes, fileName });
+  async loadFile(data, fileName = 'document.hwp', options = {}) {
+    return this._request('loadFile', {
+      data,
+      fileName,
+      skipUnsavedGuard: options.skipUnsavedGuard === true,
+      suppressDialogs: options.suppressDialogs === undefined || options.suppressDialogs === true,
+    });
   }
 
   /**
@@ -157,6 +157,24 @@ class RhwpEditor {
     return this._request('getPageSvg', { page });
   }
 
+  /**
+   * 선택된 renderer와 페이지별 CanvasKit readiness 진단을 반환합니다.
+   * @param page - 0부터 시작하는 페이지 번호
+   */
+  async getRendererDiagnostics(page = 0) {
+    if (!Number.isSafeInteger(page) || page < 0) {
+      throw new TypeError('page must be a non-negative safe integer');
+    }
+    if (!this._transport.supports('renderer-diagnostics-v1')) {
+      throw new Error('Renderer diagnostics v1 is not supported by this Studio');
+    }
+    const result = await this._request('getRendererDiagnostics', { page });
+    if (result?.schemaVersion !== 1 || result?.page?.index !== page) {
+      throw new Error('Studio returned invalid renderer diagnostics v1');
+    }
+    return result;
+  }
+
   /**
    * 현재 문서를 HWP 바이너리로 내보냅니다.
    * @returns {Promise<Uint8Array>} HWP 파일 bytes
@@ -175,6 +193,17 @@ class RhwpEditor {
     return result instanceof Uint8Array ? result : new Uint8Array(result || []);
   }
 
+  /** 현재 문서를 HML(XML) 바이너리로 내보냅니다. */
+  async exportHml() {
+    const result = await this._request('exportHml');
+    return result instanceof Uint8Array ? result : new Uint8Array(result || []);
+  }
+
+  /** 현재 문서의 HML 저장 가능 여부와 blocker를 반환합니다. */
+  async getHmlSaveState() {
+    return this._request('getHmlSaveState');
+  }
+
   /**
    * HWP 직렬화 + 자기 재로드 검증 메타데이터를 반환합니다 (#178).
    *
@@ -186,6 +215,27 @@ class RhwpEditor {
     return this._request('exportHwpVerify');
   }
 
+  /**
+   * 내보내기 바이트의 영속화(업로드/핸드오프) 완료를 스튜디오에 통지합니다.
+   *
+   * dirty 상태를 해제하고 자동복구 draft의 IndexedDB 삭제 "완료"까지 기다린 뒤
+   * resolve합니다 — resolve 이후 창을 닫아도 안전합니다. 업로드 실패 시에는
+   * 호출하지 마세요(백업 draft가 보존되어야 합니다).
+   *
+   * 스튜디오가 `notify-saved-v1` capability를 광고하지 않으면(구버전 또는
+   * legacy 폴백 연결) 요청을 보내지 않고 명시적으로 실패합니다.
+   *
+   * @param fileName - 호스트가 저장에 사용한 파일 이름 (선택)
+   * @returns {Promise<{ ok: true, wasDirty: boolean }>}
+   */
+  async notifySaved(fileName) {
+    if (!this._transport.supports('notify-saved-v1')) {
+      throw new Error('notifySaved is not supported by this Studio');
+    }
+    const params = typeof fileName === 'string' && fileName.length > 0 ? { fileName } : {};
+    return this._request('notifySaved', params);
+  }
+
   /**
    * iframe 엘리먼트를 반환합니다.
    */
@@ -197,7 +247,7 @@ class RhwpEditor {
    * 에디터를 제거합니다.
    */
   destroy() {
+    this._transport.destroy();
     this._iframe.remove();
-    this._pending.clear();
   }
 }

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@rhwp/editor",
-  "version": "0.7.18",
+  "version": "0.8.0",
   "description": "HWP 에디터 웹 컴포넌트 — iframe 기반 임베드",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "transport.js",
+    "README.md"
   ],
   "keywords": [
     "hwp",
@@ -28,6 +33,10 @@
   "bugs": {
     "url": "https://github.com/edwardkim/rhwp/issues"
   },
+  "funding": "https://github.com/sponsors/edwardkim",
   "license": "MIT",
-  "author": "Edward Kim"
+  "author": "Edward Kim",
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }

package/transport.js

@@ -0,0 +1,239 @@
+const PROTOCOL_VERSION = 1;
+const CAPABILITIES = [
+  'transferable-array-buffer',
+  'hml-export',
+  'renderer-diagnostics-v1',
+  'notify-saved-v1',
+];
+const LONG_RUNNING_METHODS = new Set([
+  'loadFile', 'exportHwp', 'exportHwpVerify', 'exportHwpx', 'exportHml',
+]);
+
+export function requestTimeoutFor(method, configuredTimeout) {
+  if (configuredTimeout != null) return configuredTimeout;
+  return LONG_RUNNING_METHODS.has(method) ? 60000 : 10000;
+}
+
+function sessionId() {
+  const secureRandom = globalThis.crypto;
+  if (typeof secureRandom?.randomUUID === 'function') return secureRandom.randomUUID();
+  if (typeof secureRandom?.getRandomValues !== 'function') {
+    throw new Error('Secure random generation is unavailable');
+  }
+  const bytes = secureRandom.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function copiedBinary(value) {
+  if (value instanceof ArrayBuffer) return new Uint8Array(value).slice();
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
+  }
+  return null;
+}
+
+function prepareParams(params) {
+  const data = copiedBinary(params?.data);
+  if (!data) return { params, transfer: [] };
+  return { params: { ...params, data }, transfer: [data.buffer] };
+}
+
+function isResponseEnvelope(message, legacy, sessionId) {
+  if (message?.type !== 'rhwp-response' || !Number.isSafeInteger(message.id)) return false;
+  if (legacy) return true;
+  if (message.version !== PROTOCOL_VERSION || message.sessionId !== sessionId) return false;
+  const hasResult = Object.prototype.hasOwnProperty.call(message, 'result');
+  const hasError = Object.prototype.hasOwnProperty.call(message, 'error');
+  if (hasResult === hasError) return false;
+  return !hasError || (typeof message.error?.code === 'string'
+    && typeof message.error?.message === 'string');
+}
+
+export class EditorTransport {
+  constructor(iframe, studioUrl, options = {}) {
+    this._iframe = iframe;
+    const targetUrl = new URL(studioUrl, globalThis.location?.href);
+    if (targetUrl.protocol !== 'http:' && targetUrl.protocol !== 'https:') {
+      throw new Error('studioUrl must use HTTP(S)');
+    }
+    this._targetOrigin = targetUrl.origin;
+    this._window = options.window || window;
+    this._requestTimeoutMs = options.requestTimeoutMs;
+    this._handshakeTimeoutMs = options.handshakeTimeoutMs ?? 1000;
+    this._sessionId = sessionId();
+    this._nextId = 0;
+    this._pending = new Map();
+    this._port = null;
+    this._peerCapabilities = new Set();
+    this._legacy = false;
+    this._destroyed = false;
+    this._onLegacyMessage = (event) => this._handleLegacyMessage(event);
+  }
+
+  connect() {
+    if (this._destroyed) return Promise.reject(new Error('Editor destroyed'));
+    const channel = new MessageChannel();
+    this._port = channel.port1;
+    this._port.onmessage = (event) => this._handlePortMessage(event.data);
+    this._port.start();
+    return new Promise((resolve, reject) => {
+      this._connectResolve = resolve;
+      this._connectReject = reject;
+      this._connectTimer = setTimeout(() => this._useLegacy(), this._handshakeTimeoutMs);
+      this._iframe.contentWindow.postMessage({
+        type: 'rhwp-connect', version: PROTOCOL_VERSION, sessionId: this._sessionId,
+        capabilities: CAPABILITIES,
+      }, this._targetOrigin, [channel.port2]);
+    });
+  }
+
+  request(method, params = {}) {
+    if (this._destroyed) return Promise.reject(new Error('Editor destroyed'));
+    const id = ++this._nextId;
+    const prepared = prepareParams(params);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new Error(`Request timeout: ${method}`));
+      }, requestTimeoutFor(method, this._requestTimeoutMs));
+      this._pending.set(id, { resolve, reject, timeout });
+      try {
+        this._send({
+          type: 'rhwp-request', version: PROTOCOL_VERSION,
+          sessionId: this._sessionId, id, method, params: prepared.params,
+        }, prepared.transfer);
+      } catch (error) {
+        clearTimeout(timeout);
+        this._pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  supports(capability) {
+    return this._peerCapabilities.has(capability);
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    clearTimeout(this._connectTimer);
+    this._port && (this._port.onmessage = null);
+    this._port?.close();
+    this._rejectConnect(new Error('Editor destroyed'));
+    this._window.removeEventListener('message', this._onLegacyMessage);
+    for (const pending of this._pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error('Editor destroyed'));
+    }
+    this._pending.clear();
+  }
+
+  _send(message, transfer) {
+    if (this._legacy) {
+      const { version, sessionId: ignored, ...legacyMessage } = message;
+      this._iframe.contentWindow.postMessage(legacyMessage, this._targetOrigin, transfer);
+      return;
+    }
+    this._port.postMessage(message, transfer);
+  }
+
+  _handlePortMessage(message) {
+    if (message?.type === 'rhwp-connected'
+        && message.version === PROTOCOL_VERSION
+        && message.sessionId === this._sessionId
+        && message.capabilities?.includes('transferable-array-buffer')) {
+      clearTimeout(this._connectTimer);
+      this._peerCapabilities = new Set(message.capabilities);
+      const resolve = this._connectResolve;
+      this._connectResolve = null;
+      this._connectReject = null;
+      resolve?.();
+      return;
+    }
+    if (message?.type === 'rhwp-connect-error'
+        && message.version === PROTOCOL_VERSION
+        && message.sessionId === this._sessionId
+        && typeof message.error?.message === 'string') {
+      const error = new Error(message.error.message);
+      error.code = message.error.code;
+      error.supportedVersions = message.error.supportedVersions;
+      this._rejectConnect(error);
+      return;
+    }
+    this._handleResponse(message);
+  }
+
+  _handleLegacyMessage(event) {
+    if (event.source !== this._iframe.contentWindow || event.origin !== this._targetOrigin) return;
+    this._handleResponse(event.data, true);
+  }
+
+  _handleResponse(message, legacy = false) {
+    if (legacy) {
+      if (!isResponseEnvelope(message, true, this._sessionId)) return;
+    } else if (message?.type !== 'rhwp-response'
+        || !Number.isSafeInteger(message.id)
+        || message.sessionId !== this._sessionId) {
+      return;
+    }
+    const pending = this._pending.get(message.id);
+    if (!pending) return;
+    if (!legacy && Number.isSafeInteger(message.version)
+        && message.version !== PROTOCOL_VERSION) {
+      this._rejectPendingResponse(message.id, pending, 'UNSUPPORTED_VERSION',
+        `Unsupported embed protocol version: ${message.version}`, [PROTOCOL_VERSION]);
+      return;
+    }
+    if (!isResponseEnvelope(message, legacy, this._sessionId)) {
+      setTimeout(() => this._rejectPendingResponse(
+        message.id, pending, 'INVALID_RESPONSE', 'Invalid response envelope',
+      ), 0);
+      return;
+    }
+    this._pending.delete(message.id);
+    clearTimeout(pending.timeout);
+    if (message.error) {
+      const error = new Error(message.error.message || message.error);
+      if (message.error.code) error.code = message.error.code;
+      pending.reject(error);
+    }
+    else pending.resolve(message.result);
+  }
+
+  _rejectPendingResponse(id, pending, code, message, supportedVersions) {
+    if (this._pending.get(id) !== pending) return;
+    this._pending.delete(id);
+    clearTimeout(pending.timeout);
+    const error = new Error(message);
+    error.code = code;
+    if (supportedVersions) error.supportedVersions = supportedVersions;
+    pending.reject(error);
+  }
+
+  _rejectConnect(error) {
+    if (!this._connectReject) return;
+    clearTimeout(this._connectTimer);
+    this._port && (this._port.onmessage = null);
+    this._port?.close();
+    this._port = null;
+    const reject = this._connectReject;
+    this._connectResolve = null;
+    this._connectReject = null;
+    reject(error);
+  }
+
+  _useLegacy() {
+    if (this._destroyed || !this._connectResolve) return;
+    this._port && (this._port.onmessage = null);
+    this._port?.close();
+    this._port = null;
+    this._legacy = true;
+    this._peerCapabilities.clear();
+    this._window.addEventListener('message', this._onLegacyMessage);
+    const resolve = this._connectResolve;
+    this._connectResolve = null;
+    this._connectReject = null;
+    resolve();
+  }
+}