@paged-media/plugin-sdk 0.2.40-canary.0 → 0.2.41-canary.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PagedBundle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, MutationInput, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome, BindingProviderHandle } from '@paged-media/plugin-api';
+import { PagedBundle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, MutationInput, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, OpenDocumentResult, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome, BindingProviderHandle } from '@paged-media/plugin-api';
 import { ComponentType } from 'react';
 
 /**
@@ -240,6 +240,27 @@ interface NativeDocumentBackend {
     listParts(prefix?: string): Promise<string[]>;
     open(bytes: Uint8Array): Promise<void>;
 }
+/**
+ * D-26 — the backend the editor injects to back `host.documents`. The SDK
+ * owns the capability gate (`capabilities.documents.export` / `.open`); the
+ * backend owns the IO AND the unsaved-edits decision: `open` must ask the
+ * user (host UI) before discarding a dirty active document and answer
+ * `{ opened: false, reason: "declined" }` when they keep it. `requester`
+ * is filled by the SDK from the calling bundle's manifest (not from the
+ * plugin's arguments), so the prompt can name who is asking. No backend →
+ * both doors reject and `supports("documents.open@1")` /
+ * `supports("documents.exportPaged@1")` are false.
+ */
+interface DocumentsBackend {
+    exportPaged(): Promise<Uint8Array>;
+    open(bytes: Uint8Array, request: {
+        name: string | null;
+        requester: {
+            id: string;
+            name: string;
+        };
+    }): Promise<OpenDocumentResult>;
+}
 /** The SHARED cross-plugin data-provider registry (paged.data §7.1 / D-09). The
  *  editor creates ONE (`createDataProviderRegistry`) and injects the SAME
  *  instance into every plugin host, so a provider plugin and a consumer plugin
@@ -469,6 +490,12 @@ interface CreateBundleHostOptions {
      *  `supports("document.openNative@1")` answer true. When absent, the reads
      *  answer `null`/`[]` and `open` rejects (the honest no-backend door). */
     nativeDocument?: NativeDocumentBackend;
+    /** D-26 — host-provided DOCUMENTS backend. When present,
+     *  `host.documents.exportPaged` / `open` go through it (gated on
+     *  `capabilities.documents.export` / `.open`) and
+     *  `supports("documents.exportPaged@1")` / `supports("documents.open@1")`
+     *  answer true. When absent, both doors reject. */
+    documents?: DocumentsBackend;
     /** Host-provided WORKER backend (K-3 / S-07 / I-02). When present,
      *  `host.workers.spawn` resolves a declared bundle-relative module +
      *  constructs a host-owned `Worker` through it (capability-gated,
@@ -521,6 +548,14 @@ interface HeadlessCanvasWorker {
     handleMessage(input: string): string;
     loadDocumentDirect(seq: number, bytes: Uint8Array, font?: Uint8Array, cmykIccProfile?: Uint8Array): string;
     runResolveJson(): string | undefined;
+    /** The engine shaper (v38): `{ advance, ascender, descender }` in pt, or
+     *  null when no document is loaded / the face resolves to nothing.
+     *  Optional so a structural fake need not carry it. */
+    measureText?(family: string, style: string | null | undefined, text: string, sizePt: number): {
+        advance: number;
+        ascender: number;
+        descender: number;
+    } | null;
     free(): void;
 }
 interface LoadedEngine {
@@ -580,6 +615,32 @@ interface RecordedContribution {
     value: ToolContribution | PanelContribution | SchemaPanelContribution | CommandContribution | KeybindingContribution | OverlayContribution | EditContextContribution | ObjectTypeContribution | ImporterContribution | ExporterContribution;
 }
 interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets" | "bindingProviders" | "willSave" | "toolSettings"> {
+    /** D-27 — back `host.text` with the ENGINE's shaper
+     *  (`CanvasWorker.measureText`, the one the editor's worker calls)
+     *  instead of the estimate, so `measureString` / `measureStrings`
+     *  answer real widths against the loaded document's fonts and
+     *  `supports("text.measure@1")` / `("text.measureStrings@1")` are true.
+     *  Off by default: existing headless suites pinned the estimate. */
+    engineShaper?: boolean;
+    /** D-26 — the headless stand-in for the editor's keep/discard prompt.
+     *  `host.documents.open` calls it ONLY when the active document has
+     *  unsaved edits; resolve `false` to keep them (the door then answers
+     *  `{ opened: false, reason: "declined" }`). Default: discard. */
+    confirmReplace?: (request: {
+        name: string | null;
+        requester: {
+            id: string;
+            name: string;
+        };
+    }) => boolean | Promise<boolean>;
+    /** D-28 — the default font every load lays out with, the headless
+     *  stand-in for the editor's `defaultFontProvider` (the editor passes
+     *  `/fonts/Inter.ttf`). The engine lays text out, and reports a story
+     *  `overset`, only when it has a font: without one nothing is laid out and
+     *  every story reads `overset: false` (not measured). Passed to every
+     *  load, `load()` and `host.documents.open` alike. Absent: no font, as
+     *  before. */
+    defaultFont?: Uint8Array;
 }
 /** A headless will-save registry: listeners register per plugin and
  *  `fire()` awaits them all, the way the editor's save path does — so a
@@ -656,6 +717,13 @@ interface HeadlessHost {
     /** Load an IDML package into the headless document. Resolves to the
      *  loaded page ids (or throws on a parse failure). */
     load(idml: Uint8Array): Promise<string[]>;
+    /** D-26 — every document a bundle opened through `host.documents.open`,
+     *  in order (declined opens are not listed). */
+    openedDocuments(): ReadonlyArray<{
+        name: string | null;
+        requester: string;
+        pageIds: string[];
+    }>;
     /** Activate a bundle against this host (apiVersion-negotiated). The
      *  returned disposer runs the bundle's teardown; the host's own
      *  facade teardown runs on `dispose()`. */
@@ -921,4 +989,4 @@ declare function contributeObjectType(host: BundleHost, contribution: ObjectType
  */
 declare function contributeBindingProvider(host: BundleHost, contextType: string, provider: BindingProvider): BindingProviderHandle;
 
-export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BindingProviderBackend, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ClipboardBackend, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type SecretStoreBackend, type SeededFace, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type ToolSettingsBackend, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, beginPageDrag, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBindingProviderRegistry, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, inMemoryToolSettings, inMemoryWillSave, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };
+export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BindingProviderBackend, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ClipboardBackend, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, type DocumentsBackend, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type SecretStoreBackend, type SeededFace, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type ToolSettingsBackend, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, beginPageDrag, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBindingProviderRegistry, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, inMemoryToolSettings, inMemoryWillSave, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };

package/dist/index.js

@@ -230,6 +230,11 @@ var HOST_FEATURES = [
   "document.onDidChange@1",
   "document.getMetadata@1",
   "document.setMetadata@1",
+  // Protocol 69 — the document-scoped label. Static like the snap door:
+  // the flag says this SDK forwards the two calls; an engine older than 69
+  // answers `null` on read (no `pluginMetadata` in its DocumentMeta) and
+  // `applied: false` on write (it does not know the op).
+  "document.documentMetadata@1",
   "selection@1",
   "viewport@1",
   "overlay.toolPreview@1",
@@ -628,6 +633,7 @@ function createBundleHost(getEditor, manifest, options) {
   const hasWorkers = () => typeof caps?.workers?.max === "number";
   const hasSecrets = () => caps?.secrets?.sources === true;
   const hasGpu = () => caps?.gpu?.realm === "bundle";
+  const hasDocuments = (dir) => caps?.documents?.[dir] === true;
   const lists = (arr, id) => arr?.includes(id) ?? false;
   const declaresType = (arr, type) => arr?.some((e) => e.type === type) ?? false;
   const requireDeclared = (ok, door, missing) => {
@@ -1098,7 +1104,7 @@ function createBundleHost(getEditor, manifest, options) {
     }
   };
   const foreignMetadataKey = (m) => {
-    if (m.op === "setPluginMetadata") {
+    if (m.op === "setPluginMetadata" || m.op === "setDocumentMetadata") {
       return m.args.key === metadataKey(manifest) ? null : m.args.key;
     }
     if (m.op === "batch") {
@@ -1147,7 +1153,7 @@ function createBundleHost(getEditor, manifest, options) {
     if (denied !== null) return { applied: false, error: denied };
     const foreign = foreignMetadataKey(mutation);
     if (foreign !== null) {
-      const error = `setPluginMetadata key "${foreign}" is outside this plugin's namespace ("${metadataKey(manifest)}")`;
+      const error = `metadata key "${foreign}" is outside this plugin's namespace ("${metadataKey(manifest)}")`;
       log.warn(error);
       return { applied: false, error };
     }
@@ -1384,6 +1390,28 @@ function createBundleHost(getEditor, manifest, options) {
         }
       });
     },
+    async getDocumentMetadata() {
+      requireDocRead("document.getDocumentMetadata");
+      const key = metadataKey(manifest);
+      const meta = await getEditor().client.documentMeta();
+      const entry = meta.pluginMetadata?.find((e) => e.key === key);
+      if (!entry) return null;
+      try {
+        return JSON.parse(entry.value);
+      } catch {
+        return null;
+      }
+    },
+    async setDocumentMetadata(envelope) {
+      return this.mutate({
+        op: "setDocumentMetadata",
+        args: {
+          key: metadataKey(manifest),
+          value: envelope === null ? null : JSON.stringify(envelope),
+          caller: manifest.id
+        }
+      });
+    },
     async frameChain(storyId) {
       requireDocRead("document.frameChain");
       const reply = await getEditor().client.send({
@@ -1487,6 +1515,25 @@ function createBundleHost(getEditor, manifest, options) {
     // "no reader").
     caret() {
       return options?.textCaret?.read() ?? null;
+    },
+    // D-27 — the batched measure. One round-trip when the editor wires
+    // `measureMany`; otherwise the same answers one call at a time (or
+    // the estimate), so a bundle never needs two code paths.
+    async measureStrings(family, style, texts, sizePt) {
+      if (texts.length === 0) return [];
+      const editorText = getEditor().text;
+      if (editorText?.measureMany) {
+        const out = await editorText.measureMany(family, style, texts, sizePt);
+        if (out.length !== texts.length) {
+          throw new Error(
+            `host.text.measureStrings: the host answered ${out.length} metrics for ${texts.length} strings`
+          );
+        }
+        return out;
+      }
+      return Promise.all(
+        texts.map((t) => text.measureString(family, style, t, sizePt))
+      );
     }
   };
   const overlay = {
@@ -2058,6 +2105,42 @@ function createBundleHost(getEditor, manifest, options) {
       return nativeDocBackend.open(bytes);
     }
   };
+  const documentsBackend = options?.documents;
+  const documents = {
+    async exportPaged() {
+      requireDeclared(
+        hasDocuments("export"),
+        "documents.exportPaged",
+        "capabilities.documents.export must be declared"
+      );
+      if (!documentsBackend) {
+        throw new Error(
+          'host.documents.exportPaged: the host wired no documents backend (supports("documents.exportPaged@1") is false)'
+        );
+      }
+      return documentsBackend.exportPaged();
+    },
+    async open(bytes, opts) {
+      requireDeclared(
+        hasDocuments("open"),
+        "documents.open",
+        "capabilities.documents.open must be declared"
+      );
+      if (!documentsBackend) {
+        throw new Error(
+          'host.documents.open: the host wired no documents backend (supports("documents.open@1") is false)'
+        );
+      }
+      if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
+        throw new Error("host.documents.open: bytes must be a non-empty Uint8Array");
+      }
+      const name = typeof opts?.name === "string" && opts.name.trim() !== "" ? opts.name.trim() : null;
+      return documentsBackend.open(bytes.slice(), {
+        name,
+        requester: { id: manifest.id, name: manifest.name }
+      });
+    }
+  };
   const clipboardBackend = options?.clipboard;
   const clipboardGate = (door) => {
     const grant = clipboardGrant();
@@ -2263,6 +2346,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (getEditor().text) {
     featureSet.add("text.measure@1");
   }
+  if (getEditor().text?.measureMany) {
+    featureSet.add("text.measureStrings@1");
+  }
   if (getEditor().sceneLayers) {
     featureSet.add("rendering.sceneLayer@1");
     featureSet.add("rendering.sceneLayer.faces@1");
@@ -2335,6 +2421,10 @@ function createBundleHost(getEditor, manifest, options) {
     featureSet.add("document.readNative@1");
     featureSet.add("document.openNative@1");
   }
+  if (options?.documents) {
+    featureSet.add("documents.exportPaged@1");
+    featureSet.add("documents.open@1");
+  }
   if (options?.workers) {
     featureSet.add("workers@1");
   }
@@ -2358,6 +2448,7 @@ function createBundleHost(getEditor, manifest, options) {
     blob,
     parts,
     nativeDocument,
+    documents,
     network,
     dataProviders,
     diagnostics,
@@ -2612,7 +2703,7 @@ function inMemorySecretStore() {
   };
 }
 var seqCounter = 1;
-function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
+function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews, engineShaper = false) {
   const protocol = worker.protocolVersion;
   const listeners = /* @__PURE__ */ new Set();
   const fanOut = (reply) => {
@@ -2772,7 +2863,23 @@ function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
     },
     contentSelection: { contentSelection: null }
   };
-  return editor;
+  const measureText = worker.measureText?.bind(worker);
+  if (engineShaper && measureText) {
+    const zero = { advance: 0, ascender: 0, descender: 0 };
+    const one = (family, style, t, sizePt) => {
+      const m = measureText(family, style, t, sizePt);
+      return m ? { advance: m.advance, ascender: m.ascender, descender: m.descender } : zero;
+    };
+    editor.text = {
+      async measure(family, style, t, sizePt) {
+        return one(family, style, t, sizePt);
+      },
+      async measureMany(family, style, texts, sizePt) {
+        return texts.map((t) => one(family, style, t, sizePt));
+      }
+    };
+  }
+  return { editor, fanOut };
 }
 async function createHeadlessHost(options = {}) {
   const engine = await loadHeadlessEngine(options);
@@ -2780,7 +2887,7 @@ async function createHeadlessHost(options = {}) {
   const contributions = [];
   let lastPreview = null;
   let lastPreviews = null;
-  const editor = makeEngineEditor(
+  const { editor, fanOut } = makeEngineEditor(
     worker,
     contributions,
     (value) => {
@@ -2788,8 +2895,54 @@ async function createHeadlessHost(options = {}) {
     },
     (value) => {
       lastPreviews = value;
-    }
+    },
+    options.engineShaper === true
   );
+  const loadDirect = (bytes) => {
+    const reply = JSON.parse(
+      options.defaultFont ? worker.loadDocumentDirect(seqCounter++, bytes, options.defaultFont) : worker.loadDocumentDirect(seqCounter++, bytes)
+    );
+    if (reply.kind === "documentLoaded") {
+      try {
+        worker.runResolveJson();
+      } catch {
+      }
+    }
+    return reply;
+  };
+  const loadFailure = (reply) => {
+    const errKind = reply.kind === "loadFailed" ? reply.payload.error.kind : reply.kind;
+    return new Error(`headless load failed (${reply.kind}: ${errKind})`);
+  };
+  const opened = [];
+  const documentsBackend = {
+    async exportPaged() {
+      const reply = await editor.client.send({ kind: "exportPaged", payload: {} });
+      if (reply.kind === "pagedExported") return Uint8Array.from(reply.payload.bytes);
+      if (reply.kind === "pagedPartFailed") throw new Error(reply.payload.error);
+      throw new Error(`unexpected reply: ${reply.kind}`);
+    },
+    async open(bytes, request) {
+      let dirty = false;
+      try {
+        dirty = (await editor.client.documentMeta()).dirty;
+      } catch {
+        dirty = false;
+      }
+      if (dirty && options.confirmReplace && !await options.confirmReplace(request)) {
+        return { opened: false, reason: "declined" };
+      }
+      const reply = loadDirect(bytes);
+      if (reply.kind !== "documentLoaded") throw loadFailure(reply);
+      fanOut(reply);
+      opened.push({
+        name: request.name,
+        requester: request.requester.id,
+        pageIds: reply.payload.pageIds
+      });
+      return { opened: true, pageIds: reply.payload.pageIds };
+    }
+  };
   let active = null;
   let currentHost = null;
   let disposed = false;
@@ -2814,6 +2967,7 @@ async function createHeadlessHost(options = {}) {
     // headlessly (the editor's real adapter currently serves null;
     // DESIGN.md §13.4). Absent → the no-bytes door.
     assetSource: options.assetSource,
+    documents: documentsBackend,
     // Record the SCHEMA verbatim at registration — the panel registry
     // only ever sees the synthesized React panel, so the conformance
     // log gets the schema through this adapter seam (no host renderer
@@ -2875,7 +3029,8 @@ async function createHeadlessHost(options = {}) {
       rendering: ["overlay", "hitTest", "sceneLayer"],
       keybindings: true,
       storage: { blob: true },
-      secrets: { sources: true }
+      secrets: { sources: true },
+      documents: { export: true, open: true }
     },
     // Broad contribution declarations so the neutral DRIVER host (which
     // registers arbitrary contributions directly in 'warn' mode) never
@@ -2931,17 +3086,12 @@ async function createHeadlessHost(options = {}) {
     willSave,
     toolSettings,
     async load(idml) {
-      const raw = worker.loadDocumentDirect(seqCounter++, idml);
-      const reply = JSON.parse(raw);
-      if (reply.kind === "documentLoaded") {
-        try {
-          worker.runResolveJson();
-        } catch {
-        }
-        return reply.payload.pageIds;
-      }
-      const errKind = reply.kind === "loadFailed" ? reply.payload.error.kind : reply.kind;
-      throw new Error(`headless load failed (${reply.kind}: ${errKind})`);
+      const reply = loadDirect(idml);
+      if (reply.kind === "documentLoaded") return reply.payload.pageIds;
+      throw loadFailure(reply);
+    },
+    openedDocuments() {
+      return opened;
     },
     loadBundle(bundle) {
       if (active) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-sdk",
-  "version": "0.2.40-canary.0",
+  "version": "0.2.41-canary.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@paged-media/plugin-api": "0.2.40-canary.0"
+    "@paged-media/plugin-api": "0.2.41-canary.0"
   },
   "peerDependencies": {
     "react": "^18.3.0"
@@ -22,7 +22,7 @@
     }
   },
   "devDependencies": {
-    "@paged-media/canvas-wasm": "0.68.0",
+    "@paged-media/canvas-wasm": "0.69.0",
     "@types/node": "20.19.39",
     "@types/react": "^18.3.31",
     "react": "^18.3.1",