@rhwp/editor 0.7.18 → 0.7.19

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,9 +78,11 @@ 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 높이 |
+| `requestTimeoutMs` | method별 기본값 | 모든 method 제한 시간 override(ms). 일반 10초, load/export 60초 |
+| `handshakeTimeoutMs` | `1000` | v1 협상 후 legacy 전환까지의 제한 시간(ms) |
 
 ### editor.loadFile(data, fileName?)
 
@@ -101,6 +109,16 @@ const count = await editor.pageCount();
 const svg = await editor.getPageSvg(0); // 첫 페이지
 ```
 
+### editor.getRendererDiagnostics(page?)
+
+선택된 renderer와 0부터 시작하는 페이지별 readiness 진단을 반환합니다.
+Studio가 `renderer-diagnostics-v1` capability를 제공하지 않으면 명시적으로 실패합니다.
+
+```javascript
+const diagnostics = await editor.getRendererDiagnostics(0);
+console.log(diagnostics.schemaVersion, diagnostics.effectiveBackend);
+```
+
 ### editor.exportHwp()
 
 현재 편집 중인 문서를 HWP 바이너리로 내보냅니다.
@@ -266,7 +284,9 @@ setInterval(() => {
 
 ### 기본 동작 — 별도 설정 없이 사용 가능
 
-`@rhwp/editor`는 오픈소스 폰트를 내장하고 있어 **별도 폰트 설정 없이 바로 사용**할 수 있습니다.
+`@rhwp/editor`가 기본으로 연결하는 rhwp-studio 배포본은 오픈소스 폰트를 포함하므로
+**별도 폰트 설정 없이 바로 사용**할 수 있습니다. `@rhwp/editor` 패키지 자체에는 폰트 파일이나
+UI runtime dependency가 포함되지 않습니다.
 
 HWP 문서에서 사용된 한컴 전용 폰트(한컴바탕, HY명조 등)는 자동으로 오픈소스 폰트로 폴백됩니다.
 
@@ -290,7 +310,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,16 @@
  */
 
 export interface EditorOptions {
-  /** rhwp-studio URL (기본: https://edwardkim.github.io/rhwp/) */
+  /** rhwp-studio HTTP(S) URL. file:, data:, browser extension 등 opaque origin은 지원하지 않음 */
   studioUrl?: string;
   /** 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,17 +30,79 @@ 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;
+}
+
+export interface RendererDiagnosticsV1 {
+  schemaVersion: 1;
+  request: {
+    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;
+  page: { index: number; canvaskit: CanvasKitRendererDiagnostics | null };
+}
+
 export declare class RhwpEditor {
+  private constructor();
   /** HWP 파일을 로드합니다 */
   loadFile(data: ArrayBuffer | Uint8Array, fileName?: string): 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>;
   /** iframe 엘리먼트를 반환합니다 */

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 에디터를 생성하여 지정된 컨테이너에 마운트합니다.
@@ -53,9 +53,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 +75,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 +86,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 */
@@ -136,8 +119,7 @@ class RhwpEditor {
    * ```
    */
   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 });
+    return this._request('loadFile', { data, fileName });
   }
 
   /**
@@ -157,6 +139,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 +175,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).
    *
@@ -197,7 +208,7 @@ class RhwpEditor {
    * 에디터를 제거합니다.
    */
   destroy() {
+    this._transport.destroy();
     this._iframe.remove();
-    this._pending.clear();
   }
 }

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@rhwp/editor",
-  "version": "0.7.18",
+  "version": "0.7.19",
   "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"
   ],
   "keywords": [
     "hwp",

package/transport.js

@@ -0,0 +1,238 @@
+const PROTOCOL_VERSION = 1;
+const CAPABILITIES = [
+  'transferable-array-buffer',
+  'hml-export',
+  'renderer-diagnostics-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();
+  }
+}