@paged-media/plugin-sdk 0.2.32-canary.0 → 0.2.34-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, 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 { PagedBundle, BindingProvider, Disposable, ActiveBindingProvider, BindingPropertyRequest, BindingReadResult, BindingPropertyWrite, BindingWriteResult, BindingCollectionRequest, BindingCollectionResult, MutationInput, FontFaceAsset, BundleHost, ClipboardPayload, ConsentResult, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, JournalRecord, 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';
 
 /**
@@ -68,6 +68,20 @@ interface DiagnosticsSink {
     publish(bundleId: string, key: string, diagnostics: Diagnostic[]): void;
     clear(bundleId: string, key?: string): void;
 }
+/**
+ * ADR 025 — the host's journal buffer, injected the same way `DiagnosticsSink`
+ * is, and for the same reason: the ring lives in the app (one per session,
+ * created outside any bundle), and every loaded bundle fans INTO it with its
+ * own id stamped by the host.
+ *
+ * Structurally identical to the diagnostics fan-out on purpose: `manifest`,
+ * `storage`, `diagnostics`, `supports` and `log` are the members DESIGN.md §6
+ * already lists as "trivial proxy" across the future isolate boundary, and a
+ * plain-JSON, bundleId-keyed sink joins them without adding a new problem.
+ */
+interface JournalSink {
+    record(bundleId: string, entry: JournalRecord): void;
+}
 /** Asset-store budgets (W-06). The per-face cap mirrors the wasm lane's
  *  per-artifact ceiling (DESIGN.md §10/§13.3) — a bundle can never be
  *  handed an unbounded face buffer. The host facade refuses an
@@ -349,8 +363,17 @@ interface CreateBundleHostOptions {
      *  (nothing would ever consult the provider) and
      *  `supports("bindings.provider@1")` is false. */
     bindingProviders?: BindingProviderBackend;
-    /** Console sink override (tests). */
+    /** Console sink override.
+     *
+     *  Originally a test hook, and now ALSO the production capture point: the
+     *  editor passes a sink that censuses every `host.log` line (severity + a
+     *  hash of the message) into the journal while forwarding the real text to
+     *  the real console. See ADR 025 §5 — a census, not a mirror, because
+     *  `host.log` is free text across ~900 call sites. */
     console?: Pick<Console, "debug" | "info" | "warn" | "error">;
+    /** ADR 025 — where `host.journal` entries go. Absent = the surface is
+     *  inert and `supports("journal@1")` is false. */
+    journal?: JournalSink;
     /** 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. Typed as
@@ -690,6 +713,10 @@ declare function makeSchemaPanelComponent(contribution: SchemaPanelContribution,
 interface LoadedBundle {
     readonly id: string;
     readonly active: boolean;
+    /** Set when `activate()` threw. `active` is then false and this bundle
+     *  contributed nothing — the host can surface the reason rather than
+     *  discovering an inert plugin by its absence. */
+    readonly activationError?: unknown;
     dispose(): void;
 }
 declare function loadBundle(getEditor: () => PagedEditor, bundle: PagedBundle, options?: CreateBundleHostOptions): LoadedBundle;
@@ -855,4 +882,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 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 };
+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, 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

@@ -478,6 +478,34 @@ function createBundleHost(getEditor, manifest, options) {
     warn: (m, ...a) => sink.warn(`${tag} ${m}`, ...a),
     error: (m, ...a) => sink.error(`${tag} ${m}`, ...a)
   };
+  const journalSink = options?.journal;
+  const journal = {
+    record(entry) {
+      if (!journalSink) return;
+      try {
+        assertNamespaced(entry.code, "journal");
+        journalSink.record(manifest.id, entry);
+      } catch (err) {
+        log.warn(`journal.record refused: ${String(err)}`);
+      }
+    },
+    async time(code, fn) {
+      const t0 = Date.now();
+      try {
+        const out = await fn();
+        journal.record({ code, durMs: Date.now() - t0, data: { ok: true } });
+        return out;
+      } catch (err) {
+        journal.record({
+          code,
+          severity: "error",
+          durMs: Date.now() - t0,
+          data: { ok: false }
+        });
+        throw err;
+      }
+    }
+  };
   const capabilityMode = options?.capabilityMode ?? "enforce";
   const caps = manifest.capabilities;
   const declared = manifest.contributes;
@@ -624,6 +652,42 @@ function createBundleHost(getEditor, manifest, options) {
       );
       return store.add(getEditor().registries.keybindings.register(c));
     },
+    menu(c) {
+      assertNamespaced(c.command, "menu");
+      requireDeclared(
+        lists(declared?.commands, c.command),
+        "contribute.menu",
+        `contributes.commands[] must include "${c.command}" before a menu entry can invoke it`
+      );
+      const scope = c.scope ?? "document";
+      const editContext = typeof scope === "object" ? scope.editContext : null;
+      const menus = getEditor().registries.menus;
+      if (!menus) {
+        return { dispose() {
+        } };
+      }
+      return store.add(
+        menus.register({
+          path: c.path,
+          command: c.command,
+          order: c.order,
+          group: c.group,
+          // The scope becomes a `when` predicate, which is the host's
+          // existing vocabulary for "does this apply where you are
+          // standing" — the same field the Insert items and the Window
+          // menu already use. A context-scoped entry is simply one whose
+          // predicate asks what context is active.
+          when: (state2) => {
+            const st = state2;
+            if (!st?.document?.handle || (st.document.handle.pageCount ?? 0) === 0) {
+              return false;
+            }
+            if (editContext === null) return true;
+            return st.editContext?.type === editContext;
+          }
+        })
+      );
+    },
     overlay(c) {
       assertNamespaced(c.id, "overlay");
       requireDeclared(
@@ -1879,6 +1943,9 @@ function createBundleHost(getEditor, manifest, options) {
     }
   };
   const featureSet = new Set(HOST_FEATURES);
+  if (options?.journal) {
+    featureSet.add("journal@1");
+  }
   if (getEditor().text) {
     featureSet.add("text.measure@1");
   }
@@ -1958,6 +2025,7 @@ function createBundleHost(getEditor, manifest, options) {
     network,
     dataProviders,
     diagnostics,
+    journal,
     bindings,
     widgets,
     assets,
@@ -2604,7 +2672,31 @@ function loadBundle(getEditor, bundle, options) {
     manifest,
     options
   );
-  const handle = bundle.activate(host);
+  let handle;
+  try {
+    handle = bundle.activate(host);
+  } catch (err) {
+    options?.journal?.record(manifest.id, {
+      code: `${manifest.id}.activate`,
+      severity: "error",
+      // Only the error KIND crosses: an activation throw routinely carries a
+      // module path or a bundler message in its text.
+      data: { ok: false, error: errorKind(err) }
+    });
+    options?.diagnosticsSink?.publish(manifest.id, "activation", [
+      {
+        severity: "error",
+        message: `${manifest.id} failed to activate: ${String(err)}`,
+        source: "loadBundle"
+      }
+    ]);
+    disposeHost();
+    return inertBundle(manifest.id, err);
+  }
+  options?.journal?.record(manifest.id, {
+    code: `${manifest.id}.activate`,
+    data: { ok: true }
+  });
   let active = true;
   return {
     id: manifest.id,
@@ -2622,6 +2714,22 @@ function loadBundle(getEditor, bundle, options) {
     }
   };
 }
+function errorKind(err) {
+  const raw = err && typeof err === "object" && typeof err.constructor?.name === "string" ? err.constructor.name : typeof err;
+  const lowered = raw.toLowerCase();
+  return /^[a-z0-9][a-z0-9._:-]{0,63}$/.test(lowered) ? lowered : "unknown";
+}
+function inertBundle(id, error) {
+  return {
+    id,
+    get active() {
+      return false;
+    },
+    activationError: error,
+    dispose() {
+    }
+  };
+}
 
 // src/wasm-bundle-loader.ts
 var WASM_BUDGETS = {

package/package.json

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