@paged-media/plugin-sdk 0.2.25-canary.0 → 0.2.27-canary.0

package/dist/index.d.ts

@@ -192,6 +192,23 @@ interface ClipboardBackend {
     read(): Promise<ClipboardPayload | null>;
     write(payload: ClipboardPayload): Promise<void>;
 }
+/**
+ * The backend the editor injects to back `host.nativeDocument` (ADR-021 /
+ * document-model direction): the isolate-safe replacement for an importer/
+ * exporter reaching through `host.editor.client`. It exposes read access to
+ * the document's CORE-OWNED native parts (the `paged/core/` MODEL + COMPOSITION
+ * parts) plus a `open` that loads a plugin-produced native/importable package
+ * as the active document. The SDK adapter owns the capability gate; this
+ * backend only does the raw IO. A headless host injects no backend → the reads
+ * answer `null`/`[]`, `open` rejects, and `supports("document.readNative@1")` /
+ * `supports("document.openNative@1")` are false (the honest no-backend door).
+ */
+interface NativeDocumentBackend {
+    readModel(): Promise<Uint8Array | null>;
+    readComposition(): Promise<Uint8Array | null>;
+    listParts(prefix?: string): Promise<string[]>;
+    open(bytes: Uint8Array): 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
@@ -305,6 +322,15 @@ interface CreateBundleHostOptions {
      *  When absent, `read` answers `null` and `write` is a no-op (the honest
      *  no-clipboard door). */
     clipboard?: ClipboardBackend;
+    /** Host-provided NATIVE-DOCUMENT backend (ADR-021). When present,
+     *  `host.nativeDocument.readModel/readComposition/listParts` read the
+     *  document's core-owned `paged/core/` native parts through it (gated on
+     *  `capabilities.document.readNative`) and `host.nativeDocument.open` loads a
+     *  plugin-produced package as the active document (gated on
+     *  `capabilities.document.openNative`); `supports("document.readNative@1")` /
+     *  `supports("document.openNative@1")` answer true. When absent, the reads
+     *  answer `null`/`[]` and `open` rejects (the honest no-backend door). */
+    nativeDocument?: NativeDocumentBackend;
     /** 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,
@@ -684,4 +710,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 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 SecretStoreBackend, type SeededFace, type SpawnedWorker, type StorageBacking, WASM_BUDGETS, WORKER_BUDGETS, type WorkerBackend, 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 NativeDocumentBackend, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type SecretStoreBackend, type SeededFace, type SpawnedWorker, type StorageBacking, WASM_BUDGETS, WORKER_BUDGETS, type WorkerBackend, 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

@@ -282,6 +282,8 @@ function createBundleHost(getEditor, manifest, options) {
   const caps = manifest.capabilities;
   const declared = manifest.contributes;
   const hasDoc = (dir) => caps?.document?.[dir] !== void 0;
+  const hasNativeRead = () => caps?.document?.readNative === true;
+  const hasNativeOpen = () => caps?.document?.openNative === true;
   const hasRendering = (s) => caps?.rendering?.includes(s) ?? false;
   const hasAsset = (k) => caps?.assets?.includes(k) ?? false;
   const hasBlobStore = () => caps?.storage?.blob === true;
@@ -538,6 +540,16 @@ function createBundleHost(getEditor, manifest, options) {
     door,
     "capabilities.document.read must be declared"
   );
+  const requireNativeRead = (door) => requireDeclared(
+    hasNativeRead(),
+    door,
+    "capabilities.document.readNative must be declared"
+  );
+  const requireNativeOpen = (door) => requireDeclared(
+    hasNativeOpen(),
+    door,
+    "capabilities.document.openNative must be declared"
+  );
   const document = {
     async mutate(mutation) {
       const denied = denyWrite(
@@ -1169,6 +1181,30 @@ function createBundleHost(getEditor, manifest, options) {
       );
     }
   };
+  const nativeDocBackend = options?.nativeDocument;
+  const nativeDocument = {
+    async readModel() {
+      requireNativeRead("nativeDocument.readModel");
+      return nativeDocBackend ? nativeDocBackend.readModel() : null;
+    },
+    async readComposition() {
+      requireNativeRead("nativeDocument.readComposition");
+      return nativeDocBackend ? nativeDocBackend.readComposition() : null;
+    },
+    async listParts(prefix2) {
+      requireNativeRead("nativeDocument.listParts");
+      return nativeDocBackend ? nativeDocBackend.listParts(prefix2) : [];
+    },
+    async open(bytes) {
+      requireNativeOpen("nativeDocument.open");
+      if (!nativeDocBackend) {
+        throw new Error(
+          'host.nativeDocument.open: the host wired no nativeDocument backend (supports("document.openNative@1") is false; the editor injects one)'
+        );
+      }
+      return nativeDocBackend.open(bytes);
+    }
+  };
   const clipboardBackend = options?.clipboard;
   const clipboardGate = (door) => {
     const grant = clipboardGrant();
@@ -1405,6 +1441,10 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.clipboard) {
     featureSet.add("clipboard@1");
   }
+  if (options?.nativeDocument) {
+    featureSet.add("document.readNative@1");
+    featureSet.add("document.openNative@1");
+  }
   if (options?.workers) {
     featureSet.add("workers@1");
   }
@@ -1427,6 +1467,7 @@ function createBundleHost(getEditor, manifest, options) {
     storage,
     blob,
     parts,
+    nativeDocument,
     network,
     dataProviders,
     diagnostics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-sdk",
-  "version": "0.2.25-canary.0",
+  "version": "0.2.27-canary.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@paged-media/plugin-api": "0.2.25-canary.0"
+    "@paged-media/plugin-api": "0.2.27-canary.0"
   },
   "peerDependencies": {
     "react": "^18.3.0"