@paged-media/plugin-sdk 0.2.27-canary.1 → 0.2.28-canary.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PagedBundle, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, Disposable, ShellSurface, WidgetSurface, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, PagedEditor, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, MutationOutcome } 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, 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 { ComponentType } from 'react';
 
 /**
@@ -192,6 +192,23 @@ interface ClipboardBackend {
     read(): Promise<ClipboardPayload | null>;
     write(payload: ClipboardPayload): Promise<void>;
 }
+/**
+ * The reader the editor injects to back `host.text.caret()` (C-9): a
+ * synchronous read of the user's ACTIVE text caret from the editor's
+ * text-editing/content-selection state (the caret lives in EDITOR
+ * state, not the engine). The SDK adapter owns nothing here but the
+ * pass-through + the honest no-backend default — `read()` answers the
+ * caret in the engine text-op offset convention (`ContentSelection`
+ * story-local offsets; see `TextCaret`), `null` when no caret is
+ * active. The editor's backend also answers `null` for a
+ * cell-qualified caret (cell-local offsets must not leak as
+ * story-local — the documented v1 gap). When absent,
+ * `host.text.caret()` is always `null` and `supports("text.caret@1")`
+ * is false.
+ */
+interface TextCaretBackend {
+    read(): TextCaret | null;
+}
 /**
  * The backend the editor injects to back `host.nativeDocument` (ADR-021 /
  * document-model direction): the isolate-safe replacement for an importer/
@@ -225,6 +242,58 @@ interface DataProviderBackend {
  *  providers and consumers (different plugin hosts) meet through it. Reference
  *  implementation — an RPC/isolate host swaps a proxy with the same contract. */
 declare function createDataProviderRegistry(): DataProviderBackend;
+/** One provider as the registry holds it (the adapter's registration
+ *  payload — the bundle identity the contract's answers carry as
+ *  `provider`, plus the borrowed context type). */
+interface RegisteredBindingProvider {
+    plugin: string;
+    contextType: string;
+    provider: BindingProvider;
+}
+/**
+ * The shared binding-provider registry (ADR-023 phase A). TWO audiences,
+ * deliberately on one object (like {@link DataProviderBackend}):
+ *
+ *   · the SDK ADAPTER calls `register` / `setContextActive` — a bundle
+ *     never touches these; it reaches the registry only through
+ *     `host.contribute.bindingProvider`;
+ *   · the HOST APP (the editor's shared panels, phase C) calls
+ *     `activeProviders` / `readProperty` / `writeProperty` /
+ *     `readCollection` / `applyMutation` / `onDidChange`.
+ *
+ * FALL-THROUGH IS THE HOST'S JOB, not the registry's: every resolution
+ * answers either a claim or a typed `resolved: false` / `handled: false`
+ * refusal, and the host reads/writes CORE on the refusal. The registry
+ * holds no editor handle and therefore cannot — and must not — fall
+ * through on the host's behalf; keeping the two separable is what lets
+ * the isolate implementation be an RPC proxy of exactly this shape.
+ */
+interface BindingProviderBackend {
+    /** Register a provider. Disposing removes it without touching the
+     *  edit context whose activation it borrows. */
+    register(entry: RegisteredBindingProvider): Disposable;
+    /** Report an edit context entering (`active: true`) or leaving. Called
+     *  by the adapter from the shell's own `onEnter`/`onExit`. */
+    setContextActive(plugin: string, contextType: string, elementId: string | null, active: boolean): void;
+    /** A provider announced `invalidate()` — fan out to host subscribers. */
+    notifyChanged(plugin: string, contextType: string): void;
+    /** The active provider stack, INNERMOST FIRST (= precedence order). */
+    activeProviders(): readonly ActiveBindingProvider[];
+    readProperty(request: BindingPropertyRequest): Promise<BindingReadResult>;
+    writeProperty(request: BindingPropertyWrite): Promise<BindingWriteResult>;
+    readCollection(request: BindingCollectionRequest): Promise<BindingCollectionResult>;
+    /** Offer a structural mutation to the active providers before sending
+     *  it to core (`layerMove`, `createSwatch`, …). */
+    applyMutation(mutation: MutationInput): Promise<BindingWriteResult>;
+    /** Fires when the active stack changes OR a provider invalidates —
+     *  the host panel's re-read signal. */
+    onDidChange(listener: () => void): Disposable;
+}
+/** Build a shared binding-provider registry (ADR-023 phase A). The editor
+ *  holds ONE and injects it into every `createBundleHost` call as
+ *  `options.bindingProviders`. Reference implementation — an
+ *  RPC/isolate host swaps a proxy with the same contract. */
+declare function createBindingProviderRegistry(): BindingProviderBackend;
 /**
  * Trust posture the HOST asserts for a bundle at the load path
  * (`plugin-trust-line.md`). Same-realm execution — full `BundleHost`
@@ -241,6 +310,16 @@ declare function createDataProviderRegistry(): DataProviderBackend;
  * still does not load until the isolate/RPC host gate is built.
  */
 type BundleTrust = "first-party";
+/**
+ * What the HOST APP injects as `shell` (K-10). Structurally the
+ * bundle-facing {@link ShellSurface}, except that doors added AFTER a
+ * host app adopted the option are optional here — today `saveFile`,
+ * which the editor gained one release after `pickFile`. A host that
+ * implements the full surface is assignable unchanged; a host that
+ * omits `saveFile` still injects a valid backend and
+ * `supports("shell.saveFile@1")` reports the truth.
+ */
+type ShellBackend = Omit<ShellSurface, "saveFile"> & Partial<Pick<ShellSurface, "saveFile">>;
 interface CreateBundleHostOptions {
     /**
      * The host's trust assertion for this bundle (`plugin-trust-line.md`).
@@ -262,12 +341,23 @@ interface CreateBundleHostOptions {
      *  through it. When absent, `host.dataProviders` discover() is empty +
      *  register() is a no-op and `supports("dataProviders@1")` is false. */
     dataProviders?: DataProviderBackend;
+    /** Host-provided SHARED BINDING-PROVIDER registry (ADR-023 phase A): the
+     *  editor creates ONE (`createBindingProviderRegistry`) and injects the SAME
+     *  instance into every plugin host, so its own panels can ask "who resolves
+     *  this path / collection / op right now?" across all loaded bundles. When
+     *  absent, `host.contribute.bindingProvider` warns + returns an inert handle
+     *  (nothing would ever consult the provider) and
+     *  `supports("bindings.provider@1")` is false. */
+    bindingProviders?: BindingProviderBackend;
     /** Console sink override (tests). */
     console?: Pick<Console, "debug" | "info" | "warn" | "error">;
     /** Shell actions the HOST APP owns (the cockpit's panel placement).
      *  When absent, `host.shell` warns and no-ops, and
-     *  `supports("shell.openPanel@1")` answers false. */
-    shell?: ShellSurface;
+     *  `supports("shell.openPanel@1")` answers false. Typed as
+     *  {@link ShellBackend}, not `ShellSurface`: doors the host app has
+     *  not adopted yet are OPTIONAL here and each answers its own honest
+     *  no-backend value through the wrapper. */
+    shell?: ShellBackend;
     /** Host-provided panel widgets (W-04): the real code editor lives in
      *  the editor's UI package and is injected here. When absent,
      *  `host.widgets` is the plain-textarea fallback and
@@ -316,6 +406,12 @@ interface CreateBundleHostOptions {
      *  When absent, reads answer empty and writes reject (the honest
      *  no-store door). */
     blobStore?: BlobStore;
+    /** Host-provided TEXT-CARET reader (C-9). When present,
+     *  `host.text.caret()` reads the user's active text caret through it
+     *  and `supports("text.caret@1")` answers true. When absent, `caret()`
+     *  always answers `null` (the honest no-reader door — a read door like
+     *  `text.measureString`, no capability gate). */
+    textCaret?: TextCaretBackend;
     /** Host-provided CLIPBOARD backend (K-6 / S-14). When present,
      *  `host.clipboard.read/write` go through it (capability-gated on
      *  `capabilities.clipboard`) and `supports("clipboard@1")` answers true.
@@ -441,7 +537,7 @@ interface RecordedContribution {
     id: string;
     value: ToolContribution | PanelContribution | SchemaPanelContribution | CommandContribution | KeybindingContribution | OverlayContribution | EditContextContribution | ObjectTypeContribution | ImporterContribution | ExporterContribution;
 }
-interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets"> {
+interface HarnessOptions extends LoadHeadlessEngineOptions, Pick<CreateBundleHostOptions, "console" | "storage" | "capabilityMode" | "assetSource" | "blobStore" | "clipboard" | "secrets" | "bindingProviders"> {
 }
 /** What `createHeadlessHost` resolves to: a real engine-backed host plus
  *  the conformance affordances (load an IDML, read the contribution log,
@@ -481,6 +577,21 @@ interface HeadlessHost {
      *  Béziers) rather than a flattened polyline. `null` until set, and
      *  reset to `null` when the bundle clears its preview. */
     lastToolPreview(): ToolPreviewShape | null;
+    /** K-9 — the last LIST a bundle pushed through
+     *  `host.overlay.setToolPreviews`, or `null` when it cleared / never
+     *  used the multi-shape door. The harness wires the multi-shape sink,
+     *  so `supports("overlay.multiPreview@1")` is true headlessly and a
+     *  bundle's "geometry AND label at once" claim is assertable without a
+     *  browser. `lastToolPreview()` tracks the list's FIRST shape. */
+    lastToolPreviews(): readonly ToolPreviewShape[] | null;
+    /** 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
+     *  the bundle's edit context, then `readProperty` / `readCollection` /
+     *  `applyMutation` through here and assert the bundle answered (and
+     *  that a path it does not declare comes back as a typed refusal to
+     *  fall through to core). */
+    readonly bindingProviders: BindingProviderBackend;
     /** 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[]>;
@@ -709,5 +820,20 @@ declare function contributeEditContext(host: BundleHost, contribution: EditConte
  *  matching element enters its `editContextType` instead of group
  *  descent. Capability-gated on `contributes.objectTypes`. */
 declare function contributeObjectType(host: BundleHost, contribution: ObjectTypeContribution): Disposable;
+/**
+ * ADR-023 phase A — register a BINDING PROVIDER: while `contextType` is
+ * the ACTIVE edit context, this bundle resolves what the HOST's own
+ * panels bind to (typed paths, named collections, structural ops; reads
+ * and writes both), so one host-owned panel serves many content types
+ * instead of each plugin minting its own copy.
+ *
+ * Lives here rather than in its own module deliberately: a provider
+ * borrows its edit context's ACTIVATION, so the two doors belong to one
+ * lifecycle and reading them side by side is the point. `contextType`
+ * must be a type this bundle already passed to
+ * {@link contributeEditContext} — the ordering is enforced, not
+ * conventional.
+ */
+declare function contributeBindingProvider(host: BundleHost, contextType: string, provider: BindingProvider): BindingProviderHandle;
 
-export { API_VERSION, ASSET_BUDGETS, BLOB_BUDGETS, type BlobStore, type BundleAssetProvider, type BundleAssetSource, type BundleHostHandle, type BundleTrust, CANVAS_WASM_PKG, CLICK_DRAG_THRESHOLD_PX, type ClipboardBackend, type ConsentBackend, type CreateBundleHostOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, FALLBACK_WIDGETS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, type PageDrag, PluginApiNotImplemented, PluginCapabilityError, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type SecretStoreBackend, type SeededFace, type SpawnedWorker, type StorageBacking, WASM_BUDGETS, WORKER_BUDGETS, type WorkerBackend, beginPageDrag, commitAndSelect, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, createBundleHost, createDataProviderRegistry, createHeadlessHost, createRecordableAssetSource, defineBundle, endLocalFor, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, protocolFromVersion, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, satisfiesApiVersion, toDisposable };
+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 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 };

package/dist/index.js

@@ -1,3 +1,7 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
 // src/define-bundle.ts
 function defineBundle(bundle) {
   return bundle;
@@ -5,8 +9,10 @@ function defineBundle(bundle) {
 
 // src/disposables.ts
 var DisposableStore = class {
-  items = [];
-  disposed = false;
+  constructor() {
+    __publicField(this, "items", []);
+    __publicField(this, "disposed", false);
+  }
   get isDisposed() {
     return this.disposed;
   }
@@ -42,19 +48,31 @@ function toDisposable(fn) {
   };
 }
 
-// src/widgets-fallback.tsx
+// src/react-optional.ts
 var createElement = null;
-try {
-  ({ createElement } = await import("react"));
-} catch {
+var state = "pending";
+void import("react").then(
+  (react) => {
+    createElement = react.createElement;
+    state = "ready";
+  },
+  () => {
+    state = "absent";
+  }
+);
+function requireCreateElement(absent) {
+  if (createElement) return createElement;
+  throw new Error(
+    state === "pending" ? `${absent} (React had not finished resolving when this rendered.)` : absent
+  );
 }
+
+// src/widgets-fallback.tsx
 function TextareaCodeEditor(props) {
-  if (!createElement) {
-    throw new Error(
-      "plugin-sdk: host.widgets.CodeEditor fell back to the built-in textarea, but React is not installed. Install react, or inject a widget catalog via createBundleHost({ widgets })."
-    );
-  }
-  return createElement("textarea", {
+  const createElement2 = requireCreateElement(
+    "plugin-sdk: host.widgets.CodeEditor fell back to the built-in textarea, but React is not installed. Install react, or inject a widget catalog via createBundleHost({ widgets })."
+  );
+  return createElement2("textarea", {
     value: props.value,
     readOnly: props.readOnly,
     spellCheck: false,
@@ -80,18 +98,10 @@ var FALLBACK_WIDGETS = {
 };
 
 // src/schema-panel.tsx
-var createElement2 = null;
-try {
-  ({ createElement: createElement2 } = await import("react"));
-} catch {
-}
 function h() {
-  if (!createElement2) {
-    throw new Error(
-      "plugin-sdk: rendering a schema panel needs React, which is not installed."
-    );
-  }
-  return createElement2;
+  return requireCreateElement(
+    "plugin-sdk: rendering a schema panel needs React, which is not installed."
+  );
 }
 function resolveGate(gate, lookup) {
   if (gate === void 0) return true;
@@ -139,6 +149,14 @@ var HOST_FEATURES = [
   "contribute.overlay@1",
   "contribute.editContext@1",
   "contribute.objectType@1",
+  // ADR-023 phase A — the binding-provider DOOR exists in this SDK (a
+  // bundle may call `host.contribute.bindingProvider` without a
+  // TypeError). STATIC, and it deliberately does NOT claim that anything
+  // will consult the provider — that is the separate, DYNAMIC
+  // `bindings.provider@1`, which is true only when the host wired a
+  // shared registry. Same static-door / dynamic-backing split as
+  // `contribute.schemaPanel@1` + `schemaPanel.renderer@1`.
+  "contribute.bindingProvider@1",
   "contribute.importer@1",
   "contribute.exporter@1",
   "document.mutate@1",
@@ -152,6 +170,12 @@ var HOST_FEATURES = [
   "document.elementProperties@1",
   "document.placeholders@1",
   "document.tree@1",
+  // C-16 — the per-element parentage read. STATIC like `document.tree@1`
+  // and for the same reason: it is served ENTIRELY by this SDK from the
+  // scene tree the existing `requestSceneTree` wire query already
+  // returns, so there is no engine version to gate on (no core door was
+  // needed — DESIGN.md §4.3d).
+  "document.parentOf@1",
   "document.onDidChange@1",
   "document.getMetadata@1",
   "document.setMetadata@1",
@@ -160,6 +184,13 @@ var HOST_FEATURES = [
   "overlay.toolPreview@1",
   "storage@1",
   "diagnostics@1",
+  // The overlay TEXT primitive (RFI "overlay carries shapes only" —
+  // consumer: paged.draw's Measure readout). A pure pass-through on the
+  // same tool-preview channel; the renderer that knows the variant ships
+  // in the same host release that bumps this SDK, so the flag is static
+  // like the channel's own `overlay.toolPreview@1`. The headless harness
+  // records the shape verbatim.
+  "overlay.text@1",
   // C-5 / I-04 (core v42): the placed-image bytes read is engine-served
   // through the wire (no injected source), so it is unconditionally
   // implemented at the pinned canvas-wasm — unlike assets.fonts@1, which
@@ -168,7 +199,17 @@ var HOST_FEATURES = [
   // .paged container parts door (file-format.md) — the engine (canvas-wasm
   // v51) is the writer, so it is live whenever a bundle runs (the worker
   // handshake guarantees a v51-protocol worker).
-  "storage.parts@1"
+  "storage.parts@1",
+  // 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`
+  // escape hatch). It does NOT claim the host's engine carries v57 — the
+  // vendored wire is still 0.51, so that answer is per-call: a pre-v57
+  // engine (or any host that doesn't answer the query) comes back as
+  // `{ found: false, reason }`, never a fake empty face list. Same
+  // honesty split as the protocol-ahead mutations (mutations.ts): the
+  // engine-level gate is the worker handshake, not `supports()`.
+  "document.planarRegions@1"
 ];
 var PluginApiNotImplemented = class extends Error {
   constructor(member, pointer) {
@@ -179,15 +220,15 @@ var PluginApiNotImplemented = class extends Error {
   }
 };
 var PluginCapabilityError = class extends Error {
-  /** The host door that was called (e.g. `"contribute.tool"`). */
-  door;
-  /** The manifest declaration that would authorize it (e.g.
-   *  `'contributes.tools[] must include "media.paged.web.tool.pen"'`). */
-  missingDeclaration;
   constructor(door, missingDeclaration, pluginId) {
     super(
       `plugin-api: ${pluginId} called ${door} without declaring it \u2014 ${missingDeclaration}. Manifest capabilities are ENFORCED (trust-line W0.11): declare the use or the host refuses it.`
     );
+    /** The host door that was called (e.g. `"contribute.tool"`). */
+    __publicField(this, "door");
+    /** The manifest declaration that would authorize it (e.g.
+     *  `'contributes.tools[] must include "media.paged.web.tool.pen"'`). */
+    __publicField(this, "missingDeclaration");
     this.name = "PluginCapabilityError";
     this.door = door;
     this.missingDeclaration = missingDeclaration;
@@ -280,6 +321,144 @@ function createDataProviderRegistry() {
     }
   };
 }
+function createBindingProviderRegistry() {
+  const providers = /* @__PURE__ */ new Map();
+  const stack = [];
+  const listeners = /* @__PURE__ */ new Set();
+  const key = (plugin, contextType) => `${plugin}\0${contextType}`;
+  const emit = () => {
+    for (const l of [...listeners]) l();
+  };
+  const active = () => {
+    const out = [];
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const frame = stack[i];
+      for (const entry of providers.get(key(frame.plugin, frame.contextType)) ?? []) {
+        out.push({ frame, entry });
+      }
+    }
+    return out;
+  };
+  const declaresPath = (e, path) => e.provider.provides.paths?.includes(path) ?? false;
+  const declaresWritablePath = (e, path) => {
+    const w = e.provider.provides.writablePaths;
+    if (w === void 0) return declaresPath(e, path);
+    return declaresPath(e, path) && w.includes(path);
+  };
+  const declaresCollection = (e, collection) => e.provider.provides.collections?.includes(collection) ?? false;
+  return {
+    register(entry) {
+      const k = key(entry.plugin, entry.contextType);
+      const list = providers.get(k) ?? [];
+      list.push(entry);
+      providers.set(k, list);
+      emit();
+      return toDisposable(() => {
+        const cur = providers.get(k);
+        if (!cur) return;
+        const i = cur.indexOf(entry);
+        if (i >= 0) cur.splice(i, 1);
+        if (cur.length === 0) providers.delete(k);
+        emit();
+      });
+    },
+    setContextActive(plugin, contextType, elementId, isActive) {
+      if (isActive) {
+        stack.push({ plugin, contextType, elementId });
+      } else {
+        for (let i = stack.length - 1; i >= 0; i--) {
+          if (stack[i].plugin === plugin && stack[i].contextType === contextType) {
+            stack.splice(i, 1);
+            break;
+          }
+        }
+      }
+      emit();
+    },
+    notifyChanged() {
+      emit();
+    },
+    activeProviders() {
+      return active().map(({ frame, entry }) => ({
+        plugin: frame.plugin,
+        contextType: frame.contextType,
+        elementId: frame.elementId,
+        provides: entry.provider.provides
+      }));
+    },
+    async readProperty(request) {
+      const rowScoped = request.target.kind === "row" ? request.target.collection : null;
+      for (const { entry } of active()) {
+        if (rowScoped !== null && !declaresCollection(entry, rowScoped)) continue;
+        if (!declaresPath(entry, request.path)) {
+          if (rowScoped === null) continue;
+          return {
+            resolved: true,
+            provider: entry.plugin,
+            read: {
+              kind: "absent",
+              reason: `${entry.plugin} owns collection "${rowScoped}" but does not serve "${request.path}" for its rows`
+            }
+          };
+        }
+        if (!entry.provider.readProperty) continue;
+        const read = await entry.provider.readProperty(request);
+        if (read.kind === "decline") continue;
+        return { resolved: true, provider: entry.plugin, read };
+      }
+      return {
+        resolved: false,
+        reason: `no active binding provider claimed "${request.path}"`
+      };
+    },
+    async writeProperty(request) {
+      const rowScoped = request.target.kind === "row" ? request.target.collection : null;
+      for (const { entry } of active()) {
+        if (rowScoped !== null && !declaresCollection(entry, rowScoped)) continue;
+        if (!declaresWritablePath(entry, request.path)) continue;
+        if (!entry.provider.writeProperty) continue;
+        const write = await entry.provider.writeProperty(request);
+        if (write.kind === "decline") continue;
+        return { handled: true, provider: entry.plugin, outcome: write.outcome };
+      }
+      return {
+        handled: false,
+        reason: `no active binding provider claimed a write to "${request.path}"`
+      };
+    },
+    async readCollection(request) {
+      for (const { entry } of active()) {
+        if (!declaresCollection(entry, request.collection)) continue;
+        if (!entry.provider.readCollection) continue;
+        const read = await entry.provider.readCollection(request);
+        if (read.kind === "decline") continue;
+        return { resolved: true, provider: entry.plugin, rows: read.rows };
+      }
+      return {
+        resolved: false,
+        reason: `no active binding provider claimed collection "${request.collection}"`
+      };
+    },
+    async applyMutation(mutation) {
+      for (const { entry } of active()) {
+        if (!(entry.provider.provides.ops?.includes(mutation.op) ?? false))
+          continue;
+        if (!entry.provider.applyMutation) continue;
+        const write = await entry.provider.applyMutation(mutation);
+        if (write.kind === "decline") continue;
+        return { handled: true, provider: entry.plugin, outcome: write.outcome };
+      }
+      return {
+        handled: false,
+        reason: `no active binding provider claimed the "${mutation.op}" op`
+      };
+    },
+    onDidChange(listener) {
+      listeners.add(listener);
+      return toDisposable(() => listeners.delete(listener));
+    }
+  };
+}
 function createBundleHost(getEditor, manifest, options) {
   const store = new DisposableStore();
   const sink = options?.console ?? console;
@@ -333,6 +512,43 @@ function createBundleHost(getEditor, manifest, options) {
     }
     return reason;
   };
+  const registeredContexts = /* @__PURE__ */ new Set();
+  const bindingRegistry = options?.bindingProviders;
+  const providerLaneGaps = (p) => {
+    const gaps = [];
+    if ((p.provides.paths?.length ?? 0) > 0 && !p.readProperty)
+      gaps.push("provides.paths declared without readProperty()");
+    if ((p.provides.collections?.length ?? 0) > 0 && !p.readCollection)
+      gaps.push("provides.collections declared without readCollection()");
+    if ((p.provides.ops?.length ?? 0) > 0 && !p.applyMutation)
+      gaps.push("provides.ops declared without applyMutation()");
+    const dupes = (label, xs) => {
+      const seen = /* @__PURE__ */ new Set();
+      for (const x of xs ?? []) {
+        if (seen.has(x)) gaps.push(`provides.${label} lists "${x}" twice`);
+        seen.add(x);
+      }
+    };
+    dupes("paths", p.provides.paths);
+    dupes("collections", p.provides.collections);
+    dupes("ops", p.provides.ops);
+    dupes("writablePaths", p.provides.writablePaths);
+    for (const w of p.provides.writablePaths ?? []) {
+      if (!(p.provides.paths ?? []).includes(w)) {
+        gaps.push(
+          `provides.writablePaths lists "${w}", which is not in provides.paths`
+        );
+      }
+    }
+    if (p.provides.writablePaths !== void 0 && !p.writeProperty) {
+      if (p.provides.writablePaths.length > 0)
+        gaps.push("provides.writablePaths declared without writeProperty()");
+    }
+    if ((p.provides.paths?.length ?? 0) === 0 && (p.provides.collections?.length ?? 0) === 0 && (p.provides.ops?.length ?? 0) === 0) {
+      gaps.push("provides declares nothing \u2014 the provider could never answer");
+    }
+    return gaps;
+  };
   const contribute = {
     tool(c) {
       assertNamespaced(c.id, "tool");
@@ -425,9 +641,30 @@ function createBundleHost(getEditor, manifest, options) {
         "contribute.editContext",
         `contributes.editContexts[] must declare { type: "${c.type}" }`
       );
+      registeredContexts.add(c.type);
       const stamped = {
         ...c,
-        metadataKey: metadataKey(manifest)
+        metadataKey: metadataKey(manifest),
+        ...bindingRegistry ? {
+          onEnter: (ctx) => {
+            bindingRegistry.setContextActive(
+              manifest.id,
+              c.type,
+              typeof ctx.id?.id === "string" ? ctx.id.id : null,
+              true
+            );
+            c.onEnter?.(ctx);
+          },
+          onExit: (ctx) => {
+            c.onExit?.(ctx);
+            bindingRegistry.setContextActive(
+              manifest.id,
+              c.type,
+              typeof ctx.id?.id === "string" ? ctx.id.id : null,
+              false
+            );
+          }
+        } : {}
       };
       const reg = getEditor().registries.editContexts;
       const recorded = options?.onEditContextRegistered?.(stamped);
@@ -473,6 +710,69 @@ function createBundleHost(getEditor, manifest, options) {
       return store.add(toDisposable(() => {
       }));
     },
+    // ADR-023 phase A — the BINDING-PROVIDER door. Three gates, in
+    // order, all loud:
+    //   1. the CAPABILITY gate, borrowed whole from the edit context the
+    //      provider attaches to (`contributes.editContexts[]` must
+    //      declare the type). No new manifest field and no new
+    //      capability: the authority a provider exercises IS the
+    //      authority the active context already holds over the selection
+    //      it owns, so a second declaration would be ceremony, not a
+    //      gate. (Precedent: `EditContextContribution.toolIds` swaps the
+    //      whole tool rail and is not separately declared either.)
+    //   2. the ORDERING rule — the context must already be registered by
+    //      THIS bundle. A provider on an unregistered type can never
+    //      activate; accepting it would be the fake-interactive failure
+    //      the platform refuses.
+    //   3. the DECLARATION shape — a lane declared without its callback,
+    //      a repeated entry, or an empty `provides` is an authoring bug
+    //      that would make the provider silently unreachable.
+    // Then the honest no-backend door: no registry wired → warn + an
+    // inert handle (probe `supports("bindings.provider@1")`).
+    bindingProvider(contextType, provider) {
+      requireDeclared(
+        declaresType(declared?.editContexts, contextType),
+        "contribute.bindingProvider",
+        `contributes.editContexts[] must declare { type: "${contextType}" } (a binding provider borrows its edit context's declaration)`
+      );
+      if (!registeredContexts.has(contextType)) {
+        throw new Error(
+          `plugin-api: contribute.bindingProvider("${contextType}") \u2014 no such edit context is registered by ${manifest.id}. A provider BORROWS its context's activation (ADR-023): call contribute.editContext({ type: "${contextType}", \u2026 }) first, or the provider could never be consulted.`
+        );
+      }
+      const gaps = providerLaneGaps(provider);
+      if (gaps.length > 0) {
+        throw new Error(
+          `plugin-api: contribute.bindingProvider("${contextType}") \u2014 ${gaps.join("; ")}. A declared lane the registry can never call is a silently dead provider, so the declaration is refused.`
+        );
+      }
+      if (!bindingRegistry) {
+        log.warn(
+          `contribute.bindingProvider("${contextType}") registered nothing \u2014 the host wired no binding-provider registry, so no panel will ever consult it (probe supports("bindings.provider@1"))`
+        );
+        return store.add({
+          invalidate() {
+          },
+          dispose() {
+          }
+        });
+      }
+      const entry = {
+        plugin: manifest.id,
+        contextType,
+        provider
+      };
+      const reg = store.add(bindingRegistry.register(entry));
+      const handle = {
+        invalidate() {
+          bindingRegistry.notifyChanged(manifest.id, contextType);
+        },
+        dispose() {
+          reg.dispose();
+        }
+      };
+      return handle;
+    },
     // K-2 / S-06 — document IO. Mirrors `command`: namespaced id the
     // manifest must list, routed to the shell registry. The registry is
     // OPTIONAL on the handle (a host that hasn't wired it stays
@@ -571,6 +871,24 @@ function createBundleHost(getEditor, manifest, options) {
     door,
     "capabilities.document.openNative must be declared"
   );
+  let parentIndex = null;
+  let parentIndexWired = false;
+  const buildParentIndex = (roots) => {
+    const index = /* @__PURE__ */ new Map();
+    const walk = (nodes, parent) => {
+      for (const node of nodes) {
+        const id = node.id ?? null;
+        if (id && typeof id.id === "string") {
+          if (parent) index.set(id.id, parent);
+          walk(node.children ?? [], id);
+        } else {
+          walk(node.children ?? [], parent);
+        }
+      }
+    };
+    walk(roots, null);
+    return index;
+  };
   const document = {
     async mutate(mutation) {
       const denied = denyWrite(
@@ -674,6 +992,30 @@ function createBundleHost(getEditor, manifest, options) {
         return null;
       }
     },
+    async planarRegions(elementIds, point) {
+      requireDocRead("document.planarRegions");
+      const refusal = (reason) => ({
+        found: false,
+        faces: [],
+        inputCount: elementIds.length,
+        complete: false,
+        reason
+      });
+      try {
+        const reply = await getEditor().client.send({
+          kind: "requestPlanarRegions",
+          payload: point ? { elementIds, point } : { elementIds }
+        });
+        if (reply.kind !== "planarRegions") {
+          return refusal(
+            "this host did not answer requestPlanarRegions \u2014 its engine predates the planar-region read door (protocol v57)"
+          );
+        }
+        return reply.payload?.result ?? refusal("the engine answered planarRegions with no result");
+      } catch (error) {
+        return refusal(`the region read door failed: ${String(error)}`);
+      }
+    },
     async tree() {
       requireDocRead("document.tree");
       const reply = await getEditor().client.send({
@@ -681,6 +1023,30 @@ function createBundleHost(getEditor, manifest, options) {
       });
       return reply.kind === "sceneTree" ? reply.payload.roots : [];
     },
+    async parentOf(id) {
+      requireDocRead("document.parentOf");
+      if (typeof id.id !== "string") return null;
+      if (!parentIndexWired) {
+        parentIndexWired = true;
+        const off = getEditor().client.subscribe((msg) => {
+          if (msg.kind === "mutationApplied" || msg.kind === "undoApplied" || msg.kind === "redoApplied" || // A newly opened document invalidates everything; the kind
+          // is matched defensively (not every host posts it).
+          msg.kind === "documentLoaded") {
+            parentIndex = null;
+          }
+        });
+        store.add(toDisposable(off));
+      }
+      if (!parentIndex) {
+        const reply = await getEditor().client.send({
+          kind: "requestSceneTree"
+        });
+        parentIndex = buildParentIndex(
+          reply.kind === "sceneTree" ? reply.payload.roots : []
+        );
+      }
+      return parentIndex.get(id.id) ?? null;
+    },
     async getMetadata(id) {
       requireDocRead("document.getMetadata");
       const key = metadataKey(manifest);
@@ -788,6 +1154,15 @@ function createBundleHost(getEditor, manifest, options) {
         ascender: sizePt * 0.8,
         descender: -sizePt * 0.2
       };
+    },
+    // C-9 — the caret read door. A read of EDITOR state (the
+    // text-editing caret), injected by the host app like clipboard /
+    // consent; no capability gate (a read door, like measureString /
+    // viewport). No backend → the honest null (probe
+    // supports("text.caret@1") to distinguish "no caret" from
+    // "no reader").
+    caret() {
+      return options?.textCaret?.read() ?? null;
     }
   };
   const overlay = {
@@ -798,6 +1173,27 @@ function createBundleHost(getEditor, manifest, options) {
         'capabilities.rendering must include "overlay"'
       );
       getEditor().overlaySignals.setToolPreview(shape);
+    },
+    // K-9 — the MULTI-shape write on the SAME slot + the SAME gate. When
+    // the host wired a multi-shape sink we hand the list over verbatim
+    // (the adapter never re-shapes a preview — the renderer owns layout).
+    // When it did not, the honest degradation is the pre-K-9 behaviour a
+    // bundle used to hand-code: the FIRST shape through the single slot,
+    // never a throw. `null`/empty clears, so a bundle's teardown path is
+    // the same either way.
+    setToolPreviews(shapes) {
+      requireDeclared(
+        hasRendering("overlay"),
+        "overlay.setToolPreviews",
+        'capabilities.rendering must include "overlay"'
+      );
+      const signals = getEditor().overlaySignals;
+      const list = shapes && shapes.length > 0 ? shapes : null;
+      if (signals.setToolPreviews) {
+        signals.setToolPreviews(list);
+        return;
+      }
+      signals.setToolPreview(list ? list[0] : null);
     }
   };
   const backing = options?.storage ?? defaultStorageBacking();
@@ -966,19 +1362,40 @@ function createBundleHost(getEditor, manifest, options) {
       return store.add(toDisposable(() => bindingListeners.delete(listener)));
     }
   };
-  const shell = options?.shell ?? {
+  const shellBackend = options?.shell;
+  const shell = {
     openPanel(panelId) {
+      if (shellBackend) {
+        shellBackend.openPanel(panelId);
+        return;
+      }
       log.warn(
         `shell.openPanel("${panelId}") ignored \u2014 the host app provided no shell actions (probe with supports("shell.openPanel@1"))`
       );
     },
-    closePanel() {
+    closePanel(panelId) {
+      shellBackend?.closePanel(panelId);
     },
-    async pickFile() {
+    async pickFile(pickOptions) {
+      if (shellBackend) return shellBackend.pickFile(pickOptions);
       log.warn(
         `shell.pickFile() ignored \u2014 the host app provided no shell actions (probe with supports("shell.pickFile@1"))`
       );
       return [];
+    },
+    // K-10 — the write half. No saver wired (headless, or a host app
+    // older than the door) answers FALSE, never a throw: "the bytes were
+    // not delivered" is a result a bundle can act on (keep the Export
+    // Center path, disable the menu item), which a rejection would turn
+    // into an unhandled promise in a click handler.
+    async saveFile(saveOptions) {
+      if (shellBackend?.saveFile) {
+        return shellBackend.saveFile(saveOptions);
+      }
+      log.warn(
+        `shell.saveFile("${saveOptions.suggestedName}") ignored \u2014 the host app wired no file saver (probe with supports("shell.saveFile@1"))`
+      );
+      return false;
     }
   };
   const widgets = options?.widgets ?? FALLBACK_WIDGETS;
@@ -1437,12 +1854,18 @@ function createBundleHost(getEditor, manifest, options) {
   if (getEditor().sceneLayers) {
     featureSet.add("rendering.sceneLayer@1");
   }
+  if (typeof getEditor().overlaySignals?.setToolPreviews === "function") {
+    featureSet.add("overlay.multiPreview@1");
+  }
   if (getEditor().images) {
     featureSet.add("rendering.resourceProvider@1");
   }
   if (options?.shell) {
     featureSet.add("shell.openPanel@1");
     featureSet.add("shell.pickFile@1");
+    if (typeof options.shell.saveFile === "function") {
+      featureSet.add("shell.saveFile@1");
+    }
   }
   if (options?.widgets) {
     featureSet.add("widgets.codeEditor@1");
@@ -1462,12 +1885,18 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.dataProviders) {
     featureSet.add("dataProviders@1");
   }
+  if (options?.bindingProviders) {
+    featureSet.add("bindings.provider@1");
+  }
   if (options?.blobStore) {
     featureSet.add("storage.blob@1");
   }
   if (options?.clipboard) {
     featureSet.add("clipboard@1");
   }
+  if (options?.textCaret) {
+    featureSet.add("text.caret@1");
+  }
   if (options?.nativeDocument) {
     featureSet.add("document.readNative@1");
     featureSet.add("document.openNative@1");
@@ -1717,7 +2146,7 @@ function inMemorySecretStore() {
   };
 }
 var seqCounter = 1;
-function makeEngineEditor(worker, recorder, onToolPreview) {
+function makeEngineEditor(worker, recorder, onToolPreview, onToolPreviews) {
   const protocol = worker.protocolVersion;
   const listeners = /* @__PURE__ */ new Set();
   const fanOut = (reply) => {
@@ -1765,6 +2194,7 @@ function makeEngineEditor(worker, recorder, onToolPreview) {
   };
   let elementSelection = [];
   let toolPreview = null;
+  let toolPreviews = null;
   const client = {
     async mutate(mutation) {
       const reply = dispatch("mutate", mutation);
@@ -1854,6 +2284,18 @@ function makeEngineEditor(worker, recorder, onToolPreview) {
       setToolPreview(value) {
         toolPreview = value;
         onToolPreview(toolPreview);
+      },
+      // K-9 — the MULTI-shape sink. Wiring it headlessly is what makes
+      // `supports("overlay.multiPreview@1")` true in the harness, so a
+      // bundle's "geometry AND label at once" claim is conformance-
+      // assertable without a browser. One slot: the list also updates
+      // `lastToolPreview()` (to its first shape) so an older assertion
+      // still reads something true rather than a stale value.
+      setToolPreviews(value) {
+        toolPreviews = value && value.length > 0 ? value : null;
+        toolPreview = toolPreviews ? toolPreviews[0] : null;
+        onToolPreviews(toolPreviews);
+        onToolPreview(toolPreview);
       }
     },
     // No tool spine + no content caret headlessly — both are inert
@@ -1871,21 +2313,31 @@ async function createHeadlessHost(options = {}) {
   const worker = engine.worker;
   const contributions = [];
   let lastPreview = null;
-  const editor = makeEngineEditor(worker, contributions, (value) => {
-    lastPreview = value;
-  });
+  let lastPreviews = null;
+  const editor = makeEngineEditor(
+    worker,
+    contributions,
+    (value) => {
+      lastPreview = value;
+    },
+    (value) => {
+      lastPreviews = value;
+    }
+  );
   let active = null;
   let currentHost = null;
   let disposed = false;
   const blobStore = options.blobStore ?? inMemoryBlobStore();
   const clipboard = options.clipboard ?? inMemoryClipboard();
   const secrets = options.secrets ?? inMemorySecretStore();
+  const bindingProviders = options.bindingProviders ?? createBindingProviderRegistry();
   const buildHost = (manifest, mode) => createBundleHost(() => editor, manifest, {
     console: options.console,
     storage: options.storage,
     blobStore,
     clipboard,
     secrets,
+    bindingProviders,
     capabilityMode: mode,
     // W-06 — a recordable fake asset source the conformance harness
     // can pass so a bundle's `@font-face` byte path is exercisable
@@ -2002,6 +2454,10 @@ async function createHeadlessHost(options = {}) {
     lastToolPreview() {
       return lastPreview;
     },
+    lastToolPreviews() {
+      return lastPreviews;
+    },
+    bindingProviders,
     async load(idml) {
       const raw = worker.loadDocumentDirect(seqCounter++, idml);
       const reply = JSON.parse(raw);
@@ -2299,6 +2755,9 @@ function contributeEditContext(host, contribution) {
 function contributeObjectType(host, contribution) {
   return host.contribute.objectType(contribution);
 }
+function contributeBindingProvider(host, contextType, provider) {
+  return host.contribute.bindingProvider(contextType, provider);
+}
 export {
   API_VERSION,
   ASSET_BUDGETS,
@@ -2314,11 +2773,13 @@ export {
   WORKER_BUDGETS,
   beginPageDrag,
   commitAndSelect,
+  contributeBindingProvider,
   contributeEditContext,
   contributeObjectType,
   contributePanel,
   contributeSchemaPanel,
   contributeTool,
+  createBindingProviderRegistry,
   createBundleHost,
   createDataProviderRegistry,
   createHeadlessHost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-sdk",
-  "version": "0.2.27-canary.1",
+  "version": "0.2.28-canary.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@paged-media/plugin-api": "0.2.27-canary.1"
+    "@paged-media/plugin-api": "0.2.28-canary.0"
   },
   "peerDependencies": {
     "react": "^18.3.0"
@@ -46,6 +46,6 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
-    "build": "tsup src/index.ts --format esm --dts --out-dir dist --clean"
+    "build": "tsup src/index.ts --format esm --target es2020 --dts --out-dir dist --clean"
   }
 }