@rhwp/editor 0.7.19 → 0.8.0

package/README.md

@@ -81,18 +81,34 @@ const editor = await createEditor(document.getElementById('editor'));
 | `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()
 
 현재 문서의 페이지 수를 반환합니다.
@@ -113,6 +129,14 @@ const svg = await editor.getPageSvg(0); // 첫 페이지
 
 선택된 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);
@@ -169,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()
 
 에디터를 제거합니다.
@@ -177,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 점검 등을 콘솔에서 직접 호출할 수 있습니다.

package/index.d.ts

@@ -5,6 +5,8 @@
 export interface EditorOptions {
   /** 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%') */
@@ -68,11 +70,61 @@ export interface CanvasKitRendererDiagnostics {
   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 };
@@ -82,13 +134,27 @@ export interface RendererDiagnosticsV1 {
   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 문자열로 렌더링합니다 */
@@ -105,6 +171,13 @@ export declare class RhwpEditor {
   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

@@ -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');
@@ -108,6 +116,11 @@ export class RhwpEditor {
    *
    * @param data - HWP 파일의 ArrayBuffer 또는 Uint8Array
    * @param fileName - 파일 이름 (선택)
+   * @param options - 로드 옵션 (선택)
+   * @param options.skipUnsavedGuard - 미저장 변경 확인 없이 문서 교체
+   * @param options.suppressDialogs - 로드 후 안내창(HWPX 검증, 로컬 글꼴 감지) 없이 열기.
+   *   임베드 환경에서 안내창의 사용자 선택을 기다리느라 loadFile 응답이 지연/교착되는
+   *   것을 방지한다. 검증 경고는 '그대로 열기'로 처리되고, 글꼴은 웹 대체 글꼴로 표시된다.
    * @returns { pageCount: number }
    *
    * @example
@@ -118,8 +131,13 @@ export class RhwpEditor {
    * console.log(`${result.pageCount}페이지`);
    * ```
    */
-  async loadFile(data, fileName = 'document.hwp') {
-    return this._request('loadFile', { data, 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,
+    });
   }
 
   /**
@@ -197,6 +215,27 @@ export 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 엘리먼트를 반환합니다.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhwp/editor",
-  "version": "0.7.19",
+  "version": "0.8.0",
   "description": "HWP 에디터 웹 컴포넌트 — iframe 기반 임베드",
   "type": "module",
   "main": "index.js",
@@ -11,7 +11,8 @@
   "files": [
     "index.js",
     "index.d.ts",
-    "transport.js"
+    "transport.js",
+    "README.md"
   ],
   "keywords": [
     "hwp",
@@ -32,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

@@ -3,6 +3,7 @@ const CAPABILITIES = [
   'transferable-array-buffer',
   'hml-export',
   'renderer-diagnostics-v1',
+  'notify-saved-v1',
 ];
 const LONG_RUNNING_METHODS = new Set([
   'loadFile', 'exportHwp', 'exportHwpVerify', 'exportHwpx', 'exportHml',