@paged-media/plugin-sdk 0.2.37-canary.0 → 0.2.39-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, 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, 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';
 
 /**
@@ -333,7 +333,19 @@ type BundleTrust = "first-party";
  * omits `saveFile` still injects a valid backend and
  * `supports("shell.saveFile@1")` reports the truth.
  */
-type ShellBackend = Omit<ShellSurface, "saveFile"> & Partial<Pick<ShellSurface, "saveFile">>;
+type ShellBackend = Omit<ShellSurface, "saveFile" | "enterEditContext"> & Partial<Pick<ShellSurface, "saveFile" | "enterEditContext">>;
+/** The host's will-save registry (protocol 66 batch): the editor awaits
+ *  every registered listener before it serialises the document. The SDK
+ *  wraps each bundle listener so it is awaited and its errors contained. */
+interface WillSaveBackend {
+    register(pluginId: string, listener: (e: WillSaveEvent) => Promise<void>): Disposable;
+}
+/** The host's tool-options store, read side: the values its tool-options
+ *  UI holds per tool id, plus a change subscription. */
+interface ToolSettingsBackend {
+    get(toolId: string): Record<string, ToolSettingValue>;
+    subscribe(toolId: string, listener: () => void): () => void;
+}
 interface CreateBundleHostOptions {
     /**
      * The host's trust assertion for this bundle (`plugin-trust-line.md`).
@@ -385,7 +397,14 @@ interface CreateBundleHostOptions {
      *  the editor's UI package and is injected here. When absent,
      *  `host.widgets` is the plain-textarea fallback and
      *  `supports("widgets.codeEditor@1")` answers false. */
-    widgets?: WidgetSurface;
+    widgets?: Partial<WidgetSurface>;
+    /** The host's will-save registry. When absent, `document.onWillSave`
+     *  holds listeners that never run and `supports("document.onWillSave@1")`
+     *  is false. */
+    willSave?: WillSaveBackend;
+    /** The host's tool-options store. When absent, `host.tools.settings`
+     *  answers `{}` and `supports("tools.settings@1")` is false. */
+    toolSettings?: ToolSettingsBackend;
     /** Host-provided SCHEMA-PANEL renderer (W3.1): the editor's
      *  `SchemaPanelRenderer` that walks a `PanelSchema` through the
      *  catalog + subscribes to the bundle's bindings. When absent,
@@ -560,8 +579,20 @@ 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" | "secrets" | "bindingProviders"> {
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets" | "bindingProviders" | "willSave" | "toolSettings"> {
 }
+/** A headless will-save registry: listeners register per plugin and
+ *  `fire()` awaits them all, the way the editor's save path does — so a
+ *  bundle's commit-before-save is assertable without an editor. */
+declare function inMemoryWillSave(): WillSaveBackend & {
+    fire(): Promise<void>;
+    count(): number;
+};
+/** A headless tool-options store: what the editor's tool-options UI would
+ *  hold, settable from a test with `set`. */
+declare function inMemoryToolSettings(): ToolSettingsBackend & {
+    set(toolId: string, key: string, value: ToolSettingValue): void;
+};
 /** What `createHeadlessHost` resolves to: a real engine-backed host plus
  *  the conformance affordances (load an IDML, read the contribution log,
  *  load a bundle, dispose honestly). */
@@ -615,6 +646,13 @@ interface HeadlessHost {
      *  that a path it does not declare comes back as a typed refusal to
      *  fall through to core). */
     readonly bindingProviders: BindingProviderBackend;
+    /** The will-save registry this host injected: `fire()` runs every
+     *  bundle's `document.onWillSave` listener and awaits them, as a save
+     *  would. */
+    readonly willSave: ReturnType<typeof inMemoryWillSave>;
+    /** The tool-options store this host injected: `set()` stands in for the
+     *  editor's tool-options UI, and `host.tools` reads it back. */
+    readonly toolSettings: ReturnType<typeof inMemoryToolSettings>;
     /** 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[]>;
@@ -664,8 +702,9 @@ declare const API_VERSION = "0.2.0";
  */
 declare function satisfiesApiVersion(range: string, version?: string): boolean;
 
-/** The default widget catalog: a textarea CodeEditor. Replaced wholesale
- *  when the host app injects `widgets` into `createBundleHost`. */
+/** The default widget catalog: a textarea CodeEditor and a native colour
+ *  input. Each member is replaced by the one the host app injects through
+ *  `createBundleHost({ widgets })`; members it omits keep the fallback. */
 declare const FALLBACK_WIDGETS: WidgetSurface;
 
 /** One recorded `getFontFace` call. */
@@ -882,4 +921,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, WASM_BUDGETS, WORKER_BUDGETS, type WorkerBackend, beginPageDrag, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBindingProviderRegistry, 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 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 };

package/dist/index.js

@@ -93,8 +93,31 @@ function TextareaCodeEditor(props) {
     }
   });
 }
+function NativeColorPicker(props) {
+  const createElement2 = requireCreateElement(
+    "plugin-sdk: host.widgets.ColorPicker fell back to <input type=color>, but React is not installed. Install react, or inject a widget catalog via createBundleHost({ widgets })."
+  );
+  return createElement2("input", {
+    type: "color",
+    value: props.value,
+    disabled: props.disabled,
+    "aria-label": props.ariaLabel,
+    "data-color-picker-fallback": "native",
+    onChange: (e) => props.onChange(e.currentTarget.value),
+    onBlur: (e) => props.onCommit?.(e.currentTarget.value),
+    style: {
+      width: 40,
+      height: 24,
+      padding: 0,
+      border: "1px solid var(--pg-border)",
+      borderRadius: "var(--radius-sm, 4px)",
+      background: "var(--pg-bg)"
+    }
+  });
+}
 var FALLBACK_WIDGETS = {
-  CodeEditor: TextareaCodeEditor
+  CodeEditor: TextareaCodeEditor,
+  ColorPicker: NativeColorPicker
 };
 
 // src/schema-panel.tsx
@@ -139,6 +162,34 @@ function makeSchemaPanelComponent(contribution, bindings, renderer) {
 }
 
 // src/host-impl.ts
+function isBytesSlot(m) {
+  if (m.op !== "replaceImageBytes") return false;
+  const b = m.args.bytes;
+  return Array.isArray(b) && b.length === 0;
+}
+function hasBytesSlot(m) {
+  if (isBytesSlot(m)) return true;
+  if (m.op === "batch") return m.args.ops.some((op) => hasBytesSlot(op));
+  return false;
+}
+function spliceBytesSlot(m, bytes) {
+  let filled = false;
+  const visit = (node) => {
+    if (filled) return node;
+    if (isBytesSlot(node)) {
+      filled = true;
+      return { ...node, args: { ...node.args, bytes } };
+    }
+    if (node.op === "batch") {
+      return {
+        ...node,
+        args: { ...node.args, ops: node.args.ops.map((op) => visit(op)) }
+      };
+    }
+    return node;
+  };
+  return visit(m);
+}
 var HOST_FEATURES = [
   "contribute.tool@1",
   "contribute.panel@1",
@@ -200,6 +251,11 @@ var HOST_FEATURES = [
   // v51) is the writer, so it is live whenever a bundle runs (the worker
   // handshake guarantees a v51-protocol worker).
   "storage.parts@1",
+  // Protocol 66 — `host.parts.delete`. Static for the same reason as @1:
+  // the pinned engine (the worker handshake refuses an older one) answers
+  // `deletePagedPart`, and the binary lane is an optimisation the SDK
+  // falls back from, not a different contract.
+  "storage.parts@2",
   // B-22 (protocol v57) — the planar-region read door. STATIC, and the
   // flag means exactly one thing: this SDK's document surface IMPLEMENTS
   // `planarRegions` and forwards it (retiring the `host.editor.client`
@@ -210,6 +266,10 @@ var HOST_FEATURES = [
   // honesty split as the protocol-ahead mutations (mutations.ts): the
   // engine-level gate is the worker handshake, not `supports()`.
   "document.planarRegions@1",
+  // v67 (RFI C-68) — the engine's point snapper. Static like the region
+  // door: the flag says this SDK forwards `snapPoint`; an engine older
+  // than v67 answers the point unsnapped, never a throw.
+  "document.snapPoint@1",
   // DOC-03 structured whole-story read (canvas-wasm v54). Static for the same
   // reason as storage.parts@1: the pinned engine is the server, and the worker
   // handshake refuses a protocol older than the pin — so a running bundle is
@@ -464,6 +524,50 @@ function createBindingProviderRegistry() {
     }
   };
 }
+function checkImage(image) {
+  const { width, height, rgba } = image;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || rgba.length !== width * height * 4) {
+    throw new Error(
+      `contribute.sceneLayer().submitImage: ${rgba.length} bytes for a ${width}x${height} RGBA8 image (want width*height*4)`
+    );
+  }
+}
+function imageLayer(image) {
+  const [x, y, w, h2] = image.dest;
+  return {
+    items: [
+      {
+        kind: "image",
+        rgba: Array.from(image.rgba),
+        width: image.width,
+        height: image.height,
+        x,
+        y,
+        w,
+        h: h2
+      }
+    ]
+  };
+}
+function checkTiles(image, tiles) {
+  for (const t of tiles) {
+    if (t.width <= 0 || t.height <= 0 || t.x < 0 || t.y < 0 || t.x + t.width > image.width || t.y + t.height > image.height || t.rgba.length !== t.width * t.height * 4) {
+      throw new Error(
+        `contribute.sceneLayer().submitImageTiles: tile ${t.x},${t.y} ${t.width}x${t.height} (${t.rgba.length} bytes) does not fit the ${image.width}x${image.height} image`
+      );
+    }
+  }
+}
+function patchImage(image, tiles) {
+  const stride = image.width * 4;
+  for (const t of tiles) {
+    const row = t.width * 4;
+    for (let j = 0; j < t.height; j++) {
+      const dst = (t.y + j) * stride + t.x * 4;
+      image.rgba.set(t.rgba.subarray(j * row, j * row + row), dst);
+    }
+  }
+}
 function createBundleHost(getEditor, manifest, options) {
   const store = new DisposableStore();
   const sink = options?.console ?? console;
@@ -892,6 +996,8 @@ function createBundleHost(getEditor, manifest, options) {
         'capabilities.rendering must include "sceneLayer"'
       );
       const submitted = /* @__PURE__ */ new Set();
+      const imaged = /* @__PURE__ */ new Map();
+      const retained = /* @__PURE__ */ new Map();
       const channel = () => getEditor().sceneLayers;
       const surface = {
         async submit(elementId, layer) {
@@ -907,14 +1013,83 @@ function createBundleHost(getEditor, manifest, options) {
         },
         async clear(elementId) {
           submitted.delete(elementId);
+          imaged.delete(elementId);
+          retained.delete(elementId);
           await channel()?.clear(elementId);
         },
+        // Protocol 66 — the binary scene-image lane, with the SDK owning
+        // the fallback so a bundle calls one method on every host.
+        async submitImage(elementId, image, options2) {
+          const ch = channel();
+          if (!ch) {
+            log.warn(
+              `contribute.sceneLayer().submitImage("${elementId}") ignored \u2014 the host wired no scene channel (probe supports("rendering.sceneLayer@1"))`
+            );
+            return;
+          }
+          checkImage(image);
+          submitted.add(elementId);
+          imaged.set(elementId, { width: image.width, height: image.height });
+          if (ch.submitImage && ch.submitImageTiles) {
+            retained.delete(elementId);
+            await ch.submitImage(
+              elementId,
+              image,
+              manifest.id,
+              options2?.transfer ?? false
+            );
+            return;
+          }
+          const copy = {
+            rgba: new Uint8Array(image.rgba),
+            width: image.width,
+            height: image.height,
+            dest: [...image.dest]
+          };
+          retained.set(elementId, copy);
+          await ch.submit(elementId, imageLayer(copy), manifest.id);
+        },
+        async submitImageTiles(elementId, tiles, options2) {
+          const ch = channel();
+          if (!ch) {
+            log.warn(
+              `contribute.sceneLayer().submitImageTiles("${elementId}") ignored \u2014 the host wired no scene channel`
+            );
+            return;
+          }
+          const size = imaged.get(elementId);
+          if (!size) {
+            throw new Error(
+              `contribute.sceneLayer().submitImageTiles("${elementId}"): no image was submitted for this element \u2014 call submitImage first`
+            );
+          }
+          checkTiles(size, tiles);
+          if (ch.submitImage && ch.submitImageTiles) {
+            await ch.submitImageTiles(
+              elementId,
+              tiles,
+              manifest.id,
+              options2?.transfer ?? false
+            );
+            return;
+          }
+          const image = retained.get(elementId);
+          if (!image) {
+            throw new Error(
+              `contribute.sceneLayer().submitImageTiles("${elementId}"): the retained image is gone (the binary lane went away mid-session)`
+            );
+          }
+          patchImage(image, tiles);
+          await ch.submit(elementId, imageLayer(image), manifest.id);
+        },
         dispose() {
           const ch = channel();
           if (ch) {
             for (const id of submitted) void ch.clear(id);
           }
           submitted.clear();
+          imaged.clear();
+          retained.clear();
         }
       };
       return store.add(surface);
@@ -965,33 +1140,66 @@ function createBundleHost(getEditor, manifest, options) {
     walk(roots, null);
     return index;
   };
+  const gateRawWrite = (mutation, door) => {
+    const denied = denyWrite(hasDoc("write"), door, "capabilities.document.write");
+    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)}")`;
+      log.warn(error);
+      return { applied: false, error };
+    }
+    return null;
+  };
+  const mutateOutcome = (reply) => {
+    if (reply.kind === "mutationApplied") {
+      const minted = reply.payload.minted;
+      return {
+        applied: true,
+        createdId: reply.payload.createdId ?? null,
+        pageIds: reply.payload.pageIds,
+        ...minted !== void 0 ? { minted } : {}
+      };
+    }
+    return {
+      applied: false,
+      error: reply.kind === "mutationFailed" ? reply.payload : reply
+    };
+  };
   const document = {
     async mutate(mutation) {
-      const denied = denyWrite(
-        hasDoc("write"),
-        "document.mutate",
-        "capabilities.document.write"
-      );
-      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)}")`;
-        log.warn(error);
-        return { applied: false, error };
-      }
+      const gated = gateRawWrite(mutation, "document.mutate");
+      if (gated !== null) return gated;
       try {
         const reply = await getEditor().client.mutate(mutation);
-        if (reply.kind === "mutationApplied") {
-          return {
-            applied: true,
-            createdId: reply.payload.createdId ?? null,
-            pageIds: reply.payload.pageIds
-          };
-        }
+        return mutateOutcome(reply);
+      } catch (error) {
+        return { applied: false, error };
+      }
+    },
+    async mutateWithBytes(mutation, bytes, options2) {
+      const gated = gateRawWrite(mutation, "document.mutateWithBytes");
+      if (gated !== null) return gated;
+      if (!hasBytesSlot(mutation)) {
         return {
           applied: false,
-          error: reply.kind === "mutationFailed" ? reply.payload : reply
+          error: "mutateWithBytes: no replaceImageBytes with an empty `bytes` slot to fill"
         };
+      }
+      try {
+        const editor = getEditor();
+        if (typeof editor.mutateWithBytes === "function") {
+          const reply2 = await editor.mutateWithBytes(
+            mutation,
+            bytes,
+            options2?.transfer === true
+          );
+          return mutateOutcome(reply2);
+        }
+        const reply = await editor.client.mutate(
+          spliceBytesSlot(mutation, Array.from(bytes))
+        );
+        return mutateOutcome(reply);
       } catch (error) {
         return { applied: false, error };
       }
@@ -1092,6 +1300,24 @@ function createBundleHost(getEditor, manifest, options) {
         return refusal(`the region read door failed: ${String(error)}`);
       }
     },
+    async snapPoint(query) {
+      requireDocRead("document.snapPoint");
+      const unsnapped = () => ({
+        point: [query.point[0], query.point[1]],
+        snapped: false,
+        lines: [],
+        tolerancePt: 0
+      });
+      try {
+        const reply = await getEditor().client.send({
+          kind: "requestSnapPoint",
+          payload: { query }
+        });
+        return reply.kind === "snapPoint" ? reply.payload.result : unsnapped();
+      } catch {
+        return unsnapped();
+      }
+    },
     async tree() {
       requireDocRead("document.tree");
       const reply = await getEditor().client.send({
@@ -1185,6 +1411,24 @@ function createBundleHost(getEditor, manifest, options) {
         }
       });
       return store.add(toDisposable(off));
+    },
+    // Protocol 66 batch — the save hook. The host awaits every
+    // registered listener before it serialises the document; the wrapper
+    // makes a bundle's failure a logged event, never a failed save.
+    onWillSave(listener) {
+      const backend = options?.willSave;
+      if (!backend) {
+        return store.add(toDisposable(() => {
+        }));
+      }
+      const wrapped = async (e) => {
+        try {
+          await listener(e);
+        } catch (err) {
+          log.error(`document.onWillSave listener failed: ${String(err)}`);
+        }
+      };
+      return store.add(backend.register(manifest.id, wrapped));
     }
   };
   const selection = {
@@ -1474,9 +1718,44 @@ function createBundleHost(getEditor, manifest, options) {
         `shell.saveFile("${saveOptions.suggestedName}") ignored \u2014 the host app wired no file saver (probe with supports("shell.saveFile@1"))`
       );
       return false;
+    },
+    // Programmatic entry into one of THIS bundle's edit contexts — the
+    // same stack push a double-click performs. A foreign or unregistered
+    // type is a bug in the bundle, so it throws; a host that cannot enter
+    // answers false.
+    async enterEditContext(type, elementId) {
+      if (!registeredContexts.has(type)) {
+        throw new Error(
+          `plugin-api: shell.enterEditContext("${type}") \u2014 ${manifest.id} has registered no edit context of that type. A bundle enters only its own contexts: call contribute.editContext({ type: "${type}", \u2026 }) first.`
+        );
+      }
+      if (!shellBackend?.enterEditContext) {
+        log.warn(
+          `shell.enterEditContext("${type}") ignored \u2014 the host app wired no context entry (probe with supports("shell.enterEditContext@1"))`
+        );
+        return false;
+      }
+      return shellBackend.enterEditContext(type, elementId);
+    }
+  };
+  const toolSettingsBackend = options?.toolSettings;
+  const tools = {
+    settings(toolId) {
+      assertNamespaced(toolId, "tools.settings tool");
+      return { ...toolSettingsBackend?.get(toolId) ?? {} };
+    },
+    onDidChangeSettings(toolId, listener) {
+      assertNamespaced(toolId, "tools.onDidChangeSettings tool");
+      if (!toolSettingsBackend) return store.add(toDisposable(() => {
+      }));
+      const off = toolSettingsBackend.subscribe(
+        toolId,
+        () => listener({ ...toolSettingsBackend.get(toolId) })
+      );
+      return store.add(toDisposable(off));
     }
   };
-  const widgets = options?.widgets ?? FALLBACK_WIDGETS;
+  const widgets = { ...FALLBACK_WIDGETS, ...options?.widgets };
   const assetSource = options?.assetSource;
   const assets = {
     async getFontFace(family, style) {
@@ -1673,10 +1952,20 @@ function createBundleHost(getEditor, manifest, options) {
   };
   const parts = {
     async write(path, bytes) {
+      const full = partsFull(path);
+      const binary = getEditor().parts;
+      if (binary) {
+        try {
+          await binary.write(full, bytes, manifest.id);
+        } catch (err) {
+          throw new Error(`host.parts.write("${path}"): ${String(err)}`);
+        }
+        return;
+      }
       const reply = await getEditor().client.send({
         kind: "writePagedPart",
         payload: {
-          path: partsFull(path),
+          path: full,
           bytes: Array.from(bytes),
           // C-34 — DECLARE WHO IS WRITING, so the engine
           // confines this to `paged/<id>/` instead of trusting that we
@@ -1692,14 +1981,6 @@ function createBundleHost(getEditor, manifest, options) {
           // probe needed — there is no degraded path to choose between.
           caller: manifest.id
         }
-        // THE CAST, named rather than left to be discovered. `wire.d.ts`
-        // is vendored from the PUBLISHED `@paged-media/canvas-wasm`
-        // (0.61.0), whose `writePagedPart` has no `caller` — the field
-        // exists in core today and reaches these types only when the
-        // next canvas-wasm publishes and `sync-wire` runs. Same escape-hatch
-        // shape the repo already uses elsewhere: a cast pointing at a
-        // contract that EXISTS AND IS COMMITTED, not at a hope. It
-        // deletes itself at the repin.
       });
       if (reply.kind !== "pagedPartWritten") {
         const err = reply.kind === "pagedPartFailed" ? reply.payload.error : `unexpected ${reply.kind}`;
@@ -1707,9 +1988,12 @@ function createBundleHost(getEditor, manifest, options) {
       }
     },
     async read(path) {
+      const full = partsFull(path);
+      const binary = getEditor().parts;
+      if (binary) return binary.read(full);
       const reply = await getEditor().client.send({
         kind: "readPagedPart",
-        payload: { path: partsFull(path) }
+        payload: { path: full }
       });
       if (reply.kind === "pagedPartRead") {
         return reply.payload.found ? Uint8Array.from(reply.payload.bytes) : null;
@@ -1725,6 +2009,27 @@ function createBundleHost(getEditor, manifest, options) {
       return reply.payload.paths.map(
         (p) => p.startsWith(partsBase) ? p.slice(partsBase.length) : p
       );
+    },
+    // Protocol 66 — `deletePagedPart`. The engine tombstones a part the
+    // loaded file carries, so it leaves the next save rather than
+    // reappearing from the source container.
+    async delete(path) {
+      const full = partsFull(path);
+      const binary = getEditor().parts;
+      if (binary) {
+        try {
+          return await binary.delete(full, manifest.id);
+        } catch (err2) {
+          throw new Error(`host.parts.delete("${path}"): ${String(err2)}`);
+        }
+      }
+      const reply = await getEditor().client.send({
+        kind: "deletePagedPart",
+        payload: { path: full, caller: manifest.id }
+      });
+      if (reply.kind === "pagedPartDeleted") return reply.payload.existed;
+      const err = reply.kind === "pagedPartFailed" ? reply.payload.error : `unexpected ${reply.kind}`;
+      throw new Error(`host.parts.delete("${path}"): ${err}`);
     }
   };
   const nativeDocBackend = options?.nativeDocument;
@@ -1972,9 +2277,30 @@ function createBundleHost(getEditor, manifest, options) {
       featureSet.add("shell.saveFile@1");
     }
   }
-  if (options?.widgets) {
+  if (options?.widgets?.CodeEditor) {
     featureSet.add("widgets.codeEditor@1");
   }
+  if (options?.widgets?.ColorPicker) {
+    featureSet.add("widgets.colorPicker@1");
+  }
+  if (options?.willSave) {
+    featureSet.add("document.onWillSave@1");
+  }
+  if (typeof options?.shell?.enterEditContext === "function") {
+    featureSet.add("shell.enterEditContext@1");
+  }
+  if (options?.toolSettings) {
+    featureSet.add("tools.settings@1");
+  }
+  {
+    const sl = getEditor().sceneLayers;
+    if (typeof sl?.submitImage === "function" && typeof sl?.submitImageTiles === "function") {
+      featureSet.add("rendering.sceneLayer.binary@1");
+    }
+  }
+  if (typeof getEditor().mutateWithBytes === "function") {
+    featureSet.add("document.mutateBinary@1");
+  }
   if (options?.schemaPanelRenderer) {
     featureSet.add("schemaPanel.renderer@1");
   }
@@ -2040,6 +2366,7 @@ function createBundleHost(getEditor, manifest, options) {
     workers,
     secrets,
     clipboard,
+    tools,
     supports: (feature) => featureSet.has(feature),
     get editor() {
       return getEditor();
@@ -2186,6 +2513,36 @@ async function loadHeadlessEngine(options = {}) {
 }
 
 // src/harness.ts
+function inMemoryWillSave() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    register(_pluginId, listener) {
+      listeners.add(listener);
+      return { dispose: () => void listeners.delete(listener) };
+    },
+    async fire() {
+      await Promise.all([...listeners].map((l) => l({ format: "paged" })));
+    },
+    count: () => listeners.size
+  };
+}
+function inMemoryToolSettings() {
+  const values = /* @__PURE__ */ new Map();
+  const subs = /* @__PURE__ */ new Map();
+  return {
+    get: (toolId) => ({ ...values.get(toolId) ?? {} }),
+    subscribe(toolId, listener) {
+      const set = subs.get(toolId) ?? /* @__PURE__ */ new Set();
+      set.add(listener);
+      subs.set(toolId, set);
+      return () => void set.delete(listener);
+    },
+    set(toolId, key, value) {
+      values.set(toolId, { ...values.get(toolId) ?? {}, [key]: value });
+      for (const l of subs.get(toolId) ?? []) l();
+    }
+  };
+}
 function inMemoryBlobStore() {
   const byPlugin = /* @__PURE__ */ new Map();
   const dir = (id) => {
@@ -2437,6 +2794,8 @@ async function createHeadlessHost(options = {}) {
   const clipboard = options.clipboard ?? inMemoryClipboard();
   const secrets = options.secrets ?? inMemorySecretStore();
   const bindingProviders = options.bindingProviders ?? createBindingProviderRegistry();
+  const willSave = inMemoryWillSave();
+  const toolSettings = inMemoryToolSettings();
   const buildHost = (manifest, mode) => createBundleHost(() => editor, manifest, {
     console: options.console,
     storage: options.storage,
@@ -2444,6 +2803,8 @@ async function createHeadlessHost(options = {}) {
     clipboard,
     secrets,
     bindingProviders,
+    willSave: options.willSave ?? willSave,
+    toolSettings: options.toolSettings ?? toolSettings,
     capabilityMode: mode,
     // W-06 — a recordable fake asset source the conformance harness
     // can pass so a bundle's `@font-face` byte path is exercisable
@@ -2564,6 +2925,8 @@ async function createHeadlessHost(options = {}) {
       return lastPreviews;
     },
     bindingProviders,
+    willSave,
+    toolSettings,
     async load(idml) {
       const raw = worker.loadDocumentDirect(seqCounter++, idml);
       const reply = JSON.parse(raw);
@@ -2951,6 +3314,8 @@ export {
   createRecordableAssetSource,
   defineBundle,
   endLocalFor,
+  inMemoryToolSettings,
+  inMemoryWillSave,
   loadBundle,
   loadBundleWasm,
   loadHeadlessEngine,

package/package.json

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