@3rtools/tyts-embed 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @3rtools/tyts-embed
+
+Host SDK for embedding the [ТИЦЬ (Tyts)](https://github.com/alexkolodko/tyts) annotated-collage
+editor in an iframe and driving it over postMessage. Zero dependencies, one file.
+
+Host SDK для вбудовування редактора ТИЦЬ в iframe і керування ним через postMessage.
+Без залежностей, один файл.
+
+## Встановлення
+
+```bash
+npm i @3rtools/tyts-embed
+```
+
+```js
+import { TytsEmbed } from '@3rtools/tyts-embed';
+```
+
+Або без збирача — класичний скрипт, який ставить `window.TytsEmbed`:
+
+```html
+<script src="https://unpkg.com/@3rtools/tyts-embed/dist/tyts-embed.js"></script>
+```
+
+Сам редактор — окрема статична збірка (`npm run build:embed` у репозиторії ТИЦЬ → `build/embed/`),
+яку ви викладаєте на свій хостинг. SDK і збірка мають однакову версію протоколу (`TytsEmbed.PROTOCOL`).
+
+## Використання
+
+```js
+const editor = TytsEmbed.create({
+  container: '#tyts',                 // контейнер має мати висоту або min-height
+  src: 'https://app.example/tyts/embed/',
+  onChange(doc, { dirty }) { saveButton.disabled = !dirty; },
+  onError(err) { console.warn(err.code, err.message); },
+});
+
+await editor.init({ token: 'change-me' });          // токен задається при збірці редактора
+await editor.loadImage(await TytsEmbed.fileToDataUrl(file));
+
+const doc = await editor.getDocument();             // JSON для збереження у себе
+const { dataUrl } = await editor.export('png', 2);  // 'png' | 'jpeg' | 'pdf'
+await editor.markSaved();                           // далі onChange дає dirty:false
+await editor.loadDocument(doc);                     // відновити
+```
+
+Усі методи повертають проміси, які резолвляться відповіддю редактора або відхиляються
+обʼєктом `{ code, message }`: `timeout`, `not_initialized`, `origin_denied`, `invalid_token`,
+`protocol_mismatch`, `invalid_document`, `export_failed`, `destroyed`.
+
+## Документація
+
+- Повний довідник методів, подій, помилок, протоколу і формату документа:
+  [docs/API.md](https://github.com/alexkolodko/tyts/blob/main/docs/API.md)
+- Встановлення й викладання збірки редактора, безпека (`VITE_TYTS_EMBED_ALLOWED_ORIGINS`,
+  `VITE_TYTS_EMBED_TOKEN`): [docs/embed-api.md](https://github.com/alexkolodko/tyts/blob/main/docs/embed-api.md)
+- Інтерактивний довідник із живими запитами — `api.html` у збірці редактора.
+
+Типи (`TytsDocument`, `TytsPin`, `TytsAnchor`, `TytsEmbedInstance`) — в `index.d.ts`.

package/dist/tyts-embed.js

@@ -0,0 +1,242 @@
+/* @3rtools/tyts-embed 0.1.0 — Host SDK для вбудовування редактора ТИЦЬ (Tyts) в iframe через postMessage */
+(function () {
+'use strict';
+/**
+ * Tyts embed host SDK — load the editor in an iframe and control it via postMessage.
+ *
+ * Every request resolves when the editor answers (`tyts:initialized`, `tyts:done`,
+ * `tyts:document`, `tyts:exportResult`) or rejects with `{ code, message }`.
+ * Security (allowed origins, token) is configured when the editor bundle is built,
+ * not by the host page.
+ *
+ * This file is the single source: `build.mjs` emits it as ESM (`tyts-embed.mjs`)
+ * and as a classic script that sets `window.TytsEmbed` (`tyts-embed.js`).
+ *
+ * @example
+ * const editor = TytsEmbed.create({ container: '#host', src: '/tyts/embed/', onChange(doc, meta) { ... } });
+ * await editor.init({ token: 'secret' });
+ * await editor.loadImage(await TytsEmbed.fileToDataUrl(file));
+ * const png = await editor.export('png');
+ * await editor.markSaved();
+ */
+
+var PROTOCOL = 1;
+var VERSION = '0.1.0';
+var DEFAULT_TIMEOUT_MS = 60000;
+
+function createRequestId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return 'req-' + Date.now() + '-' + Math.random().toString(16).slice(2);
+}
+
+function resolveOrigin(src) {
+  try {
+    return new URL(src, window.location.href).origin;
+  } catch {
+    return window.location.origin;
+  }
+}
+
+function TytsEmbedInstance(options) {
+  this._options = options;
+  this._iframe = null;
+  this._targetOrigin = '*';
+  this._ready = false;
+  this._initialized = false;
+  this._queuedUntilReady = [];
+  this._requests = new Map();
+  this._onChange = options.onChange || null;
+  this._onReady = options.onReady || null;
+  this._onError = options.onError || null;
+  this._messageHandler = this._handleMessage.bind(this);
+}
+
+TytsEmbedInstance.prototype._handleMessage = function (event) {
+  if (!this._iframe || event.source !== this._iframe.contentWindow) return;
+  if (this._targetOrigin !== '*' && event.origin !== this._targetOrigin) return;
+
+  var data = event.data;
+  if (!data || typeof data.type !== 'string' || data.type.indexOf('tyts:') !== 0) return;
+
+  if (data.type === 'tyts:ready') {
+    if (this._ready) return;
+    this._ready = true;
+    var queued = this._queuedUntilReady;
+    this._queuedUntilReady = [];
+    for (var i = 0; i < queued.length; i++) this._post(queued[i]);
+    if (this._onReady) this._onReady();
+    return;
+  }
+
+  if (data.type === 'tyts:change') {
+    if (this._onChange) this._onChange(data.document, { dirty: !!data.dirty });
+    return;
+  }
+
+  var pending = data.requestId ? this._requests.get(data.requestId) : null;
+
+  if (data.type === 'tyts:error') {
+    var error = { code: data.error.code, message: data.error.message };
+    if (pending) {
+      this._requests.delete(data.requestId);
+      pending.reject(error);
+    } else if (this._onError) {
+      this._onError(error);
+    }
+    return;
+  }
+
+  if (!pending) return;
+  this._requests.delete(data.requestId);
+
+  if (data.type === 'tyts:initialized') {
+    this._initialized = true;
+    pending.resolve();
+  } else if (data.type === 'tyts:done') {
+    pending.resolve();
+  } else if (data.type === 'tyts:document') {
+    pending.resolve(data.document);
+  } else if (data.type === 'tyts:exportResult') {
+    pending.resolve({ format: data.format, mime: data.mime, dataUrl: data.dataUrl });
+  }
+};
+
+TytsEmbedInstance.prototype._post = function (message) {
+  if (!this._iframe || !this._iframe.contentWindow) return;
+  this._iframe.contentWindow.postMessage(message, this._targetOrigin);
+};
+
+/** Send a message with a fresh requestId and resolve on the matching reply. */
+TytsEmbedInstance.prototype._request = function (message, timeoutMs) {
+  var self = this;
+  var requestId = createRequestId();
+  var payload = Object.assign({}, message, { requestId: requestId });
+  return new Promise(function (resolve, reject) {
+    var timer = setTimeout(function () {
+      self._requests.delete(requestId);
+      reject({ code: 'timeout', message: 'Request timed out: ' + message.type });
+    }, timeoutMs || DEFAULT_TIMEOUT_MS);
+    self._requests.set(requestId, {
+      resolve: function (value) {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      reject: function (err) {
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+    if (self._ready) self._post(payload);
+    else self._queuedUntilReady.push(payload);
+  });
+};
+
+TytsEmbedInstance.prototype.mount = function () {
+  var container = this._options.container;
+  var el = typeof container === 'string' ? window.document.querySelector(container) : container;
+  if (!el) throw new Error('TytsEmbed: container not found');
+
+  var src = this._options.src || './';
+  this._targetOrigin = this._options.origin || resolveOrigin(src);
+
+  var iframe = window.document.createElement('iframe');
+  iframe.src = src;
+  iframe.title = this._options.title || 'Tyts Editor';
+  iframe.style.border = '0';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  iframe.style.display = 'block';
+  iframe.setAttribute('allow', 'clipboard-read; clipboard-write');
+  el.innerHTML = '';
+  el.appendChild(iframe);
+  this._iframe = iframe;
+
+  window.addEventListener('message', this._messageHandler);
+  return this;
+};
+
+/**
+ * Open the session. Resolves once the editor confirms (`tyts:initialized`);
+ * the optional `document` is loaded before that.
+ * @param {{ token?: string, document?: object, timeoutMs?: number }} [config]
+ */
+TytsEmbedInstance.prototype.init = function (config) {
+  config = config || {};
+  return this._request({
+    type: 'tyts:init',
+    protocol: PROTOCOL,
+    token: config.token,
+    document: config.document,
+  }, config.timeoutMs);
+};
+
+TytsEmbedInstance.prototype.loadDocument = function (document) {
+  return this._request({ type: 'tyts:loadDocument', document: document });
+};
+
+TytsEmbedInstance.prototype.loadImage = function (dataUrl) {
+  return this._request({ type: 'tyts:loadImage', dataUrl: dataUrl });
+};
+
+TytsEmbedInstance.prototype.getDocument = function () {
+  return this._request({ type: 'tyts:getDocument' }, 30000);
+};
+
+TytsEmbedInstance.prototype.export = function (format, scale) {
+  return this._request({
+    type: 'tyts:export',
+    format: format || 'png',
+    scale: scale == null ? 1 : scale,
+  }, 120000);
+};
+
+/** Tell the editor the current state is persisted: the next `onChange` reports `dirty: false`. */
+TytsEmbedInstance.prototype.markSaved = function () {
+  return this._request({ type: 'tyts:markSaved' });
+};
+
+TytsEmbedInstance.prototype.reset = function () {
+  return this._request({ type: 'tyts:reset' });
+};
+
+TytsEmbedInstance.prototype.destroy = function () {
+  window.removeEventListener('message', this._messageHandler);
+  this._requests.forEach(function (pending) {
+    pending.reject({ code: 'destroyed', message: 'Embed instance destroyed' });
+  });
+  this._requests.clear();
+  this._queuedUntilReady = [];
+  if (this._iframe && this._iframe.parentNode) {
+    this._iframe.parentNode.removeChild(this._iframe);
+  }
+  this._iframe = null;
+  this._ready = false;
+  this._initialized = false;
+};
+
+function create(options) {
+  var instance = new TytsEmbedInstance(options || {});
+  return instance.mount();
+}
+
+function fileToDataUrl(file) {
+  return new Promise(function (resolve, reject) {
+    var reader = new FileReader();
+    reader.onload = function () {
+      resolve(typeof reader.result === 'string' ? reader.result : '');
+    };
+    reader.onerror = function () { reject(new Error('Failed to read file')); };
+    reader.readAsDataURL(file);
+  });
+}
+
+var TytsEmbed = {
+  create: create,
+  fileToDataUrl: fileToDataUrl,
+  PROTOCOL: PROTOCOL,
+  VERSION: VERSION,
+};
+
+
+window.TytsEmbed = TytsEmbed;
+})();

package/dist/tyts-embed.mjs

@@ -0,0 +1,237 @@
+/**
+ * Tyts embed host SDK — load the editor in an iframe and control it via postMessage.
+ *
+ * Every request resolves when the editor answers (`tyts:initialized`, `tyts:done`,
+ * `tyts:document`, `tyts:exportResult`) or rejects with `{ code, message }`.
+ * Security (allowed origins, token) is configured when the editor bundle is built,
+ * not by the host page.
+ *
+ * This file is the single source: `build.mjs` emits it as ESM (`tyts-embed.mjs`)
+ * and as a classic script that sets `window.TytsEmbed` (`tyts-embed.js`).
+ *
+ * @example
+ * const editor = TytsEmbed.create({ container: '#host', src: '/tyts/embed/', onChange(doc, meta) { ... } });
+ * await editor.init({ token: 'secret' });
+ * await editor.loadImage(await TytsEmbed.fileToDataUrl(file));
+ * const png = await editor.export('png');
+ * await editor.markSaved();
+ */
+
+var PROTOCOL = 1;
+var VERSION = '0.1.0';
+var DEFAULT_TIMEOUT_MS = 60000;
+
+function createRequestId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return 'req-' + Date.now() + '-' + Math.random().toString(16).slice(2);
+}
+
+function resolveOrigin(src) {
+  try {
+    return new URL(src, window.location.href).origin;
+  } catch {
+    return window.location.origin;
+  }
+}
+
+function TytsEmbedInstance(options) {
+  this._options = options;
+  this._iframe = null;
+  this._targetOrigin = '*';
+  this._ready = false;
+  this._initialized = false;
+  this._queuedUntilReady = [];
+  this._requests = new Map();
+  this._onChange = options.onChange || null;
+  this._onReady = options.onReady || null;
+  this._onError = options.onError || null;
+  this._messageHandler = this._handleMessage.bind(this);
+}
+
+TytsEmbedInstance.prototype._handleMessage = function (event) {
+  if (!this._iframe || event.source !== this._iframe.contentWindow) return;
+  if (this._targetOrigin !== '*' && event.origin !== this._targetOrigin) return;
+
+  var data = event.data;
+  if (!data || typeof data.type !== 'string' || data.type.indexOf('tyts:') !== 0) return;
+
+  if (data.type === 'tyts:ready') {
+    if (this._ready) return;
+    this._ready = true;
+    var queued = this._queuedUntilReady;
+    this._queuedUntilReady = [];
+    for (var i = 0; i < queued.length; i++) this._post(queued[i]);
+    if (this._onReady) this._onReady();
+    return;
+  }
+
+  if (data.type === 'tyts:change') {
+    if (this._onChange) this._onChange(data.document, { dirty: !!data.dirty });
+    return;
+  }
+
+  var pending = data.requestId ? this._requests.get(data.requestId) : null;
+
+  if (data.type === 'tyts:error') {
+    var error = { code: data.error.code, message: data.error.message };
+    if (pending) {
+      this._requests.delete(data.requestId);
+      pending.reject(error);
+    } else if (this._onError) {
+      this._onError(error);
+    }
+    return;
+  }
+
+  if (!pending) return;
+  this._requests.delete(data.requestId);
+
+  if (data.type === 'tyts:initialized') {
+    this._initialized = true;
+    pending.resolve();
+  } else if (data.type === 'tyts:done') {
+    pending.resolve();
+  } else if (data.type === 'tyts:document') {
+    pending.resolve(data.document);
+  } else if (data.type === 'tyts:exportResult') {
+    pending.resolve({ format: data.format, mime: data.mime, dataUrl: data.dataUrl });
+  }
+};
+
+TytsEmbedInstance.prototype._post = function (message) {
+  if (!this._iframe || !this._iframe.contentWindow) return;
+  this._iframe.contentWindow.postMessage(message, this._targetOrigin);
+};
+
+/** Send a message with a fresh requestId and resolve on the matching reply. */
+TytsEmbedInstance.prototype._request = function (message, timeoutMs) {
+  var self = this;
+  var requestId = createRequestId();
+  var payload = Object.assign({}, message, { requestId: requestId });
+  return new Promise(function (resolve, reject) {
+    var timer = setTimeout(function () {
+      self._requests.delete(requestId);
+      reject({ code: 'timeout', message: 'Request timed out: ' + message.type });
+    }, timeoutMs || DEFAULT_TIMEOUT_MS);
+    self._requests.set(requestId, {
+      resolve: function (value) {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      reject: function (err) {
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+    if (self._ready) self._post(payload);
+    else self._queuedUntilReady.push(payload);
+  });
+};
+
+TytsEmbedInstance.prototype.mount = function () {
+  var container = this._options.container;
+  var el = typeof container === 'string' ? window.document.querySelector(container) : container;
+  if (!el) throw new Error('TytsEmbed: container not found');
+
+  var src = this._options.src || './';
+  this._targetOrigin = this._options.origin || resolveOrigin(src);
+
+  var iframe = window.document.createElement('iframe');
+  iframe.src = src;
+  iframe.title = this._options.title || 'Tyts Editor';
+  iframe.style.border = '0';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  iframe.style.display = 'block';
+  iframe.setAttribute('allow', 'clipboard-read; clipboard-write');
+  el.innerHTML = '';
+  el.appendChild(iframe);
+  this._iframe = iframe;
+
+  window.addEventListener('message', this._messageHandler);
+  return this;
+};
+
+/**
+ * Open the session. Resolves once the editor confirms (`tyts:initialized`);
+ * the optional `document` is loaded before that.
+ * @param {{ token?: string, document?: object, timeoutMs?: number }} [config]
+ */
+TytsEmbedInstance.prototype.init = function (config) {
+  config = config || {};
+  return this._request({
+    type: 'tyts:init',
+    protocol: PROTOCOL,
+    token: config.token,
+    document: config.document,
+  }, config.timeoutMs);
+};
+
+TytsEmbedInstance.prototype.loadDocument = function (document) {
+  return this._request({ type: 'tyts:loadDocument', document: document });
+};
+
+TytsEmbedInstance.prototype.loadImage = function (dataUrl) {
+  return this._request({ type: 'tyts:loadImage', dataUrl: dataUrl });
+};
+
+TytsEmbedInstance.prototype.getDocument = function () {
+  return this._request({ type: 'tyts:getDocument' }, 30000);
+};
+
+TytsEmbedInstance.prototype.export = function (format, scale) {
+  return this._request({
+    type: 'tyts:export',
+    format: format || 'png',
+    scale: scale == null ? 1 : scale,
+  }, 120000);
+};
+
+/** Tell the editor the current state is persisted: the next `onChange` reports `dirty: false`. */
+TytsEmbedInstance.prototype.markSaved = function () {
+  return this._request({ type: 'tyts:markSaved' });
+};
+
+TytsEmbedInstance.prototype.reset = function () {
+  return this._request({ type: 'tyts:reset' });
+};
+
+TytsEmbedInstance.prototype.destroy = function () {
+  window.removeEventListener('message', this._messageHandler);
+  this._requests.forEach(function (pending) {
+    pending.reject({ code: 'destroyed', message: 'Embed instance destroyed' });
+  });
+  this._requests.clear();
+  this._queuedUntilReady = [];
+  if (this._iframe && this._iframe.parentNode) {
+    this._iframe.parentNode.removeChild(this._iframe);
+  }
+  this._iframe = null;
+  this._ready = false;
+  this._initialized = false;
+};
+
+function create(options) {
+  var instance = new TytsEmbedInstance(options || {});
+  return instance.mount();
+}
+
+function fileToDataUrl(file) {
+  return new Promise(function (resolve, reject) {
+    var reader = new FileReader();
+    reader.onload = function () {
+      resolve(typeof reader.result === 'string' ? reader.result : '');
+    };
+    reader.onerror = function () { reject(new Error('Failed to read file')); };
+    reader.readAsDataURL(file);
+  });
+}
+
+export const TytsEmbed = {
+  create: create,
+  fileToDataUrl: fileToDataUrl,
+  PROTOCOL: PROTOCOL,
+  VERSION: VERSION,
+};
+
+export default TytsEmbed;

package/index.d.ts

@@ -0,0 +1,156 @@
+// Типи host SDK @3rtools/tyts-embed. Формат документа дублює src/types.ts і src/embed/document.ts
+// редактора; при зміні схеми оновлювати обидва місця (див. docs/API.md, розділ 7).
+
+export type TytsExportFormat = 'png' | 'jpeg' | 'pdf';
+
+export type TytsAnchor =
+  | { type: 'point'; x: number; y: number }
+  | { type: 'numbering'; start: { x: number; y: number }; end: { x: number; y: number } }
+  | { type: 'standalone'; x: number; y: number }
+  | { type: 'polygon'; points: Array<{ x: number; y: number }>; rotation?: number }
+  | { type: 'polyline'; points: Array<{ x: number; y: number }>; rotation?: number }
+  | { type: 'arrow'; start: { x: number; y: number }; end: { x: number; y: number }; control: { x: number; y: number } }
+  | { type: 'rectangle'; x: number; y: number; width: number; height: number; rotation?: number }
+  | { type: 'ellipse'; cx: number; cy: number; rx: number; ry: number; rotation?: number }
+  | { type: 'compass'; cx: number; cy: number; radius: number; rotation?: number }
+  | { type: 'text'; x: number; y: number; width: number; height: number; point?: { x: number; y: number } }
+  | { type: 'image'; x: number; y: number; width: number; height: number; src: string; aspect: number }
+  | { type: 'redact'; x: number; y: number; width: number; height: number; mode: 'blur' | 'pixelate' | 'fill'; strength: number }
+  | { type: 'linked'; pinId: string };
+
+export interface TytsPin {
+  id: string;
+  anchor: TytsAnchor;
+  /** CSS-колір маркера й лінії. */
+  color: string;
+  /** Номер виноски, від 1. */
+  label: number;
+  /** HTML картки (TipTap). Порожній рядок — без тексту. */
+  description: string;
+  descPos: 'above' | 'below';
+  /** data: URL фото в картці або null. */
+  image: string | null;
+  imageAspect: number | null;
+  strokeStyle?: 'solid' | 'dashed';
+  fillStyle?: 'filled' | 'none';
+  strokeWidthScale?: number;
+  leaderPoints?: Array<{ x: number; y: number }>;
+  theme?: 'dark' | 'light';
+  textBold?: boolean;
+  textItalic?: boolean;
+  textUnderline?: boolean;
+  textStrike?: boolean;
+  textFontSize?: number;
+  textColor?: string;
+  textBackgroundColor?: string | null;
+  calloutHidden?: boolean;
+  z?: number;
+}
+
+export interface TytsCardPosition {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface TytsDocument {
+  version: 1;
+  /** data: URL фонового зображення. */
+  backgroundImage: string;
+  imageSize: { w: number; h: number };
+  sourceImageSize: { w: number; h: number } | null;
+  pins: TytsPin[];
+  /** Позиції карток за pin.id; порожній обʼєкт — редактор розкладе сам. */
+  cardPositions: Record<string, TytsCardPosition>;
+  settings?: { fontId?: 'road-ui' | 'uaf-sans'; strokeWidthScale?: number };
+  meta?: { sourceUrl?: string; sourceTitle?: string; capturedAt?: number };
+}
+
+export interface TytsEmbedError {
+  code:
+    | 'timeout'
+    | 'not_initialized'
+    | 'origin_denied'
+    | 'invalid_token'
+    | 'protocol_mismatch'
+    | 'invalid_document'
+    | 'init_failed'
+    | 'export_failed'
+    | 'handler_error'
+    | 'unknown_message'
+    | 'destroyed'
+    | (string & {});
+  message: string;
+}
+
+export interface TytsEmbedOptions {
+  /** Селектор або елемент; вміст очищається. Контейнер має мати висоту або min-height. */
+  container: string | Element;
+  /** URL теки embed-збірки (або її index.html). За замовчуванням `./`. */
+  src?: string;
+  /** Origin бандла для перевірки відповідей; за замовчуванням береться з `src`. */
+  origin?: string;
+  /** Атрибут title iframe. */
+  title?: string;
+  /** Iframe завантажився і слухає (один раз). */
+  onReady?: () => void;
+  /** Стан змінився (після init, з дебаунсом 250 мс, повний документ). */
+  onChange?: (document: TytsDocument, meta: { dirty: boolean }) => void;
+  /** Помилка без requestId. */
+  onError?: (error: TytsEmbedError) => void;
+}
+
+export interface TytsEmbedInitConfig {
+  /** Обовʼязковий, якщо бандл зібрано з VITE_TYTS_EMBED_TOKEN. */
+  token?: string;
+  /** Початковий документ; застосовується до відповіді. */
+  document?: TytsDocument;
+  /** Таймаут очікування, мс (типово 60000). */
+  timeoutMs?: number;
+}
+
+export interface TytsExportResult {
+  format: TytsExportFormat;
+  mime: string;
+  dataUrl: string;
+}
+
+export interface TytsEmbedInstance {
+  /** Відкрити сесію; резолвиться після tyts:initialized. */
+  init(config?: TytsEmbedInitConfig): Promise<void>;
+  /** Нове фонове зображення (data: URL); піни скидаються. */
+  loadImage(dataUrl: string): Promise<void>;
+  /** Відновити документ. Відхиляється з invalid_document, редактор при цьому не змінюється. */
+  loadDocument(document: TytsDocument): Promise<void>;
+  /** Поточний стан або null, якщо зображення немає. */
+  getDocument(): Promise<TytsDocument | null>;
+  /** Рендер колажу. scale — множник роздільної здатності (png/jpeg). */
+  export(format?: TytsExportFormat, scale?: number): Promise<TytsExportResult>;
+  /** Поточний стан вважати збереженим: наступний onChange дає dirty:false. */
+  markSaved(): Promise<void>;
+  /** Порожній редактор. */
+  reset(): Promise<void>;
+  /** Прибрати iframe і слухачі; незавершені запити відхиляються з destroyed. */
+  destroy(): void;
+}
+
+export interface TytsEmbedStatic {
+  create(options: TytsEmbedOptions): TytsEmbedInstance;
+  /** File/Blob → data: URL для loadImage. */
+  fileToDataUrl(file: Blob): Promise<string>;
+  /** Версія postMessage-протоколу; має збігатися з бандлом редактора. */
+  readonly PROTOCOL: 1;
+  /** Версія пакета. */
+  readonly VERSION: string;
+}
+
+export declare const TytsEmbed: TytsEmbedStatic;
+export default TytsEmbed;
+
+declare global {
+  interface Window {
+    /** Доступно після підключення dist/tyts-embed.js як <script>. */
+    TytsEmbed: TytsEmbedStatic;
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@3rtools/tyts-embed",
+  "version": "0.1.0",
+  "description": "Host SDK для вбудовування редактора ТИЦЬ (Tyts) в iframe через postMessage",
+  "keywords": ["tyts", "embed", "iframe", "postmessage", "annotation", "collage"],
+  "homepage": "https://github.com/alexkolodko/tyts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexkolodko/tyts.git",
+    "directory": "packages/embed"
+  },
+  "type": "module",
+  "main": "./dist/tyts-embed.js",
+  "module": "./dist/tyts-embed.mjs",
+  "types": "./index.d.ts",
+  "unpkg": "./dist/tyts-embed.js",
+  "jsdelivr": "./dist/tyts-embed.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/tyts-embed.mjs",
+      "default": "./dist/tyts-embed.js"
+    },
+    "./tyts-embed.js": "./dist/tyts-embed.js",
+    "./tyts-embed.mjs": "./dist/tyts-embed.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "index.d.ts", "README.md"],
+  "sideEffects": ["./dist/tyts-embed.js"],
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}