@paged-media/plugin-sdk 0.2.41-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, 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
@@ -423,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;
@@ -699,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

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:
@@ -333,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
@@ -1104,7 +1117,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 +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.
@@ -1536,6 +1571,9 @@ function createBundleHost(getEditor, manifest, options) {
       );
     }
   };
+  let overlayLayerSeq = 0;
+  let overlayLayerWarned = false;
+  const liveOverlayLayers = /* @__PURE__ */ new Set();
   const overlay = {
     setToolPreview(shape) {
       requireDeclared(
@@ -1565,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();
@@ -1829,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
@@ -2356,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");
   }
@@ -2399,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");
   }
@@ -2703,7 +2859,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 +3009,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 +3052,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 +3062,7 @@ async function createHeadlessHost(options = {}) {
     (value) => {
       lastPreviews = value;
     },
+    overlayLayerMap,
     options.engineShaper === true
   );
   const loadDirect = (bytes) => {
@@ -2967,6 +3134,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 +3252,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.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.41-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.69.0",
+    "@paged-media/canvas-wasm": "0.70.0",
     "@types/node": "20.19.39",
     "@types/react": "^18.3.31",
     "react": "^18.3.1",