@paged-media/plugin-sdk 0.2.16-canary.0 → 0.2.19-canary.0

package/dist/index.d.ts

@@ -98,6 +98,17 @@ declare const BLOB_BUDGETS: {
     /** Default per-plugin blob ceiling, in bytes (64 MiB). */
     readonly defaultQuotaBytes: number;
 };
+/** Worker spawn + SAB budgets (K-3 / S-07). The host enforces the
+ *  stricter of these and any manifest tightening. */
+declare const WORKER_BUDGETS: {
+    /** Hard worker-count cap per bundle. The grant is `min(declared.max,
+     *  hardwareConcurrency, maxWorkers)` — a runaway `max` can't exhaust
+     *  the machine. */
+    readonly maxWorkers: 8;
+    /** Default per-bundle shared-memory ceiling, in bytes (256 MiB). A
+     *  manifest's `maxSharedBytes` may only TIGHTEN this. */
+    readonly defaultSharedBytes: number;
+};
 /**
  * The backend the editor injects to back `host.blob` (K-4 / S-08): a
  * RAW per-plugin byte store (OPFS in-browser; an in-memory map in the
@@ -113,6 +124,60 @@ interface BlobStore {
     /** Total bytes this plugin currently stores. */
     used(pluginId: string): Promise<number>;
 }
+/**
+ * A raw spawned worker the `WorkerBackend` hands back (K-3 / S-07). The
+ * SDK adapter owns the capability gate, the count cap, the SAB budget,
+ * and teardown tracking; this backend only constructs the realm + does
+ * the raw message IO. `post` forwards to the underlying worker (optional
+ * transfer); `onMessage` subscribes (the backend fans out); `terminate`
+ * destroys the realm.
+ */
+interface SpawnedWorker {
+    post(message: unknown, transfer?: Transferable[]): void;
+    onMessage(handler: (message: unknown) => void): Disposable;
+    terminate(): void;
+}
+/**
+ * The backend the editor injects to back `host.workers` (K-3 / S-07 /
+ * I-02): it resolves a bundle's DECLARED, bundle-relative `module` path
+ * through the bundle's own asset base (the `/@fs/`-allowed sibling-plugin
+ * path the wasm artifacts use) and constructs an ES-module `Worker`. The
+ * SDK adapter passes the plugin id + the declared module path; the
+ * backend never invents a URL. Returns a `SpawnedWorker` (or rejects when
+ * the module fails to resolve/construct). The SAB itself is allocated by
+ * the SDK adapter (a plain `new SharedArrayBuffer` under the host budget)
+ * — the backend's job is purely the worker realm. A headless host injects
+ * no backend → `spawn` rejects + `supports("workers@1")` is false.
+ */
+interface WorkerBackend {
+    spawn(pluginId: string, module: string, name?: string): Promise<SpawnedWorker>;
+}
+/**
+ * The backend the editor injects to back `host.secrets` (D-11;
+ * rfc-credential-store): a REFERENCE-ONLY, host-owned credential store. The
+ * SDK adapter owns the capability gate + the namespacing (passes the plugin
+ * id); this backend owns the storage tier (WebCrypto-wrapped IndexedDB in
+ * the editor, an in-memory map in the headless harness) AND the user PROMPT
+ * — the RFC's "via host UI only": `set` resolves only after the host has
+ * the material (the editor backing prompts the user; the plugin's supplied
+ * `secret` is the value to STORE, never persisted silently by the adapter).
+ *
+ * The trust line is the ABSENCE of a read: there is `set`/`exists`/`forget`
+ * and NO `get` — secret bytes never leave the host realm. A headless host
+ * injects no backend → `set`/`forget` reject, `exists` is false,
+ * `supports("secrets@1")` is false. The plugin id + the (caller-supplied)
+ * `ref` together namespace the stored secret (`paged:<plugin-id>:<ref>`).
+ */
+interface SecretStoreBackend {
+    /** Store `secret` for `pluginId` under `ref` (the editor backing PROMPTS
+     *  the user — "via host UI only"). Rejects when the user declines or the
+     *  store is unavailable. */
+    set(pluginId: string, ref: string, secret: string): Promise<void>;
+    /** Whether a secret is stored for `pluginId`/`ref`. */
+    exists(pluginId: string, ref: string): Promise<boolean>;
+    /** Forget the secret for `pluginId`/`ref` (idempotent). */
+    forget(pluginId: string, ref: string): Promise<void>;
+}
 /**
  * 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`
@@ -240,6 +305,22 @@ interface CreateBundleHostOptions {
      *  When absent, `read` answers `null` and `write` is a no-op (the honest
      *  no-clipboard door). */
     clipboard?: ClipboardBackend;
+    /** 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,
+     *  count-capped, SAB-budgeted, teardown-tracked) and
+     *  `supports("workers@1")` answers true. When absent, `spawn` rejects
+     *  honestly, `concurrency()` is 0, and the feature flag is false (the
+     *  honest no-worker door). */
+    workers?: WorkerBackend;
+    /** Host-provided CREDENTIAL-STORE backend (D-11; rfc-credential-store).
+     *  When present, `host.secrets.set/exists/forget` go through it
+     *  (capability-gated on `capabilities.secrets`; `set` prompts the user —
+     *  "via host UI only") and `supports("secrets@1")` answers true. When
+     *  absent, `set`/`forget` reject and `exists` is false (the honest
+     *  no-store door). REFERENCE-ONLY: there is no `get` anywhere — secret
+     *  bytes never enter the plugin realm. */
+    secrets?: SecretStoreBackend;
     /**
      * How the host treats a declaration↔use mismatch — a bundle that
      * USES a door (`contribute.tool`, `document.mutate`, …) it did not
@@ -334,7 +415,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" | "clipboard"> {
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets"> {
 }
 /** What `createHeadlessHost` resolves to: a real engine-backed host plus
  *  the conformance affordances (load an IDML, read the contribution log,
@@ -603,4 +684,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 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 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

@@ -201,6 +201,15 @@ var BLOB_BUDGETS = {
   /** Default per-plugin blob ceiling, in bytes (64 MiB). */
   defaultQuotaBytes: 64 * 1024 * 1024
 };
+var WORKER_BUDGETS = {
+  /** Hard worker-count cap per bundle. The grant is `min(declared.max,
+   *  hardwareConcurrency, maxWorkers)` — a runaway `max` can't exhaust
+   *  the machine. */
+  maxWorkers: 8,
+  /** Default per-bundle shared-memory ceiling, in bytes (256 MiB). A
+   *  manifest's `maxSharedBytes` may only TIGHTEN this. */
+  defaultSharedBytes: 256 * 1024 * 1024
+};
 function createDataProviderRegistry() {
   const providers = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Map();
@@ -273,6 +282,8 @@ function createBundleHost(getEditor, manifest, options) {
   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 hasWorkers = () => typeof caps?.workers?.max === "number";
+  const hasSecrets = () => caps?.secrets?.sources === 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) => {
@@ -984,6 +995,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,
@@ -1077,6 +1169,159 @@ function createBundleHost(getEditor, manifest, options) {
       }
     }
   };
+  const workerBackend = options?.workers;
+  const declaredWorkers = caps?.workers;
+  const hardwareConcurrency = globalThis.navigator?.hardwareConcurrency ?? 1;
+  const workerCap = hasWorkers() && workerBackend ? Math.max(
+    0,
+    Math.min(
+      declaredWorkers?.max ?? 0,
+      hardwareConcurrency,
+      WORKER_BUDGETS.maxWorkers
+    )
+  ) : 0;
+  const sharedByteBudget = Math.min(
+    WORKER_BUDGETS.defaultSharedBytes,
+    declaredWorkers?.maxSharedBytes ?? WORKER_BUDGETS.defaultSharedBytes
+  );
+  const sharedMemoryDeclared = declaredWorkers?.sharedMemory === true;
+  const crossOriginIsolated = globalThis.crossOriginIsolated === true;
+  let liveWorkerCount = 0;
+  let sharedBytesUsed = 0;
+  const makeBundleWorker = (raw) => {
+    let terminated = false;
+    let mySharedBytes = 0;
+    const subs = new DisposableStore();
+    const worker = {
+      post(message, transfer) {
+        if (terminated) return;
+        raw.post(message, transfer);
+      },
+      onMessage(handler) {
+        if (terminated) return toDisposable(() => {
+        });
+        return subs.add(raw.onMessage(handler));
+      },
+      allocateShared(bytes) {
+        if (terminated) return null;
+        if (!sharedMemoryDeclared) {
+          log.warn(
+            "workers.allocateShared: capabilities.workers.sharedMemory is not declared \u2014 no SharedArrayBuffer (declare it to allocate)"
+          );
+          return null;
+        }
+        if (!crossOriginIsolated) {
+          log.warn(
+            "workers.allocateShared: the environment is not cross-origin isolated \u2014 SharedArrayBuffer is unavailable (the host needs COOP/COEP)"
+          );
+          return null;
+        }
+        if (!Number.isInteger(bytes) || bytes <= 0) return null;
+        if (sharedBytesUsed + bytes > sharedByteBudget) {
+          log.warn(
+            `workers.allocateShared(${bytes}) would exceed the ${sharedByteBudget}-byte per-bundle shared-memory budget (used ${sharedBytesUsed}) \u2014 refused`
+          );
+          return null;
+        }
+        let sab;
+        try {
+          sab = new SharedArrayBuffer(bytes);
+        } catch (err) {
+          log.warn(`workers.allocateShared(${bytes}) failed`, err);
+          return null;
+        }
+        sharedBytesUsed += bytes;
+        mySharedBytes += bytes;
+        return sab;
+      },
+      terminate() {
+        if (terminated) return;
+        terminated = true;
+        subs.dispose();
+        sharedBytesUsed -= mySharedBytes;
+        mySharedBytes = 0;
+        liveWorkerCount = Math.max(0, liveWorkerCount - 1);
+        try {
+          raw.terminate();
+        } catch (err) {
+          log.warn("workers.terminate: backend terminate threw", err);
+        }
+      }
+    };
+    return worker;
+  };
+  const workers = {
+    async spawn(opts) {
+      requireDeclared(
+        hasWorkers(),
+        "workers.spawn",
+        "capabilities.workers must be declared"
+      );
+      if (!workerBackend) {
+        throw new Error(
+          `host.workers.spawn("${opts.module}") \u2014 no worker backend wired (supports("workers@1") is false; the editor injects one)`
+        );
+      }
+      if (liveWorkerCount >= workerCap) {
+        throw new Error(
+          `host.workers.spawn("${opts.module}") \u2014 the ${workerCap}-worker count cap is reached (declared max ${declaredWorkers?.max}, clamped to min(declared, hardwareConcurrency ${hardwareConcurrency}, ${WORKER_BUDGETS.maxWorkers})) \u2014 terminate a worker first`
+        );
+      }
+      liveWorkerCount++;
+      let raw;
+      try {
+        raw = await workerBackend.spawn(manifest.id, opts.module, opts.name);
+      } catch (err) {
+        liveWorkerCount = Math.max(0, liveWorkerCount - 1);
+        throw err instanceof Error ? err : new Error(
+          `host.workers.spawn("${opts.module}") failed: ${String(err)}`
+        );
+      }
+      const worker = makeBundleWorker(raw);
+      store.add(toDisposable(() => worker.terminate()));
+      return worker;
+    },
+    concurrency: () => workerCap
+  };
+  const secretStore = options?.secrets;
+  const secrets = {
+    async set(ref, secret) {
+      requireDeclared(
+        hasSecrets(),
+        "secrets.set",
+        "capabilities.secrets must declare { sources: true }"
+      );
+      if (!secretStore) {
+        throw new Error(
+          `host.secrets.set("${ref}") \u2014 no secret-store backend wired (supports("secrets@1") is false; the editor injects one)`
+        );
+      }
+      await secretStore.set(manifest.id, ref, secret);
+    },
+    async exists(ref) {
+      requireDeclared(
+        hasSecrets(),
+        "secrets.exists",
+        "capabilities.secrets must declare { sources: true }"
+      );
+      if (!secretStore) return false;
+      return secretStore.exists(manifest.id, ref);
+    },
+    async forget(ref) {
+      requireDeclared(
+        hasSecrets(),
+        "secrets.forget",
+        "capabilities.secrets must declare { sources: true }"
+      );
+      if (!secretStore) {
+        log.warn(
+          `host.secrets.forget("${ref}") \u2014 no secret-store backend wired (supports("secrets@1") is false); nothing to forget`
+        );
+        return;
+      }
+      await secretStore.forget(manifest.id, ref);
+    }
+  };
   const featureSet = new Set(HOST_FEATURES);
   if (getEditor().text) {
     featureSet.add("text.measure@1");
@@ -1084,6 +1329,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");
@@ -1112,6 +1360,12 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.clipboard) {
     featureSet.add("clipboard@1");
   }
+  if (options?.workers) {
+    featureSet.add("workers@1");
+  }
+  if (options?.secrets) {
+    featureSet.add("secrets@1");
+  }
   const host = {
     manifest,
     log,
@@ -1130,6 +1384,9 @@ function createBundleHost(getEditor, manifest, options) {
     bindings,
     widgets,
     assets,
+    images,
+    workers,
+    secrets,
     clipboard,
     supports: (feature) => featureSet.has(feature),
     get editor() {
@@ -1323,6 +1580,25 @@ function inMemoryClipboard() {
     }
   };
 }
+function inMemorySecretStore() {
+  const byPlugin = /* @__PURE__ */ new Map();
+  const dir = (id) => {
+    let d = byPlugin.get(id);
+    if (!d) byPlugin.set(id, d = /* @__PURE__ */ new Set());
+    return d;
+  };
+  return {
+    async set(id, ref, _secret) {
+      dir(id).add(ref);
+    },
+    async exists(id, ref) {
+      return dir(id).has(ref);
+    },
+    async forget(id, ref) {
+      dir(id).delete(ref);
+    }
+  };
+}
 var seqCounter = 1;
 function makeEngineEditor(worker, recorder, onToolPreview) {
   const protocol = worker.protocolVersion;
@@ -1486,11 +1762,13 @@ async function createHeadlessHost(options = {}) {
   let disposed = false;
   const blobStore = options.blobStore ?? inMemoryBlobStore();
   const clipboard = options.clipboard ?? inMemoryClipboard();
+  const secrets = options.secrets ?? inMemorySecretStore();
   const buildHost = (manifest, mode) => createBundleHost(() => editor, manifest, {
     console: options.console,
     storage: options.storage,
     blobStore,
     clipboard,
+    secrets,
     capabilityMode: mode,
     // W-06 — a recordable fake asset source the conformance harness
     // can pass so a bundle's `@font-face` byte path is exercisable
@@ -1557,7 +1835,8 @@ async function createHeadlessHost(options = {}) {
       document: { read: "broad", write: "broad" },
       rendering: ["overlay", "hitTest", "sceneLayer"],
       keybindings: true,
-      storage: { blob: true }
+      storage: { blob: true },
+      secrets: { sources: true }
     },
     // Broad contribution declarations so the neutral DRIVER host (which
     // registers arbitrary contributions directly in 'warn' mode) never
@@ -1915,6 +2194,7 @@ export {
   PluginApiNotImplemented,
   PluginCapabilityError,
   WASM_BUDGETS,
+  WORKER_BUDGETS,
   beginPageDrag,
   commitAndSelect,
   contributeEditContext,

package/package.json

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