@paged-media/plugin-sdk 0.2.41-canary.0 → 0.2.43-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, 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 { 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, EnteredEditContext, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome, BindingProviderHandle } from '@paged-media/plugin-api';
 import { ComponentType } from 'react';
 
 /**
@@ -104,6 +104,18 @@ interface BundleAssetProvider {
     /** The bytes of a document font face, or `null` when the host has
      *  none. Style-agnostic when `style` is omitted. */
     getFontFace(family: string, style?: string): Promise<FontFaceAsset | null>;
+    /** W-15 — register a face in the engine's SCENE-LAYER face table
+     *  (`registerFont` with `scope: "sceneLayer"`): scene-layer text
+     *  resolves it, the document never sees it. The SDK calls it once per
+     *  `host.assets.registerFont` and again when it replays the live faces
+     *  after a disposal. Optional: a host without it (with
+     *  `clearSceneFonts`) leaves `supports("assets.registerFont@1")` false. */
+    registerFont?(family: string, bytes: Uint8Array, style?: string): Promise<void>;
+    /** W-15 — drop every scene-layer face (`clearFontRegistry` with
+     *  `scope: "sceneLayer"`), leaving the document's faces alone. The SDK
+     *  owns which faces are live, so disposing one face is "clear, then
+     *  register the rest again". */
+    clearSceneFonts?(): Promise<void>;
 }
 /** Blob-store budgets (K-4 / S-08). The default per-plugin quota when a
  *  manifest requests none; a manifest's `storage.quotaBytes` may only
@@ -261,6 +273,18 @@ interface DocumentsBackend {
         };
     }): Promise<OpenDocumentResult>;
 }
+/**
+ * v70 — the backend the editor injects to back `host.viewport`'s page
+ * members. The editor owns the camera and the page layout, so it answers
+ * which page is active and moves the camera to one. No backend →
+ * `goToPage` answers false, `activePage` null, the event never fires and
+ * `supports("viewport.pages@1")` is false.
+ */
+interface PagesBackend {
+    goToPage(pageId: string, fit: "page" | "width"): boolean | Promise<boolean>;
+    activePage(): string | null;
+    onDidChangeActivePage(listener: (pageId: string | null) => void): () => 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
@@ -423,6 +447,13 @@ interface CreateBundleHostOptions {
      *  holds listeners that never run and `supports("document.onWillSave@1")`
      *  is false. */
     willSave?: WillSaveBackend;
+    /** W-19 — the host's shell fills `pageId` / `pagePoint` /
+     *  `contentPoint` on the `EnteredEditContext` of a POINTER entry (the
+     *  double-click, the Type-tool click on owned content). The SDK passes
+     *  the entered context through untouched either way; this flag only
+     *  makes `supports("editContext.enterPoint@1")` true, so it is the HOST
+     *  that vouches for delivery. */
+    editContextEnterPoint?: boolean;
     /** The host's tool-options store. When absent, `host.tools.settings`
      *  answers `{}` and `supports("tools.settings@1")` is false. */
     toolSettings?: ToolSettingsBackend;
@@ -496,6 +527,10 @@ interface CreateBundleHostOptions {
      *  `supports("documents.exportPaged@1")` / `supports("documents.open@1")`
      *  answer true. When absent, both doors reject. */
     documents?: DocumentsBackend;
+    /** v70 — page navigation for `host.viewport` (`goToPage`,
+     *  `activePage`, `onDidChangeActivePage`). When present,
+     *  `supports("viewport.pages@1")` is true. */
+    pages?: PagesBackend;
     /** 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,
@@ -699,6 +734,19 @@ interface HeadlessHost {
      *  bundle's "geometry AND label at once" claim is assertable without a
      *  browser. `lastToolPreview()` tracks the list's FIRST shape. */
     lastToolPreviews(): readonly ToolPreviewShape[] | null;
+    /** W-20 — every LIVE overlay layer (`host.overlay.layer`), in stack
+     *  order (bottom-most first), keyed `<manifest id>/<layer id>`, with the
+     *  shapes it holds now (`[]` once cleared). A disposed layer is gone. */
+    overlayLayers(): ReadonlyArray<{
+        key: string;
+        shapes: readonly ToolPreviewShape[];
+    }>;
+    /** W-19 — play the SHELL's part on a pointer entry: call the registered
+     *  edit context's `onEnter` with `ctx` (which may carry `pageId` /
+     *  `pagePoint` / `contentPoint`, as the editor fills them). The harness
+     *  advertises `editContext.enterPoint@1`. Returns `false` when no
+     *  context of `ctx.type` is registered. */
+    enterEditContext(ctx: EnteredEditContext): boolean;
     /** ADR-023 phase A — the SHARED binding-provider registry this host
      *  injected. It is the HOST side of the seam, so a conformance test
      *  plays the part the editor's shared panel plays in phase C: enter
@@ -989,4 +1037,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, 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 };
+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, type PagesBackend, 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

@@ -228,6 +228,10 @@ var HOST_FEATURES = [
   // needed — DESIGN.md §4.3d).
   "document.parentOf@1",
   "document.onDidChange@1",
+  // W-22 — the document-opened event. STATIC: it is the client's
+  // `documentLoaded` broadcast filtered, and every host posts that on
+  // every load (File ▸ Open, File ▸ New, a native-document open).
+  "document.onDidOpen@1",
   "document.getMetadata@1",
   "document.setMetadata@1",
   // Protocol 69 — the document-scoped label. Static like the snap door:
@@ -275,6 +279,10 @@ var HOST_FEATURES = [
   // door: the flag says this SDK forwards `snapPoint`; an engine older
   // than v67 answers the point unsnapped, never a throw.
   "document.snapPoint@1",
+  // v70 — page images from the engine's renderer (`requestSnapshot` with
+  // `hideItems`). Static like the snapper: the flag says this SDK
+  // forwards the query; an engine that refuses answers null.
+  "render.snapshot@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
@@ -333,6 +341,15 @@ var ASSET_BUDGETS = {
   /** Largest font face the door will serve, in bytes (8 MiB). */
   maxFontFaceBytes: 8 * 1024 * 1024
 };
+var sceneFaceLedgers = /* @__PURE__ */ new WeakMap();
+function sceneFaceLedger(provider) {
+  let ledger = sceneFaceLedgers.get(provider);
+  if (!ledger) {
+    ledger = { entries: [], queue: Promise.resolve() };
+    sceneFaceLedgers.set(provider, ledger);
+  }
+  return ledger;
+}
 var BLOB_BUDGETS = {
   /** Default per-plugin blob ceiling, in bytes (64 MiB). */
   defaultQuotaBytes: 64 * 1024 * 1024
@@ -1104,7 +1121,7 @@ function createBundleHost(getEditor, manifest, options) {
     }
   };
   const foreignMetadataKey = (m) => {
-    if (m.op === "setPluginMetadata" || m.op === "setDocumentMetadata") {
+    if (m.op === "setPluginMetadata" || m.op === "setDocumentMetadata" || m.op === "setPageMetadata") {
       return m.args.key === metadataKey(manifest) ? null : m.args.key;
     }
     if (m.op === "batch") {
@@ -1442,6 +1459,28 @@ function createBundleHost(getEditor, manifest, options) {
       });
       return store.add(toDisposable(off));
     },
+    // W-22 — the raw `documentLoaded` broadcast, narrowed to a clonable
+    // snapshot (the handle's stats / ruler guides stay host-side).
+    onDidOpen(listener) {
+      requireDocRead("document.onDidOpen");
+      const off = getEditor().client.subscribe((msg) => {
+        if (msg.kind !== "documentLoaded") return;
+        const h2 = msg.payload;
+        try {
+          listener({
+            docId: h2.docId,
+            pageCount: h2.pageCount,
+            pageIds: [...h2.pageIds],
+            pageSizesPt: h2.pageSizesPt.map(
+              ([w, hgt]) => [w, hgt]
+            )
+          });
+        } catch (err) {
+          log.error(`document.onDidOpen listener failed: ${String(err)}`);
+        }
+      });
+      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.
@@ -1485,6 +1524,7 @@ function createBundleHost(getEditor, manifest, options) {
       return store.add(toDisposable(off));
     }
   };
+  const pagesBackend = options?.pages;
   const viewport = {
     camera() {
       const cam = getEditor().camera.camera;
@@ -1493,6 +1533,53 @@ function createBundleHost(getEditor, manifest, options) {
     pxToPt(px) {
       const scale = getEditor().camera.camera.scale;
       return px / (scale > 0 ? scale : 1);
+    },
+    async goToPage(pageId, opts) {
+      if (!pagesBackend || typeof pageId !== "string" || pageId === "") {
+        return false;
+      }
+      const fit = opts?.fit === "width" ? "width" : "page";
+      return await pagesBackend.goToPage(pageId, fit) === true;
+    },
+    activePage() {
+      return pagesBackend ? pagesBackend.activePage() : null;
+    },
+    onDidChangeActivePage(listener) {
+      if (!pagesBackend) {
+        return toDisposable(() => {
+        });
+      }
+      return store.add(toDisposable(pagesBackend.onDidChangeActivePage(listener)));
+    }
+  };
+  const render = {
+    async snapshot(pageId, opts) {
+      requireDocRead("render.snapshot");
+      const widthPx = Math.round(opts?.widthPx ?? 0);
+      if (!(widthPx >= 1 && widthPx <= 8192)) {
+        throw new Error("host.render.snapshot: widthPx must be 1 to 8192");
+      }
+      const hideItems = Array.isArray(opts?.hideItems) ? opts.hideItems : [];
+      let reply;
+      try {
+        reply = await getEditor().client.send({
+          kind: "requestSnapshot",
+          payload: { pageId, targetWidthPx: widthPx, hideItems }
+        });
+      } catch {
+        return null;
+      }
+      if (reply.kind !== "snapshotReady") {
+        return null;
+      }
+      const p = reply.payload;
+      return {
+        pageId: p.pageId,
+        widthPx: p.widthPx,
+        heightPx: p.heightPx,
+        png: Uint8Array.from(p.pngBytes),
+        layoutGeneration: p.layoutGeneration
+      };
     }
   };
   const text = {
@@ -1536,6 +1623,9 @@ function createBundleHost(getEditor, manifest, options) {
       );
     }
   };
+  let overlayLayerSeq = 0;
+  let overlayLayerWarned = false;
+  const liveOverlayLayers = /* @__PURE__ */ new Set();
   const overlay = {
     setToolPreview(shape) {
       requireDeclared(
@@ -1565,6 +1655,56 @@ function createBundleHost(getEditor, manifest, options) {
         return;
       }
       signals.setToolPreview(list ? list[0] : null);
+    },
+    // W-20 — retained per-bundle layers. Each layer is a host-wide key
+    // `<manifest id>/<layer id>`; registering it with `[]` at creation
+    // fixes its place in the stack (creation order), so a later `set`
+    // never reorders it. Without a host sink the handle is inert (warned
+    // once per bundle) — never a throw, never a write into the shared
+    // tool-preview slot, which would erase the active tool's preview.
+    layer(id) {
+      requireDeclared(
+        hasRendering("overlay"),
+        "overlay.layer",
+        'capabilities.rendering must include "overlay"'
+      );
+      const layerId = id ?? `layer-${++overlayLayerSeq}`;
+      if (liveOverlayLayers.has(layerId)) {
+        throw new Error(
+          `host.overlay.layer("${layerId}"): a layer with this id is already live in ${manifest.id} \u2014 dispose it first or pick another id`
+        );
+      }
+      const key = `${manifest.id}/${layerId}`;
+      const signals = getEditor().overlaySignals;
+      const sink2 = typeof signals?.setOverlayLayer === "function" && typeof signals?.removeOverlayLayer === "function" ? signals : null;
+      if (!sink2 && !overlayLayerWarned) {
+        overlayLayerWarned = true;
+        log.warn(
+          'host.overlay.layer \u2014 this host renders no overlay layers (supports("overlay.layers@1") is false); shapes are dropped'
+        );
+      }
+      liveOverlayLayers.add(layerId);
+      sink2?.setOverlayLayer(key, []);
+      let disposed = false;
+      const handle = {
+        id: layerId,
+        set(shapes) {
+          if (disposed) return;
+          sink2?.setOverlayLayer(key, [...shapes]);
+        },
+        clear() {
+          if (disposed) return;
+          sink2?.setOverlayLayer(key, []);
+        },
+        dispose() {
+          if (disposed) return;
+          disposed = true;
+          liveOverlayLayers.delete(layerId);
+          sink2?.removeOverlayLayer(key);
+        }
+      };
+      store.add(handle);
+      return handle;
     }
   };
   const backing = options?.storage ?? defaultStorageBacking();
@@ -1829,6 +1969,65 @@ function createBundleHost(getEditor, manifest, options) {
       }
       return face;
     },
+    // W-15 — the one WRITE: a scene-layer face. The engine has a single
+    // scene table that `clearFontRegistry` can only empty as a whole, so
+    // the SDK keeps the list of live faces per provider (across bundles)
+    // and disposes one face by clearing and replaying the others. Every
+    // engine call goes through the ledger's queue, so a replay never
+    // interleaves with a registration.
+    async registerFont(bytes, family, style) {
+      requireDeclared(
+        hasAsset("fonts"),
+        "assets.registerFont",
+        'capabilities.assets must include "fonts"'
+      );
+      const label = `assets.registerFont("${family}"${style ? `, "${style}"` : ""})`;
+      if (bytes.byteLength > ASSET_BUDGETS.maxFontFaceBytes) {
+        throw new Error(
+          `${label}: ${bytes.byteLength} bytes is over the ${ASSET_BUDGETS.maxFontFaceBytes}-byte per-face cap`
+        );
+      }
+      const provider = assetSource;
+      const register = provider?.registerFont?.bind(provider);
+      const clear = provider?.clearSceneFonts?.bind(provider);
+      if (!provider || !register || !clear) {
+        log.warn(
+          `${label} ignored \u2014 the host cannot register scene faces (probe supports("assets.registerFont@1")); scene text keeps its fallback face`
+        );
+        return toDisposable(() => {
+        });
+      }
+      const ledger = sceneFaceLedger(provider);
+      const entry = style === void 0 ? { family, bytes: bytes.slice() } : { family, style, bytes: bytes.slice() };
+      const run = (job) => {
+        const next = ledger.queue.then(job);
+        ledger.queue = next.catch(() => {
+        });
+        return next;
+      };
+      await run(async () => {
+        await register(entry.family, entry.bytes, entry.style);
+        ledger.entries.push(entry);
+      });
+      let disposed = false;
+      return store.add(
+        toDisposable(() => {
+          if (disposed) return;
+          disposed = true;
+          void run(async () => {
+            const i = ledger.entries.indexOf(entry);
+            if (i < 0) return;
+            ledger.entries.splice(i, 1);
+            await clear();
+            for (const live of ledger.entries) {
+              await register(live.family, live.bytes, live.style);
+            }
+          }).catch((error) => {
+            log.warn(`${label}: dropping the face failed: ${String(error)}`);
+          });
+        })
+      );
+    },
     // C-5 / I-04 (core v42): a placed DOCUMENT image's ORIGINAL bytes,
     // straight from the engine's resolver/parse cache through the
     // `requestPlacedAssetBytes` wire query — no injected source needed
@@ -2356,6 +2555,12 @@ function createBundleHost(getEditor, manifest, options) {
   if (typeof getEditor().overlaySignals?.setToolPreviews === "function") {
     featureSet.add("overlay.multiPreview@1");
   }
+  if (typeof getEditor().overlaySignals?.setOverlayLayer === "function" && typeof getEditor().overlaySignals?.removeOverlayLayer === "function") {
+    featureSet.add("overlay.layers@1");
+  }
+  if (options?.editContextEnterPoint === true) {
+    featureSet.add("editContext.enterPoint@1");
+  }
   if (getEditor().images) {
     featureSet.add("rendering.resourceProvider@1");
   }
@@ -2399,6 +2604,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.assetSource) {
     featureSet.add("assets.fonts@1");
   }
+  if (typeof options?.assetSource?.registerFont === "function" && typeof options?.assetSource?.clearSceneFonts === "function") {
+    featureSet.add("assets.registerFont@1");
+  }
   if (options?.consent) {
     featureSet.add("network.consent@1");
   }
@@ -2421,6 +2629,9 @@ function createBundleHost(getEditor, manifest, options) {
     featureSet.add("document.readNative@1");
     featureSet.add("document.openNative@1");
   }
+  if (options?.pages) {
+    featureSet.add("viewport.pages@1");
+  }
   if (options?.documents) {
     featureSet.add("documents.exportPaged@1");
     featureSet.add("documents.open@1");
@@ -2441,6 +2652,7 @@ function createBundleHost(getEditor, manifest, options) {
     document,
     selection,
     viewport,
+    render,
     text,
     overlay,
     shell,
@@ -2703,7 +2915,7 @@ function inMemorySecretStore() {
   };
 }
 var seqCounter = 1;
-function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews, engineShaper = false) {
+function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews, overlayLayers, engineShaper = false) {
   const protocol = worker.protocolVersion;
   const listeners = /* @__PURE__ */ new Set();
   const fanOut = (reply) => {
@@ -2853,6 +3065,15 @@ function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews, engin
         toolPreview = toolPreviews ? toolPreviews[0] : null;
         onToolPreviews(toolPreviews);
         onToolPreview(toolPreview);
+      },
+      // W-20 — the retained layers. A Map keeps first-insertion order,
+      // which is the stack order the editor renders; a re-set keeps the
+      // key's place.
+      setOverlayLayer(key, shapes) {
+        overlayLayers.set(key, shapes);
+      },
+      removeOverlayLayer(key) {
+        overlayLayers.delete(key);
       }
     },
     // No tool spine + no content caret headlessly — both are inert
@@ -2887,6 +3108,7 @@ async function createHeadlessHost(options = {}) {
   const contributions = [];
   let lastPreview = null;
   let lastPreviews = null;
+  const overlayLayerMap = /* @__PURE__ */ new Map();
   const { editor, fanOut } = makeEngineEditor(
     worker,
     contributions,
@@ -2896,6 +3118,7 @@ async function createHeadlessHost(options = {}) {
     (value) => {
       lastPreviews = value;
     },
+    overlayLayerMap,
     options.engineShaper === true
   );
   const loadDirect = (bytes) => {
@@ -2967,6 +3190,9 @@ 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,
+    // W-19 — `enterEditContext()` below delivers the entering point the
+    // way the editor shell does, so the harness vouches for it.
+    editContextEnterPoint: true,
     documents: documentsBackend,
     // Record the SCHEMA verbatim at registration — the panel registry
     // only ever sees the synthesized React panel, so the conformance
@@ -3082,12 +3308,26 @@ async function createHeadlessHost(options = {}) {
     lastToolPreviews() {
       return lastPreviews;
     },
+    overlayLayers() {
+      return [...overlayLayerMap].map(([key, shapes]) => ({ key, shapes }));
+    },
+    enterEditContext(ctx) {
+      const entry = contributions.find(
+        (c) => c.kind === "editContext" && c.id === ctx.type
+      );
+      if (!entry) return false;
+      entry.value.onEnter?.(ctx);
+      return true;
+    },
     bindingProviders,
     willSave,
     toolSettings,
     async load(idml) {
       const reply = loadDirect(idml);
-      if (reply.kind === "documentLoaded") return reply.payload.pageIds;
+      if (reply.kind === "documentLoaded") {
+        fanOut(reply);
+        return reply.payload.pageIds;
+      }
       throw loadFailure(reply);
     },
     openedDocuments() {

package/package.json

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