@paged-media/plugin-sdk 0.2.14-canary.0 → 0.2.17-canary.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PagedBundle, FontFaceAsset, BundleHost, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, Disposable, ShellSurface, WidgetSurface, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome } from '@paged-media/plugin-api';
+import { PagedBundle, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, Disposable, ShellSurface, WidgetSurface, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome } from '@paged-media/plugin-api';
 import { ComponentType } from 'react';
 
 /**
@@ -113,6 +113,20 @@ interface BlobStore {
     /** Total bytes this plugin currently stores. */
     used(pluginId: string): Promise<number>;
 }
+/**
+ * The backend the editor injects to back `host.clipboard` (K-6 / S-14): a
+ * thin read/write pair over the REAL system clipboard (`navigator.clipboard`
+ * in-browser; a fake in the headless harness). The SDK adapter owns the
+ * capability gate + the `"vector"` tabular-stripping; this backend only does
+ * the raw IO. `read` recovers a `{ text?, tabular? }` payload (or `null` when
+ * the platform offers nothing / refuses); `write` puts a payload on the
+ * clipboard (the editor backend lays down BOTH `text/plain` TSV and a
+ * `text/html` `<table>` so a paste into Excel/Sheets/Word lands a real grid).
+ */
+interface ClipboardBackend {
+    read(): Promise<ClipboardPayload | null>;
+    write(payload: ClipboardPayload): Promise<void>;
+}
 /** 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
@@ -220,6 +234,12 @@ interface CreateBundleHostOptions {
      *  When absent, reads answer empty and writes reject (the honest
      *  no-store door). */
     blobStore?: BlobStore;
+    /** Host-provided CLIPBOARD backend (K-6 / S-14). When present,
+     *  `host.clipboard.read/write` go through it (capability-gated on
+     *  `capabilities.clipboard`) and `supports("clipboard@1")` answers true.
+     *  When absent, `read` answers `null` and `write` is a no-op (the honest
+     *  no-clipboard door). */
+    clipboard?: ClipboardBackend;
     /**
      * How the host treats a declaration↔use mismatch — a bundle that
      * USES a door (`contribute.tool`, `document.mutate`, …) it did not
@@ -314,7 +334,7 @@ interface RecordedContribution {
     id: string;
     value: ToolContribution | PanelContribution | SchemaPanelContribution | CommandContribution | KeybindingContribution | OverlayContribution | EditContextContribution | ObjectTypeContribution | ImporterContribution | ExporterContribution;
 }
-interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore"> {
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard"> {
 }
 /** What `createHeadlessHost` resolves to: a real engine-backed host plus
  *  the conformance affordances (load an IDML, read the contribution log,
@@ -583,4 +603,4 @@ declare function contributeEditContext(host: BundleHost, contribution: EditConte
  *  descent. Capability-gated on `contributes.objectTypes`. */
 declare function contributeObjectType(host: BundleHost, contribution: ObjectTypeContribution): Disposable;
 
-export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type SeededFace, type StorageBacking, WASM_BUDGETS, beginPageDrag, commitAndSelect, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };
+export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, 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 LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type SeededFace, type StorageBacking, WASM_BUDGETS, beginPageDrag, commitAndSelect, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };

package/dist/index.js

@@ -272,6 +272,7 @@ function createBundleHost(getEditor, manifest, options) {
   const hasRendering = (s) => caps?.rendering?.includes(s) ?? false;
   const hasAsset = (k) => caps?.assets?.includes(k) ?? false;
   const hasBlobStore = () => caps?.storage?.blob === true;
+  const clipboardGrant = () => caps?.clipboard === "full" ? "full" : caps?.clipboard === "vector" ? "vector" : "none";
   const lists = (arr, id) => arr?.includes(id) ?? false;
   const declaresType = (arr, type) => arr?.some((e) => e.type === type) ?? false;
   const requireDeclared = (ok, door, missing) => {
@@ -983,6 +984,87 @@ function createBundleHost(getEditor, manifest, options) {
       }
     }
   };
+  const imageChannel = () => getEditor().images;
+  const images = {
+    claimImageResource(elementId, opts) {
+      requireDeclared(
+        hasRendering("resourceProvider"),
+        "images.claimImageResource",
+        'capabilities.rendering must include "resourceProvider"'
+      );
+      const channel = imageChannel();
+      if (!channel) {
+        log.warn(
+          `images.claimImageResource("${elementId}") ignored \u2014 the host wired no resource channel (probe supports("rendering.resourceProvider@1"))`
+        );
+        return store.add(toDisposable(() => {
+        }));
+      }
+      let released = false;
+      const off = channel.onResourceTilesNeeded((need) => {
+        if (released || need.imageId !== elementId) return;
+        void (async () => {
+          const tiles = [];
+          for (const [x, y] of need.tiles) {
+            let tile;
+            try {
+              tile = await opts.source(need.level, x, y);
+            } catch (err) {
+              log.warn(
+                `images.source(level ${need.level}, ${x}, ${y}) threw \u2014 tile skipped`,
+                err
+              );
+              continue;
+            }
+            if (!tile) continue;
+            tiles.push({
+              x: tile.x,
+              y: tile.y,
+              width: tile.width,
+              height: tile.height,
+              // The wire carries a plain number[]; Array.from copies the
+              // RGBA8 view (isolate-proxy-safe, like the scene-layer path).
+              rgba: Array.from(tile.rgba)
+            });
+          }
+          if (released || tiles.length === 0) return;
+          try {
+            await channel.submitTiles(
+              elementId,
+              need.level,
+              tiles,
+              need.generation
+            );
+          } catch (err) {
+            log.warn(
+              `images.submitTiles("${elementId}", level ${need.level}) failed`,
+              err
+            );
+          }
+        })();
+      });
+      void channel.claim({
+        imageId: elementId,
+        levels: opts.levels,
+        tileSize: opts.tileSize,
+        baseWidth: opts.baseWidth,
+        baseHeight: opts.baseHeight,
+        revision: opts.revision()
+      }).catch((err) => {
+        log.warn(`images.claim("${elementId}") failed`, err);
+      });
+      return store.add(
+        toDisposable(() => {
+          if (released) return;
+          released = true;
+          off();
+          void channel.release(elementId).catch((err) => {
+            log.warn(`images.release("${elementId}") failed`, err);
+          });
+        })
+      );
+    }
+  };
   const blobBackend = options?.blobStore;
   const blobQuota = Math.min(
     BLOB_BUDGETS.defaultQuotaBytes,
@@ -1031,6 +1113,51 @@ function createBundleHost(getEditor, manifest, options) {
       return { used: await blobBackend.used(manifest.id), quota: blobQuota };
     }
   };
+  const clipboardBackend = options?.clipboard;
+  const clipboardGate = (door) => {
+    const grant = clipboardGrant();
+    requireDeclared(
+      grant !== "none",
+      door,
+      'capabilities.clipboard must be "full" or "vector"'
+    );
+    return grant === "full" ? "full" : "vector";
+  };
+  const clipboard = {
+    async read() {
+      const tier = clipboardGate("clipboard.read");
+      if (!clipboardBackend) return null;
+      let payload;
+      try {
+        payload = await clipboardBackend.read();
+      } catch {
+        return null;
+      }
+      if (!payload) return null;
+      if (tier === "vector" && payload.tabular !== void 0) {
+        const { tabular: _dropped, ...rest } = payload;
+        return rest;
+      }
+      return payload;
+    },
+    async write(payload) {
+      const tier = clipboardGate("clipboard.write");
+      if (!clipboardBackend) return;
+      let toWrite = payload;
+      if (tier === "vector" && payload.tabular !== void 0) {
+        log.warn(
+          'clipboard.write: dropping the tabular payload \u2014 capabilities.clipboard is "vector" (text only); declare "full" to copy a cell grid'
+        );
+        const { tabular: _dropped, ...rest } = payload;
+        toWrite = rest;
+      }
+      try {
+        await clipboardBackend.write(toWrite);
+      } catch (err) {
+        log.warn("clipboard.write: the platform refused the write", err);
+      }
+    }
+  };
   const featureSet = new Set(HOST_FEATURES);
   if (getEditor().text) {
     featureSet.add("text.measure@1");
@@ -1038,6 +1165,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (getEditor().sceneLayers) {
     featureSet.add("rendering.sceneLayer@1");
   }
+  if (getEditor().images) {
+    featureSet.add("rendering.resourceProvider@1");
+  }
   if (options?.shell) {
     featureSet.add("shell.openPanel@1");
     featureSet.add("shell.pickFile@1");
@@ -1063,6 +1193,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.blobStore) {
     featureSet.add("storage.blob@1");
   }
+  if (options?.clipboard) {
+    featureSet.add("clipboard@1");
+  }
   const host = {
     manifest,
     log,
@@ -1081,6 +1214,8 @@ function createBundleHost(getEditor, manifest, options) {
     bindings,
     widgets,
     assets,
+    images,
+    clipboard,
     supports: (feature) => featureSet.has(feature),
     get editor() {
       return getEditor();
@@ -1255,6 +1390,24 @@ function inMemoryBlobStore() {
     }
   };
 }
+function inMemoryClipboard() {
+  let slot = null;
+  return {
+    async read() {
+      if (!slot) return null;
+      return {
+        ...slot.text !== void 0 ? { text: slot.text } : {},
+        ...slot.tabular ? { tabular: { rows: slot.tabular.rows.map((r) => [...r]) } } : {}
+      };
+    },
+    async write(payload) {
+      slot = {
+        ...payload.text !== void 0 ? { text: payload.text } : {},
+        ...payload.tabular ? { tabular: { rows: payload.tabular.rows.map((r) => [...r]) } } : {}
+      };
+    }
+  };
+}
 var seqCounter = 1;
 function makeEngineEditor(worker, recorder, onToolPreview) {
   const protocol = worker.protocolVersion;
@@ -1417,10 +1570,12 @@ async function createHeadlessHost(options = {}) {
   let currentHost = null;
   let disposed = false;
   const blobStore = options.blobStore ?? inMemoryBlobStore();
+  const clipboard = options.clipboard ?? inMemoryClipboard();
   const buildHost = (manifest, mode) => createBundleHost(() => editor, manifest, {
     console: options.console,
     storage: options.storage,
     blobStore,
+    clipboard,
     capabilityMode: mode,
     // W-06 — a recordable fake asset source the conformance harness
     // can pass so a bundle's `@font-face` byte path is exercisable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-sdk",
-  "version": "0.2.14-canary.0",
+  "version": "0.2.17-canary.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@paged-media/plugin-api": "0.2.14-canary.0"
+    "@paged-media/plugin-api": "0.2.17-canary.0"
   },
   "peerDependencies": {
     "react": "^18.3.0"
@@ -22,7 +22,7 @@
     }
   },
   "devDependencies": {
-    "@paged-media/canvas-wasm": "0.43.0",
+    "@paged-media/canvas-wasm": "0.44.0",
     "@types/node": "20.19.39",
     "@types/react": "^18.3.12",
     "react": "^18.3.0",