@casualoffice/sheets 0.9.0

package/dist/embed.cjs

@@ -0,0 +1,225 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/embed/index.ts
+var embed_exports = {};
+__export(embed_exports, {
+  EmbedTransport: () => EmbedTransport,
+  isCasualEnvelope: () => isCasualEnvelope
+});
+module.exports = __toCommonJS(embed_exports);
+
+// src/embed/protocol.ts
+function isCasualEnvelope(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.type === "string" && v.type.startsWith("casual.") && (v.app === "docs" || v.app === "sheet") && v.v === 1 && "data" in v;
+}
+
+// src/embed/EmbedTransport.ts
+var EmbedTransport = class {
+  constructor(opts) {
+    __publicField(this, "opts");
+    __publicField(this, "handlers", {});
+    __publicField(this, "destroyed", false);
+    __publicField(this, "pendingRequests", /* @__PURE__ */ new Map());
+    this.opts = {
+      ...opts,
+      parentWindow: opts.parentWindow ?? (typeof window !== "undefined" ? window.parent : { postMessage: () => void 0 }),
+      hostWindow: opts.hostWindow ?? (typeof window !== "undefined" ? window : {
+        addEventListener: () => void 0,
+        removeEventListener: () => void 0
+      })
+    };
+    this.boundMessage = this.boundMessage.bind(this);
+    this.opts.hostWindow.addEventListener("message", this.boundMessage);
+  }
+  /** Replaces the handler set. Idempotent — call multiple times. */
+  on(handlers) {
+    this.handlers = { ...this.handlers, ...handlers };
+  }
+  /** Editor → Host: announce ourselves. Call once after handlers are wired. */
+  sendHello() {
+    const data = {
+      capabilities: this.opts.capabilities,
+      version: this.opts.version,
+      commit: this.opts.commit
+    };
+    this.post("casual.hello", data);
+  }
+  /** Editor → Host: editor is ready to receive commands. */
+  sendReady() {
+    this.post("casual.ready", {});
+  }
+  /** Editor → Host: ask the host to supply document bytes for `docId`. */
+  async requestLoad(docId, timeoutMs = 3e4) {
+    return this.request(
+      "casual.load.request",
+      { docId },
+      timeoutMs
+    );
+  }
+  /** Editor → Host: ask the host to persist `bytes`. */
+  async requestSave(req, timeoutMs = 3e4) {
+    return this.request("casual.save.request", req, timeoutMs, [req.bytes]);
+  }
+  /** Editor → Host: selection moved. Fire-and-forget. */
+  sendSelectionChanged(data) {
+    this.post("casual.selection.changed", data);
+  }
+  /** Editor → Host: format flags on the active cell changed (bold,
+   *  italic, …). Drive's custom toolbar mirrors this state in its
+   *  "pressed" indicators. v0.6+. */
+  sendSelectionFormatState(data) {
+    this.post("casual.selection.format-state", data);
+  }
+  /** Editor → Host: a noteworthy event. */
+  sendTelemetry(data) {
+    this.post("casual.telemetry.event", data);
+  }
+  /** Editor → Host: per-field progress during a signing session. */
+  sendSignatureFieldSigned(data) {
+    this.post("casual.signature.field.signed", data, [data.bytes]);
+  }
+  /** Editor → Host: signing session is finished. */
+  sendSignatureComplete(data) {
+    this.post("casual.signature.complete", data, [data.bytes]);
+  }
+  /** Editor → Host: editor-side cancel of a signing session. */
+  sendSignatureCancel(reason) {
+    this.post("casual.signature.cancel", { reason });
+  }
+  /** Editor → Host: fatal boot / load error. Host surfaces via wrapper
+   *  `onError` callback. Fire-and-forget. */
+  sendError(data) {
+    this.post("casual.error", data);
+  }
+  /** Tear down listeners. Idempotent. */
+  destroy() {
+    if (this.destroyed) return;
+    this.opts.hostWindow.removeEventListener("message", this.boundMessage);
+    this.pendingRequests.clear();
+    this.destroyed = true;
+  }
+  // ---------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------
+  boundMessage(ev) {
+    const msg = ev;
+    if (msg.origin && msg.origin !== this.opts.hostOrigin) return;
+    if (!isCasualEnvelope(msg.data)) return;
+    void this.dispatch(msg.data);
+  }
+  async dispatch(env) {
+    if (env.id && this.pendingRequests.has(env.id)) {
+      const resolve = this.pendingRequests.get(env.id);
+      this.pendingRequests.delete(env.id);
+      resolve(env);
+      return;
+    }
+    switch (env.type) {
+      case "casual.hello":
+        await this.handlers.onHostHello?.(env.data);
+        this.sendReady();
+        return;
+      case "casual.command.setReadOnly":
+        await this.handlers.onCommandSetReadOnly?.(env.data);
+        return;
+      case "casual.command.setTheme":
+        await this.handlers.onCommandSetTheme?.(env.data);
+        return;
+      case "casual.command.setLocale":
+        await this.handlers.onCommandSetLocale?.(env.data);
+        return;
+      case "casual.command.set.viewmode":
+        await this.handlers.onCommandSetViewMode?.(env.data);
+        return;
+      case "casual.command.execute":
+        await this.handlers.onCommandExecute?.(env.data);
+        return;
+      case "casual.command.focus":
+        await this.handlers.onCommandFocus?.();
+        return;
+      case "casual.command.save":
+        await this.handlers.onCommandSave?.();
+        return;
+      case "casual.command.load":
+        await this.handlers.onCommandLoad?.();
+        return;
+      case "casual.signature.request": {
+        const ack = await this.handlers.onSignatureRequest?.(
+          env.data
+        ) ?? {
+          ok: false,
+          code: "unhandled"
+        };
+        if (env.id) {
+          this.postReply(env.id, "casual.signature.request.ack", ack);
+        }
+        return;
+      }
+      case "casual.signature.cancel":
+        await this.handlers.onSignatureCancel?.(env.data);
+        return;
+      default:
+        return;
+    }
+  }
+  post(type, data, transfer) {
+    const env = { type, app: this.opts.app, v: 1, data };
+    try {
+      this.opts.parentWindow.postMessage(env, this.opts.hostOrigin, transfer);
+    } catch {
+    }
+  }
+  postReply(id, type, data) {
+    const env = { type, app: this.opts.app, id, v: 1, data };
+    try {
+      this.opts.parentWindow.postMessage(env, this.opts.hostOrigin);
+    } catch {
+    }
+  }
+  async request(type, data, timeoutMs, transfer) {
+    const id = newRequestId();
+    return new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Embed request ${type} timed out after ${timeoutMs}ms`));
+      }, timeoutMs) : null;
+      this.pendingRequests.set(id, (env2) => {
+        if (timer) clearTimeout(timer);
+        resolve(env2.data);
+      });
+      const env = { type, app: this.opts.app, id, v: 1, data };
+      try {
+        this.opts.parentWindow.postMessage(env, this.opts.hostOrigin, transfer);
+      } catch (err) {
+        if (timer) clearTimeout(timer);
+        this.pendingRequests.delete(id);
+        reject(err);
+      }
+    });
+  }
+};
+function newRequestId() {
+  return Math.random().toString(16).slice(2, 10);
+}
+//# sourceMappingURL=embed.cjs.map

package/dist/embed.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embed/index.ts","../src/embed/protocol.ts","../src/embed/EmbedTransport.ts"],"sourcesContent":["/**\n * Embed — iframe delivery surface.\n *\n * EmbedTransport bridges postMessage to React handlers. The\n * envelope shapes (`./protocol.ts`) mirror the documentation\n * contract in `docs/internal/13-iframe-protocol.md` and the\n * signing payloads from `../signing/types.ts`.\n */\n\nexport {\n  EmbedTransport,\n  type EmbedTransportHandlers,\n  type EmbedTransportOptions,\n} from './EmbedTransport';\nexport {\n  isCasualEnvelope,\n  type CasualApp,\n  type CasualEnvelope,\n  type EditorHelloData,\n  type HostHelloData,\n  type LoadRequestData,\n  type LoadResponseData,\n  type LoadResponseDataOk,\n  type LoadResponseDataErr,\n  type SaveRequestData,\n  type SaveResponseData,\n  type SaveResponseDataOk,\n  type SaveResponseDataErr,\n  type SelectionChangedData,\n  type TelemetryEventData,\n  type LockLostData,\n  type CommandSetReadOnlyData,\n  type CommandSetThemeData,\n  type CommandSetLocaleData,\n  type SignatureRequestData,\n  type SignatureRequestAckData,\n  type SignatureFieldSignedData,\n  type SignatureCompleteData,\n  type SignatureCancelData,\n} from './protocol';\n","/**\n * Iframe protocol — wire envelopes that match\n * `docs/internal/13-iframe-protocol.md`.\n *\n * Mirror updates to the doc whenever a new envelope shape lands.\n * The discriminator on `type` (always starts with `casual.`) and\n * the per-envelope `data` shape are the contract.\n */\n\nimport type {\n  CancelReason,\n  SignatureCompletePayload,\n  SignatureField,\n  SignatureMode,\n  SignedFieldPayload,\n} from '../signing/types';\n\nexport type CasualApp = 'docs' | 'sheet';\n\n/** Common envelope shape — every postMessage on the wire matches this. */\nexport interface CasualEnvelope<T = unknown> {\n  type: string;\n  app: CasualApp;\n  /** Per-request id for request/response correlation. Empty for fire-and-forget. */\n  id?: string;\n  /** Protocol version. Bumped only on breaking changes. */\n  v: 1;\n  data: T;\n}\n\n// ---------------------------------------------------------------\n// Handshake\n// ---------------------------------------------------------------\n\nexport interface EditorHelloData {\n  capabilities: string[];\n  version: string;\n  commit: string;\n}\n\nexport interface HostHelloData {\n  capabilities: string[];\n  authToken?: string;\n}\n\n// ---------------------------------------------------------------\n// Load + save (editor → host requests; host → editor responses)\n// ---------------------------------------------------------------\n\nexport interface LoadRequestData {\n  docId: string;\n}\n\nexport interface LoadResponseDataOk {\n  ok: true;\n  bytes: ArrayBuffer;\n  etag?: string;\n  fileName: string;\n  readOnly?: boolean;\n}\n\nexport interface LoadResponseDataErr {\n  ok: false;\n  code: string;\n  message?: string;\n}\n\nexport type LoadResponseData = LoadResponseDataOk | LoadResponseDataErr;\n\nexport interface SaveRequestData {\n  docId: string;\n  bytes: ArrayBuffer;\n  baseEtag?: string;\n}\n\nexport interface SaveResponseDataOk {\n  ok: true;\n  etag: string;\n}\n\nexport interface SaveResponseDataErr {\n  ok: false;\n  code: string;\n  etag?: string;\n  message?: string;\n}\n\nexport type SaveResponseData = SaveResponseDataOk | SaveResponseDataErr;\n\n// ---------------------------------------------------------------\n// Selection + telemetry + lock (editor → host notifications)\n// ---------------------------------------------------------------\n\nexport interface SelectionChangedData {\n  docs?: { paraId: string; from: number; to: number; selectedText: string };\n  sheet?: { sheet: string; from: string; to: string };\n}\n\nexport interface TelemetryEventData {\n  kind: string;\n  /** Arbitrary metric fields. */\n  [k: string]: unknown;\n}\n\nexport interface LockLostData {\n  reason: 'taken_by_other' | 'expired' | 'host_revoked';\n}\n\n// ---------------------------------------------------------------\n// Commands (host → editor)\n// ---------------------------------------------------------------\n\nexport interface CommandSetReadOnlyData {\n  readOnly: boolean;\n}\n\nexport interface CommandSetThemeData {\n  theme: 'light' | 'dark' | 'system';\n}\n\nexport interface CommandSetLocaleData {\n  locale: string;\n}\n\n/** Host → editor: switch chrome density between the two consumer-facing\n *  modes without re-mounting. `preview` hides toolbar / formula bar /\n *  side panel / status bar / sheet tabs and runs read-only; `editor`\n *  shows the full UI. Mirrors the `viewMode` prop on `<CasualSheetsIframe>`. */\nexport interface CommandSetViewModeData {\n  viewMode: 'preview' | 'editor';\n}\n\n/** Host → editor: execute a formatting / navigation command against\n *  the active selection in the embedded workbook. Hosts (like Casual\n *  Drive) build their own toolbar above the iframe and dispatch these\n *  commands instead of Univer's built-in ribbon, which the SDK can't\n *  ship because the ribbon resolves IRPCChannelService at construction\n *  and that service needs a worker the SDK doesn't bundle.\n *\n *  v0.6 covered the toggle set; v0.7 adds the rich-format set (font,\n *  size, colour, fill) + merge / unmerge. Arg-carrying commands read\n *  the relevant field off `args` — every other command ignores it. */\nexport interface CommandExecuteData {\n  command: // v0.6 — toggle / nav (no args)\n    | 'undo'\n    | 'redo'\n    | 'bold'\n    | 'italic'\n    | 'underline'\n    | 'strikethrough'\n    | 'align-left'\n    | 'align-center'\n    | 'align-right'\n    // v0.7 — rich format (args carry the value)\n    | 'set-font-family'\n    | 'set-font-size'\n    | 'set-text-color'\n    | 'reset-text-color'\n    | 'set-bg-color'\n    | 'reset-bg-color'\n    | 'merge'\n    | 'unmerge'\n    // v0.8 — number formats + freeze + wrap\n    | 'numfmt-currency'\n    | 'numfmt-percent'\n    | 'numfmt-add-decimal'\n    | 'numfmt-subtract-decimal'\n    | 'numfmt-custom'\n    | 'wrap-toggle'\n    | 'freeze-first-row'\n    | 'freeze-first-column'\n    | 'freeze-none';\n  args?: {\n    /** Used by `set-font-family`. */\n    family?: string;\n    /** Used by `set-font-size`. Integer point size. */\n    size?: number;\n    /** Used by `set-text-color` and `set-bg-color`. Hex like `#1a73e8`. */\n    color?: string;\n    /** Used by `numfmt-custom`. The Excel-style format string, e.g.\n     *  `\"#,##0.00\"`, `\"$#,##0\"`, `\"0.00%\"`, `\"d-mmm-yy\"`. v0.8+. */\n    pattern?: string;\n  };\n}\n\n/** Editor → host: emitted whenever the selection's active cell's\n *  format flags change. Drive's toolbar mirrors this state in the\n *  button \"pressed\" / value indicators so the surface always reflects\n *  what the user would see in the cell. v0.7 widens the payload with\n *  the rich-format read-back (fontFamily, fontSize, textColor, bgColor)\n *  so the toolbar's font picker / size stepper / colour swatches stay\n *  in sync without the host having to poll. */\nexport interface SelectionFormatStateData {\n  bold: boolean;\n  italic: boolean;\n  underline: boolean;\n  strikethrough: boolean;\n  align: 'left' | 'center' | 'right' | null;\n  /** Defined font family on the active cell, or null when the cell\n   *  inherits the workbook default. v0.7+. */\n  fontFamily: string | null;\n  /** Defined font size on the active cell, or null when the cell\n   *  inherits the workbook default. v0.7+. */\n  fontSize: number | null;\n  /** Hex text colour like `#1a73e8`, or null when default. v0.7+. */\n  textColor: string | null;\n  /** Hex background colour, or null when no fill is set. v0.7+. */\n  bgColor: string | null;\n}\n\n// ---------------------------------------------------------------\n// Errors (editor → host fatal signals)\n// ---------------------------------------------------------------\n\n/** Editor → host: a fatal error during boot / load. Hosts surface this\n *  via the wrapper's `onError` callback. */\nexport interface CasualErrorData {\n  code: 'embed_not_served' | 'load_failed' | 'parse_failed' | 'boot_failed' | 'internal';\n  message: string;\n}\n\n// ---------------------------------------------------------------\n// Signing (uniform with the SDK `signing` prop)\n// ---------------------------------------------------------------\n\nexport interface SignatureRequestData {\n  fields: SignatureField[];\n  mode: SignatureMode;\n  banner?: string;\n}\n\nexport interface SignatureRequestAckData {\n  ok: boolean;\n  code?: string;\n}\n\nexport type SignatureFieldSignedData = SignedFieldPayload;\nexport type SignatureCompleteData = SignatureCompletePayload;\n\nexport interface SignatureCancelData {\n  reason: CancelReason;\n}\n\n// ---------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------\n\nexport function isCasualEnvelope(value: unknown): value is CasualEnvelope {\n  if (!value || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return (\n    typeof v.type === 'string' &&\n    v.type.startsWith('casual.') &&\n    (v.app === 'docs' || v.app === 'sheet') &&\n    v.v === 1 &&\n    'data' in v\n  );\n}\n","/**\n * EmbedTransport — postMessage bridge for the iframe-embedded\n * editor. Validates origin, dispatches envelopes to handlers,\n * sends responses back to the host. Pure TypeScript — no React.\n *\n * Wire shape defined in\n * `docs/internal/13-iframe-protocol.md` + `./protocol.ts`.\n *\n * Lifetime: constructed once when the /embed page mounts.\n * Destroyed when the page unloads. Concurrent calls into the same\n * handler are the host's responsibility (well-behaved hosts\n * serialise requests by id).\n */\n\nimport {\n  isCasualEnvelope,\n  type CasualApp,\n  type CasualEnvelope,\n  type EditorHelloData,\n  type HostHelloData,\n  type LoadResponseData,\n  type LoadRequestData,\n  type SaveRequestData,\n  type SaveResponseData,\n  type SelectionChangedData,\n  type TelemetryEventData,\n  type CommandSetReadOnlyData,\n  type CommandSetThemeData,\n  type CommandSetLocaleData,\n  type CommandSetViewModeData,\n  type CommandExecuteData,\n  type SelectionFormatStateData,\n  type CasualErrorData,\n  type SignatureRequestData,\n  type SignatureRequestAckData,\n  type SignatureFieldSignedData,\n  type SignatureCompleteData,\n  type SignatureCancelData,\n} from './protocol';\n\nexport interface EmbedTransportOptions {\n  app: CasualApp;\n  /** Origin allowed to send messages. Required — no `*` default. */\n  hostOrigin: string;\n  /** Editor build identity, surfaced in the editor.hello handshake. */\n  version: string;\n  commit: string;\n  /** Editor-side capabilities advertised at handshake. */\n  capabilities: string[];\n  /** Optional injection for `window.parent` — tests pass a stub. */\n  parentWindow?: {\n    postMessage: (msg: unknown, targetOrigin: string, transfer?: Transferable[]) => void;\n  };\n  /** Optional injection for the window receiving messages — tests pass a stub. */\n  hostWindow?: Pick<Window, 'addEventListener' | 'removeEventListener'>;\n}\n\nexport interface EmbedTransportHandlers {\n  /** Host → editor handshake. Editor responds with `editor.ready`. */\n  onHostHello?: (data: HostHelloData) => void | Promise<void>;\n  /** Host → editor: command.* messages. */\n  onCommandSetReadOnly?: (data: CommandSetReadOnlyData) => void | Promise<void>;\n  onCommandSetTheme?: (data: CommandSetThemeData) => void | Promise<void>;\n  onCommandSetLocale?: (data: CommandSetLocaleData) => void | Promise<void>;\n  /** Host → editor: switch chrome density (preview ↔ editor). */\n  onCommandSetViewMode?: (data: CommandSetViewModeData) => void | Promise<void>;\n  /** Host → editor: execute a formatting / navigation command (bold,\n   *  italic, undo, …) against the active selection. v0.6+. */\n  onCommandExecute?: (data: CommandExecuteData) => void | Promise<void>;\n  onCommandFocus?: () => void | Promise<void>;\n  onCommandSave?: () => void | Promise<void>;\n  onCommandLoad?: () => void | Promise<void>;\n  /** Host → editor signing session. Editor responds with `signature.request.ack`. */\n  onSignatureRequest?: (\n    data: SignatureRequestData,\n  ) => SignatureRequestAckData | Promise<SignatureRequestAckData>;\n  onSignatureCancel?: (data: SignatureCancelData) => void | Promise<void>;\n  /** Host → editor: response to a prior load.request the editor issued. */\n  onLoadResponse?: (id: string, data: LoadResponseData) => void;\n  /** Host → editor: response to a prior save.request the editor issued. */\n  onSaveResponse?: (id: string, data: SaveResponseData) => void;\n}\n\nexport class EmbedTransport {\n  private readonly opts: Required<Omit<EmbedTransportOptions, 'parentWindow' | 'hostWindow'>> & {\n    parentWindow: NonNullable<EmbedTransportOptions['parentWindow']>;\n    hostWindow: NonNullable<EmbedTransportOptions['hostWindow']>;\n  };\n  private handlers: EmbedTransportHandlers = {};\n  private destroyed = false;\n  private pendingRequests = new Map<string, (env: CasualEnvelope) => void>();\n\n  constructor(opts: EmbedTransportOptions) {\n    this.opts = {\n      ...opts,\n      parentWindow:\n        opts.parentWindow ??\n        (typeof window !== 'undefined'\n          ? (window.parent as unknown as NonNullable<EmbedTransportOptions['parentWindow']>)\n          : { postMessage: () => undefined }),\n      hostWindow:\n        opts.hostWindow ??\n        (typeof window !== 'undefined'\n          ? window\n          : ({\n              addEventListener: () => undefined,\n              removeEventListener: () => undefined,\n            } as unknown as NonNullable<EmbedTransportOptions['hostWindow']>)),\n    };\n    this.boundMessage = this.boundMessage.bind(this);\n    this.opts.hostWindow.addEventListener('message', this.boundMessage as EventListener);\n  }\n\n  /** Replaces the handler set. Idempotent — call multiple times. */\n  on(handlers: EmbedTransportHandlers): void {\n    this.handlers = { ...this.handlers, ...handlers };\n  }\n\n  /** Editor → Host: announce ourselves. Call once after handlers are wired. */\n  sendHello(): void {\n    const data: EditorHelloData = {\n      capabilities: this.opts.capabilities,\n      version: this.opts.version,\n      commit: this.opts.commit,\n    };\n    this.post('casual.hello', data);\n  }\n\n  /** Editor → Host: editor is ready to receive commands. */\n  sendReady(): void {\n    this.post('casual.ready', {});\n  }\n\n  /** Editor → Host: ask the host to supply document bytes for `docId`. */\n  async requestLoad(docId: string, timeoutMs = 30000): Promise<LoadResponseData> {\n    return this.request<LoadResponseData>(\n      'casual.load.request',\n      { docId } as LoadRequestData,\n      timeoutMs,\n    );\n  }\n\n  /** Editor → Host: ask the host to persist `bytes`. */\n  async requestSave(req: SaveRequestData, timeoutMs = 30000): Promise<SaveResponseData> {\n    return this.request<SaveResponseData>('casual.save.request', req, timeoutMs, [req.bytes]);\n  }\n\n  /** Editor → Host: selection moved. Fire-and-forget. */\n  sendSelectionChanged(data: SelectionChangedData): void {\n    this.post('casual.selection.changed', data);\n  }\n\n  /** Editor → Host: format flags on the active cell changed (bold,\n   *  italic, …). Drive's custom toolbar mirrors this state in its\n   *  \"pressed\" indicators. v0.6+. */\n  sendSelectionFormatState(data: SelectionFormatStateData): void {\n    this.post('casual.selection.format-state', data);\n  }\n\n  /** Editor → Host: a noteworthy event. */\n  sendTelemetry(data: TelemetryEventData): void {\n    this.post('casual.telemetry.event', data);\n  }\n\n  /** Editor → Host: per-field progress during a signing session. */\n  sendSignatureFieldSigned(data: SignatureFieldSignedData): void {\n    // Bytes ride the transfer list.\n    this.post('casual.signature.field.signed', data, [data.bytes]);\n  }\n\n  /** Editor → Host: signing session is finished. */\n  sendSignatureComplete(data: SignatureCompleteData): void {\n    this.post('casual.signature.complete', data, [data.bytes]);\n  }\n\n  /** Editor → Host: editor-side cancel of a signing session. */\n  sendSignatureCancel(reason: SignatureCancelData['reason']): void {\n    this.post('casual.signature.cancel', { reason });\n  }\n\n  /** Editor → Host: fatal boot / load error. Host surfaces via wrapper\n   *  `onError` callback. Fire-and-forget. */\n  sendError(data: CasualErrorData): void {\n    this.post('casual.error', data);\n  }\n\n  /** Tear down listeners. Idempotent. */\n  destroy(): void {\n    if (this.destroyed) return;\n    this.opts.hostWindow.removeEventListener('message', this.boundMessage as EventListener);\n    this.pendingRequests.clear();\n    this.destroyed = true;\n  }\n\n  // ---------------------------------------------------------------\n  // Internals\n  // ---------------------------------------------------------------\n\n  private boundMessage(ev: Event): void {\n    // MessageEvent isn't always available on the typing side when\n    // a stub window is injected; cast pragmatically.\n    const msg = ev as unknown as MessageEvent;\n    if (msg.origin && msg.origin !== this.opts.hostOrigin) return;\n    if (!isCasualEnvelope(msg.data)) return;\n    void this.dispatch(msg.data as CasualEnvelope);\n  }\n\n  private async dispatch(env: CasualEnvelope): Promise<void> {\n    // Responses to outbound requests route through the correlation map.\n    if (env.id && this.pendingRequests.has(env.id)) {\n      const resolve = this.pendingRequests.get(env.id)!;\n      this.pendingRequests.delete(env.id);\n      resolve(env);\n      return;\n    }\n\n    switch (env.type) {\n      case 'casual.hello':\n        await this.handlers.onHostHello?.(env.data as HostHelloData);\n        this.sendReady();\n        return;\n      case 'casual.command.setReadOnly':\n        await this.handlers.onCommandSetReadOnly?.(env.data as CommandSetReadOnlyData);\n        return;\n      case 'casual.command.setTheme':\n        await this.handlers.onCommandSetTheme?.(env.data as CommandSetThemeData);\n        return;\n      case 'casual.command.setLocale':\n        await this.handlers.onCommandSetLocale?.(env.data as CommandSetLocaleData);\n        return;\n      case 'casual.command.set.viewmode':\n        await this.handlers.onCommandSetViewMode?.(env.data as CommandSetViewModeData);\n        return;\n      case 'casual.command.execute':\n        await this.handlers.onCommandExecute?.(env.data as CommandExecuteData);\n        return;\n      case 'casual.command.focus':\n        await this.handlers.onCommandFocus?.();\n        return;\n      case 'casual.command.save':\n        await this.handlers.onCommandSave?.();\n        return;\n      case 'casual.command.load':\n        await this.handlers.onCommandLoad?.();\n        return;\n      case 'casual.signature.request': {\n        const ack = (await this.handlers.onSignatureRequest?.(\n          env.data as SignatureRequestData,\n        )) ?? {\n          ok: false,\n          code: 'unhandled',\n        };\n        if (env.id) {\n          this.postReply(env.id, 'casual.signature.request.ack', ack);\n        }\n        return;\n      }\n      case 'casual.signature.cancel':\n        await this.handlers.onSignatureCancel?.(env.data as SignatureCancelData);\n        return;\n      default:\n        // Unknown envelope — silently drop per the forward-compat\n        // convention in the protocol doc.\n        return;\n    }\n  }\n\n  private post(type: string, data: unknown, transfer?: Transferable[]): void {\n    const env: CasualEnvelope = { type, app: this.opts.app, v: 1, data };\n    try {\n      this.opts.parentWindow.postMessage(env, this.opts.hostOrigin, transfer);\n    } catch {\n      // Cross-origin postMessage can throw if the parent went away;\n      // silently swallow — the next user action will retry.\n    }\n  }\n\n  private postReply(id: string, type: string, data: unknown): void {\n    const env: CasualEnvelope = { type, app: this.opts.app, id, v: 1, data };\n    try {\n      this.opts.parentWindow.postMessage(env, this.opts.hostOrigin);\n    } catch {\n      // see post()\n    }\n  }\n\n  private async request<T>(\n    type: string,\n    data: unknown,\n    timeoutMs: number,\n    transfer?: Transferable[],\n  ): Promise<T> {\n    const id = newRequestId();\n    return new Promise<T>((resolve, reject) => {\n      const timer =\n        timeoutMs > 0\n          ? setTimeout(() => {\n              this.pendingRequests.delete(id);\n              reject(new Error(`Embed request ${type} timed out after ${timeoutMs}ms`));\n            }, timeoutMs)\n          : null;\n      this.pendingRequests.set(id, (env) => {\n        if (timer) clearTimeout(timer);\n        resolve(env.data as T);\n      });\n      const env: CasualEnvelope = { type, app: this.opts.app, id, v: 1, data };\n      try {\n        this.opts.parentWindow.postMessage(env, this.opts.hostOrigin, transfer);\n      } catch (err) {\n        if (timer) clearTimeout(timer);\n        this.pendingRequests.delete(id);\n        reject(err);\n      }\n    });\n  }\n}\n\nfunction newRequestId(): string {\n  // 8 hex chars is plenty — IDs only need to be unique within a\n  // single editor session. Math.random is fine; the host can't\n  // use these for security.\n  return Math.random().toString(16).slice(2, 10);\n}\n"],"mappings":"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","names":["env"]}

package/dist/embed.d.cts

@@ -0,0 +1,100 @@
+import { C as CasualApp, H as HostHelloData, e as CommandSetReadOnlyData, f as CommandSetThemeData, d as CommandSetLocaleData, g as CommandSetViewModeData, c as CommandExecuteData, u as SignatureRequestData, t as SignatureRequestAckData, q as SignatureCancelData, h as LoadResponseData, l as SaveResponseData, S as SaveRequestData, o as SelectionChangedData, p as SelectionFormatStateData, T as TelemetryEventData, s as SignatureFieldSignedData, r as SignatureCompleteData, b as CasualErrorData } from './protocol--KyBQUjU.cjs';
+export { a as CasualEnvelope, E as EditorHelloData, L as LoadRequestData, i as LoadResponseDataErr, j as LoadResponseDataOk, k as LockLostData, m as SaveResponseDataErr, n as SaveResponseDataOk, v as isCasualEnvelope } from './protocol--KyBQUjU.cjs';
+import './types-s_O0u6Cg.cjs';
+
+/**
+ * EmbedTransport — postMessage bridge for the iframe-embedded
+ * editor. Validates origin, dispatches envelopes to handlers,
+ * sends responses back to the host. Pure TypeScript — no React.
+ *
+ * Wire shape defined in
+ * `docs/internal/13-iframe-protocol.md` + `./protocol.ts`.
+ *
+ * Lifetime: constructed once when the /embed page mounts.
+ * Destroyed when the page unloads. Concurrent calls into the same
+ * handler are the host's responsibility (well-behaved hosts
+ * serialise requests by id).
+ */
+
+interface EmbedTransportOptions {
+    app: CasualApp;
+    /** Origin allowed to send messages. Required — no `*` default. */
+    hostOrigin: string;
+    /** Editor build identity, surfaced in the editor.hello handshake. */
+    version: string;
+    commit: string;
+    /** Editor-side capabilities advertised at handshake. */
+    capabilities: string[];
+    /** Optional injection for `window.parent` — tests pass a stub. */
+    parentWindow?: {
+        postMessage: (msg: unknown, targetOrigin: string, transfer?: Transferable[]) => void;
+    };
+    /** Optional injection for the window receiving messages — tests pass a stub. */
+    hostWindow?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}
+interface EmbedTransportHandlers {
+    /** Host → editor handshake. Editor responds with `editor.ready`. */
+    onHostHello?: (data: HostHelloData) => void | Promise<void>;
+    /** Host → editor: command.* messages. */
+    onCommandSetReadOnly?: (data: CommandSetReadOnlyData) => void | Promise<void>;
+    onCommandSetTheme?: (data: CommandSetThemeData) => void | Promise<void>;
+    onCommandSetLocale?: (data: CommandSetLocaleData) => void | Promise<void>;
+    /** Host → editor: switch chrome density (preview ↔ editor). */
+    onCommandSetViewMode?: (data: CommandSetViewModeData) => void | Promise<void>;
+    /** Host → editor: execute a formatting / navigation command (bold,
+     *  italic, undo, …) against the active selection. v0.6+. */
+    onCommandExecute?: (data: CommandExecuteData) => void | Promise<void>;
+    onCommandFocus?: () => void | Promise<void>;
+    onCommandSave?: () => void | Promise<void>;
+    onCommandLoad?: () => void | Promise<void>;
+    /** Host → editor signing session. Editor responds with `signature.request.ack`. */
+    onSignatureRequest?: (data: SignatureRequestData) => SignatureRequestAckData | Promise<SignatureRequestAckData>;
+    onSignatureCancel?: (data: SignatureCancelData) => void | Promise<void>;
+    /** Host → editor: response to a prior load.request the editor issued. */
+    onLoadResponse?: (id: string, data: LoadResponseData) => void;
+    /** Host → editor: response to a prior save.request the editor issued. */
+    onSaveResponse?: (id: string, data: SaveResponseData) => void;
+}
+declare class EmbedTransport {
+    private readonly opts;
+    private handlers;
+    private destroyed;
+    private pendingRequests;
+    constructor(opts: EmbedTransportOptions);
+    /** Replaces the handler set. Idempotent — call multiple times. */
+    on(handlers: EmbedTransportHandlers): void;
+    /** Editor → Host: announce ourselves. Call once after handlers are wired. */
+    sendHello(): void;
+    /** Editor → Host: editor is ready to receive commands. */
+    sendReady(): void;
+    /** Editor → Host: ask the host to supply document bytes for `docId`. */
+    requestLoad(docId: string, timeoutMs?: number): Promise<LoadResponseData>;
+    /** Editor → Host: ask the host to persist `bytes`. */
+    requestSave(req: SaveRequestData, timeoutMs?: number): Promise<SaveResponseData>;
+    /** Editor → Host: selection moved. Fire-and-forget. */
+    sendSelectionChanged(data: SelectionChangedData): void;
+    /** Editor → Host: format flags on the active cell changed (bold,
+     *  italic, …). Drive's custom toolbar mirrors this state in its
+     *  "pressed" indicators. v0.6+. */
+    sendSelectionFormatState(data: SelectionFormatStateData): void;
+    /** Editor → Host: a noteworthy event. */
+    sendTelemetry(data: TelemetryEventData): void;
+    /** Editor → Host: per-field progress during a signing session. */
+    sendSignatureFieldSigned(data: SignatureFieldSignedData): void;
+    /** Editor → Host: signing session is finished. */
+    sendSignatureComplete(data: SignatureCompleteData): void;
+    /** Editor → Host: editor-side cancel of a signing session. */
+    sendSignatureCancel(reason: SignatureCancelData['reason']): void;
+    /** Editor → Host: fatal boot / load error. Host surfaces via wrapper
+     *  `onError` callback. Fire-and-forget. */
+    sendError(data: CasualErrorData): void;
+    /** Tear down listeners. Idempotent. */
+    destroy(): void;
+    private boundMessage;
+    private dispatch;
+    private post;
+    private postReply;
+    private request;
+}
+
+export { CasualApp, CommandSetLocaleData, CommandSetReadOnlyData, CommandSetThemeData, EmbedTransport, type EmbedTransportHandlers, type EmbedTransportOptions, HostHelloData, LoadResponseData, SaveRequestData, SaveResponseData, SelectionChangedData, SignatureCancelData, SignatureCompleteData, SignatureFieldSignedData, SignatureRequestAckData, SignatureRequestData, TelemetryEventData };

package/dist/embed.d.ts

@@ -0,0 +1,100 @@
+import { C as CasualApp, H as HostHelloData, e as CommandSetReadOnlyData, f as CommandSetThemeData, d as CommandSetLocaleData, g as CommandSetViewModeData, c as CommandExecuteData, u as SignatureRequestData, t as SignatureRequestAckData, q as SignatureCancelData, h as LoadResponseData, l as SaveResponseData, S as SaveRequestData, o as SelectionChangedData, p as SelectionFormatStateData, T as TelemetryEventData, s as SignatureFieldSignedData, r as SignatureCompleteData, b as CasualErrorData } from './protocol-cEzy7S0i.js';
+export { a as CasualEnvelope, E as EditorHelloData, L as LoadRequestData, i as LoadResponseDataErr, j as LoadResponseDataOk, k as LockLostData, m as SaveResponseDataErr, n as SaveResponseDataOk, v as isCasualEnvelope } from './protocol-cEzy7S0i.js';
+import './types-s_O0u6Cg.js';
+
+/**
+ * EmbedTransport — postMessage bridge for the iframe-embedded
+ * editor. Validates origin, dispatches envelopes to handlers,
+ * sends responses back to the host. Pure TypeScript — no React.
+ *
+ * Wire shape defined in
+ * `docs/internal/13-iframe-protocol.md` + `./protocol.ts`.
+ *
+ * Lifetime: constructed once when the /embed page mounts.
+ * Destroyed when the page unloads. Concurrent calls into the same
+ * handler are the host's responsibility (well-behaved hosts
+ * serialise requests by id).
+ */
+
+interface EmbedTransportOptions {
+    app: CasualApp;
+    /** Origin allowed to send messages. Required — no `*` default. */
+    hostOrigin: string;
+    /** Editor build identity, surfaced in the editor.hello handshake. */
+    version: string;
+    commit: string;
+    /** Editor-side capabilities advertised at handshake. */
+    capabilities: string[];
+    /** Optional injection for `window.parent` — tests pass a stub. */
+    parentWindow?: {
+        postMessage: (msg: unknown, targetOrigin: string, transfer?: Transferable[]) => void;
+    };
+    /** Optional injection for the window receiving messages — tests pass a stub. */
+    hostWindow?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}
+interface EmbedTransportHandlers {
+    /** Host → editor handshake. Editor responds with `editor.ready`. */
+    onHostHello?: (data: HostHelloData) => void | Promise<void>;
+    /** Host → editor: command.* messages. */
+    onCommandSetReadOnly?: (data: CommandSetReadOnlyData) => void | Promise<void>;
+    onCommandSetTheme?: (data: CommandSetThemeData) => void | Promise<void>;
+    onCommandSetLocale?: (data: CommandSetLocaleData) => void | Promise<void>;
+    /** Host → editor: switch chrome density (preview ↔ editor). */
+    onCommandSetViewMode?: (data: CommandSetViewModeData) => void | Promise<void>;
+    /** Host → editor: execute a formatting / navigation command (bold,
+     *  italic, undo, …) against the active selection. v0.6+. */
+    onCommandExecute?: (data: CommandExecuteData) => void | Promise<void>;
+    onCommandFocus?: () => void | Promise<void>;
+    onCommandSave?: () => void | Promise<void>;
+    onCommandLoad?: () => void | Promise<void>;
+    /** Host → editor signing session. Editor responds with `signature.request.ack`. */
+    onSignatureRequest?: (data: SignatureRequestData) => SignatureRequestAckData | Promise<SignatureRequestAckData>;
+    onSignatureCancel?: (data: SignatureCancelData) => void | Promise<void>;
+    /** Host → editor: response to a prior load.request the editor issued. */
+    onLoadResponse?: (id: string, data: LoadResponseData) => void;
+    /** Host → editor: response to a prior save.request the editor issued. */
+    onSaveResponse?: (id: string, data: SaveResponseData) => void;
+}
+declare class EmbedTransport {
+    private readonly opts;
+    private handlers;
+    private destroyed;
+    private pendingRequests;
+    constructor(opts: EmbedTransportOptions);
+    /** Replaces the handler set. Idempotent — call multiple times. */
+    on(handlers: EmbedTransportHandlers): void;
+    /** Editor → Host: announce ourselves. Call once after handlers are wired. */
+    sendHello(): void;
+    /** Editor → Host: editor is ready to receive commands. */
+    sendReady(): void;
+    /** Editor → Host: ask the host to supply document bytes for `docId`. */
+    requestLoad(docId: string, timeoutMs?: number): Promise<LoadResponseData>;
+    /** Editor → Host: ask the host to persist `bytes`. */
+    requestSave(req: SaveRequestData, timeoutMs?: number): Promise<SaveResponseData>;
+    /** Editor → Host: selection moved. Fire-and-forget. */
+    sendSelectionChanged(data: SelectionChangedData): void;
+    /** Editor → Host: format flags on the active cell changed (bold,
+     *  italic, …). Drive's custom toolbar mirrors this state in its
+     *  "pressed" indicators. v0.6+. */
+    sendSelectionFormatState(data: SelectionFormatStateData): void;
+    /** Editor → Host: a noteworthy event. */
+    sendTelemetry(data: TelemetryEventData): void;
+    /** Editor → Host: per-field progress during a signing session. */
+    sendSignatureFieldSigned(data: SignatureFieldSignedData): void;
+    /** Editor → Host: signing session is finished. */
+    sendSignatureComplete(data: SignatureCompleteData): void;
+    /** Editor → Host: editor-side cancel of a signing session. */
+    sendSignatureCancel(reason: SignatureCancelData['reason']): void;
+    /** Editor → Host: fatal boot / load error. Host surfaces via wrapper
+     *  `onError` callback. Fire-and-forget. */
+    sendError(data: CasualErrorData): void;
+    /** Tear down listeners. Idempotent. */
+    destroy(): void;
+    private boundMessage;
+    private dispatch;
+    private post;
+    private postReply;
+    private request;
+}
+
+export { CasualApp, CommandSetLocaleData, CommandSetReadOnlyData, CommandSetThemeData, EmbedTransport, type EmbedTransportHandlers, type EmbedTransportOptions, HostHelloData, LoadResponseData, SaveRequestData, SaveResponseData, SelectionChangedData, SignatureCancelData, SignatureCompleteData, SignatureFieldSignedData, SignatureRequestAckData, SignatureRequestData, TelemetryEventData };