mindoodb-app-sdk 0.0.42 → 0.0.44

package/README.md

@@ -229,6 +229,32 @@ Important constraints:
 - Call `session.menus.hide()` if your app needs to explicitly dismiss a pending host menu.
 - Host-rendered menus are intended for `runtime === "iframe"`. Window-mode apps can usually show local menus instead.
 
+### Host-owned drag
+
+When two apps run as visible workspace chicklets, native HTML5 drag dies at the iframe boundary. The SDK therefore hands the gesture to Haven: the source starts it, Haven draws a PNG ghost above every frame, and the target hit-tests the drop.
+
+```ts
+await session.drag.setProfile({
+  accepts: ["text/plain", "text/markdown", "application/json", "application/x-mindoo-document"],
+  onOver: (event) => {
+    const zone = document.elementFromPoint(event.x, event.y)?.closest("[data-drop-zone]");
+    return { accept: Boolean(zone), effect: zone ? "copy" : "forbidden" };
+  },
+  onDrop: (event) => {
+    console.log(event.items["text/markdown"]);
+  },
+});
+
+const unbind = session.drag.bindSource(cardEl, {
+  offers: () => [
+    { type: "text/plain", data: "Hello" },
+    { type: "text/markdown", data: "**Hello**" },
+  ],
+});
+```
+
+`bindSource` starts after an 8px mouse/pen move, or a 400ms long-press on touch (so lists can still scroll). You can also call `session.drag.start` yourself with a PNG `ArrayBuffer` preview. v1 is **copy-only** and **iframe-only**. Well-known types: `text/plain`, `text/markdown`, `application/json`, `application/x-mindoo-document`.
+
 ### Databases and capabilities
 
 Each database mapped to your app carries a set of **capabilities** that Haven controls. Your app should check capabilities before attempting operations and adapt its UI accordingly.
@@ -1488,7 +1514,7 @@ export default defineConfig({
 });
 ```
 
-After `vite build`, `dist/` additionally contains `haven-bundle.json` (app id, version, a SHA-256 for every file, and one for the bundle as a whole) and `haven-bundle.zip` (all of it in one archive). The app's own service worker files are left out — Haven serves the bundle and a second service worker would only fight it for the scope. The user pastes the URL of `haven-bundle.json` into Haven's application settings; Haven downloads the archive, rejects it unless every hash matches the manifest, and installs it.
+After `vite build`, `dist/` additionally contains `haven-bundle.json` (app id, version, a SHA-256 for every file, and one for the bundle as a whole) and `haven-bundle.zip` (all of it in one archive). The app's own service worker files are left out — Haven serves the bundle and a second service worker would only fight it for the scope. The user pastes the app origin into Haven's application settings (the same URL as for external hosting); Haven fetches `/haven-bundle.json` from there, downloads the archive, rejects it unless every hash matches the manifest, and installs it.
 
 Haven then owns updates. It re-reads the manifest before launches and on a slow background timer, and installs a new version when the `contentHash` changes — which means an app in hosted mode should **not** run its own update logic:
 
@@ -1573,6 +1599,10 @@ Connect options: `launchId?`, `targetOrigin?`, `connectTimeoutMs?`.
 | `closeSealedChannel(channelId)`       | `Promise<void>`                      |
 | `menus.show(input)`                   | `Promise<MindooDBAppShowMenuResult>` |
 | `menus.hide()`                        | `Promise<void>`                      |
+| `drag.setProfile(profile)`            | `Promise<void>`                      |
+| `drag.start(input)`                   | `Promise<MindooDBAppDragStartResult>` |
+| `drag.cancel()`                       | `Promise<void>`                      |
+| `drag.bindSource(el, options)`        | `() => void` (unbind)                |
 | `storage`                             | `MindooDBAppStorageApi`              |
 | `onThemeChange(listener)`             | `() => void` (unsubscribe)           |
 | `onViewportChange(listener)`          | `() => void` (unsubscribe)           |

package/dist/{chunk-6433L6TE.js → chunk-ZO7UE6B2.js}

@@ -1,3 +1,430 @@
+// src/drag.ts
+var MINDOODB_APP_MAX_DRAG_TYPES = 8;
+var MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES = 32 * 1024;
+var MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES = 256 * 1024;
+var MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE = 512;
+var DEFAULT_DRAG_LONG_PRESS_MS = 400;
+var DEFAULT_DRAG_POINTER_THRESHOLD_PX = 8;
+var MINIMAL_DRAG_PREVIEW_PNG = Uint8Array.from(
+  atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="),
+  (character) => character.charCodeAt(0)
+);
+var DRAG_TYPE_PATTERN = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i;
+var MindooDBAppDragInputError = class extends Error {
+  name = "invalid-drag-input";
+  constructor(message) {
+    super(message);
+  }
+};
+function isMindooDBAppDragType(type) {
+  return DRAG_TYPE_PATTERN.test(type);
+}
+function utf8ByteLength(value) {
+  return new TextEncoder().encode(value).length;
+}
+function requireFiniteNumber(value, fieldPath) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new MindooDBAppDragInputError(`Expected ${fieldPath} to be a finite number.`);
+  }
+  return value;
+}
+function toPreviewArrayBuffer(value) {
+  if (value instanceof ArrayBuffer) {
+    return value.slice(0);
+  }
+  if (ArrayBuffer.isView(value)) {
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+  }
+  return null;
+}
+function normalizeDragType(value, fieldPath) {
+  if (typeof value !== "string" || !isMindooDBAppDragType(value)) {
+    throw new MindooDBAppDragInputError(`Expected ${fieldPath} to be a MIME-like type string.`);
+  }
+  return value;
+}
+function normalizeOffers(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new MindooDBAppDragInputError("A drag must offer at least one type.");
+  }
+  if (value.length > MINDOODB_APP_MAX_DRAG_TYPES) {
+    throw new MindooDBAppDragInputError(
+      `A drag supports at most ${MINDOODB_APP_MAX_DRAG_TYPES} types.`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== "object") {
+      throw new MindooDBAppDragInputError(`Expected offers[${index}] to be an object.`);
+    }
+    const candidate = entry;
+    const type = normalizeDragType(candidate.type, `offers[${index}].type`);
+    if (seen.has(type)) {
+      throw new MindooDBAppDragInputError(`Duplicate drag type "${type}".`);
+    }
+    seen.add(type);
+    if (typeof candidate.data !== "string") {
+      throw new MindooDBAppDragInputError(`Expected offers[${index}].data to be a string.`);
+    }
+    if (utf8ByteLength(candidate.data) > MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES) {
+      throw new MindooDBAppDragInputError(
+        `offers[${index}].data exceeds ${MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES} bytes.`
+      );
+    }
+    return { type, data: candidate.data };
+  });
+}
+function normalizeDragAccepts(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new MindooDBAppDragInputError("A drag profile must accept at least one type.");
+  }
+  if (value.length > MINDOODB_APP_MAX_DRAG_TYPES) {
+    throw new MindooDBAppDragInputError(
+      `A drag profile supports at most ${MINDOODB_APP_MAX_DRAG_TYPES} types.`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const accepts = [];
+  value.forEach((entry, index) => {
+    const type = normalizeDragType(entry, `accepts[${index}]`);
+    if (seen.has(type)) {
+      return;
+    }
+    seen.add(type);
+    accepts.push(type);
+  });
+  return accepts;
+}
+function normalizePreview(value) {
+  if (!value || typeof value !== "object") {
+    throw new MindooDBAppDragInputError("A drag preview is required.");
+  }
+  const candidate = value;
+  const pngBuffer = toPreviewArrayBuffer(candidate.png);
+  if (!pngBuffer) {
+    throw new MindooDBAppDragInputError("preview.png must be an ArrayBuffer.");
+  }
+  if (pngBuffer.byteLength === 0 || pngBuffer.byteLength > MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES) {
+    throw new MindooDBAppDragInputError(
+      `preview.png must be between 1 and ${MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES} bytes.`
+    );
+  }
+  const width = requireFiniteNumber(candidate.width, "preview.width");
+  const height = requireFiniteNumber(candidate.height, "preview.height");
+  if (width <= 0 || height <= 0 || width > MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE * 4 || height > MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE * 4) {
+    throw new MindooDBAppDragInputError("preview width/height are out of range.");
+  }
+  return {
+    png: pngBuffer,
+    width,
+    height,
+    hotspotX: requireFiniteNumber(candidate.hotspotX, "preview.hotspotX"),
+    hotspotY: requireFiniteNumber(candidate.hotspotY, "preview.hotspotY")
+  };
+}
+function normalizeDragStartInput(value) {
+  if (!value || typeof value !== "object") {
+    throw new MindooDBAppDragInputError("drag.start requires a payload object.");
+  }
+  const candidate = value;
+  if (!candidate.pointer || typeof candidate.pointer !== "object") {
+    throw new MindooDBAppDragInputError("pointer is required.");
+  }
+  const pointer = candidate.pointer;
+  let allowedEffects;
+  if (candidate.allowedEffects !== void 0) {
+    if (!Array.isArray(candidate.allowedEffects) || candidate.allowedEffects.length === 0 || candidate.allowedEffects.some((effect) => effect !== "copy")) {
+      throw new MindooDBAppDragInputError('allowedEffects may only include "copy".');
+    }
+    allowedEffects = ["copy"];
+  }
+  return {
+    offers: normalizeOffers(candidate.offers),
+    preview: normalizePreview(candidate.preview),
+    pointer: {
+      x: requireFiniteNumber(pointer.x, "pointer.x"),
+      y: requireFiniteNumber(pointer.y, "pointer.y")
+    },
+    allowedEffects
+  };
+}
+function canvasToPng(canvas) {
+  if (typeof canvas.toBlob === "function") {
+    return new Promise((resolve, reject) => {
+      canvas.toBlob((blob) => {
+        if (!blob) {
+          reject(new Error("Could not encode the drag preview as PNG."));
+          return;
+        }
+        void blob.arrayBuffer().then(resolve, reject);
+      }, "image/png");
+    });
+  }
+  if (typeof canvas.toDataURL !== "function") {
+    return Promise.resolve(MINIMAL_DRAG_PREVIEW_PNG.buffer.slice(0));
+  }
+  const dataUrl = canvas.toDataURL("image/png");
+  const encoded = dataUrl.split(",")[1];
+  if (!encoded) {
+    return Promise.resolve(MINIMAL_DRAG_PREVIEW_PNG.buffer.slice(0));
+  }
+  const binary = atob(encoded);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return Promise.resolve(bytes.buffer);
+}
+function drawFallbackCard(element, width, height) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext("2d");
+  if (!context) {
+    return null;
+  }
+  context.fillStyle = "#1c2333";
+  context.fillRect(0, 0, width, height);
+  context.strokeStyle = "#6ea8fe";
+  context.strokeRect(0.5, 0.5, width - 1, height - 1);
+  context.fillStyle = "#f4f7fb";
+  context.font = "12px sans-serif";
+  const label = (element.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 48);
+  context.fillText(label || "Drag", 8, Math.min(20, height - 6));
+  return canvas;
+}
+function scaledPreviewSize(width, height) {
+  const safeWidth = Math.max(1, Math.round(width));
+  const safeHeight = Math.max(1, Math.round(height));
+  const scale = Math.min(1, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE / Math.max(safeWidth, safeHeight));
+  return {
+    width: Math.max(1, Math.round(safeWidth * scale)),
+    height: Math.max(1, Math.round(safeHeight * scale))
+  };
+}
+async function snapshotElementToPng(element) {
+  const bounds = element.getBoundingClientRect();
+  const size = scaledPreviewSize(bounds.width || 160, bounds.height || 72);
+  const canvas = drawFallbackCard(element, size.width, size.height);
+  const png = canvas ? await canvasToPng(canvas) : MINIMAL_DRAG_PREVIEW_PNG.buffer.slice(0);
+  if (png.byteLength > MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES) {
+    throw new MindooDBAppDragInputError(
+      `Drag preview exceeds ${MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES} bytes.`
+    );
+  }
+  return {
+    png,
+    width: size.width,
+    height: size.height,
+    hotspotX: size.width / 2,
+    hotspotY: size.height / 2
+  };
+}
+function pointerDistance(origin, event) {
+  const dx = event.clientX - origin.x;
+  const dy = event.clientY - origin.y;
+  return Math.hypot(dx, dy);
+}
+function readOffers(options) {
+  return typeof options.offers === "function" ? options.offers() : options.offers;
+}
+function readPreviewElement(source, options) {
+  if (!options.preview) {
+    return source;
+  }
+  return typeof options.preview === "function" ? options.preview() : options.preview;
+}
+function bindDragSource(element, options, start) {
+  const longPressMs = options.longPressMs ?? DEFAULT_DRAG_LONG_PRESS_MS;
+  const thresholdPx = options.pointerThresholdPx ?? DEFAULT_DRAG_POINTER_THRESHOLD_PX;
+  let active = null;
+  const reset = () => {
+    if (active?.timer != null) {
+      clearTimeout(active.timer);
+    }
+    active = null;
+  };
+  const beginHostDrag = async (event) => {
+    if (!active || active.started) {
+      return;
+    }
+    active.started = true;
+    if (active.timer != null) {
+      clearTimeout(active.timer);
+      active.timer = null;
+    }
+    const offers = readOffers(options);
+    if (offers.length === 0) {
+      reset();
+      return;
+    }
+    event.preventDefault();
+    const preview = await active.preview;
+    const hotX = event.clientX - element.getBoundingClientRect().left;
+    const hotY = event.clientY - element.getBoundingClientRect().top;
+    await start({
+      offers,
+      preview: {
+        ...preview,
+        hotspotX: hotX,
+        hotspotY: hotY
+      },
+      pointer: { x: event.clientX, y: event.clientY },
+      allowedEffects: ["copy"]
+    });
+  };
+  const onPointerDown = (event) => {
+    if (event.button !== 0) {
+      return;
+    }
+    reset();
+    const previewElement = readPreviewElement(element, options);
+    active = {
+      pointerId: event.pointerId,
+      origin: { x: event.clientX, y: event.clientY },
+      pointerType: event.pointerType,
+      preview: snapshotElementToPng(previewElement).catch(() => ({
+        png: MINIMAL_DRAG_PREVIEW_PNG.buffer.slice(0),
+        width: Math.max(1, Math.round(previewElement.getBoundingClientRect().width) || 160),
+        height: Math.max(1, Math.round(previewElement.getBoundingClientRect().height) || 72),
+        hotspotX: 0,
+        hotspotY: 0
+      })),
+      timer: null,
+      started: false
+    };
+    if (event.pointerType === "touch") {
+      active.timer = setTimeout(() => {
+        if (!active || active.started) {
+          return;
+        }
+        void beginHostDrag(event);
+      }, longPressMs);
+    }
+  };
+  const onPointerMove = (event) => {
+    if (!active || event.pointerId !== active.pointerId || active.started) {
+      return;
+    }
+    const distance = pointerDistance(active.origin, event);
+    if (active.pointerType === "touch") {
+      if (distance > thresholdPx) {
+        reset();
+      }
+      return;
+    }
+    if (distance >= thresholdPx) {
+      void beginHostDrag(event);
+    }
+  };
+  const onPointerUp = (event) => {
+    if (!active || event.pointerId !== active.pointerId) {
+      return;
+    }
+    reset();
+  };
+  element.addEventListener("pointerdown", onPointerDown);
+  window.addEventListener("pointermove", onPointerMove);
+  window.addEventListener("pointerup", onPointerUp);
+  window.addEventListener("pointercancel", onPointerUp);
+  return () => {
+    reset();
+    element.removeEventListener("pointerdown", onPointerDown);
+    window.removeEventListener("pointermove", onPointerMove);
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerUp);
+  };
+}
+
+// src/hostShortcuts.ts
+var DEFAULT_HAVEN_HOST_SHORTCUTS = [
+  { action: "open-workspace", code: "Enter", shiftKey: true, metaOrCtrl: true },
+  { action: "toggle-app-drawer", code: "Space", shiftKey: true, metaOrCtrl: true }
+];
+var HOST_SHORTCUT_ACTIONS = /* @__PURE__ */ new Set([
+  "open-workspace",
+  "toggle-app-drawer"
+]);
+function normalizeShortcutCode(code) {
+  return code === "NumpadEnter" ? "Enter" : code;
+}
+function matchHostShortcut(event, shortcuts = DEFAULT_HAVEN_HOST_SHORTCUTS) {
+  if (event.repeat || event.altKey) {
+    return null;
+  }
+  const primary = event.metaKey || event.ctrlKey;
+  const code = normalizeShortcutCode(event.code);
+  for (const binding of shortcuts) {
+    if (code !== binding.code) {
+      continue;
+    }
+    if (Boolean(event.shiftKey) !== Boolean(binding.shiftKey)) {
+      continue;
+    }
+    if (Boolean(binding.metaOrCtrl) !== primary) {
+      continue;
+    }
+    return binding.action;
+  }
+  return null;
+}
+function isHostShortcutAction(value) {
+  return typeof value === "string" && HOST_SHORTCUT_ACTIONS.has(value);
+}
+function sanitizeHostShortcutBindings(value) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const bindings = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") {
+      return null;
+    }
+    const candidate = entry;
+    if (!isHostShortcutAction(candidate.action) || typeof candidate.code !== "string" || !candidate.code) {
+      return null;
+    }
+    bindings.push({
+      action: candidate.action,
+      code: candidate.code,
+      shiftKey: Boolean(candidate.shiftKey),
+      metaOrCtrl: Boolean(candidate.metaOrCtrl)
+    });
+  }
+  return bindings;
+}
+function applyHostedDocumentOverscrollContain(doc = globalThis.document) {
+  if (!doc?.documentElement) {
+    return;
+  }
+  doc.documentElement.style.overscrollBehavior = "contain";
+  if (doc.body) {
+    doc.body.style.overscrollBehavior = "contain";
+  }
+}
+function installHostShortcutCapture(options) {
+  const target = options.target ?? (typeof document === "undefined" ? void 0 : document);
+  if (!target) {
+    return () => void 0;
+  }
+  const onKeyDown = (event) => {
+    const action = matchHostShortcut(event, options.getShortcuts());
+    if (!action) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    options.onInvoke(action);
+  };
+  target.addEventListener("keydown", onKeyDown, true);
+  return () => {
+    target.removeEventListener("keydown", onKeyDown, true);
+  };
+}
+
 // src/client/createMindooDBAppBridge.ts
 import { parseMindooDBFormulaBooleanExpression } from "mindoodb-view-language";
 
@@ -201,6 +628,15 @@ function isUiPreferencesChangedMessage(message) {
 function isLocaleChangedMessage(message) {
   return message.kind === "locale-changed";
 }
+function isDragOverMessage(message) {
+  return message.kind === "drag-over";
+}
+function isDragLeaveMessage(message) {
+  return message.kind === "drag-leave";
+}
+function isDragDropMessage(message) {
+  return message.kind === "drag-drop";
+}
 function toStreamError(message) {
   const error = new Error(message.error.message);
   error.name = message.error.code || "MindooDBAppBridgeStreamError";
@@ -755,11 +1191,11 @@ var MindooDBAppDatabaseImpl = class {
           }
           const ids = [];
           for (const input of inputs) {
-            const document = await this.rpc.call("documents.create", {
+            const document2 = await this.rpc.call("documents.create", {
               databaseId: this.databaseId,
               input
             });
-            ids.push(document.id);
+            ids.push(document2.id);
           }
           return { ids };
         }
@@ -1077,8 +1513,72 @@ var MindooDBAppDatabaseImpl = class {
     });
   }
 };
+var MindooDBAppDragApiImpl = class {
+  constructor(rpc) {
+    this.rpc = rpc;
+    this.rpc.addMessageListener((message) => {
+      if (isDragOverMessage(message)) {
+        const result = this.profile?.onOver?.({
+          x: message.x,
+          y: message.y,
+          types: message.types
+        });
+        const accept = result?.accept ?? true;
+        void this.rpc.call("drag.reportHover", {
+          accept,
+          effect: accept ? result?.effect ?? "copy" : "forbidden"
+        }).catch((error) => {
+          console.warn("[mindoodb-app-sdk] Could not report a drag hover.", error);
+        });
+        return;
+      }
+      if (isDragLeaveMessage(message)) {
+        this.profile?.onLeave?.();
+        return;
+      }
+      if (isDragDropMessage(message)) {
+        this.profile?.onDrop?.({
+          x: message.x,
+          y: message.y,
+          items: message.items
+        });
+      }
+    });
+  }
+  rpc;
+  profile = null;
+  unbindSources = /* @__PURE__ */ new Set();
+  async setProfile(profile) {
+    this.profile = profile;
+    await this.rpc.call("drag.setProfile", {
+      accepts: normalizeDragAccepts(profile.accepts)
+    });
+  }
+  async start(input) {
+    return await this.rpc.call(
+      "drag.start",
+      normalizeDragStartInput(input)
+    );
+  }
+  async cancel() {
+    await this.rpc.call("drag.cancel", {});
+  }
+  bindSource(element, options) {
+    const unbind = bindDragSource(element, options, (input) => this.start(input));
+    this.unbindSources.add(unbind);
+    return () => {
+      unbind();
+      this.unbindSources.delete(unbind);
+    };
+  }
+  dispose() {
+    this.unbindSources.forEach((unbind) => unbind());
+    this.unbindSources.clear();
+    this.profile = null;
+  }
+};
 var MindooDBAppSessionImpl = class {
-  constructor(rpc, onDisconnect) {
+  constructor(rpc, onDisconnect, hostShortcutsEnabled = true) {
     this.rpc = rpc;
     this.onDisconnect = onDisconnect;
     this.menus = {
@@ -1087,6 +1587,7 @@ var MindooDBAppSessionImpl = class {
         await this.rpc.call("menus.hide", {});
       }
     };
+    this.drag = new MindooDBAppDragApiImpl(this.rpc);
     this.storage = {
       snapshot: async (options) => await this.rpc.call("appStorage.snapshot", {
         prefixes: options?.prefixes
@@ -1107,13 +1608,39 @@ var MindooDBAppSessionImpl = class {
       if (message.kind === "before-close") {
         void this.handleBeforeClose(message.closeId);
       }
+      if (message.kind === "shortcuts-changed") {
+        const next = sanitizeHostShortcutBindings(message.shortcuts);
+        if (next) {
+          this.hostShortcuts = next;
+        }
+      }
     });
+    this.stopHostShortcuts = hostShortcutsEnabled ? installHostShortcutCapture({
+      getShortcuts: () => this.hostShortcuts,
+      onInvoke: (action) => {
+        if (!isHostShortcutAction(action)) {
+          return;
+        }
+        try {
+          this.rpc.postMessage({
+            protocol: PROTOCOL2,
+            kind: "shortcut-invoked",
+            action
+          });
+        } catch (error) {
+          console.warn("[mindoodb-app-sdk] Could not report a host shortcut.", error);
+        }
+      }
+    }) : () => void 0;
   }
   rpc;
   onDisconnect;
   menus;
+  drag;
   storage;
   beforeCloseListeners = /* @__PURE__ */ new Set();
+  hostShortcuts = DEFAULT_HAVEN_HOST_SHORTCUTS;
+  stopHostShortcuts;
   /**
    * Lets every listener finish, then tells the host it may proceed.
    *
@@ -1251,6 +1778,8 @@ var MindooDBAppSessionImpl = class {
   }
   /** Disconnects from the host and always disposes the underlying port client. */
   async disconnect() {
+    this.stopHostShortcuts();
+    this.drag.dispose();
     try {
       await this.rpc.call("session.disconnect", {});
     } finally {
@@ -1277,12 +1806,17 @@ function createMindooDBAppBridge() {
       }
       const pending = (async () => {
         const port = await waitForConnectedPort(options, launchId);
+        applyHostedDocumentOverscrollContain();
         const rpc = new PortRpcClient(port);
-        return new MindooDBAppSessionImpl(rpc, () => {
-          if (sessionsByLaunchId.get(launchId) === pending) {
-            sessionsByLaunchId.delete(launchId);
-          }
-        });
+        return new MindooDBAppSessionImpl(
+          rpc,
+          () => {
+            if (sessionsByLaunchId.get(launchId) === pending) {
+              sessionsByLaunchId.delete(launchId);
+            }
+          },
+          options?.hostShortcuts !== false
+        );
       })();
       sessionsByLaunchId.set(launchId, pending);
       try {
@@ -1298,6 +1832,25 @@ function createMindooDBAppBridge() {
 }
 
 export {
+  MINDOODB_APP_MAX_DRAG_TYPES,
+  MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE,
+  DEFAULT_DRAG_LONG_PRESS_MS,
+  DEFAULT_DRAG_POINTER_THRESHOLD_PX,
+  MINIMAL_DRAG_PREVIEW_PNG,
+  MindooDBAppDragInputError,
+  isMindooDBAppDragType,
+  normalizeDragAccepts,
+  normalizeDragStartInput,
+  snapshotElementToPng,
+  bindDragSource,
+  DEFAULT_HAVEN_HOST_SHORTCUTS,
+  matchHostShortcut,
+  isHostShortcutAction,
+  sanitizeHostShortcutBindings,
+  applyHostedDocumentOverscrollContain,
+  installHostShortcutCapture,
   releaseMindooDBAppBridgeSessions,
   createMindooDBAppBridge
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppBridge, b as MindooDBAppHostingMode, c as MindooDBAppDatabase, d as MindooDBAppDocument, e as MindooDBAppRichTextSpan, f as MindooDBAppRichTextSnapshot } from './types-DxnCg5IW.js';
-export { g as MINDOODB_APP_SEAL_SIGNING_DOMAIN, h as MindooDBAppAccessDecision, i as MindooDBAppAccessTier, j as MindooDBAppAttachmentApi, k as MindooDBAppAttachmentChunk, l as MindooDBAppAttachmentInfo, m as MindooDBAppAttachmentPreviewOptions, n as MindooDBAppAttachmentPreviewSession, o as MindooDBAppAutomergeChangesPatch, p as MindooDBAppAutomergeChangesSince, q as MindooDBAppAutomergeGetOptions, r as MindooDBAppAutomergePatchResult, s as MindooDBAppAutomergeSnapshot, t as MindooDBAppBridgeBeforeCloseAck, u as MindooDBAppBridgeBeforeCloseMessage, v as MindooDBAppBridgeConnectMessage, w as MindooDBAppBridgeConnectOptions, x as MindooDBAppBridgeConnectedMessage, y as MindooDBAppBridgeErrorPayload, z as MindooDBAppBridgeHandshakeErrorMessage, A as MindooDBAppBridgeLocaleChangedMessage, B as MindooDBAppBridgePortMessage, C as MindooDBAppBridgeQueryResultMessage, D as MindooDBAppBridgeRpcError, E as MindooDBAppBridgeRpcMessage, F as MindooDBAppBridgeRpcRequest, G as MindooDBAppBridgeRpcSuccess, H as MindooDBAppBridgeStreamAbortRequest, I as MindooDBAppBridgeStreamAck, J as MindooDBAppBridgeStreamCloseRequest, K as MindooDBAppBridgeStreamError, L as MindooDBAppBridgeStreamMessage, N as MindooDBAppBridgeStreamOpenResult, O as MindooDBAppBridgeStreamReadRequest, P as MindooDBAppBridgeStreamWriteRequest, Q as MindooDBAppBridgeThemeChangedMessage, R as MindooDBAppBridgeUiPreferencesChangedMessage, S as MindooDBAppBridgeViewChangedMessage, T as MindooDBAppBridgeViewportChangedMessage, U as MindooDBAppCapability, V as MindooDBAppConfiguredViewCategorizationStyle, W as MindooDBAppConfiguredViewColumn, X as MindooDBAppConfiguredViewColumnRole, Y as MindooDBAppConfiguredViewExpressionMode, Z as MindooDBAppConfiguredViewFieldExpression, _ as MindooDBAppConfiguredViewFilterDefinition, $ as MindooDBAppConfiguredViewFilterMode, a0 as MindooDBAppConfiguredViewFilterRule, a1 as MindooDBAppConfiguredViewFormulaExpression, a2 as MindooDBAppConfiguredViewFormulaFilterDefinition, a3 as MindooDBAppConfiguredViewPreviewMode, a4 as MindooDBAppConfiguredViewRuleFilterDefinition, a5 as MindooDBAppConfiguredViewRuleMatchMode, a6 as MindooDBAppConfiguredViewRuleOperator, a7 as MindooDBAppConfiguredViewValueExpression, a8 as MindooDBAppCreateDocumentInput, a9 as MindooDBAppCreateKeyInfo, aa as MindooDBAppCreateViewInput, ab as MindooDBAppCreateViewNavigatorInput, ac as MindooDBAppDatabaseInfo, ad as MindooDBAppDirectoryApi, ae as MindooDBAppDirectoryEntry, af as MindooDBAppDocumentApi, ag as MindooDBAppDocumentHeadCursorResult, ah as MindooDBAppDocumentHistoryEntry, ai as MindooDBAppDocumentListQuery, aj as MindooDBAppDocumentListResult, ak as MindooDBAppDocumentQuery, al as MindooDBAppDocumentRevisionId, am as MindooDBAppDocumentScanPreset, an as MindooDBAppDocumentSummary, ao as MindooDBAppEntryAttachmentRef, ap as MindooDBAppEntryProvenance, aq as MindooDBAppExtractDocumentTextInput, ar as MindooDBAppExtractDocumentTextResult, as as MindooDBAppExtractTextFormat, at as MindooDBAppExtractionSetup, au as MindooDBAppFulltextSetup, av as MindooDBAppHistoricalDocument, aw as MindooDBAppHistoryQuery, ax as MindooDBAppHostTheme, ay as MindooDBAppIdentityApi, az as MindooDBAppInaccessibleDocument, aA as MindooDBAppInaccessibleDocumentListQuery, aB as MindooDBAppInaccessibleDocumentListResult, aC as MindooDBAppJsonListDeletePatch, aD as MindooDBAppJsonListInsertPatch, aE as MindooDBAppJsonPatch, aF as MindooDBAppJsonSetPatch, aG as MindooDBAppJsonTextMarkPatch, aH as MindooDBAppJsonTextSplicePatch, aI as MindooDBAppJsonTextUnmarkPatch, aJ as MindooDBAppJsonUnsetPatch, aK as MindooDBAppLaunchContext, aL as MindooDBAppLiveQuerySubscription, aM as MindooDBAppMenuAnchor, aN as MindooDBAppMenuApi, aO as MindooDBAppMenuCommandItem, aP as MindooDBAppMenuDismissReason, aQ as MindooDBAppMenuDismissedResult, aR as MindooDBAppMenuItem, aS as MindooDBAppMenuKind, aT as MindooDBAppMenuPlacement, aU as MindooDBAppMenuPointAnchor, aV as MindooDBAppMenuRect, aW as MindooDBAppMenuRectAnchor, aX as MindooDBAppMenuSelectionResult, aY as MindooDBAppMenuSeparatorItem, aZ as MindooDBAppQueryCoverage, a_ as MindooDBAppQueryResult, a$ as MindooDBAppQueryRow, b0 as MindooDBAppQuerySortKey, b1 as MindooDBAppQueryTextClause, b2 as MindooDBAppReadableAttachmentStream, b3 as MindooDBAppRecipientOptions, b4 as MindooDBAppResolvedViewDefinition, b5 as MindooDBAppResolvedViewSource, b6 as MindooDBAppRevisionPhase, b7 as MindooDBAppRevisionVerification, b8 as MindooDBAppRichTextBlockSpan, b9 as MindooDBAppRichTextGetOptions, ba as MindooDBAppRichTextImmutableString, bb as MindooDBAppRichTextMarkRange, bc as MindooDBAppRichTextMaterializeValue, bd as MindooDBAppRichTextPatch, be as MindooDBAppRichTextScalar, bf as MindooDBAppRichTextSpliceStep, bg as MindooDBAppRichTextStep, bh as MindooDBAppRichTextStepPatch, bi as MindooDBAppRichTextTextSpan, bj as MindooDBAppRuntime, bk as MindooDBAppScanAttachmentOptions, bl as MindooDBAppScanAttachmentResult, bm as MindooDBAppScopedDocId, bn as MindooDBAppScopedDocumentSummary, bo as MindooDBAppSealIntent, bp as MindooDBAppSealedChannelOpenInput, bq as MindooDBAppSealedChannelOpenResult, br as MindooDBAppSealedChannelRequestInput, bs as MindooDBAppSession, bt as MindooDBAppShowMenuInput, bu as MindooDBAppShowMenuResult, bv as MindooDBAppSignPreview, bw as MindooDBAppSignPreviewScope, bx as MindooDBAppSignStatementInput, by as MindooDBAppSignStatementResult, bz as MindooDBAppStorageApi, bA as MindooDBAppTextEdit, bB as MindooDBAppTextPatch, bC as MindooDBAppThemeMode, bD as MindooDBAppTimestampApi, bE as MindooDBAppTimestampInput, bF as MindooDBAppTimestampProvider, bG as MindooDBAppTimestampResult, bH as MindooDBAppUiPreferences, bI as MindooDBAppUpdateDocumentInput, bJ as MindooDBAppViewCursorDocumentListResult, bK as MindooDBAppViewCursorResult, bL as MindooDBAppViewEntry, bM as MindooDBAppViewEntryKind, bN as MindooDBAppViewNavigator, bO as MindooDBAppViewNavigatorExpansionState, bP as MindooDBAppViewNavigatorOpenOptions, bQ as MindooDBAppViewNavigatorPageOptions, bR as MindooDBAppViewNavigatorPageResult, bS as MindooDBAppViewNavigatorRangeQuery, bT as MindooDBAppViewNavigatorSelectionState, bU as MindooDBAppViewUpdateStats, bV as MindooDBAppViewport, bW as MindooDBAppWritableAttachmentStream } from './types-DxnCg5IW.js';
+import { M as MindooDBAppAttachmentPreviewMode, a as MindooDBAppDragBindSourceOptions, b as MindooDBAppDragStartInput, c as MindooDBAppDragStartResult, d as MindooDBAppDragPreview, e as MindooDBAppBridge, f as MindooDBAppHostShortcutBinding, g as MindooDBAppHostShortcutAction, h as MindooDBAppHostingMode, i as MindooDBAppDatabase, j as MindooDBAppDocument, k as MindooDBAppRichTextSpan, l as MindooDBAppRichTextSnapshot } from './types-M3RwHErO.js';
+export { m as MINDOODB_APP_SEAL_SIGNING_DOMAIN, n as MINDOODB_APP_WELL_KNOWN_DRAG_TYPES, o as MindooDBAppAccessDecision, p as MindooDBAppAccessTier, q as MindooDBAppAttachmentApi, r as MindooDBAppAttachmentChunk, s as MindooDBAppAttachmentInfo, t as MindooDBAppAttachmentPreviewOptions, u as MindooDBAppAttachmentPreviewSession, v as MindooDBAppAutomergeChangesPatch, w as MindooDBAppAutomergeChangesSince, x as MindooDBAppAutomergeGetOptions, y as MindooDBAppAutomergePatchResult, z as MindooDBAppAutomergeSnapshot, A as MindooDBAppBridgeBeforeCloseAck, B as MindooDBAppBridgeBeforeCloseMessage, C as MindooDBAppBridgeConnectMessage, D as MindooDBAppBridgeConnectOptions, E as MindooDBAppBridgeConnectedMessage, F as MindooDBAppBridgeDragDropMessage, G as MindooDBAppBridgeDragLeaveMessage, H as MindooDBAppBridgeDragOverMessage, I as MindooDBAppBridgeErrorPayload, J as MindooDBAppBridgeHandshakeErrorMessage, K as MindooDBAppBridgeLocaleChangedMessage, L as MindooDBAppBridgePortMessage, N as MindooDBAppBridgeQueryResultMessage, O as MindooDBAppBridgeRpcError, P as MindooDBAppBridgeRpcMessage, Q as MindooDBAppBridgeRpcRequest, R as MindooDBAppBridgeRpcSuccess, S as MindooDBAppBridgeShortcutInvokedMessage, T as MindooDBAppBridgeShortcutsChangedMessage, U as MindooDBAppBridgeStreamAbortRequest, V as MindooDBAppBridgeStreamAck, W as MindooDBAppBridgeStreamCloseRequest, X as MindooDBAppBridgeStreamError, Y as MindooDBAppBridgeStreamMessage, Z as MindooDBAppBridgeStreamOpenResult, _ as MindooDBAppBridgeStreamReadRequest, $ as MindooDBAppBridgeStreamWriteRequest, a0 as MindooDBAppBridgeThemeChangedMessage, a1 as MindooDBAppBridgeUiPreferencesChangedMessage, a2 as MindooDBAppBridgeViewChangedMessage, a3 as MindooDBAppBridgeViewportChangedMessage, a4 as MindooDBAppCapability, a5 as MindooDBAppConfiguredViewCategorizationStyle, a6 as MindooDBAppConfiguredViewColumn, a7 as MindooDBAppConfiguredViewColumnRole, a8 as MindooDBAppConfiguredViewExpressionMode, a9 as MindooDBAppConfiguredViewFieldExpression, aa as MindooDBAppConfiguredViewFilterDefinition, ab as MindooDBAppConfiguredViewFilterMode, ac as MindooDBAppConfiguredViewFilterRule, ad as MindooDBAppConfiguredViewFormulaExpression, ae as MindooDBAppConfiguredViewFormulaFilterDefinition, af as MindooDBAppConfiguredViewPreviewMode, ag as MindooDBAppConfiguredViewRuleFilterDefinition, ah as MindooDBAppConfiguredViewRuleMatchMode, ai as MindooDBAppConfiguredViewRuleOperator, aj as MindooDBAppConfiguredViewValueExpression, ak as MindooDBAppCreateDocumentInput, al as MindooDBAppCreateKeyInfo, am as MindooDBAppCreateViewInput, an as MindooDBAppCreateViewNavigatorInput, ao as MindooDBAppDatabaseInfo, ap as MindooDBAppDirectoryApi, aq as MindooDBAppDirectoryEntry, ar as MindooDBAppDocumentApi, as as MindooDBAppDocumentHeadCursorResult, at as MindooDBAppDocumentHistoryEntry, au as MindooDBAppDocumentListQuery, av as MindooDBAppDocumentListResult, aw as MindooDBAppDocumentQuery, ax as MindooDBAppDocumentRevisionId, ay as MindooDBAppDocumentScanPreset, az as MindooDBAppDocumentSummary, aA as MindooDBAppDragApi, aB as MindooDBAppDragCancelReason, aC as MindooDBAppDragDropEvent, aD as MindooDBAppDragEffect, aE as MindooDBAppDragHoverResult, aF as MindooDBAppDragOffer, aG as MindooDBAppDragOverEvent, aH as MindooDBAppDragPointer, aI as MindooDBAppDragProfile, aJ as MindooDBAppEntryAttachmentRef, aK as MindooDBAppEntryProvenance, aL as MindooDBAppExtractDocumentTextInput, aM as MindooDBAppExtractDocumentTextResult, aN as MindooDBAppExtractTextFormat, aO as MindooDBAppExtractionSetup, aP as MindooDBAppFulltextSetup, aQ as MindooDBAppHistoricalDocument, aR as MindooDBAppHistoryQuery, aS as MindooDBAppHostTheme, aT as MindooDBAppIdentityApi, aU as MindooDBAppInaccessibleDocument, aV as MindooDBAppInaccessibleDocumentListQuery, aW as MindooDBAppInaccessibleDocumentListResult, aX as MindooDBAppJsonListDeletePatch, aY as MindooDBAppJsonListInsertPatch, aZ as MindooDBAppJsonPatch, a_ as MindooDBAppJsonSetPatch, a$ as MindooDBAppJsonTextMarkPatch, b0 as MindooDBAppJsonTextSplicePatch, b1 as MindooDBAppJsonTextUnmarkPatch, b2 as MindooDBAppJsonUnsetPatch, b3 as MindooDBAppLaunchContext, b4 as MindooDBAppLiveQuerySubscription, b5 as MindooDBAppMenuAnchor, b6 as MindooDBAppMenuApi, b7 as MindooDBAppMenuCommandItem, b8 as MindooDBAppMenuDismissReason, b9 as MindooDBAppMenuDismissedResult, ba as MindooDBAppMenuItem, bb as MindooDBAppMenuKind, bc as MindooDBAppMenuPlacement, bd as MindooDBAppMenuPointAnchor, be as MindooDBAppMenuRect, bf as MindooDBAppMenuRectAnchor, bg as MindooDBAppMenuSelectionResult, bh as MindooDBAppMenuSeparatorItem, bi as MindooDBAppQueryCoverage, bj as MindooDBAppQueryResult, bk as MindooDBAppQueryRow, bl as MindooDBAppQuerySortKey, bm as MindooDBAppQueryTextClause, bn as MindooDBAppReadableAttachmentStream, bo as MindooDBAppRecipientOptions, bp as MindooDBAppResolvedViewDefinition, bq as MindooDBAppResolvedViewSource, br as MindooDBAppRevisionPhase, bs as MindooDBAppRevisionVerification, bt as MindooDBAppRichTextBlockSpan, bu as MindooDBAppRichTextGetOptions, bv as MindooDBAppRichTextImmutableString, bw as MindooDBAppRichTextMarkRange, bx as MindooDBAppRichTextMaterializeValue, by as MindooDBAppRichTextPatch, bz as MindooDBAppRichTextScalar, bA as MindooDBAppRichTextSpliceStep, bB as MindooDBAppRichTextStep, bC as MindooDBAppRichTextStepPatch, bD as MindooDBAppRichTextTextSpan, bE as MindooDBAppRuntime, bF as MindooDBAppScanAttachmentOptions, bG as MindooDBAppScanAttachmentResult, bH as MindooDBAppScopedDocId, bI as MindooDBAppScopedDocumentSummary, bJ as MindooDBAppSealIntent, bK as MindooDBAppSealedChannelOpenInput, bL as MindooDBAppSealedChannelOpenResult, bM as MindooDBAppSealedChannelRequestInput, bN as MindooDBAppSession, bO as MindooDBAppShowMenuInput, bP as MindooDBAppShowMenuResult, bQ as MindooDBAppSignPreview, bR as MindooDBAppSignPreviewScope, bS as MindooDBAppSignStatementInput, bT as MindooDBAppSignStatementResult, bU as MindooDBAppStorageApi, bV as MindooDBAppTextEdit, bW as MindooDBAppTextPatch, bX as MindooDBAppThemeMode, bY as MindooDBAppTimestampApi, bZ as MindooDBAppTimestampInput, b_ as MindooDBAppTimestampProvider, b$ as MindooDBAppTimestampResult, c0 as MindooDBAppUiPreferences, c1 as MindooDBAppUpdateDocumentInput, c2 as MindooDBAppViewCursorDocumentListResult, c3 as MindooDBAppViewCursorResult, c4 as MindooDBAppViewEntry, c5 as MindooDBAppViewEntryKind, c6 as MindooDBAppViewNavigator, c7 as MindooDBAppViewNavigatorExpansionState, c8 as MindooDBAppViewNavigatorOpenOptions, c9 as MindooDBAppViewNavigatorPageOptions, ca as MindooDBAppViewNavigatorPageResult, cb as MindooDBAppViewNavigatorRangeQuery, cc as MindooDBAppViewNavigatorSelectionState, cd as MindooDBAppViewUpdateStats, ce as MindooDBAppViewport, cf as MindooDBAppWellKnownDragType, cg as MindooDBAppWritableAttachmentStream } from './types-M3RwHErO.js';
 export { M as MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME, a as MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME, b as MINDOODB_APP_BUNDLE_MANIFEST_FORMAT, c as MINDOODB_APP_BUNDLE_MANIFEST_VERSION, d as MindooDBAppBundleArchive, e as MindooDBAppBundleFileEntry, f as MindooDBAppBundleHash, g as MindooDBAppBundleManifest, h as MindooDBAppBundleManifestValidation, i as buildMindooDBAppBundleContentHashInput, j as isMindooDBAppBundleHash, n as normalizeMindooDBAppBundlePath, v as validateMindooDBAppBundleManifest } from './appBundleManifest-B0xfpaXG.js';
 import { MindooDBAppBooleanExpression } from 'mindoodb-view-language';
 export { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppFilterDefinition, MindooDBAppViewCategoryChildrenPageRequest, MindooDBAppViewColumn, MindooDBAppViewColumnRole, MindooDBAppViewDefinition, MindooDBAppViewExpansionState, MindooDBAppViewExpressionBase, MindooDBAppViewExpressionDatePart, MindooDBAppViewExpressionOperation, MindooDBAppViewFieldExpression, MindooDBAppViewIfExpression, MindooDBAppViewLetExpression, MindooDBAppViewLiteralExpression, MindooDBAppViewLookupByPath, MindooDBAppViewOperationExpression, MindooDBAppViewOriginExpression, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewRow, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewValueExpressionRef, MindooDBAppViewVariableExpression, createViewLanguage } from 'mindoodb-view-language';
@@ -31,6 +31,57 @@ declare function abbreviateCanonicalName(value: string): string;
  */
 declare function expandAbbreviatedName(value: string): string;
 
+/**
+ * Client helpers for host-owned cross-iframe drag.
+ *
+ * Validation lives here so the SDK rejects bad `start` / `setProfile`
+ * payloads before they cross the bridge. Haven re-validates the same
+ * limits on untyped JSON. `bindDragSource` and `snapshotElementToPng`
+ * stay in the app document: Haven only ever receives PNG bytes and
+ * string snapshots.
+ *
+ * @module drag
+ */
+
+/** Maximum number of types in one profile or start payload. */
+declare const MINDOODB_APP_MAX_DRAG_TYPES = 8;
+/** Maximum UTF-8 size of one offer string. */
+declare const MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES: number;
+/** Maximum encoded PNG size for the host ghost. */
+declare const MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES: number;
+/** Longest CSS-pixel edge Haven will display for a ghost. */
+declare const MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE = 512;
+/** Touch hold before the host takes over. */
+declare const DEFAULT_DRAG_LONG_PRESS_MS = 400;
+/** Mouse/pen start distance, and touch scroll-cancel slop. */
+declare const DEFAULT_DRAG_POINTER_THRESHOLD_PX = 8;
+/**
+ * 1×1 PNG used when the browser cannot snapshot a node. Haven still
+ * sizes the ghost from `preview.width` / `preview.height`.
+ */
+declare const MINIMAL_DRAG_PREVIEW_PNG: Uint8Array<ArrayBuffer>;
+/** Structured validation failure. `name` is the bridge error code. */
+declare class MindooDBAppDragInputError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/** True when `type` is a MIME-like token Haven will accept. */
+declare function isMindooDBAppDragType(type: string): boolean;
+/** Project and validate the `accepts` list sent with `drag.setProfile`. */
+declare function normalizeDragAccepts(value: unknown): string[];
+/** Project and validate a `drag.start` payload. */
+declare function normalizeDragStartInput(value: unknown): MindooDBAppDragStartInput;
+/**
+ * Snapshot an element in the app document. Failures fall back to a labeled
+ * card or a 1×1 PNG — Haven must never receive HTML.
+ */
+declare function snapshotElementToPng(element: HTMLElement): Promise<MindooDBAppDragPreview>;
+/**
+ * Start a host drag from a pointer gesture. Mouse/pen use a move threshold;
+ * touch waits for a long-press so lists can still scroll.
+ */
+declare function bindDragSource(element: HTMLElement, options: MindooDBAppDragBindSourceOptions, start: (input: MindooDBAppDragStartInput) => Promise<MindooDBAppDragStartResult>): () => void;
+
 /**
  * Drops memoised sessions so the next `connect()` performs a fresh handshake.
  *
@@ -54,6 +105,38 @@ declare function releaseMindooDBAppBridgeSessions(launchId?: string): void;
  */
 declare function createMindooDBAppBridge(): MindooDBAppBridge;
 
+/**
+ * Haven's default host chords. Both sides of the bridge use this table so a
+ * key that Haven handles on its own pages is the same key an iframe reports.
+ *
+ * `code` is the physical {@link KeyboardEvent.code}: layout-independent, so
+ * AltGr on a German keyboard cannot turn these into `@` or a nbsp.
+ */
+declare const DEFAULT_HAVEN_HOST_SHORTCUTS: readonly MindooDBAppHostShortcutBinding[];
+/**
+ * Returns the host action for this key event, or `null` when it is not one
+ * of the registered chords. `Alt` is rejected so AltGr (`Ctrl+Alt` on
+ * European Windows layouts) never fires a shortcut while typing.
+ */
+declare function matchHostShortcut(event: Pick<KeyboardEvent, "code" | "shiftKey" | "metaKey" | "ctrlKey" | "altKey" | "repeat">, shortcuts?: readonly MindooDBAppHostShortcutBinding[]): MindooDBAppHostShortcutAction | null;
+declare function isHostShortcutAction(value: unknown): value is MindooDBAppHostShortcutAction;
+/** Accepts a host-pushed table; anything malformed is ignored. */
+declare function sanitizeHostShortcutBindings(value: unknown): MindooDBAppHostShortcutBinding[] | null;
+/**
+ * Stops wheel chaining out of a hosted app document into Haven's workspace
+ * scroller once the app page (or its `body`) has reached its end.
+ */
+declare function applyHostedDocumentOverscrollContain(doc?: Document | undefined): void;
+/**
+ * Capture-phase listener that reports a matched host chord. Returns a disposer.
+ * No-ops when `document` is missing (Node tests that stub only `window`).
+ */
+declare function installHostShortcutCapture(options: {
+    getShortcuts: () => readonly MindooDBAppHostShortcutBinding[];
+    onInvoke: (action: MindooDBAppHostShortcutAction) => void;
+    target?: Document;
+}): () => void;
+
 /**
  * Query parameter the host appends to the app URL so the app can tell how it is being
  * delivered before any asynchronous work has happened.
@@ -274,4 +357,4 @@ declare function createMindooDBTextBuffer(options: CreateMindooDBTextBufferOptio
  */
 declare function queryDocuments(db: Pick<MindooDB, "query">, filter: MindooDBAppBooleanExpression | string, sortBy?: MindooQuerySortKey[], options?: MindooQueryOptions): Promise<MindooQueryResult>;
 
-export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, MINDOODB_APP_HOSTING_QUERY_PARAM, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, MindooDBAppDatabase, MindooDBAppDocument, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, abbreviateCanonicalName, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, installHavenStorageShim, isHostedBundleRuntime, queryDocuments, readMindooDBAppHostingMode, releaseMindooDBAppBridgeSessions };
+export { type CreateMindooDBRichTextHandleOptions, type CreateMindooDBTextBufferOptions, DEFAULT_DRAG_LONG_PRESS_MS, DEFAULT_DRAG_POINTER_THRESHOLD_PX, DEFAULT_HAVEN_HOST_SHORTCUTS, type HavenStorageShimHandle, type InstallHavenStorageShimOptions, MINDOODB_APP_HOSTING_QUERY_PARAM, MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES, MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE, MINDOODB_APP_MAX_DRAG_TYPES, MINIMAL_DRAG_PREVIEW_PNG, MindooDBAppAttachmentPreviewMode, MindooDBAppBridge, MindooDBAppDatabase, MindooDBAppDocument, MindooDBAppDragBindSourceOptions, MindooDBAppDragInputError, MindooDBAppDragPreview, MindooDBAppDragStartInput, MindooDBAppDragStartResult, MindooDBAppHostShortcutAction, MindooDBAppHostShortcutBinding, MindooDBAppHostingMode, MindooDBAppRichTextSnapshot, MindooDBAppRichTextSpan, MindooDBRichTextHandle, type MindooDBRichTextHandleChangeListener, type MindooDBRichTextHandleFlushResult, MindooDBTextBuffer, type MindooDBTextBufferFlushResult, abbreviateCanonicalName, applyHostedDocumentOverscrollContain, bindDragSource, canPreviewAttachment, createMindooDBAppBridge, createMindooDBRichTextHandle, createMindooDBTextBuffer, expandAbbreviatedName, installHavenStorageShim, installHostShortcutCapture, isHostShortcutAction, isHostedBundleRuntime, isMindooDBAppDragType, matchHostShortcut, normalizeDragAccepts, normalizeDragStartInput, queryDocuments, readMindooDBAppHostingMode, releaseMindooDBAppBridgeSessions, sanitizeHostShortcutBindings, snapshotElementToPng };

package/dist/index.js

@@ -1,7 +1,26 @@
 import {
+  DEFAULT_DRAG_LONG_PRESS_MS,
+  DEFAULT_DRAG_POINTER_THRESHOLD_PX,
+  DEFAULT_HAVEN_HOST_SHORTCUTS,
+  MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE,
+  MINDOODB_APP_MAX_DRAG_TYPES,
+  MINIMAL_DRAG_PREVIEW_PNG,
+  MindooDBAppDragInputError,
+  applyHostedDocumentOverscrollContain,
+  bindDragSource,
   createMindooDBAppBridge,
-  releaseMindooDBAppBridgeSessions
-} from "./chunk-6433L6TE.js";
+  installHostShortcutCapture,
+  isHostShortcutAction,
+  isMindooDBAppDragType,
+  matchHostShortcut,
+  normalizeDragAccepts,
+  normalizeDragStartInput,
+  releaseMindooDBAppBridgeSessions,
+  sanitizeHostShortcutBindings,
+  snapshotElementToPng
+} from "./chunk-ZO7UE6B2.js";
 import {
   MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
@@ -14,6 +33,12 @@ import {
 } from "./chunk-LT4FK6LU.js";
 
 // src/types.ts
+var MINDOODB_APP_WELL_KNOWN_DRAG_TYPES = [
+  "text/plain",
+  "text/markdown",
+  "application/json",
+  "application/x-mindoo-document"
+];
 var MINDOODB_APP_SEAL_SIGNING_DOMAIN = "mindoodb-seal/v1";
 
 // src/attachmentPreview.ts
@@ -747,15 +772,27 @@ async function queryDocuments(db, filter, sortBy, options) {
   return db.query({ filter: expression, sortBy }, options);
 }
 export {
+  DEFAULT_DRAG_LONG_PRESS_MS,
+  DEFAULT_DRAG_POINTER_THRESHOLD_PX,
+  DEFAULT_HAVEN_HOST_SHORTCUTS,
   MINDOODB_APP_BUNDLE_ARCHIVE_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FILE_NAME,
   MINDOODB_APP_BUNDLE_MANIFEST_FORMAT,
   MINDOODB_APP_BUNDLE_MANIFEST_VERSION,
   MINDOODB_APP_HOSTING_QUERY_PARAM,
+  MINDOODB_APP_MAX_DRAG_PAYLOAD_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_BYTES,
+  MINDOODB_APP_MAX_DRAG_PREVIEW_EDGE,
+  MINDOODB_APP_MAX_DRAG_TYPES,
   MINDOODB_APP_SEAL_SIGNING_DOMAIN,
+  MINDOODB_APP_WELL_KNOWN_DRAG_TYPES,
+  MINIMAL_DRAG_PREVIEW_PNG,
+  MindooDBAppDragInputError,
   MindooDBRichTextHandle,
   MindooDBTextBuffer,
   abbreviateCanonicalName,
+  applyHostedDocumentOverscrollContain,
+  bindDragSource,
   buildMindooDBAppBundleContentHashInput,
   canPreviewAttachment,
   createMindooDBAppBridge,
@@ -764,11 +801,19 @@ export {
   createViewLanguage,
   expandAbbreviatedName,
   installHavenStorageShim,
+  installHostShortcutCapture,
+  isHostShortcutAction,
   isHostedBundleRuntime,
   isMindooDBAppBundleHash,
+  isMindooDBAppDragType,
+  matchHostShortcut,
+  normalizeDragAccepts,
+  normalizeDragStartInput,
   normalizeMindooDBAppBundlePath,
   queryDocuments,
   readMindooDBAppHostingMode,
   releaseMindooDBAppBridgeSessions,
+  sanitizeHostShortcutBindings,
+  snapshotElementToPng,
   validateMindooDBAppBundleManifest
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { ab as MindooDBAppCreateViewNavigatorInput, bN as MindooDBAppViewNavigator, aK as MindooDBAppLaunchContext, ac as MindooDBAppDatabaseInfo, af as MindooDBAppDocumentApi, bP as MindooDBAppViewNavigatorOpenOptions, j as MindooDBAppAttachmentApi, ay as MindooDBAppIdentityApi, bD as MindooDBAppTimestampApi, ad as MindooDBAppDirectoryApi, d as MindooDBAppDocument, au as MindooDBAppFulltextSetup, at as MindooDBAppExtractionSetup, a as MindooDBAppBridge, bs as MindooDBAppSession, F as MindooDBAppBridgeRpcRequest, ax as MindooDBAppHostTheme, bV as MindooDBAppViewport, bH as MindooDBAppUiPreferences, a_ as MindooDBAppQueryResult, bU as MindooDBAppViewUpdateStats, B as MindooDBAppBridgePortMessage } from '../types-DxnCg5IW.js';
+import { an as MindooDBAppCreateViewNavigatorInput, c6 as MindooDBAppViewNavigator, b3 as MindooDBAppLaunchContext, ao as MindooDBAppDatabaseInfo, ar as MindooDBAppDocumentApi, c8 as MindooDBAppViewNavigatorOpenOptions, q as MindooDBAppAttachmentApi, aT as MindooDBAppIdentityApi, bY as MindooDBAppTimestampApi, ap as MindooDBAppDirectoryApi, j as MindooDBAppDocument, aP as MindooDBAppFulltextSetup, aO as MindooDBAppExtractionSetup, e as MindooDBAppBridge, bN as MindooDBAppSession, Q as MindooDBAppBridgeRpcRequest, aS as MindooDBAppHostTheme, ce as MindooDBAppViewport, c0 as MindooDBAppUiPreferences, bj as MindooDBAppQueryResult, cd as MindooDBAppViewUpdateStats, L as MindooDBAppBridgePortMessage, c as MindooDBAppDragStartResult, aI as MindooDBAppDragProfile } from '../types-M3RwHErO.js';
 import * as mindoodb from 'mindoodb';
 import 'mindoodb-view-language';
 
@@ -115,6 +115,8 @@ interface MockMindooDBAppSessionController {
     emitLocaleChange(locale: string): void;
     /** Runs the app's `onBeforeClose` listeners, as the host does before a teardown. */
     emitBeforeClose(): Promise<void>;
+    resolveDrag(result: MindooDBAppDragStartResult): void;
+    getDragProfile(): MindooDBAppDragProfile | null;
 }
 
 declare function createMockMindooDBAppSession(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;

package/dist/testing/index.js

@@ -1,6 +1,6 @@
 import {
   releaseMindooDBAppBridgeSessions
-} from "../chunk-6433L6TE.js";
+} from "../chunk-ZO7UE6B2.js";
 
 // src/testing/index.ts
 import * as Automerge from "@automerge/automerge";
@@ -1857,6 +1857,8 @@ function createMockSessionState(options = {}) {
   const databaseViewApis = /* @__PURE__ */ new Map();
   const sessionViews = /* @__PURE__ */ new Map();
   let activeMenuResolve = null;
+  let activeDragResolve = null;
+  let dragProfile = null;
   let databaseInfos = [];
   const openSealedChannels = /* @__PURE__ */ new Map();
   const appStorage = new Map(Object.entries(options.storage ?? {}));
@@ -1871,6 +1873,32 @@ function createMockSessionState(options = {}) {
       );
     }
   };
+  const drag = {
+    async setProfile(profile) {
+      dragProfile = profile;
+    },
+    async start(_input) {
+      if (activeDragResolve) {
+        activeDragResolve({
+          action: "cancelled",
+          reason: "replaced"
+        });
+      }
+      return await new Promise((resolve) => {
+        activeDragResolve = resolve;
+      });
+    },
+    async cancel() {
+      activeDragResolve?.({
+        action: "cancelled",
+        reason: "source_cancelled"
+      });
+      activeDragResolve = null;
+    },
+    bindSource() {
+      return () => void 0;
+    }
+  };
   const menus = {
     async show(_input) {
       if (activeMenuResolve) {
@@ -2023,6 +2051,7 @@ function createMockSessionState(options = {}) {
       return view;
     },
     menus,
+    drag,
     storage: {
       async snapshot(snapshotOptions) {
         const prefixes = snapshotOptions?.prefixes;
@@ -2146,6 +2175,13 @@ function createMockSessionState(options = {}) {
     },
     async emitBeforeClose() {
       await Promise.all([...beforeCloseListeners].map(async (listener) => listener()));
+    },
+    resolveDrag(result) {
+      activeDragResolve?.(result);
+      activeDragResolve = null;
+    },
+    getDragProfile() {
+      return dragProfile;
     }
   };
 }
@@ -2163,7 +2199,9 @@ function createMockMindooDBAppSession(options = {}) {
     emitViewportChange: state.emitViewportChange,
     emitUiPreferencesChange: state.emitUiPreferencesChange,
     emitLocaleChange: state.emitLocaleChange,
-    emitBeforeClose: state.emitBeforeClose
+    emitBeforeClose: state.emitBeforeClose,
+    resolveDrag: state.resolveDrag,
+    getDragProfile: state.getDragProfile
   };
 }
 function createMockMindooDBAppBridge(options = {}) {

package/dist/{types-DxnCg5IW.d.ts → types-M3RwHErO.d.ts}

@@ -779,6 +779,12 @@ interface MindooDBAppBridgeConnectOptions {
     targetOrigin?: string;
     /** How long to wait for the host to answer the handshake before rejecting (default 10000 ms). */
     connectTimeoutMs?: number;
+    /**
+     * When `false`, the SDK does not listen for Haven's host keyboard shortcuts
+     * (workspace / app drawer). Default is on: the same chords Haven handles
+     * on its own pages are reported from inside the iframe.
+     */
+    hostShortcuts?: boolean;
 }
 /** Initial postMessage handshake sent from the app to the Haven. */
 interface MindooDBAppBridgeConnectMessage {
@@ -949,8 +955,31 @@ interface MindooDBAppBridgeBeforeCloseAck {
     kind: "before-close-ack";
     closeId: string;
 }
+/** A Haven-owned keyboard chord the iframe should recognise. */
+type MindooDBAppHostShortcutAction = "open-workspace" | "toggle-app-drawer";
+/** One host shortcut, matched against {@link KeyboardEvent.code} plus modifiers. */
+interface MindooDBAppHostShortcutBinding {
+    action: MindooDBAppHostShortcutAction;
+    /** Physical key, e.g. `"Space"` or `"Enter"`. */
+    code: string;
+    shiftKey: boolean;
+    /** Meta (macOS) or Control (Windows/Linux); Alt is never part of the chord. */
+    metaOrCtrl: boolean;
+}
+/** Host-pushed table of chords. The iframe replaces its local copy. */
+interface MindooDBAppBridgeShortcutsChangedMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "shortcuts-changed";
+    shortcuts: MindooDBAppHostShortcutBinding[];
+}
+/** App → host: a host shortcut was pressed inside the iframe. */
+interface MindooDBAppBridgeShortcutInvokedMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "shortcut-invoked";
+    action: MindooDBAppHostShortcutAction;
+}
 /** Any message that can travel across the dedicated bridge MessagePort. */
-type MindooDBAppBridgePortMessage = MindooDBAppBridgeRpcMessage | MindooDBAppBridgeStreamMessage | MindooDBAppBridgeThemeChangedMessage | MindooDBAppBridgeViewportChangedMessage | MindooDBAppBridgeUiPreferencesChangedMessage | MindooDBAppBridgeLocaleChangedMessage | MindooDBAppBridgeQueryResultMessage | MindooDBAppBridgeViewChangedMessage | MindooDBAppBridgeBeforeCloseMessage | MindooDBAppBridgeBeforeCloseAck;
+type MindooDBAppBridgePortMessage = MindooDBAppBridgeRpcMessage | MindooDBAppBridgeStreamMessage | MindooDBAppBridgeThemeChangedMessage | MindooDBAppBridgeViewportChangedMessage | MindooDBAppBridgeUiPreferencesChangedMessage | MindooDBAppBridgeLocaleChangedMessage | MindooDBAppBridgeQueryResultMessage | MindooDBAppBridgeViewChangedMessage | MindooDBAppBridgeBeforeCloseMessage | MindooDBAppBridgeBeforeCloseAck | MindooDBAppBridgeShortcutsChangedMessage | MindooDBAppBridgeShortcutInvokedMessage | MindooDBAppBridgeDragOverMessage | MindooDBAppBridgeDragLeaveMessage | MindooDBAppBridgeDragDropMessage;
 /** Placement hint for a host-rendered overlay menu. */
 type MindooDBAppMenuPlacement = "auto" | "bottom-start" | "bottom-end" | "top-start" | "top-end" | "right-start" | "left-start";
 /** Semantic hint allowing Haven to tune menu behavior or styling. */
@@ -1024,6 +1053,125 @@ type MindooDBAppShowMenuResult = MindooDBAppMenuSelectionResult | MindooDBAppMen
  * data-only (no HTML/CSS/script crosses the bridge). Intended for
  * `runtime === "iframe"`; window-mode apps can usually render local menus.
  */
+/** Well-known copy payloads for host-owned cross-iframe drag. */
+declare const MINDOODB_APP_WELL_KNOWN_DRAG_TYPES: readonly ["text/plain", "text/markdown", "application/json", "application/x-mindoo-document"];
+/** One of the documented interchange types apps should prefer. */
+type MindooDBAppWellKnownDragType = (typeof MINDOODB_APP_WELL_KNOWN_DRAG_TYPES)[number];
+/** Copy is the only effect in v1. `forbidden` is a hover result, not an offer. */
+type MindooDBAppDragEffect = "copy" | "forbidden";
+/** One typed string snapshot offered at `drag.start`. */
+interface MindooDBAppDragOffer {
+    type: string;
+    data: string;
+}
+/** PNG ghost sent to Haven. Haven never receives HTML. */
+interface MindooDBAppDragPreview {
+    png: ArrayBuffer;
+    width: number;
+    height: number;
+    hotspotX: number;
+    hotspotY: number;
+}
+/** Iframe-viewport pointer at the moment the host should take over. */
+interface MindooDBAppDragPointer {
+    x: number;
+    y: number;
+}
+/** Input for a host-owned drag gesture. Iframe-only, copy-only. */
+interface MindooDBAppDragStartInput {
+    offers: MindooDBAppDragOffer[];
+    preview: MindooDBAppDragPreview;
+    pointer: MindooDBAppDragPointer;
+    allowedEffects?: Array<"copy">;
+}
+/** Why a host drag ended without a copy. */
+type MindooDBAppDragCancelReason = "escape" | "pointercancel" | "gap" | "replaced" | "hide" | "source_cancelled";
+/** Result of `session.drag.start`. */
+type MindooDBAppDragStartResult = {
+    action: "copied";
+} | {
+    action: "cancelled";
+    reason: MindooDBAppDragCancelReason;
+};
+/** Coordinates and offered types pushed to a potential drop target. */
+interface MindooDBAppDragOverEvent {
+    x: number;
+    y: number;
+    types: string[];
+}
+/** Target answer after hit-testing a `drag-over`. */
+interface MindooDBAppDragHoverResult {
+    accept: boolean;
+    effect?: MindooDBAppDragEffect;
+}
+/** Copy payloads delivered to the target on drop. */
+interface MindooDBAppDragDropEvent {
+    x: number;
+    y: number;
+    items: Record<string, string>;
+}
+/**
+ * What this launch can receive, plus in-app callbacks. `accepts` is sent to
+ * Haven; the callbacks stay in the SDK and run from host push events.
+ */
+interface MindooDBAppDragProfile {
+    accepts: string[];
+    onOver?: (event: MindooDBAppDragOverEvent) => MindooDBAppDragHoverResult | void;
+    onLeave?: () => void;
+    onDrop?: (event: MindooDBAppDragDropEvent) => void;
+}
+/** Options for `session.drag.bindSource`. */
+interface MindooDBAppDragBindSourceOptions {
+    offers: MindooDBAppDragOffer[] | (() => MindooDBAppDragOffer[]);
+    /** Touch only: hold this long before Haven takes over. Default 400. */
+    longPressMs?: number;
+    /** Mouse/pen move, or the scroll-cancel slop on touch. Default 8. */
+    pointerThresholdPx?: number;
+    /** Element to snapshot; defaults to the bound source element. */
+    preview?: HTMLElement | (() => HTMLElement);
+}
+/**
+ * Host-owned drag across iframe chicklets. Haven renders the ghost above
+ * every frame; apps only start the gesture and hit-test drops.
+ */
+interface MindooDBAppDragApi {
+    /** Tell Haven which types this launch can receive. */
+    setProfile(profile: MindooDBAppDragProfile): Promise<void>;
+    /**
+     * Hand the gesture to Haven. Resolves when the copy completes or the
+     * user cancels. Iframe-only.
+     */
+    start(input: MindooDBAppDragStartInput): Promise<MindooDBAppDragStartResult>;
+    /** Abort a gesture this app started. */
+    cancel(): Promise<void>;
+    /**
+     * Pointer helper: mouse/pen starts after a small move; touch starts after
+     * a long-press. Each element can be bound independently; the returned
+     * function unbinds only that element.
+     */
+    bindSource(element: HTMLElement, options: MindooDBAppDragBindSourceOptions): () => void;
+}
+/** Host → target: pointer is over this iframe. */
+interface MindooDBAppBridgeDragOverMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "drag-over";
+    x: number;
+    y: number;
+    types: string[];
+}
+/** Host → previous target: pointer left this iframe. */
+interface MindooDBAppBridgeDragLeaveMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "drag-leave";
+}
+/** Host → target: copy payloads for the types this launch accepts. */
+interface MindooDBAppBridgeDragDropMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "drag-drop";
+    x: number;
+    y: number;
+    items: Record<string, string>;
+}
 interface MindooDBAppMenuApi {
     /**
      * Show a host-rendered menu at the given anchor (iframe-relative
@@ -2162,6 +2310,8 @@ interface MindooDBAppSession {
      */
     openViewNavigator(viewId: string, options?: MindooDBAppViewNavigatorOpenOptions): Promise<MindooDBAppViewNavigator>;
     menus: MindooDBAppMenuApi;
+    /** Host-owned cross-iframe drag. Iframe-only; copy-only in v1. */
+    drag: MindooDBAppDragApi;
     /**
      * Host-backed key/value storage for this app registration. Usable in both hosting
      * modes; required in `"hosted"` mode, where `localStorage` throws.
@@ -2219,4 +2369,4 @@ interface MindooDBAppBridge {
     connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
 }
 
-export { type MindooDBAppConfiguredViewFilterMode as $, type MindooDBAppBridgeLocaleChangedMessage as A, type MindooDBAppBridgePortMessage as B, type MindooDBAppBridgeQueryResultMessage as C, type MindooDBAppBridgeRpcError as D, type MindooDBAppBridgeRpcMessage as E, type MindooDBAppBridgeRpcRequest as F, type MindooDBAppBridgeRpcSuccess as G, type MindooDBAppBridgeStreamAbortRequest as H, type MindooDBAppBridgeStreamAck as I, type MindooDBAppBridgeStreamCloseRequest as J, type MindooDBAppBridgeStreamError as K, type MindooDBAppBridgeStreamMessage as L, type MindooDBAppAttachmentPreviewMode as M, type MindooDBAppBridgeStreamOpenResult as N, type MindooDBAppBridgeStreamReadRequest as O, type MindooDBAppBridgeStreamWriteRequest as P, type MindooDBAppBridgeThemeChangedMessage as Q, type MindooDBAppBridgeUiPreferencesChangedMessage as R, type MindooDBAppBridgeViewChangedMessage as S, type MindooDBAppBridgeViewportChangedMessage as T, type MindooDBAppCapability as U, type MindooDBAppConfiguredViewCategorizationStyle as V, type MindooDBAppConfiguredViewColumn as W, type MindooDBAppConfiguredViewColumnRole as X, type MindooDBAppConfiguredViewExpressionMode as Y, type MindooDBAppConfiguredViewFieldExpression as Z, type MindooDBAppConfiguredViewFilterDefinition as _, type MindooDBAppBridge as a, type MindooDBAppQueryRow as a$, type MindooDBAppConfiguredViewFilterRule as a0, type MindooDBAppConfiguredViewFormulaExpression as a1, type MindooDBAppConfiguredViewFormulaFilterDefinition as a2, type MindooDBAppConfiguredViewPreviewMode as a3, type MindooDBAppConfiguredViewRuleFilterDefinition as a4, type MindooDBAppConfiguredViewRuleMatchMode as a5, type MindooDBAppConfiguredViewRuleOperator as a6, type MindooDBAppConfiguredViewValueExpression as a7, type MindooDBAppCreateDocumentInput as a8, type MindooDBAppCreateKeyInfo as a9, type MindooDBAppInaccessibleDocumentListQuery as aA, type MindooDBAppInaccessibleDocumentListResult as aB, type MindooDBAppJsonListDeletePatch as aC, type MindooDBAppJsonListInsertPatch as aD, type MindooDBAppJsonPatch as aE, type MindooDBAppJsonSetPatch as aF, type MindooDBAppJsonTextMarkPatch as aG, type MindooDBAppJsonTextSplicePatch as aH, type MindooDBAppJsonTextUnmarkPatch as aI, type MindooDBAppJsonUnsetPatch as aJ, type MindooDBAppLaunchContext as aK, type MindooDBAppLiveQuerySubscription as aL, type MindooDBAppMenuAnchor as aM, type MindooDBAppMenuApi as aN, type MindooDBAppMenuCommandItem as aO, type MindooDBAppMenuDismissReason as aP, type MindooDBAppMenuDismissedResult as aQ, type MindooDBAppMenuItem as aR, type MindooDBAppMenuKind as aS, type MindooDBAppMenuPlacement as aT, type MindooDBAppMenuPointAnchor as aU, type MindooDBAppMenuRect as aV, type MindooDBAppMenuRectAnchor as aW, type MindooDBAppMenuSelectionResult as aX, type MindooDBAppMenuSeparatorItem as aY, type MindooDBAppQueryCoverage as aZ, type MindooDBAppQueryResult as a_, type MindooDBAppCreateViewInput as aa, type MindooDBAppCreateViewNavigatorInput as ab, type MindooDBAppDatabaseInfo as ac, type MindooDBAppDirectoryApi as ad, type MindooDBAppDirectoryEntry as ae, type MindooDBAppDocumentApi as af, type MindooDBAppDocumentHeadCursorResult as ag, type MindooDBAppDocumentHistoryEntry as ah, type MindooDBAppDocumentListQuery as ai, type MindooDBAppDocumentListResult as aj, type MindooDBAppDocumentQuery as ak, type MindooDBAppDocumentRevisionId as al, type MindooDBAppDocumentScanPreset as am, type MindooDBAppDocumentSummary as an, type MindooDBAppEntryAttachmentRef as ao, type MindooDBAppEntryProvenance as ap, type MindooDBAppExtractDocumentTextInput as aq, type MindooDBAppExtractDocumentTextResult as ar, type MindooDBAppExtractTextFormat as as, type MindooDBAppExtractionSetup as at, type MindooDBAppFulltextSetup as au, type MindooDBAppHistoricalDocument as av, type MindooDBAppHistoryQuery as aw, type MindooDBAppHostTheme as ax, type MindooDBAppIdentityApi as ay, type MindooDBAppInaccessibleDocument as az, type MindooDBAppHostingMode as b, type MindooDBAppQuerySortKey as b0, type MindooDBAppQueryTextClause as b1, type MindooDBAppReadableAttachmentStream as b2, type MindooDBAppRecipientOptions as b3, type MindooDBAppResolvedViewDefinition as b4, type MindooDBAppResolvedViewSource as b5, type MindooDBAppRevisionPhase as b6, type MindooDBAppRevisionVerification as b7, type MindooDBAppRichTextBlockSpan as b8, type MindooDBAppRichTextGetOptions as b9, type MindooDBAppTextEdit as bA, type MindooDBAppTextPatch as bB, type MindooDBAppThemeMode as bC, type MindooDBAppTimestampApi as bD, type MindooDBAppTimestampInput as bE, type MindooDBAppTimestampProvider as bF, type MindooDBAppTimestampResult as bG, type MindooDBAppUiPreferences as bH, type MindooDBAppUpdateDocumentInput as bI, type MindooDBAppViewCursorDocumentListResult as bJ, type MindooDBAppViewCursorResult as bK, type MindooDBAppViewEntry as bL, type MindooDBAppViewEntryKind as bM, type MindooDBAppViewNavigator as bN, type MindooDBAppViewNavigatorExpansionState as bO, type MindooDBAppViewNavigatorOpenOptions as bP, type MindooDBAppViewNavigatorPageOptions as bQ, type MindooDBAppViewNavigatorPageResult as bR, type MindooDBAppViewNavigatorRangeQuery as bS, type MindooDBAppViewNavigatorSelectionState as bT, type MindooDBAppViewUpdateStats as bU, type MindooDBAppViewport as bV, type MindooDBAppWritableAttachmentStream as bW, type MindooDBAppRichTextImmutableString as ba, type MindooDBAppRichTextMarkRange as bb, type MindooDBAppRichTextMaterializeValue as bc, type MindooDBAppRichTextPatch as bd, type MindooDBAppRichTextScalar as be, type MindooDBAppRichTextSpliceStep as bf, type MindooDBAppRichTextStep as bg, type MindooDBAppRichTextStepPatch as bh, type MindooDBAppRichTextTextSpan as bi, type MindooDBAppRuntime as bj, type MindooDBAppScanAttachmentOptions as bk, type MindooDBAppScanAttachmentResult as bl, type MindooDBAppScopedDocId as bm, type MindooDBAppScopedDocumentSummary as bn, type MindooDBAppSealIntent as bo, type MindooDBAppSealedChannelOpenInput as bp, type MindooDBAppSealedChannelOpenResult as bq, type MindooDBAppSealedChannelRequestInput as br, type MindooDBAppSession as bs, type MindooDBAppShowMenuInput as bt, type MindooDBAppShowMenuResult as bu, type MindooDBAppSignPreview as bv, type MindooDBAppSignPreviewScope as bw, type MindooDBAppSignStatementInput as bx, type MindooDBAppSignStatementResult as by, type MindooDBAppStorageApi as bz, type MindooDBAppDatabase as c, type MindooDBAppDocument as d, type MindooDBAppRichTextSpan as e, type MindooDBAppRichTextSnapshot as f, MINDOODB_APP_SEAL_SIGNING_DOMAIN as g, type MindooDBAppAccessDecision as h, type MindooDBAppAccessTier as i, type MindooDBAppAttachmentApi as j, type MindooDBAppAttachmentChunk as k, type MindooDBAppAttachmentInfo as l, type MindooDBAppAttachmentPreviewOptions as m, type MindooDBAppAttachmentPreviewSession as n, type MindooDBAppAutomergeChangesPatch as o, type MindooDBAppAutomergeChangesSince as p, type MindooDBAppAutomergeGetOptions as q, type MindooDBAppAutomergePatchResult as r, type MindooDBAppAutomergeSnapshot as s, type MindooDBAppBridgeBeforeCloseAck as t, type MindooDBAppBridgeBeforeCloseMessage as u, type MindooDBAppBridgeConnectMessage as v, type MindooDBAppBridgeConnectOptions as w, type MindooDBAppBridgeConnectedMessage as x, type MindooDBAppBridgeErrorPayload as y, type MindooDBAppBridgeHandshakeErrorMessage as z };
+export { type MindooDBAppBridgeStreamWriteRequest as $, type MindooDBAppBridgeBeforeCloseAck as A, type MindooDBAppBridgeBeforeCloseMessage as B, type MindooDBAppBridgeConnectMessage as C, type MindooDBAppBridgeConnectOptions as D, type MindooDBAppBridgeConnectedMessage as E, type MindooDBAppBridgeDragDropMessage as F, type MindooDBAppBridgeDragLeaveMessage as G, type MindooDBAppBridgeDragOverMessage as H, type MindooDBAppBridgeErrorPayload as I, type MindooDBAppBridgeHandshakeErrorMessage as J, type MindooDBAppBridgeLocaleChangedMessage as K, type MindooDBAppBridgePortMessage as L, type MindooDBAppAttachmentPreviewMode as M, type MindooDBAppBridgeQueryResultMessage as N, type MindooDBAppBridgeRpcError as O, type MindooDBAppBridgeRpcMessage as P, type MindooDBAppBridgeRpcRequest as Q, type MindooDBAppBridgeRpcSuccess as R, type MindooDBAppBridgeShortcutInvokedMessage as S, type MindooDBAppBridgeShortcutsChangedMessage as T, type MindooDBAppBridgeStreamAbortRequest as U, type MindooDBAppBridgeStreamAck as V, type MindooDBAppBridgeStreamCloseRequest as W, type MindooDBAppBridgeStreamError as X, type MindooDBAppBridgeStreamMessage as Y, type MindooDBAppBridgeStreamOpenResult as Z, type MindooDBAppBridgeStreamReadRequest as _, type MindooDBAppDragBindSourceOptions as a, type MindooDBAppJsonTextMarkPatch as a$, type MindooDBAppBridgeThemeChangedMessage as a0, type MindooDBAppBridgeUiPreferencesChangedMessage as a1, type MindooDBAppBridgeViewChangedMessage as a2, type MindooDBAppBridgeViewportChangedMessage as a3, type MindooDBAppCapability as a4, type MindooDBAppConfiguredViewCategorizationStyle as a5, type MindooDBAppConfiguredViewColumn as a6, type MindooDBAppConfiguredViewColumnRole as a7, type MindooDBAppConfiguredViewExpressionMode as a8, type MindooDBAppConfiguredViewFieldExpression as a9, type MindooDBAppDragApi as aA, type MindooDBAppDragCancelReason as aB, type MindooDBAppDragDropEvent as aC, type MindooDBAppDragEffect as aD, type MindooDBAppDragHoverResult as aE, type MindooDBAppDragOffer as aF, type MindooDBAppDragOverEvent as aG, type MindooDBAppDragPointer as aH, type MindooDBAppDragProfile as aI, type MindooDBAppEntryAttachmentRef as aJ, type MindooDBAppEntryProvenance as aK, type MindooDBAppExtractDocumentTextInput as aL, type MindooDBAppExtractDocumentTextResult as aM, type MindooDBAppExtractTextFormat as aN, type MindooDBAppExtractionSetup as aO, type MindooDBAppFulltextSetup as aP, type MindooDBAppHistoricalDocument as aQ, type MindooDBAppHistoryQuery as aR, type MindooDBAppHostTheme as aS, type MindooDBAppIdentityApi as aT, type MindooDBAppInaccessibleDocument as aU, type MindooDBAppInaccessibleDocumentListQuery as aV, type MindooDBAppInaccessibleDocumentListResult as aW, type MindooDBAppJsonListDeletePatch as aX, type MindooDBAppJsonListInsertPatch as aY, type MindooDBAppJsonPatch as aZ, type MindooDBAppJsonSetPatch as a_, type MindooDBAppConfiguredViewFilterDefinition as aa, type MindooDBAppConfiguredViewFilterMode as ab, type MindooDBAppConfiguredViewFilterRule as ac, type MindooDBAppConfiguredViewFormulaExpression as ad, type MindooDBAppConfiguredViewFormulaFilterDefinition as ae, type MindooDBAppConfiguredViewPreviewMode as af, type MindooDBAppConfiguredViewRuleFilterDefinition as ag, type MindooDBAppConfiguredViewRuleMatchMode as ah, type MindooDBAppConfiguredViewRuleOperator as ai, type MindooDBAppConfiguredViewValueExpression as aj, type MindooDBAppCreateDocumentInput as ak, type MindooDBAppCreateKeyInfo as al, type MindooDBAppCreateViewInput as am, type MindooDBAppCreateViewNavigatorInput as an, type MindooDBAppDatabaseInfo as ao, type MindooDBAppDirectoryApi as ap, type MindooDBAppDirectoryEntry as aq, type MindooDBAppDocumentApi as ar, type MindooDBAppDocumentHeadCursorResult as as, type MindooDBAppDocumentHistoryEntry as at, type MindooDBAppDocumentListQuery as au, type MindooDBAppDocumentListResult as av, type MindooDBAppDocumentQuery as aw, type MindooDBAppDocumentRevisionId as ax, type MindooDBAppDocumentScanPreset as ay, type MindooDBAppDocumentSummary as az, type MindooDBAppDragStartInput as b, type MindooDBAppTimestampResult as b$, type MindooDBAppJsonTextSplicePatch as b0, type MindooDBAppJsonTextUnmarkPatch as b1, type MindooDBAppJsonUnsetPatch as b2, type MindooDBAppLaunchContext as b3, type MindooDBAppLiveQuerySubscription as b4, type MindooDBAppMenuAnchor as b5, type MindooDBAppMenuApi as b6, type MindooDBAppMenuCommandItem as b7, type MindooDBAppMenuDismissReason as b8, type MindooDBAppMenuDismissedResult as b9, type MindooDBAppRichTextSpliceStep as bA, type MindooDBAppRichTextStep as bB, type MindooDBAppRichTextStepPatch as bC, type MindooDBAppRichTextTextSpan as bD, type MindooDBAppRuntime as bE, type MindooDBAppScanAttachmentOptions as bF, type MindooDBAppScanAttachmentResult as bG, type MindooDBAppScopedDocId as bH, type MindooDBAppScopedDocumentSummary as bI, type MindooDBAppSealIntent as bJ, type MindooDBAppSealedChannelOpenInput as bK, type MindooDBAppSealedChannelOpenResult as bL, type MindooDBAppSealedChannelRequestInput as bM, type MindooDBAppSession as bN, type MindooDBAppShowMenuInput as bO, type MindooDBAppShowMenuResult as bP, type MindooDBAppSignPreview as bQ, type MindooDBAppSignPreviewScope as bR, type MindooDBAppSignStatementInput as bS, type MindooDBAppSignStatementResult as bT, type MindooDBAppStorageApi as bU, type MindooDBAppTextEdit as bV, type MindooDBAppTextPatch as bW, type MindooDBAppThemeMode as bX, type MindooDBAppTimestampApi as bY, type MindooDBAppTimestampInput as bZ, type MindooDBAppTimestampProvider as b_, type MindooDBAppMenuItem as ba, type MindooDBAppMenuKind as bb, type MindooDBAppMenuPlacement as bc, type MindooDBAppMenuPointAnchor as bd, type MindooDBAppMenuRect as be, type MindooDBAppMenuRectAnchor as bf, type MindooDBAppMenuSelectionResult as bg, type MindooDBAppMenuSeparatorItem as bh, type MindooDBAppQueryCoverage as bi, type MindooDBAppQueryResult as bj, type MindooDBAppQueryRow as bk, type MindooDBAppQuerySortKey as bl, type MindooDBAppQueryTextClause as bm, type MindooDBAppReadableAttachmentStream as bn, type MindooDBAppRecipientOptions as bo, type MindooDBAppResolvedViewDefinition as bp, type MindooDBAppResolvedViewSource as bq, type MindooDBAppRevisionPhase as br, type MindooDBAppRevisionVerification as bs, type MindooDBAppRichTextBlockSpan as bt, type MindooDBAppRichTextGetOptions as bu, type MindooDBAppRichTextImmutableString as bv, type MindooDBAppRichTextMarkRange as bw, type MindooDBAppRichTextMaterializeValue as bx, type MindooDBAppRichTextPatch as by, type MindooDBAppRichTextScalar as bz, type MindooDBAppDragStartResult as c, type MindooDBAppUiPreferences as c0, type MindooDBAppUpdateDocumentInput as c1, type MindooDBAppViewCursorDocumentListResult as c2, type MindooDBAppViewCursorResult as c3, type MindooDBAppViewEntry as c4, type MindooDBAppViewEntryKind as c5, type MindooDBAppViewNavigator as c6, type MindooDBAppViewNavigatorExpansionState as c7, type MindooDBAppViewNavigatorOpenOptions as c8, type MindooDBAppViewNavigatorPageOptions as c9, type MindooDBAppViewNavigatorPageResult as ca, type MindooDBAppViewNavigatorRangeQuery as cb, type MindooDBAppViewNavigatorSelectionState as cc, type MindooDBAppViewUpdateStats as cd, type MindooDBAppViewport as ce, type MindooDBAppWellKnownDragType as cf, type MindooDBAppWritableAttachmentStream as cg, type MindooDBAppDragPreview as d, type MindooDBAppBridge as e, type MindooDBAppHostShortcutBinding as f, type MindooDBAppHostShortcutAction as g, type MindooDBAppHostingMode as h, type MindooDBAppDatabase as i, type MindooDBAppDocument as j, type MindooDBAppRichTextSpan as k, type MindooDBAppRichTextSnapshot as l, MINDOODB_APP_SEAL_SIGNING_DOMAIN as m, MINDOODB_APP_WELL_KNOWN_DRAG_TYPES as n, type MindooDBAppAccessDecision as o, type MindooDBAppAccessTier as p, type MindooDBAppAttachmentApi as q, type MindooDBAppAttachmentChunk as r, type MindooDBAppAttachmentInfo as s, type MindooDBAppAttachmentPreviewOptions as t, type MindooDBAppAttachmentPreviewSession as u, type MindooDBAppAutomergeChangesPatch as v, type MindooDBAppAutomergeChangesSince as w, type MindooDBAppAutomergeGetOptions as x, type MindooDBAppAutomergePatchResult as y, type MindooDBAppAutomergeSnapshot as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindoodb-app-sdk",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "engines": {
     "node": ">=22.13.0"
   },
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@automerge/automerge": "^3.3.2",
-    "mindoodb": ">=0.0.57"
+    "mindoodb": ">=0.0.58"
   },
   "peerDependenciesMeta": {
     "@automerge/automerge": {
@@ -57,8 +57,9 @@
   },
   "devDependencies": {
     "@automerge/automerge": "^3.3.2",
-    "mindoodb": "^0.0.57",
+    "mindoodb": "^0.0.58",
     "@types/node": "25.5.0",
+    "jsdom": "^29.0.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"