@paged-media/plugin-sdk 0.2.49-canary.0 → 0.2.51-canary.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PagedBundle, ParsedAddress, ElementId, MutationInput, MutationOutcome, ObjectErrorCode, ObjectKindInfo, PropertySchema, ObjectValue, ObjectOp, PagedEditor, ObjectsSurface, ObjectModelContribution, PartsSurface, PluginLogger, ObjectModelHandle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, OpenDocumentResult, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, EnteredEditContext, ValueType, ObjectCommandInfo, PropertyPath, BindingsSurface, PanelProps, SchemaGate, WasmArtifact, CanvasPointerEvent, Mutation, PanelSchemaPropertyRow, PanelSchemaRow, PropertyFieldAddress, PanelSchema, ValueEdit, Address, ListEdit, StructEdit, ObjectWriteResult, BindingProviderHandle } from '@paged-media/plugin-api';
+import { PagedBundle, ParsedAddress, ElementId, MutationInput, MutationOutcome, ObjectErrorCode, ObjectKindInfo, PropertySchema, ObjectValue, ObjectOp, PagedEditor, ObjectsSurface, ObjectModelContribution, PartsSurface, PluginLogger, ObjectModelHandle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, ShellSurface, WidgetSurface, WillSaveEvent, ToolSettingValue, SchemaPanelRenderer, SchemaPanelContribution, EditContextContribution, ObjectTypeContribution, Diagnostic, TextCaret, OpenDocumentResult, WasmArtifact, PluginManifest, ToolContribution, PanelContribution, CommandContribution, KeybindingContribution, OverlayContribution, ImporterContribution, ExporterContribution, ToolPreviewShape, EnteredEditContext, ValueType, ObjectCommandInfo, PropertyPath, BindingsSurface, PanelProps, SchemaGate, ModulesSurface, CanvasPointerEvent, Mutation, PanelSchemaPropertyRow, PanelSchemaRow, PropertyFieldAddress, PanelSchema, ValueEdit, Address, ListEdit, StructEdit, ObjectWriteResult, BindingProviderHandle } from '@paged-media/plugin-api';
 import { ComponentType } from 'react';
 
 /**
@@ -339,6 +339,31 @@ interface SpawnedWorker {
 interface WorkerBackend {
     spawn(pluginId: string, module: string, name?: string): Promise<SpawnedWorker>;
 }
+/**
+ * What a `ModulesBackend` answers for one declared artifact: the URL the
+ * host serves its bytes at and, when the host knows it, the bytes'
+ * Subresource Integrity (`sha384-…`).
+ */
+interface ModuleLocation {
+    url: string;
+    integrity?: string | null;
+}
+/**
+ * The backend the editor injects to back `host.modules` (ADR 326). The SDK
+ * adapter owns the capability gate (only a name declared in
+ * `capabilities.wasm` reaches the backend, and the backend receives the
+ * DECLARED artifact, never a bundle-supplied path) and the integrity rule
+ * (the manifest's own `integrity` wins; a contradicting host answer is
+ * refused). The backend maps `(pluginId, artifact)` to where the host serves
+ * those bytes — the editor answers from its build-time module manifest
+ * (`https://modules.paged.media/<package>/<version>/<path>` in a deployed
+ * build). `null` = "not served here": the bundle loads its own copy. A
+ * headless host injects none → every answer is `null` and
+ * `supports("modules@1")` is false.
+ */
+interface ModulesBackend {
+    url(pluginId: string, artifact: WasmArtifact): ModuleLocation | null | Promise<ModuleLocation | null>;
+}
 /**
  * The backend the editor injects to back `host.secrets` (D-11;
  * rfc-credential-store): a REFERENCE-ONLY, host-owned credential store. The
@@ -446,6 +471,20 @@ interface PagesBackend {
     activePage(): string | null;
     onDidChangeActivePage(listener: (pageId: string | null) => void): () => void;
 }
+/**
+ * The backend the editor injects to back `host.viewport.revealText`. The
+ * editor owns the camera, the page layout and the text selection, so it
+ * locates the range on the page, moves there and (optionally) selects it.
+ * No backend → `revealText` answers false and
+ * `supports("viewport.revealText@1")` is false.
+ */
+interface TextRevealBackend {
+    revealText(range: {
+        storyId: string;
+        start: number;
+        end: number;
+    }, select: boolean): boolean | Promise<boolean>;
+}
 /** 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
@@ -704,6 +743,9 @@ interface CreateBundleHostOptions {
      *  `activePage`, `onDidChangeActivePage`). When present,
      *  `supports("viewport.pages@1")` is true. */
     pages?: PagesBackend;
+    /** Text navigation for `host.viewport.revealText`. When present,
+     *  `supports("viewport.revealText@1")` is true. */
+    text?: TextRevealBackend;
     /** 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,
@@ -712,6 +754,12 @@ interface CreateBundleHostOptions {
      *  honestly, `concurrency()` is 0, and the feature flag is false (the
      *  honest no-worker door). */
     workers?: WorkerBackend;
+    /** Host-provided MODULE backend (ADR 326). When present,
+     *  `host.modules.resolve/url/fetch` answer a declared `capabilities.wasm`
+     *  artifact with the URL the host serves it at (+ integrity) and
+     *  `supports("modules@1")` answers true. When absent every answer is
+     *  `null` and the bundle loads its bundle-relative copy. */
+    modules?: ModulesBackend;
     /** Host-provided CREDENTIAL-STORE backend (D-11; rfc-credential-store).
      *  When present, `host.secrets.set/exists/forget` go through it
      *  (capability-gated on `capabilities.secrets`; `set` prompts the user —
@@ -1417,6 +1465,37 @@ interface LoadBundleWasmOptions {
  */
 declare function loadBundleWasm(bundle: PagedBundle, name: string, options: LoadBundleWasmOptions): Promise<LoadedBundleWasm>;
 
+/** Where a wasm artifact will be loaded from. */
+interface ResolvedWasm {
+    /** The URL to load. */
+    url: string;
+    /** Subresource Integrity to fetch it with, or `null` when unknown. */
+    integrity: string | null;
+    /** `"host"` when the host served the answer, `"bundle"` for the fallback. */
+    source: "host" | "bundle";
+}
+type HostLike = Pick<BundleHost, "manifest" | "supports"> & {
+    readonly modules?: Partial<ModulesSurface>;
+};
+/**
+ * Resolve the declared wasm artifact `name`: the host's URL + integrity when
+ * the host serves it (`supports("modules@1")`), else `fallbackUrl` (the
+ * bundle-relative URL the bundle used before) with the manifest's own
+ * integrity stamp, if it has one. Never rejects: a host path that fails —
+ * no door, an undeclared name, a throwing backend — is the fallback.
+ */
+declare function resolveWasm(host: HostLike, name: string, fallbackUrl: string | URL): Promise<ResolvedWasm>;
+/** `resolveWasm(...)`'s URL alone. */
+declare function resolveWasmUrl(host: HostLike, name: string, fallbackUrl: string | URL): Promise<string>;
+/**
+ * Fetch the declared wasm artifact `name` from wherever `resolveWasm` says,
+ * with `{ integrity }` when one is known — a byte that differs fails the
+ * fetch instead of reaching `WebAssembly`. Hand the promise to
+ * `WebAssembly.instantiateStreaming` or a wasm-bindgen
+ * `init({ module_or_path })`.
+ */
+declare function fetchWasm(host: HostLike, name: string, fallbackUrl: string | URL): Promise<Response>;
+
 declare const CLICK_DRAG_THRESHOLD_PX = 4;
 /** A drag anchored to the page under the pointer at pointer-down. */
 interface PageDrag {
@@ -1580,4 +1659,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, CORE_CATALOG_ROWS, CORE_COMMAND_CREATES, CORE_COMMAND_EXCLUSIONS, CORE_COMMAND_OPS, CORE_COMMAND_PREFIX, CORE_PATHS, CORE_PATH_ALIASES, CORE_WIRE_OPS, type ClipboardBackend, type ConsentBackend, type CoreCatalogRow, type CoreCreatePlan, type CoreObjects, type CorePathRow, type CorePathScope, type CorePlan, type CoreRow71, type CoreWireOpRow, type CreateBundleHostOptions, type CreateCoreObjectsOptions, type CreateObjectRegistryOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, type DocumentsBackend, FALLBACK_WIDGETS, FRAME_KIND_WORDS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type HostObjectAnswer, type HostObjectCall, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type NativeDocumentBackend, OBJECT_MODEL_PROTOCOL, type ObjectListRow, type ObjectModelRegistration, type ObjectRegistry, type PageDrag, type PagesBackend, type PanelSchemaIssue, type ParsedSelector, PluginApiNotImplemented, PluginCapabilityError, type PropertyRowOptions, type PublishObjectListOptions, ROW_PATH, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type ScriptRunResult, type ScriptSend, type SecretStoreBackend, type SeededFace, type SelectorHead, type SelectorPredicate, type SelectorStep, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type ToolSettingsBackend, VALUE_TYPE_KINDS, type ValidatePanelSchemaOptions, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, addressKindOf, answerHostObjects, answerHostObjectsRound, applyDefaults, applyValueEdit, assetFromBytes, beginPageDrag, checkSchemaRows, checkValueType, codeOfEngineError, coerceValue, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, coreCommandInfos, coreSchema71, createBindingProviderRegistry, createBundleHost, createCoreObjects, createDataProviderRegistry, createHeadlessHost, createObjectRegistry, createRecordableAssetSource, defaultValueOf, defineBundle, editValue, endLocalFor, escapeLabelValue, findRow, formatAddress, fromElementId, inMemoryToolSettings, inMemoryWillSave, isCoreCommand, isPropertyRow, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, normalizeAddress, normalizeCoreType, parseAddress, parseLength, parseSelector, planValueEdit, propertyRow, propertyRows, propertyRowsOf, protocolFromVersion, publishObjectList, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, rowPathOf, runScriptWithObjects, satisfiesApiVersion, selectorKind, toDisposable, toElementId, validatePanelSchema, validateValue };
+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, CORE_CATALOG_ROWS, CORE_COMMAND_CREATES, CORE_COMMAND_EXCLUSIONS, CORE_COMMAND_OPS, CORE_COMMAND_PREFIX, CORE_PATHS, CORE_PATH_ALIASES, CORE_WIRE_OPS, type ClipboardBackend, type ConsentBackend, type CoreCatalogRow, type CoreCreatePlan, type CoreObjects, type CorePathRow, type CorePathScope, type CorePlan, type CoreRow71, type CoreWireOpRow, type CreateBundleHostOptions, type CreateCoreObjectsOptions, type CreateObjectRegistryOptions, type DataProviderBackend, type DiagnosticsSink, DisposableStore, type DocumentsBackend, FALLBACK_WIDGETS, FRAME_KIND_WORDS, HOST_FEATURES, type HarnessOptions, type HeadlessCanvasWorker, type HeadlessHost, type HeadlessHostHandle, type HostObjectAnswer, type HostObjectCall, type JournalSink, type LoadBundleWasmOptions, type LoadHeadlessEngineOptions, type LoadedBundle, type LoadedBundleWasm, type LoadedEngine, type ModuleLocation, type ModulesBackend, type NativeDocumentBackend, OBJECT_MODEL_PROTOCOL, type ObjectListRow, type ObjectModelRegistration, type ObjectRegistry, type PageDrag, type PagesBackend, type PanelSchemaIssue, type ParsedSelector, PluginApiNotImplemented, PluginCapabilityError, type PropertyRowOptions, type PublishObjectListOptions, ROW_PATH, type RecordableAssetSource, type RecordedContribution, type RecordedFontFaceRequest, type RegisteredBindingProvider, type ResolvedWasm, type ScriptRunResult, type ScriptSend, type SecretStoreBackend, type SeededFace, type SelectorHead, type SelectorPredicate, type SelectorStep, type ShellBackend, type SpawnedWorker, type StorageBacking, type TextCaretBackend, type TextRevealBackend, type ToolSettingsBackend, VALUE_TYPE_KINDS, type ValidatePanelSchemaOptions, WASM_BUDGETS, WORKER_BUDGETS, type WillSaveBackend, type WorkerBackend, addressKindOf, answerHostObjects, answerHostObjectsRound, applyDefaults, applyValueEdit, assetFromBytes, beginPageDrag, checkSchemaRows, checkValueType, codeOfEngineError, coerceValue, commitAndSelect, contributeBindingProvider, contributeEditContext, contributeObjectType, contributePanel, contributeSchemaPanel, contributeTool, coreCommandInfos, coreSchema71, createBindingProviderRegistry, createBundleHost, createCoreObjects, createDataProviderRegistry, createHeadlessHost, createObjectRegistry, createRecordableAssetSource, defaultValueOf, defineBundle, editValue, endLocalFor, escapeLabelValue, fetchWasm, findRow, formatAddress, fromElementId, inMemoryToolSettings, inMemoryWillSave, isCoreCommand, isPropertyRow, loadBundle, loadBundleWasm, loadHeadlessEngine, makeSchemaPanelComponent, normalizeAddress, normalizeCoreType, parseAddress, parseLength, parseSelector, planValueEdit, propertyRow, propertyRows, propertyRowsOf, protocolFromVersion, publishObjectList, pxToPt, readVendoredWireVersion, resolveCanvasWasm, resolveGate, resolveWasm, resolveWasmUrl, rowPathOf, runScriptWithObjects, satisfiesApiVersion, selectorKind, toDisposable, toElementId, validatePanelSchema, validateValue };

package/dist/index.js

@@ -11717,6 +11717,23 @@ function createBundleHost(getEditor, manifest, options) {
         });
       }
       return store.add(toDisposable(pagesBackend.onDidChangeActivePage(listener)));
+    },
+    async revealText(range, opts) {
+      const textBackend = options?.text;
+      if (!textBackend || !range || typeof range.storyId !== "string" || range.storyId === "") {
+        return false;
+      }
+      const start = Math.trunc(Number(range.start));
+      const end = Math.trunc(Number(range.end));
+      if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end < start) {
+        return false;
+      }
+      const select = opts?.select !== false;
+      try {
+        return await textBackend.revealText({ storyId: range.storyId, start, end }, select) === true;
+      } catch {
+        return false;
+      }
     }
   };
   const render = {
@@ -12666,6 +12683,52 @@ function createBundleHost(getEditor, manifest, options) {
     },
     concurrency: () => workerCap
   };
+  const modulesBackend = options?.modules;
+  const declaredWasm = (name) => caps?.wasm?.find((a) => a.name === name);
+  const sriAlgorithm = (sri) => sri.split("-", 1)[0] ?? "";
+  const modules = {
+    async resolve(name) {
+      const artifact = declaredWasm(name);
+      requireDeclared(
+        artifact !== void 0,
+        `modules.resolve("${name}")`,
+        `capabilities.wasm must declare an artifact named "${name}"`
+      );
+      if (!artifact || !modulesBackend) return null;
+      let answer;
+      try {
+        answer = await modulesBackend.url(manifest.id, { ...artifact });
+      } catch (err) {
+        log.warn(`modules.resolve("${name}"): the host backend threw`, err);
+        return null;
+      }
+      if (!answer || typeof answer.url !== "string") return null;
+      let url;
+      try {
+        url = new URL(answer.url).href;
+      } catch {
+        log.warn(`modules.resolve("${name}"): the host answered a non-absolute URL "${answer.url}"`);
+        return null;
+      }
+      const declaredSri = artifact.integrity ?? null;
+      const hostSri = answer.integrity ?? null;
+      if (declaredSri && hostSri && sriAlgorithm(declaredSri) === sriAlgorithm(hostSri) && declaredSri !== hostSri) {
+        log.warn(
+          `modules.resolve("${name}"): the host serves bytes whose integrity (${hostSri}) differs from the manifest's (${declaredSri}) \u2014 refused; load the bundle's own copy`
+        );
+        return null;
+      }
+      return { url, integrity: declaredSri ?? hostSri, artifact };
+    },
+    async url(name) {
+      return (await modules.resolve(name))?.url ?? null;
+    },
+    async fetch(name) {
+      const hosted = await modules.resolve(name);
+      if (!hosted) return null;
+      return hosted.integrity ? globalThis.fetch(hosted.url, { integrity: hosted.integrity }) : globalThis.fetch(hosted.url);
+    }
+  };
   const secretStore = options?.secrets;
   const secrets = {
     async set(ref, secret) {
@@ -12803,6 +12866,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.pages) {
     featureSet.add("viewport.pages@1");
   }
+  if (options?.text) {
+    featureSet.add("viewport.revealText@1");
+  }
   if (options?.documents) {
     featureSet.add("documents.exportPaged@1");
     featureSet.add("documents.open@1");
@@ -12810,6 +12876,9 @@ function createBundleHost(getEditor, manifest, options) {
   if (options?.workers) {
     featureSet.add("workers@1");
   }
+  if (options?.modules) {
+    featureSet.add("modules@1");
+  }
   if (options?.secrets) {
     featureSet.add("secrets@1");
   }
@@ -12879,6 +12948,7 @@ function createBundleHost(getEditor, manifest, options) {
     assets,
     images,
     workers,
+    modules,
     secrets,
     clipboard,
     tools,
@@ -13989,6 +14059,35 @@ async function loadBundleWasm(bundle, name, options) {
   return { artifact, module, instance, memory, byteLength: view.byteLength };
 }
 
+// src/modules.ts
+function declaredIntegrity(host, name) {
+  const a = host.manifest.capabilities?.wasm?.find((w) => w.name === name);
+  return a?.integrity ?? null;
+}
+async function resolveWasm(host, name, fallbackUrl) {
+  const fallback = {
+    url: String(fallbackUrl),
+    integrity: declaredIntegrity(host, name),
+    source: "bundle"
+  };
+  if (!host.supports("modules@1") || typeof host.modules?.resolve !== "function") {
+    return fallback;
+  }
+  try {
+    const hosted = await host.modules.resolve(name);
+    if (hosted) return { url: hosted.url, integrity: hosted.integrity, source: "host" };
+  } catch {
+  }
+  return fallback;
+}
+async function resolveWasmUrl(host, name, fallbackUrl) {
+  return (await resolveWasm(host, name, fallbackUrl)).url;
+}
+async function fetchWasm(host, name, fallbackUrl) {
+  const r = await resolveWasm(host, name, fallbackUrl);
+  return r.integrity ? fetch(r.url, { integrity: r.integrity }) : fetch(r.url);
+}
+
 // src/gestures.ts
 var CLICK_DRAG_THRESHOLD_PX = 4;
 function beginPageDrag(e) {
@@ -14496,6 +14595,7 @@ export {
   editValue,
   endLocalFor,
   escapeLabelValue,
+  fetchWasm,
   findRow,
   formatAddress,
   fromElementId,
@@ -14522,6 +14622,8 @@ export {
   readVendoredWireVersion,
   resolveCanvasWasm,
   resolveGate,
+  resolveWasm,
+  resolveWasmUrl,
   rowPathOf,
   runScriptWithObjects,
   satisfiesApiVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-sdk",
-  "version": "0.2.49-canary.0",
+  "version": "0.2.51-canary.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@paged-media/plugin-api": "0.2.48-canary.0"
+    "@paged-media/plugin-api": "0.2.50-canary.0"
   },
   "peerDependencies": {
     "react": "^18.3.0"