@paged-media/plugin-sdk 0.2.40-canary.0 → 0.2.42-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, 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
@@ -240,6 +252,27 @@ interface NativeDocumentBackend {
     listParts(prefix?: string): Promise<string[]>;
     open(bytes: Uint8Array): Promise<void>;
 }
+/**
+ * D-26 — the backend the editor injects to back `host.documents`. The SDK
+ * owns the capability gate (`capabilities.documents.export` / `.open`); the
+ * backend owns the IO AND the unsaved-edits decision: `open` must ask the
+ * user (host UI) before discarding a dirty active document and answer
+ * `{ opened: false, reason: "declined" }` when they keep it. `requester`
+ * is filled by the SDK from the calling bundle's manifest (not from the
+ * plugin's arguments), so the prompt can name who is asking. No backend →
+ * both doors reject and `supports("documents.open@1")` /
+ * `supports("documents.exportPaged@1")` are false.
+ */
+interface DocumentsBackend {
+    exportPaged(): Promise<Uint8Array>;
+    open(bytes: Uint8Array, request: {
+        name: string | null;
+        requester: {
+            id: string;
+            name: string;
+        };
+    }): Promise<OpenDocumentResult>;
+}
 /** 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
@@ -402,6 +435,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;
@@ -469,6 +509,12 @@ interface CreateBundleHostOptions {
      *  `supports("document.openNative@1")` answer true. When absent, the reads
      *  answer `null`/`[]` and `open` rejects (the honest no-backend door). */
     nativeDocument?: NativeDocumentBackend;
+    /** D-26 — host-provided DOCUMENTS backend. When present,
+     *  `host.documents.exportPaged` / `open` go through it (gated on
+     *  `capabilities.documents.export` / `.open`) and
+     *  `supports("documents.exportPaged@1")` / `supports("documents.open@1")`
+     *  answer true. When absent, both doors reject. */
+    documents?: DocumentsBackend;
     /** 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,
@@ -521,6 +567,14 @@ interface HeadlessCanvasWorker {
     handleMessage(input: string): string;
     loadDocumentDirect(seq: number, bytes: Uint8Array, font?: Uint8Array, cmykIccProfile?: Uint8Array): string;
     runResolveJson(): string | undefined;
+    /** The engine shaper (v38): `{ advance, ascender, descender }` in pt, or
+     *  null when no document is loaded / the face resolves to nothing.
+     *  Optional so a structural fake need not carry it. */
+    measureText?(family: string, style: string | null | undefined, text: string, sizePt: number): {
+        advance: number;
+        ascender: number;
+        descender: number;
+    } | null;
     free(): void;
 }
 interface LoadedEngine {
@@ -580,6 +634,32 @@ interface RecordedContribution {
     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" | "willSave" | "toolSettings"> {
+    /** D-27 — back `host.text` with the ENGINE's shaper
+     *  (`CanvasWorker.measureText`, the one the editor's worker calls)
+     *  instead of the estimate, so `measureString` / `measureStrings`
+     *  answer real widths against the loaded document's fonts and
+     *  `supports("text.measure@1")` / `("text.measureStrings@1")` are true.
+     *  Off by default: existing headless suites pinned the estimate. */
+    engineShaper?: boolean;
+    /** D-26 — the headless stand-in for the editor's keep/discard prompt.
+     *  `host.documents.open` calls it ONLY when the active document has
+     *  unsaved edits; resolve `false` to keep them (the door then answers
+     *  `{ opened: false, reason: "declined" }`). Default: discard. */
+    confirmReplace?: (request: {
+        name: string | null;
+        requester: {
+            id: string;
+            name: string;
+        };
+    }) => boolean | Promise<boolean>;
+    /** D-28 — the default font every load lays out with, the headless
+     *  stand-in for the editor's `defaultFontProvider` (the editor passes
+     *  `/fonts/Inter.ttf`). The engine lays text out, and reports a story
+     *  `overset`, only when it has a font: without one nothing is laid out and
+     *  every story reads `overset: false` (not measured). Passed to every
+     *  load, `load()` and `host.documents.open` alike. Absent: no font, as
+     *  before. */
+    defaultFont?: Uint8Array;
 }
 /** A headless will-save registry: listeners register per plugin and
  *  `fire()` awaits them all, the way the editor's save path does — so a
@@ -638,6 +718,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
@@ -656,6 +749,13 @@ interface HeadlessHost {
     /** 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[]>;
+    /** D-26 — every document a bundle opened through `host.documents.open`,
+     *  in order (declined opens are not listed). */
+    openedDocuments(): ReadonlyArray<{
+        name: string | null;
+        requester: string;
+        pageIds: string[];
+    }>;
     /** Activate a bundle against this host (apiVersion-negotiated). The
      *  returned disposer runs the bundle's teardown; the host's own
      *  facade teardown runs on `dispose()`. */
@@ -921,4 +1021,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, 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, 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,8 +228,17 @@ 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:
+  // the flag says this SDK forwards the two calls; an engine older than 69
+  // answers `null` on read (no `pluginMetadata` in its DocumentMeta) and
+  // `applied: false` on write (it does not know the op).
+  "document.documentMetadata@1",
   "selection@1",
   "viewport@1",
   "overlay.toolPreview@1",
@@ -328,6 +337,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
@@ -628,6 +646,7 @@ function createBundleHost(getEditor, manifest, options) {
   const hasWorkers = () => typeof caps?.workers?.max === "number";
   const hasSecrets = () => caps?.secrets?.sources === true;
   const hasGpu = () => caps?.gpu?.realm === "bundle";
+  const hasDocuments = (dir) => caps?.documents?.[dir] === 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) => {
@@ -1098,7 +1117,7 @@ function createBundleHost(getEditor, manifest, options) {
     }
   };
   const foreignMetadataKey = (m) => {
-    if (m.op === "setPluginMetadata") {
+    if (m.op === "setPluginMetadata" || m.op === "setDocumentMetadata" || m.op === "setPageMetadata") {
       return m.args.key === metadataKey(manifest) ? null : m.args.key;
     }
     if (m.op === "batch") {
@@ -1147,7 +1166,7 @@ function createBundleHost(getEditor, manifest, options) {
     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)}")`;
+      const error = `metadata key "${foreign}" is outside this plugin's namespace ("${metadataKey(manifest)}")`;
       log.warn(error);
       return { applied: false, error };
     }
@@ -1384,6 +1403,28 @@ function createBundleHost(getEditor, manifest, options) {
         }
       });
     },
+    async getDocumentMetadata() {
+      requireDocRead("document.getDocumentMetadata");
+      const key = metadataKey(manifest);
+      const meta = await getEditor().client.documentMeta();
+      const entry = meta.pluginMetadata?.find((e) => e.key === key);
+      if (!entry) return null;
+      try {
+        return JSON.parse(entry.value);
+      } catch {
+        return null;
+      }
+    },
+    async setDocumentMetadata(envelope) {
+      return this.mutate({
+        op: "setDocumentMetadata",
+        args: {
+          key: metadataKey(manifest),
+          value: envelope === null ? null : JSON.stringify(envelope),
+          caller: manifest.id
+        }
+      });
+    },
     async frameChain(storyId) {
       requireDocRead("document.frameChain");
       const reply = await getEditor().client.send({
@@ -1414,6 +1455,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.
@@ -1487,8 +1550,30 @@ function createBundleHost(getEditor, manifest, options) {
     // "no reader").
     caret() {
       return options?.textCaret?.read() ?? null;
+    },
+    // D-27 — the batched measure. One round-trip when the editor wires
+    // `measureMany`; otherwise the same answers one call at a time (or
+    // the estimate), so a bundle never needs two code paths.
+    async measureStrings(family, style, texts, sizePt) {
+      if (texts.length === 0) return [];
+      const editorText = getEditor().text;
+      if (editorText?.measureMany) {
+        const out = await editorText.measureMany(family, style, texts, sizePt);
+        if (out.length !== texts.length) {
+          throw new Error(
+            `host.text.measureStrings: the host answered ${out.length} metrics for ${texts.length} strings`
+          );
+        }
+        return out;
+      }
+      return Promise.all(
+        texts.map((t) => text.measureString(family, style, t, sizePt))
+      );
     }
   };
+  let overlayLayerSeq = 0;
+  let overlayLayerWarned = false;
+  const liveOverlayLayers = /* @__PURE__ */ new Set();
   const overlay = {
     setToolPreview(shape) {
       requireDeclared(
@@ -1518,6 +1603,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();
@@ -1782,6 +1917,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
@@ -2058,6 +2252,42 @@ function createBundleHost(getEditor, manifest, options) {
       return nativeDocBackend.open(bytes);
     }
   };
+  const documentsBackend = options?.documents;
+  const documents = {
+    async exportPaged() {
+      requireDeclared(
+        hasDocuments("export"),
+        "documents.exportPaged",
+        "capabilities.documents.export must be declared"
+      );
+      if (!documentsBackend) {
+        throw new Error(
+          'host.documents.exportPaged: the host wired no documents backend (supports("documents.exportPaged@1") is false)'
+        );
+      }
+      return documentsBackend.exportPaged();
+    },
+    async open(bytes, opts) {
+      requireDeclared(
+        hasDocuments("open"),
+        "documents.open",
+        "capabilities.documents.open must be declared"
+      );
+      if (!documentsBackend) {
+        throw new Error(
+          'host.documents.open: the host wired no documents backend (supports("documents.open@1") is false)'
+        );
+      }
+      if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
+        throw new Error("host.documents.open: bytes must be a non-empty Uint8Array");
+      }
+      const name = typeof opts?.name === "string" && opts.name.trim() !== "" ? opts.name.trim() : null;
+      return documentsBackend.open(bytes.slice(), {
+        name,
+        requester: { id: manifest.id, name: manifest.name }
+      });
+    }
+  };
   const clipboardBackend = options?.clipboard;
   const clipboardGate = (door) => {
     const grant = clipboardGrant();
@@ -2263,6 +2493,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (getEditor().text) {
     featureSet.add("text.measure@1");
   }
+  if (getEditor().text?.measureMany) {
+    featureSet.add("text.measureStrings@1");
+  }
   if (getEditor().sceneLayers) {
     featureSet.add("rendering.sceneLayer@1");
     featureSet.add("rendering.sceneLayer.faces@1");
@@ -2270,6 +2503,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");
   }
@@ -2313,6 +2552,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");
   }
@@ -2335,6 +2577,10 @@ function createBundleHost(getEditor, manifest, options) {
     featureSet.add("document.readNative@1");
     featureSet.add("document.openNative@1");
   }
+  if (options?.documents) {
+    featureSet.add("documents.exportPaged@1");
+    featureSet.add("documents.open@1");
+  }
   if (options?.workers) {
     featureSet.add("workers@1");
   }
@@ -2358,6 +2604,7 @@ function createBundleHost(getEditor, manifest, options) {
     blob,
     parts,
     nativeDocument,
+    documents,
     network,
     dataProviders,
     diagnostics,
@@ -2612,7 +2859,7 @@ function inMemorySecretStore() {
   };
 }
 var seqCounter = 1;
-function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
+function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews, overlayLayers, engineShaper = false) {
   const protocol = worker.protocolVersion;
   const listeners = /* @__PURE__ */ new Set();
   const fanOut = (reply) => {
@@ -2762,6 +3009,15 @@ function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
         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
@@ -2772,7 +3028,23 @@ function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
     },
     contentSelection: { contentSelection: null }
   };
-  return editor;
+  const measureText = worker.measureText?.bind(worker);
+  if (engineShaper && measureText) {
+    const zero = { advance: 0, ascender: 0, descender: 0 };
+    const one = (family, style, t, sizePt) => {
+      const m = measureText(family, style, t, sizePt);
+      return m ? { advance: m.advance, ascender: m.ascender, descender: m.descender } : zero;
+    };
+    editor.text = {
+      async measure(family, style, t, sizePt) {
+        return one(family, style, t, sizePt);
+      },
+      async measureMany(family, style, texts, sizePt) {
+        return texts.map((t) => one(family, style, t, sizePt));
+      }
+    };
+  }
+  return { editor, fanOut };
 }
 async function createHeadlessHost(options = {}) {
   const engine = await loadHeadlessEngine(options);
@@ -2780,7 +3052,8 @@ async function createHeadlessHost(options = {}) {
   const contributions = [];
   let lastPreview = null;
   let lastPreviews = null;
-  const editor = makeEngineEditor(
+  const overlayLayerMap = /* @__PURE__ */ new Map();
+  const { editor, fanOut } = makeEngineEditor(
     worker,
     contributions,
     (value) => {
@@ -2788,8 +3061,55 @@ async function createHeadlessHost(options = {}) {
     },
     (value) => {
       lastPreviews = value;
-    }
+    },
+    overlayLayerMap,
+    options.engineShaper === true
   );
+  const loadDirect = (bytes) => {
+    const reply = JSON.parse(
+      options.defaultFont ? worker.loadDocumentDirect(seqCounter++, bytes, options.defaultFont) : worker.loadDocumentDirect(seqCounter++, bytes)
+    );
+    if (reply.kind === "documentLoaded") {
+      try {
+        worker.runResolveJson();
+      } catch {
+      }
+    }
+    return reply;
+  };
+  const loadFailure = (reply) => {
+    const errKind = reply.kind === "loadFailed" ? reply.payload.error.kind : reply.kind;
+    return new Error(`headless load failed (${reply.kind}: ${errKind})`);
+  };
+  const opened = [];
+  const documentsBackend = {
+    async exportPaged() {
+      const reply = await editor.client.send({ kind: "exportPaged", payload: {} });
+      if (reply.kind === "pagedExported") return Uint8Array.from(reply.payload.bytes);
+      if (reply.kind === "pagedPartFailed") throw new Error(reply.payload.error);
+      throw new Error(`unexpected reply: ${reply.kind}`);
+    },
+    async open(bytes, request) {
+      let dirty = false;
+      try {
+        dirty = (await editor.client.documentMeta()).dirty;
+      } catch {
+        dirty = false;
+      }
+      if (dirty && options.confirmReplace && !await options.confirmReplace(request)) {
+        return { opened: false, reason: "declined" };
+      }
+      const reply = loadDirect(bytes);
+      if (reply.kind !== "documentLoaded") throw loadFailure(reply);
+      fanOut(reply);
+      opened.push({
+        name: request.name,
+        requester: request.requester.id,
+        pageIds: reply.payload.pageIds
+      });
+      return { opened: true, pageIds: reply.payload.pageIds };
+    }
+  };
   let active = null;
   let currentHost = null;
   let disposed = false;
@@ -2814,6 +3134,10 @@ 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
     // log gets the schema through this adapter seam (no host renderer
@@ -2875,7 +3199,8 @@ async function createHeadlessHost(options = {}) {
       rendering: ["overlay", "hitTest", "sceneLayer"],
       keybindings: true,
       storage: { blob: true },
-      secrets: { sources: true }
+      secrets: { sources: true },
+      documents: { export: true, open: true }
     },
     // Broad contribution declarations so the neutral DRIVER host (which
     // registers arbitrary contributions directly in 'warn' mode) never
@@ -2927,21 +3252,30 @@ 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 raw = worker.loadDocumentDirect(seqCounter++, idml);
-      const reply = JSON.parse(raw);
+      const reply = loadDirect(idml);
       if (reply.kind === "documentLoaded") {
-        try {
-          worker.runResolveJson();
-        } catch {
-        }
+        fanOut(reply);
         return reply.payload.pageIds;
       }
-      const errKind = reply.kind === "loadFailed" ? reply.payload.error.kind : reply.kind;
-      throw new Error(`headless load failed (${reply.kind}: ${errKind})`);
+      throw loadFailure(reply);
+    },
+    openedDocuments() {
+      return opened;
     },
     loadBundle(bundle) {
       if (active) {

package/package.json

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