@clipbus/plugin-sdk 0.9.9 → 0.10.0

package/dist/ui/index.js

@@ -2,6 +2,14 @@
 var STRUCTURED_ERROR_PREFIX = "__clipbus_structured_error__:";
 var CAPABILITIES_GLOBAL = "__CLIPBUS_PLUGIN_CAPABILITIES__";
 var CAPABILITY_UNSUPPORTED_ERROR_NAME = "PluginCapabilityUnsupported";
+var PLUGIN_CALL_HANDLER_NAME = "clipbusPluginCall";
+var WIRE_ERROR_NAMES = {
+  methodNotFound: "PluginRuntimeMethodNotFound",
+  handlerNotFound: "PluginRuntimeHandlerNotFound",
+  invocationExpired: "PluginRuntimeInvocationExpired",
+  hostCallLimitExceeded: "PluginRuntimeHostCallLimitExceeded",
+  hostBridgeUnavailable: "PluginHostBridgeUnavailable"
+};
 
 // src/internal/capabilities.ts
 var CapabilityUnsupportedError = class extends Error {
@@ -36,35 +44,36 @@ function mapToCapabilityError(err, unsupportedName) {
   return err;
 }
 
-// src/internal/runtimeInvokeClient.ts
-var HANDLER_NAME = "clipbusPluginCall";
-async function callRuntimeInvokeStrict(payload) {
-  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME];
+// src/internal/pluginCall.ts
+async function callPluginMethod(method, payload) {
+  const handler = globalThis.webkit?.messageHandlers?.[PLUGIN_CALL_HANDLER_NAME];
   if (!handler) {
-    throw new Error("runtime.invoke is only available inside a Clipbus plugin WebView");
+    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
+    err.name = WIRE_ERROR_NAMES.hostBridgeUnavailable;
+    throw err;
   }
   const normalized = JSON.parse(JSON.stringify(payload));
-  let reply;
   try {
-    reply = await handler.postMessage({ method: "runtime.invoke", payload: normalized });
+    return await handler.postMessage({ method, payload: normalized });
   } catch (err) {
     throw parseReplyError(err);
   }
+}
+async function callRuntimeInvoke(payload) {
+  if (!globalThis.webkit?.messageHandlers?.[PLUGIN_CALL_HANDLER_NAME]) {
+    throw new Error("runtime.invoke is only available inside a Clipbus plugin WebView");
+  }
+  const reply = await callPluginMethod("runtime.invoke", payload);
   return reply?.response;
 }
 function parseReplyError(raw) {
   const message = extractMessage(raw);
   if (message.startsWith(STRUCTURED_ERROR_PREFIX)) {
-    const json = message.slice(STRUCTURED_ERROR_PREFIX.length);
     try {
-      const parsed = JSON.parse(json);
+      const parsed = JSON.parse(message.slice(STRUCTURED_ERROR_PREFIX.length));
       const err = new Error(typeof parsed.message === "string" ? parsed.message : "");
-      if (typeof parsed.name === "string" && parsed.name.length > 0) {
-        err.name = parsed.name;
-      }
-      if (parsed.data !== void 0) {
-        err.data = parsed.data;
-      }
+      if (typeof parsed.name === "string" && parsed.name.length > 0) err.name = parsed.name;
+      if (parsed.data !== void 0) err.data = parsed.data;
       return mapToCapabilityError(err, CAPABILITY_UNSUPPORTED_ERROR_NAME);
     } catch {
       return new Error(message);
@@ -82,44 +91,20 @@ function extractMessage(raw) {
   return String(raw);
 }
 
-// src/generated/capabilityClients.generated.ts
-var HANDLER_NAME2 = "clipbusPluginCall";
-async function callPluginMethod(method, payload) {
-  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME2];
-  if (!handler) {
-    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
-    err.name = "PluginHostBridgeUnavailable";
-    throw err;
-  }
-  const normalized = JSON.parse(JSON.stringify(payload));
-  let reply;
-  try {
-    reply = await handler.postMessage({ method, payload: normalized });
-  } catch (err) {
-    throw parseReplyError(err);
-  }
-  return reply;
-}
-var callItemReadAttachment = (payload) => callPluginMethod("item.readAttachment", payload);
-var callAssetCurrentItemImageUrl = () => callPluginMethod("asset.currentItemImageUrl", {});
-var callAssetPathReferenceImageUrl = (payload) => callPluginMethod("asset.pathReferenceImageUrl", payload);
-var callAssetCurrentActionInputImageUrl = () => callPluginMethod("asset.currentActionInputImageUrl", {});
-var callAssetCurrentActionInputPathReferenceImageUrl = (payload) => callPluginMethod("asset.currentActionInputPathReferenceImageUrl", payload);
-var callClipboardCopyText = (payload) => callPluginMethod("clipboard.copyText", payload);
-var callNavigationOpenUrl = (payload) => callPluginMethod("navigation.openUrl", payload);
-var callNavigationRevealInFinder = (payload) => callPluginMethod("navigation.revealInFinder", payload);
-var callNavigationOpenFilePath = (payload) => callPluginMethod("navigation.openFilePath", payload);
-var callActionSetButtons = (payload) => callPluginMethod("action.setButtons", payload);
-var callActionComplete = (payload) => callPluginMethod("action.complete", payload);
-var callAttachmentRendererSetButtons = (payload) => callPluginMethod("attachmentRenderer.setButtons", payload);
-var callWindowSetHeight = (payload) => callPluginMethod("window.setHeight", payload);
-var callWindowAutoFit = () => callPluginMethod("window.autoFit", {});
-var callInfoPanelOpen = (payload) => callPluginMethod("infoPanel.open", payload);
-var callInfoPanelClose = (payload) => callPluginMethod("infoPanel.close", payload);
-var callSettingsGet = (payload) => callPluginMethod("settings.get", payload);
-var callSettingsGetAll = () => callPluginMethod("settings.getAll", {});
-var callConsoleLog = (payload) => callPluginMethod("console.log", payload);
-var callTextInputStateChanged = (payload) => callPluginMethod("textInput.stateChanged", payload);
+// src/generated/hostEvents.generated.ts
+var HOST_EVENT_WINDOW_GLOBALS = {
+  "clipbus-plugin-context": "__CLIPBUS_PLUGIN_CONTEXT__",
+  "clipbus-plugin-item": "__CLIPBUS_PLUGIN_ITEM__",
+  "clipbus-plugin-attachment": "__CLIPBUS_PLUGIN_ATTACHMENT__",
+  "clipbus-plugin-draft": "__CLIPBUS_PLUGIN_DRAFT__",
+  "clipbus-plugin-action-input": "__CLIPBUS_PLUGIN_ACTION_INPUT__",
+  "clipbus-plugin-theme": "__CLIPBUS_PLUGIN_THEME__",
+  "clipbus-plugin-attachment-host-invoke": null,
+  "clipbus-plugin-action-host-invoke": null,
+  "clipbus-plugin-info-panel-on-action": null,
+  "clipbus-plugin-info-panel-on-close": null,
+  "clipbus-plugin-locale": "__CLIPBUS_PLUGIN_LOCALE__"
+};
 
 // src/internal/topic.ts
 function createTopic(initial) {
@@ -164,95 +149,36 @@ function readWindowGlobal(key) {
   return window[key];
 }
 
-// src/generated/topicSubscribers.generated.ts
-function onContext(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-context", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-context", handler);
-}
-function onItem(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-item", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-item", handler);
-}
-function onAttachment(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-attachment", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-attachment", handler);
-}
-function onDraft(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-draft", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-draft", handler);
-}
-function onActionInput(listener) {
+// src/internal/hostEvents.ts
+function onHostEvent(name, listener) {
   const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-action-input", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-action-input", handler);
+  globalThis.addEventListener(name, handler);
+  return () => globalThis.removeEventListener(name, handler);
 }
-function onTheme(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-theme", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-theme", handler);
-}
-function onAttachmentHostInvoke(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-attachment-host-invoke", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-attachment-host-invoke", handler);
-}
-function onActionHostInvoke(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-action-host-invoke", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-action-host-invoke", handler);
+function createHostTopic(name) {
+  const windowGlobal = HOST_EVENT_WINDOW_GLOBALS[name];
+  const topic = createTopic(
+    windowGlobal === null ? void 0 : readWindowGlobal(windowGlobal)
+  );
+  onHostEvent(name, (payload) => topic.set(payload));
+  return topic;
 }
-function onInfoPanelOnAction(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-info-panel-on-action", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-action", handler);
-}
-function onInfoPanelOnClose(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-info-panel-on-close", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-close", handler);
-}
-function onLocale(listener) {
-  const handler = (e) => listener(e.detail);
-  globalThis.addEventListener("clipbus-plugin-locale", handler);
-  return () => globalThis.removeEventListener("clipbus-plugin-locale", handler);
+function createHostStream(name) {
+  const stream = createStream();
+  onHostEvent(name, (payload) => stream.emit(payload));
+  return stream;
 }
 
-// src/generated/ui.bootstrap.generated.ts
-var _pluginContextTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_CONTEXT__"));
-onContext((p) => _pluginContextTopic.set(p));
-var _itemTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ITEM__"));
-onItem((p) => _itemTopic.set(p));
-var _itemAttachmentTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ATTACHMENT__"));
-onAttachment((p) => _itemAttachmentTopic.set(p));
-var _actionDraftTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_DRAFT__"));
-onDraft((p) => _actionDraftTopic.set(p));
-var _actionInputTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ACTION_INPUT__"));
-onActionInput((p) => _actionInputTopic.set(p));
-var _themeTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_THEME__"));
-onTheme((p) => _themeTopic.set(p));
-var _attachmentRendererOnHostInvokeStream = createStream();
-onAttachmentHostInvoke((p) => _attachmentRendererOnHostInvokeStream.emit(p));
-var _actionOnHostInvokeStream = createStream();
-onActionHostInvoke((p) => _actionOnHostInvokeStream.emit(p));
-var _infoPanelOnActionStream = createStream();
-onInfoPanelOnAction((p) => _infoPanelOnActionStream.emit(p));
-var _infoPanelOnCloseStream = createStream();
-onInfoPanelOnClose((p) => _infoPanelOnCloseStream.emit(p));
-var _localeTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_LOCALE__"));
-onLocale((p) => _localeTopic.set(p));
+// src/internal/pluginContext.ts
 var PluginContextError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "PluginContextError";
   }
 };
-function guardContext(expected, run) {
+function guardContext(contextTopic, expected, run) {
   return (...args) => {
-    const current = _pluginContextTopic.current()?.mode;
+    const current = contextTopic.current()?.mode;
     if (current !== expected) {
       throw new PluginContextError(
         `This verb is not available in the current plugin context (expected: ${expected}, got: ${current || "unknown"})`
@@ -263,90 +189,102 @@ function guardContext(expected, run) {
 }
 
 // src/generated/ui.clipbus.generated.ts
+var pluginContextTopic = createHostTopic("clipbus-plugin-context");
+var itemTopic = createHostTopic("clipbus-plugin-item");
+var itemAttachmentTopic = createHostTopic("clipbus-plugin-attachment");
+var actionDraftTopic = createHostTopic("clipbus-plugin-draft");
+var actionInputTopic = createHostTopic("clipbus-plugin-action-input");
+var themeTopic = createHostTopic("clipbus-plugin-theme");
+var attachmentRendererOnHostInvokeStream = createHostStream("clipbus-plugin-attachment-host-invoke");
+var actionOnHostInvokeStream = createHostStream("clipbus-plugin-action-host-invoke");
+var infoPanelOnActionStream = createHostStream("clipbus-plugin-info-panel-on-action");
+var infoPanelOnCloseStream = createHostStream("clipbus-plugin-info-panel-on-close");
+var localeTopic = createHostTopic("clipbus-plugin-locale");
 var clipbus = {
   capabilities: createCapabilitiesApi(() => readInjectedCapabilities(globalThis, CAPABILITIES_GLOBAL)),
   runtime: {
-    invoke: (payload) => callRuntimeInvokeStrict(payload)
+    invoke: (payload) => callRuntimeInvoke(payload)
   },
   item: {
-    current: () => _itemTopic.current(),
-    on: (fn) => _itemTopic.on(fn),
-    readAttachment: (payload) => callItemReadAttachment(payload),
+    current: itemTopic.current,
+    on: itemTopic.on,
+    readAttachment: (payload) => callPluginMethod("item.readAttachment", payload),
     attachment: {
-      current: () => _itemAttachmentTopic.current(),
-      on: (fn) => _itemAttachmentTopic.on(fn)
+      current: itemAttachmentTopic.current,
+      on: itemAttachmentTopic.on
     }
   },
   asset: {
-    currentItemImageUrl: () => callAssetCurrentItemImageUrl(),
-    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload),
-    currentActionInputImageUrl: guardContext("action", () => callAssetCurrentActionInputImageUrl()),
-    currentActionInputPathReferenceImageUrl: guardContext("action", (payload) => callAssetCurrentActionInputPathReferenceImageUrl(payload))
+    currentItemImageUrl: () => callPluginMethod("asset.currentItemImageUrl", {}),
+    pathReferenceImageUrl: (payload) => callPluginMethod("asset.pathReferenceImageUrl", payload),
+    currentActionInputImageUrl: guardContext(pluginContextTopic, "action", () => callPluginMethod("asset.currentActionInputImageUrl", {})),
+    currentActionInputPathReferenceImageUrl: guardContext(pluginContextTopic, "action", (payload) => callPluginMethod("asset.currentActionInputPathReferenceImageUrl", payload))
   },
   clipboard: {
-    copyText: (payload) => callClipboardCopyText(payload)
+    copyText: (payload) => callPluginMethod("clipboard.copyText", payload)
   },
   navigation: {
-    openUrl: (payload) => callNavigationOpenUrl(payload),
-    revealInFinder: (payload) => callNavigationRevealInFinder(payload),
-    openFilePath: (payload) => callNavigationOpenFilePath(payload)
+    openUrl: (payload) => callPluginMethod("navigation.openUrl", payload),
+    revealInFinder: (payload) => callPluginMethod("navigation.revealInFinder", payload),
+    openFilePath: (payload) => callPluginMethod("navigation.openFilePath", payload)
   },
   action: {
-    setButtons: guardContext("action", (payload) => callActionSetButtons(payload)),
-    complete: guardContext("action", (payload) => callActionComplete(payload)),
+    setButtons: guardContext(pluginContextTopic, "action", (payload) => callPluginMethod("action.setButtons", payload)),
+    complete: guardContext(pluginContextTopic, "action", (payload) => callPluginMethod("action.complete", payload)),
     draft: {
-      current: () => _actionDraftTopic.current(),
-      on: (fn) => _actionDraftTopic.on(fn)
+      current: actionDraftTopic.current,
+      on: actionDraftTopic.on
     },
     input: {
-      current: () => _actionInputTopic.current(),
-      on: (fn) => _actionInputTopic.on(fn)
+      current: actionInputTopic.current,
+      on: actionInputTopic.on
     },
     onHostInvoke: {
-      on: (fn) => _actionOnHostInvokeStream.on(fn)
+      on: actionOnHostInvokeStream.on
     }
   },
   attachmentRenderer: {
-    setButtons: guardContext("attachmentRenderer", (payload) => callAttachmentRendererSetButtons(payload)),
+    setButtons: guardContext(pluginContextTopic, "attachmentRenderer", (payload) => callPluginMethod("attachmentRenderer.setButtons", payload)),
     onHostInvoke: {
-      on: (fn) => _attachmentRendererOnHostInvokeStream.on(fn)
+      on: attachmentRendererOnHostInvokeStream.on
     }
   },
   window: {
-    setHeight: (payload) => callWindowSetHeight(payload),
-    autoFit: () => callWindowAutoFit()
+    setHeight: (payload) => callPluginMethod("window.setHeight", payload),
+    autoFit: () => callPluginMethod("window.autoFit", {})
   },
   infoPanel: {
-    open: (payload) => callInfoPanelOpen(payload),
-    close: (payload) => callInfoPanelClose(payload),
+    open: (payload) => callPluginMethod("infoPanel.open", payload),
+    close: (payload) => callPluginMethod("infoPanel.close", payload),
     onAction: {
-      on: (fn) => _infoPanelOnActionStream.on(fn)
+      on: infoPanelOnActionStream.on
     },
     onClose: {
-      on: (fn) => _infoPanelOnCloseStream.on(fn)
+      on: infoPanelOnCloseStream.on
     }
   },
   settings: {
-    get: (payload) => callSettingsGet(payload),
-    getAll: () => callSettingsGetAll()
+    get: (payload) => callPluginMethod("settings.get", payload),
+    getAll: () => callPluginMethod("settings.getAll", {})
   },
   console: {
-    log: (payload) => callConsoleLog(payload)
+    log: (payload) => callPluginMethod("console.log", payload),
+    diagnostic: (payload) => callPluginMethod("console.diagnostic", payload)
   },
   textInput: {
-    stateChanged: (payload) => callTextInputStateChanged(payload)
+    stateChanged: (payload) => callPluginMethod("textInput.stateChanged", payload)
   },
   pluginContext: {
-    current: () => _pluginContextTopic.current(),
-    on: (fn) => _pluginContextTopic.on(fn)
+    current: pluginContextTopic.current,
+    on: pluginContextTopic.on
   },
   theme: {
-    current: () => _themeTopic.current(),
-    on: (fn) => _themeTopic.on(fn)
+    current: themeTopic.current,
+    on: themeTopic.on
   },
   locale: {
-    current: () => _localeTopic.current(),
-    on: (fn) => _localeTopic.on(fn)
+    current: localeTopic.current,
+    on: localeTopic.on
   }
 };
 

package/dist/validate/index.d.cts

@@ -4,9 +4,10 @@
  * JavaScript mirror of the native PluginManifestValidator (Swift).
  * Authority: platform/macos/Sources/Services/Impl/Plugins/PluginManifestValidator.swift
  *
- * Parity: scripts/checks/check-plugin-manifest-validator-parity.sh enforces that
- *   MANIFEST_VALIDATION_CODES equals the Swift ValidationError case set, and that
- *   CANONICAL_ITEM_TYPES equals ClipboardItemType.swift enum case raw values.
+ * Parity: Swift, JavaScript and C# validator tests all consume
+ *   protocol/plugin/fixtures/manifest-validator-parity.v4.json; MANIFEST_VALIDATION_CODES
+ *   mirrors the Swift ValidationError case set and CANONICAL_ITEM_TYPES mirrors
+ *   ClipboardItemType.swift enum case raw values.
  *
  * Design difference from native: native throws on the first error (fail-fast); this
  * function collects ALL issues and returns them — better DX for development so that
@@ -32,7 +33,7 @@ export interface ValidateManifestOptions {
 }
 /**
  * All validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
- * Parity with native is enforced by scripts/checks/check-plugin-manifest-validator-parity.sh.
+ * Parity with native is proven by the shared manifest-validator-parity corpus.
  */
 export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "invalidPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedInputKinds", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedInputKind"];
 /**

package/dist/validate/index.d.ts

@@ -4,9 +4,10 @@
  * JavaScript mirror of the native PluginManifestValidator (Swift).
  * Authority: platform/macos/Sources/Services/Impl/Plugins/PluginManifestValidator.swift
  *
- * Parity: scripts/checks/check-plugin-manifest-validator-parity.sh enforces that
- *   MANIFEST_VALIDATION_CODES equals the Swift ValidationError case set, and that
- *   CANONICAL_ITEM_TYPES equals ClipboardItemType.swift enum case raw values.
+ * Parity: Swift, JavaScript and C# validator tests all consume
+ *   protocol/plugin/fixtures/manifest-validator-parity.v4.json; MANIFEST_VALIDATION_CODES
+ *   mirrors the Swift ValidationError case set and CANONICAL_ITEM_TYPES mirrors
+ *   ClipboardItemType.swift enum case raw values.
  *
  * Design difference from native: native throws on the first error (fail-fast); this
  * function collects ALL issues and returns them — better DX for development so that
@@ -32,7 +33,7 @@ export interface ValidateManifestOptions {
 }
 /**
  * All validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
- * Parity with native is enforced by scripts/checks/check-plugin-manifest-validator-parity.sh.
+ * Parity with native is proven by the shared manifest-validator-parity corpus.
  */
 export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "invalidPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedInputKinds", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedInputKind"];
 /**

package/docs/authoring.md

@@ -278,7 +278,7 @@ import { defineMessage } from '@clipbus/plugin-sdk/runtime';  // 或 /ui，类
 export const GenerateImage = defineMessage<{ prompt: string }, { imageTempPath: string }>('generate-image');
 
 // runtime/index.ts
-const { definePlugin, host } = require('@clipbus/plugin-sdk/runtime');
+const { definePlugin } = require('@clipbus/plugin-sdk/runtime');
 const fs = require('node:fs/promises');
 const { GenerateImage } = require('../shared/contracts');
 

package/docs/capability-detection.md

@@ -55,9 +55,9 @@ try {
 ### 调用前门控
 
 ```ts
-import type { PluginActionHandler } from '@clipbus/plugin-sdk/runtime';
+import type { PluginAutoRunActionHandler } from '@clipbus/plugin-sdk/runtime';
 
-const action: PluginActionHandler = {
+const action: PluginAutoRunActionHandler = {
   async runAutoAction(input, ctx) {
     if (ctx.host.capabilities.has('item.setTags')) {
       await ctx.host.item.setTags({ tags: ['processed'] });

package/docs/entry.md

@@ -8,7 +8,7 @@ SDK 暴露两个 subpath。每个入口导出的符号**完全由 codegen 生成
 
 ```ts
 // CommonJS（推荐与现行 bundler 配合）
-const { definePlugin, host, actionResult, defineMessage } = require('@clipbus/plugin-sdk/runtime');
+const { definePlugin, actionResult, defineMessage } = require('@clipbus/plugin-sdk/runtime');
 
 // ESM（types）
 import type { PluginAttachmentRendererHandler, PluginAutoRunActionHandler, PluginDetectorHandler } from '@clipbus/plugin-sdk/runtime';
@@ -16,11 +16,12 @@ import type { PluginAttachmentRendererHandler, PluginAutoRunActionHandler, Plugi
 
 入口导出：
 
-- `definePlugin` —— 注册 handler；本地校验 registry 形状
-- `host` —— 直接调宿主能力的单例（`host.<domain>.<verb>(payload)`）。**推荐写法**是从 handler 收到的 `ctx.host` 调用（同一个对象，但写在 handler 内更显式）。
+- `definePlugin` —— 注册 handler；本地校验 registry 形状。传入 `{ setup(context) { … } }` 时，`context` 是宿主提供的 `PluginRuntimeLaunchContext`（`plugin`、`host`、`supportedCapabilities`）
 - `actionResult` —— `runAutoAction` 的返回值构造器
 - `defineMessage` —— UI ↔ Runtime RPC 的类型契约
 
+宿主能力只能通过 handler 收到的 `ctx.host.<domain>.<verb>(payload)` 调用：`ctx` 与本次调用绑定，调用结束后失效。0.10.0 起不再导出 `host` 单例（它从未能在宿主中工作）；迁移方式是把 `host.x.y(...)` 改为 handler 内的 `ctx.host.x.y(...)`。
+
 ## UI 入口
 
 ```ts

package/docs/item-context.md

@@ -153,6 +153,7 @@ WebView 沙箱禁止 `file://`，且 SDK **从不**把真实文件路径暴露
 | `clipbus.asset.pathReferenceImageUrl({ index })` | UI | `{ index }` | `{ url?: string }` | 当前 item 第 `index` 个 `path_reference` 条目的图（越界 / 非图片文件 → `url` 缺失） |
 | `clipbus.asset.currentActionInputImageUrl()` | UI/action | `{}` | `{ url?: string }` | 当前 Action image 值，与原始 item type 无关 |
 | `clipbus.asset.currentActionInputPathReferenceImageUrl({ index })` | UI/action | `{ index }` | `{ url?: string }` | 当前 Action path_reference 中第 `index` 张图 |
+| `host.asset.allocateImageTempPath({ formatHint })` | runtime | `{ formatHint }` | `{ path: string }` | 为当前 session 分配生成图片的路径；随 owner 释放 |
 | `host.asset.registerImage({ path })` | runtime | `{ path }` | `{ url: string }` | 把 **Node 产出 / 已有**的本地图注册进当前 session，签发 URL |
 
 capability 完整签名见 [API.md](../API.md)。
@@ -196,8 +197,9 @@ const { GenerateImage } = require('../shared/contracts');
 module.exports = definePlugin({
   messageHandlers: Object.fromEntries([
     GenerateImage.handle(async (_req, ctx) => {
-      const tmpPath = await writeSomePng();                 // 你的产图逻辑，写到临时文件
-      const { url } = await ctx.host.asset.registerImage({ path: tmpPath });
+      const { path } = await ctx.host.asset.allocateImageTempPath({ formatHint: 'png' });
+      await writeSomePng(path);                              // Node 写入宿主分配的会话路径
+      const { url } = await ctx.host.asset.registerImage({ path });
       return { url };                                       // 只回传 URL，不回传字节
     }),
   ]),
@@ -209,7 +211,7 @@ const { url } = await GenerateImage.invoke({});
 imageUrl.value = url;   // <img :src="imageUrl">
 ```
 
-> **token 生命周期：** URL 绑定当前 session owner，invocation / WebView 释放时一并失效，且跨 owner 隔离——不要持久化或跨会话复用。
+> **路径与 token 生命周期：** 分配的文件及 URL 绑定当前 session owner，invocation / WebView 释放时一并失效，且跨 owner 隔离——不要持久化或跨会话复用。Windows 只接受该 owner 已分配的注册路径。
 > **何时用哪个：** renderer 显示原始 item 用 `currentItemImageUrl` /
 > `pathReferenceImageUrl`；Draft Action 显示当前级联值用
 > `currentActionInputImageUrl` / `currentActionInputPathReferenceImageUrl`；

package/docs/permissions.md

@@ -23,7 +23,7 @@
 | `setAttachment` | `host.item.setAttachments` |
 | `setSearchExtension` | `host.item.setSearchExtension` |
 
-**不受门控：** `host.clipboard.*`、`host.navigation.*`、`host.settings.*`（只读）、`host.console.log`、`host.action.allocateImageTempPath`、`host.action.materializeInputImagePath`、`host.action.allocateOutputFilePath`、`host.item.materializeImagePath`、`host.item.readAttachment`、所有 `clipbus.*` 中的 UI 专属 verb（`window.*`、`action.setButtons`、`action.complete`、`attachmentRenderer.setButtons` 等）。
+**不受门控：** `host.clipboard.*`、`host.navigation.*`、`host.settings.*`（只读）、`host.console.log`、`host.console.diagnostic`、`host.asset.allocateImageTempPath`、`host.asset.registerImage`、`host.action.allocateImageTempPath`、`host.action.materializeInputImagePath`、`host.action.allocateOutputFilePath`、`host.item.materializeImagePath`、`host.item.readAttachment`、所有 `clipbus.*` 中的 UI 专属 verb（`window.*`、`action.setButtons`、`action.complete`、`attachmentRenderer.setButtons` 等）。
 
 各 verb 的完整签名见 [API.md](../API.md)。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipbus/plugin-sdk",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "type": "module",
   "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
   "keywords": [
@@ -9,10 +9,10 @@
     "sdk"
   ],
   "license": "MIT",
+  "homepage": "https://github.com/scubers/clipbus-release/releases?q=%22Clipbus+Plugin+SDK%22&expanded=true",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/scubers/clipbus.git",
-    "directory": "packages/plugin-sdk"
+    "url": "git+https://github.com/scubers/clipbus-release.git"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -78,7 +78,8 @@
     "build": "node ./scripts/build.mjs",
     "pretest": "node ./scripts/build.mjs",
     "test": "node --require ./tests/setup.cjs --test",
-    "prepublishOnly": "npm run build && npm test"
+    "prepack": "node ./scripts/release-notes.mjs changelog",
+    "prepublishOnly": "npm run build && npm test && node ./scripts/release-notes.mjs check"
   },
   "files": [
     "dist",
@@ -86,6 +87,7 @@
     "SPECIFICATION.md",
     "README.md",
     "API.md",
+    "CHANGELOG.md",
     "docs"
   ],
   "publishConfig": {

package/dist/generated/INDEX.runtime.generated.d.ts

@@ -1,6 +0,0 @@
-export { host } from './runtime.host.generated.js';
-export { definePlugin } from './runtime.definePlugin.generated.js';
-export { actionResult } from './runtime.actionResult.generated.js';
-export type * from './data.generated.js';
-export type * from './capabilityClients.generated.js';
-export type * from './runtime.handlers.generated.js';

package/dist/generated/INDEX.ui.generated.d.ts

@@ -1,4 +0,0 @@
-export { clipbus } from './ui.clipbus.generated.js';
-export type * from './data.generated.js';
-export type * from './capabilityClients.generated.js';
-export { PluginContextError } from './ui.bootstrap.generated.js';