@clipbus/plugin-sdk 0.8.6 → 0.9.1

package/dist/preview/index.js

@@ -1330,6 +1330,10 @@ function emitActionBootstrap(p) {
     globalThis["__CLIPBUS_PLUGIN_DRAFT__"] = p.draft;
     globalThis.dispatchEvent(new CustomEvent("clipbus-plugin-draft", { detail: p.draft }));
   }
+  if (p.actionInput !== void 0) {
+    globalThis["__CLIPBUS_PLUGIN_ACTION_INPUT__"] = p.actionInput;
+    globalThis.dispatchEvent(new CustomEvent("clipbus-plugin-action-input", { detail: p.actionInput }));
+  }
   if (p.theme !== void 0) {
     globalThis["__CLIPBUS_PLUGIN_THEME__"] = p.theme;
     globalThis.dispatchEvent(new CustomEvent("clipbus-plugin-theme", { detail: p.theme }));
@@ -1367,6 +1371,7 @@ function computeWirePayloads(scenario, themeKey = DEFAULT_THEME_KEY) {
     context,
     item: scenario.item,
     draft: scenario.draft ?? {},
+    actionInput: scenario.actionInput,
     theme,
     locale
   };
@@ -1385,6 +1390,7 @@ function injectWire(_target, payloads) {
       context: payloads.context,
       item: payloads.item,
       draft: payloads.draft,
+      actionInput: payloads.actionInput,
       theme: payloads.theme,
       locale: payloads.locale
     });
@@ -1441,6 +1447,12 @@ function classifyWireSections(payloads) {
       defaultOpen: true,
       value: payloads.draft
     });
+    sections.push({
+      key: "actionInput",
+      kind: "content",
+      defaultOpen: true,
+      value: payloads.actionInput
+    });
   }
   sections.push({
     key: "theme",

package/dist/preview/inputPanel.d.ts

@@ -16,7 +16,7 @@ import type { WirePayloads } from './wire.js';
 export interface WireSection {
     /** The payload key name (e.g. 'context', 'item', 'attachment'). */
     key: string;
-    /** content = item + attachment/draft (user-facing data; open by default).
+    /** content = item + attachment/draft/actionInput (user-facing data; open by default).
      *  infra  = context + theme + locale (plumbing; collapsed by default).   */
     kind: 'content' | 'infra';
     /** Whether the section is expanded when first rendered. */
@@ -27,8 +27,8 @@ export interface WireSection {
 /**
  * Classify wire payload sections into display order with open/collapsed defaults.
  *
- * Fixed order: context · item · attachment(renderer)/draft(action) · theme · locale
- *   content: item + attachment/draft — defaultOpen true  (user compares these with output)
+ * Fixed order: context · item · attachment(renderer)/draft+actionInput(action) · theme · locale
+ *   content: item + attachment/draft/actionInput — defaultOpen true
  *   infra:   context + theme + locale — defaultOpen false (plumbing, low signal)
  */
 export declare function classifyWireSections(payloads: WirePayloads): WireSection[];

package/dist/preview/types.d.ts

@@ -1,4 +1,4 @@
-import type { PluginClipboardItem, PluginAttachmentPayload } from '../generated/data.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem } from '../generated/data.generated.js';
 export interface PreviewViewport {
     /** Initial viewport width (px). Defaults to the per-mode width when omitted. */
     width?: number;
@@ -27,6 +27,8 @@ export interface PreviewScenario {
     attachment?: PluginAttachmentPayload;
     /** Action mode draft payload. */
     draft?: Record<string, unknown>;
+    /** Sanitized current Action value; never include real filesystem paths. */
+    actionInput?: PluginActionUIInput;
     buttons?: {
         id: string;
         title: string;

package/dist/preview/wire.d.ts

@@ -1,6 +1,6 @@
 import type { PluginThemeTokenSnapshot } from '../generated/data.generated.js';
 import type { PluginContextPayload, PluginLocalePayload } from '../generated/hostBootstrap.generated.js';
-import type { PluginClipboardItem, PluginAttachmentPayload } from '../generated/data.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem } from '../generated/data.generated.js';
 import type { PreviewScenario } from './types.js';
 /**
  * Backward-compat alias. Now accepts any preset key string ('graphite', 'ember',
@@ -13,6 +13,7 @@ export interface WirePayloads {
     item: PluginClipboardItem;
     attachment?: PluginAttachmentPayload;
     draft?: Record<string, unknown>;
+    actionInput?: PluginActionUIInput;
     theme: PluginThemeTokenSnapshot;
     locale: PluginLocalePayload;
 }

package/dist/runtime/index.cjs

@@ -79,7 +79,9 @@ var host = {
     openFilePath: (payload) => ipcBus.request("navigation.openFilePath", payload)
   },
   action: {
-    allocateImageTempPath: (payload) => ipcBus.request("action.allocateImageTempPath", payload)
+    allocateImageTempPath: (payload) => ipcBus.request("action.allocateImageTempPath", payload),
+    materializeInputImagePath: () => ipcBus.request("action.materializeInputImagePath", {}),
+    allocateOutputFilePath: (payload) => ipcBus.request("action.allocateOutputFilePath", payload)
   },
   settings: {
     get: (payload) => ipcBus.request("settings.get", payload),
@@ -132,6 +134,10 @@ var actionResult = {
     result: { resultKind: "image", imageTempPath, ...options && "imageFormatHint" in options ? { imageFormatHint: options.imageFormatHint } : {} },
     userMessage: options?.userMessage
   }),
+  path_reference: (entries, options) => ({
+    result: { resultKind: "path_reference", entries },
+    userMessage: options?.userMessage
+  }),
   none: (options) => ({
     result: { resultKind: "none" },
     userMessage: options?.userMessage

package/dist/runtime/index.js

@@ -49,7 +49,9 @@ var host = {
     openFilePath: (payload) => ipcBus.request("navigation.openFilePath", payload)
   },
   action: {
-    allocateImageTempPath: (payload) => ipcBus.request("action.allocateImageTempPath", payload)
+    allocateImageTempPath: (payload) => ipcBus.request("action.allocateImageTempPath", payload),
+    materializeInputImagePath: () => ipcBus.request("action.materializeInputImagePath", {}),
+    allocateOutputFilePath: (payload) => ipcBus.request("action.allocateOutputFilePath", payload)
   },
   settings: {
     get: (payload) => ipcBus.request("settings.get", payload),
@@ -102,6 +104,10 @@ var actionResult = {
     result: { resultKind: "image", imageTempPath, ...options && "imageFormatHint" in options ? { imageFormatHint: options.imageFormatHint } : {} },
     userMessage: options?.userMessage
   }),
+  path_reference: (entries, options) => ({
+    result: { resultKind: "path_reference", entries },
+    userMessage: options?.userMessage
+  }),
   none: (options) => ({
     result: { resultKind: "none" },
     userMessage: options?.userMessage

package/dist/ui/index.cjs

@@ -132,6 +132,8 @@ async function callPluginMethod(method, payload) {
 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);
@@ -212,6 +214,11 @@ function onDraft(listener) {
   globalThis.addEventListener("clipbus-plugin-draft", handler);
   return () => globalThis.removeEventListener("clipbus-plugin-draft", handler);
 }
+function onActionInput(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-action-input", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-action-input", handler);
+}
 function onTheme(listener) {
   const handler = (e) => listener(e.detail);
   globalThis.addEventListener("clipbus-plugin-theme", handler);
@@ -252,6 +259,8 @@ var _itemAttachmentTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ATTACH
 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();
@@ -299,7 +308,9 @@ var clipbus = {
   },
   asset: {
     currentItemImageUrl: () => callAssetCurrentItemImageUrl(),
-    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload)
+    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload),
+    currentActionInputImageUrl: guardContext("action", () => callAssetCurrentActionInputImageUrl()),
+    currentActionInputPathReferenceImageUrl: guardContext("action", (payload) => callAssetCurrentActionInputPathReferenceImageUrl(payload))
   },
   clipboard: {
     copyText: (payload) => callClipboardCopyText(payload)
@@ -316,6 +327,10 @@ var clipbus = {
       current: () => _actionDraftTopic.current(),
       on: (fn) => _actionDraftTopic.on(fn)
     },
+    input: {
+      current: () => _actionInputTopic.current(),
+      on: (fn) => _actionInputTopic.on(fn)
+    },
     onHostInvoke: {
       on: (fn) => _actionOnHostInvokeStream.on(fn)
     }

package/dist/ui/index.js

@@ -103,6 +103,8 @@ async function callPluginMethod(method, payload) {
 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);
@@ -183,6 +185,11 @@ function onDraft(listener) {
   globalThis.addEventListener("clipbus-plugin-draft", handler);
   return () => globalThis.removeEventListener("clipbus-plugin-draft", handler);
 }
+function onActionInput(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-action-input", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-action-input", handler);
+}
 function onTheme(listener) {
   const handler = (e) => listener(e.detail);
   globalThis.addEventListener("clipbus-plugin-theme", handler);
@@ -223,6 +230,8 @@ var _itemAttachmentTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_ATTACH
 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();
@@ -270,7 +279,9 @@ var clipbus = {
   },
   asset: {
     currentItemImageUrl: () => callAssetCurrentItemImageUrl(),
-    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload)
+    pathReferenceImageUrl: (payload) => callAssetPathReferenceImageUrl(payload),
+    currentActionInputImageUrl: guardContext("action", () => callAssetCurrentActionInputImageUrl()),
+    currentActionInputPathReferenceImageUrl: guardContext("action", (payload) => callAssetCurrentActionInputPathReferenceImageUrl(payload))
   },
   clipboard: {
     copyText: (payload) => callClipboardCopyText(payload)
@@ -287,6 +298,10 @@ var clipbus = {
       current: () => _actionDraftTopic.current(),
       on: (fn) => _actionDraftTopic.on(fn)
     },
+    input: {
+      current: () => _actionInputTopic.current(),
+      on: (fn) => _actionInputTopic.on(fn)
+    },
     onHostInvoke: {
       on: (fn) => _actionOnHostInvokeStream.on(fn)
     }

package/dist/validate/index.cjs

@@ -46,6 +46,7 @@ var MANIFEST_VALIDATION_CODES = [
   "duplicateDetectorID",
   "duplicateActionID",
   "emptyPluginID",
+  "invalidPluginID",
   "emptyPluginTitle",
   "installEntryMissing",
   "installEntryOutsideRoot",
@@ -58,11 +59,11 @@ var MANIFEST_VALIDATION_CODES = [
   "detectorAttachmentTypeOutsideNamespace",
   "rendererUIEntryMissing",
   "rendererUIEntryOutsideRoot",
-  "actionMissingSupportedItemTypes",
+  "actionMissingSupportedInputKinds",
   "actionUIEntryMissing",
   "actionUIEntryOutsideRoot",
   "detectorInvalidSupportedInputKind",
-  "actionInvalidSupportedItemType"
+  "actionInvalidSupportedInputKind"
 ];
 var CANONICAL_ITEM_TYPES = ["text", "image", "path_reference"];
 function asRecord(val) {
@@ -89,25 +90,41 @@ function isInsideRoot(entryRelative, rootAbsolute) {
   const resolvedEntry = import_node_path.default.resolve(rootAbsolute, entryRelative);
   return resolvedEntry === rootAbsolute || resolvedEntry.startsWith(rootAbsolute + import_node_path.default.sep);
 }
+var PLUGIN_ID_MAX_LENGTH = 128;
+var PLUGIN_ID_PATTERN = /^[a-z0-9._-]+$/;
+function isValidPluginID(id) {
+  if (id.length === 0 || id.length > PLUGIN_ID_MAX_LENGTH) return false;
+  if (id.startsWith(".") || id.includes("..")) return false;
+  return PLUGIN_ID_PATTERN.test(id);
+}
 function validateSchemaVersion(raw, issues) {
   const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
-  if (version !== 2) {
+  if (version !== 3) {
     issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
   }
 }
 var LEGACY_RENDERER_FIELDS = ["displayName", "defaultEnabled", "defaultOrderKey", "actions"];
 var LEGACY_DETECTOR_FIELDS = ["displayName", "capabilityID", "defaultEnabled", "timeoutMs"];
-var LEGACY_ACTION_FIELDS = ["displayName", "actionID", "defaultEnabled", "defaultOrderKey", "revealButtons"];
+var LEGACY_ACTION_FIELDS = [
+  "displayName",
+  "actionID",
+  "defaultEnabled",
+  "defaultOrderKey",
+  "revealButtons",
+  "supportedItemTypes",
+  "inputConstraints",
+  "possibleResultKinds"
+];
 function validateLegacyFields(raw, issues) {
   const plugin = asRecord(raw["plugin"]);
   if (plugin && "displayName" in plugin) {
-    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: plugin.displayName`));
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: plugin.displayName`));
   }
   const renderers = asRecordArray(raw["attachmentRenderers"]);
   for (let i = 0; i < renderers.length; i++) {
     for (const field of LEGACY_RENDERER_FIELDS) {
       if (field in renderers[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: attachmentRenderers[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: attachmentRenderers[${i}].${field}`));
       }
     }
   }
@@ -115,7 +132,7 @@ function validateLegacyFields(raw, issues) {
   for (let i = 0; i < detectors.length; i++) {
     for (const field of LEGACY_DETECTOR_FIELDS) {
       if (field in detectors[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: detectors[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: detectors[${i}].${field}`));
       }
     }
   }
@@ -123,7 +140,7 @@ function validateLegacyFields(raw, issues) {
   for (let i = 0; i < actions.length; i++) {
     for (const field of LEGACY_ACTION_FIELDS) {
       if (field in actions[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: actions[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: actions[${i}].${field}`));
       }
     }
   }
@@ -139,9 +156,9 @@ function validateCanonicalItemTypeSpellings(raw, issues) {
   }
   for (const action of asRecordArray(raw["actions"])) {
     const actionID = asString(action["id"]) ?? "";
-    for (const value of asStringArray(action["supportedItemTypes"])) {
+    for (const value of asStringArray(action["supportedInputKinds"])) {
       if (!CANONICAL_ITEM_TYPES.includes(value)) {
-        issues.push(issue("actionInvalidSupportedItemType", `Action supported item types contain unsupported value: ${actionID} -> ${value}`));
+        issues.push(issue("actionInvalidSupportedInputKind", `Action supported input kinds contain unsupported value: ${actionID} -> ${value}`));
       }
     }
   }
@@ -190,9 +207,9 @@ function validateActions(actions, issues) {
     if (title.trim().length === 0) {
       issues.push(issue("actionTitleEmpty", `Action title is empty: ${id}`));
     }
-    const supportedItemTypes = asStringArray(action["supportedItemTypes"]);
-    if (supportedItemTypes.length === 0) {
-      issues.push(issue("actionMissingSupportedItemTypes", `Action is missing supported item types: ${id}`));
+    const supportedInputKinds = asStringArray(action["supportedInputKinds"]);
+    if (supportedInputKinds.length === 0) {
+      issues.push(issue("actionMissingSupportedInputKinds", `Action is missing supported input kinds: ${id}`));
     }
   }
 }
@@ -240,6 +257,8 @@ function validateManifest(manifest, options = {}) {
   const pluginTitle = asString(plugin["title"]) ?? "";
   if (pluginID.trim().length === 0) {
     issues.push(issue("emptyPluginID", "Plugin id is empty"));
+  } else if (!isValidPluginID(pluginID)) {
+    issues.push(issue("invalidPluginID", `Invalid plugin id: ${pluginID}`));
   }
   if (pluginTitle.trim().length === 0) {
     issues.push(issue("emptyPluginTitle", "Plugin title is empty"));

package/dist/validate/index.d.cts

@@ -31,10 +31,10 @@ export interface ValidateManifestOptions {
     rootDir?: string;
 }
 /**
- * All 26 validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
+ * 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.
  */
-export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedItemTypes", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedItemType"];
+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"];
 /**
  * Validate a parsed manifest JSON object against the Clipbus plugin manifest rules.
  *

package/dist/validate/index.d.ts

@@ -31,10 +31,10 @@ export interface ValidateManifestOptions {
     rootDir?: string;
 }
 /**
- * All 26 validation error codes, verbatim camelCase mirror of Swift ValidationError cases.
+ * 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.
  */
-export declare const MANIFEST_VALIDATION_CODES: readonly ["unsupportedSchemaVersion", "missingManifest", "missingRuntimeEntry", "missingUIRoot", "legacyFieldNotSupported", "duplicateAttachmentRendererID", "duplicateDetectorID", "duplicateActionID", "emptyPluginID", "emptyPluginTitle", "installEntryMissing", "installEntryOutsideRoot", "rendererTitleEmpty", "detectorTitleEmpty", "actionTitleEmpty", "detectorMissingSupportedInputKinds", "detectorAttachmentTypesEmpty", "detectorAttachmentTypeNotRenderable", "detectorAttachmentTypeOutsideNamespace", "rendererUIEntryMissing", "rendererUIEntryOutsideRoot", "actionMissingSupportedItemTypes", "actionUIEntryMissing", "actionUIEntryOutsideRoot", "detectorInvalidSupportedInputKind", "actionInvalidSupportedItemType"];
+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"];
 /**
  * Validate a parsed manifest JSON object against the Clipbus plugin manifest rules.
  *

package/dist/validate/index.js

@@ -11,6 +11,7 @@ var MANIFEST_VALIDATION_CODES = [
   "duplicateDetectorID",
   "duplicateActionID",
   "emptyPluginID",
+  "invalidPluginID",
   "emptyPluginTitle",
   "installEntryMissing",
   "installEntryOutsideRoot",
@@ -23,11 +24,11 @@ var MANIFEST_VALIDATION_CODES = [
   "detectorAttachmentTypeOutsideNamespace",
   "rendererUIEntryMissing",
   "rendererUIEntryOutsideRoot",
-  "actionMissingSupportedItemTypes",
+  "actionMissingSupportedInputKinds",
   "actionUIEntryMissing",
   "actionUIEntryOutsideRoot",
   "detectorInvalidSupportedInputKind",
-  "actionInvalidSupportedItemType"
+  "actionInvalidSupportedInputKind"
 ];
 var CANONICAL_ITEM_TYPES = ["text", "image", "path_reference"];
 function asRecord(val) {
@@ -54,25 +55,41 @@ function isInsideRoot(entryRelative, rootAbsolute) {
   const resolvedEntry = path.resolve(rootAbsolute, entryRelative);
   return resolvedEntry === rootAbsolute || resolvedEntry.startsWith(rootAbsolute + path.sep);
 }
+var PLUGIN_ID_MAX_LENGTH = 128;
+var PLUGIN_ID_PATTERN = /^[a-z0-9._-]+$/;
+function isValidPluginID(id) {
+  if (id.length === 0 || id.length > PLUGIN_ID_MAX_LENGTH) return false;
+  if (id.startsWith(".") || id.includes("..")) return false;
+  return PLUGIN_ID_PATTERN.test(id);
+}
 function validateSchemaVersion(raw, issues) {
   const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
-  if (version !== 2) {
+  if (version !== 3) {
     issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
   }
 }
 var LEGACY_RENDERER_FIELDS = ["displayName", "defaultEnabled", "defaultOrderKey", "actions"];
 var LEGACY_DETECTOR_FIELDS = ["displayName", "capabilityID", "defaultEnabled", "timeoutMs"];
-var LEGACY_ACTION_FIELDS = ["displayName", "actionID", "defaultEnabled", "defaultOrderKey", "revealButtons"];
+var LEGACY_ACTION_FIELDS = [
+  "displayName",
+  "actionID",
+  "defaultEnabled",
+  "defaultOrderKey",
+  "revealButtons",
+  "supportedItemTypes",
+  "inputConstraints",
+  "possibleResultKinds"
+];
 function validateLegacyFields(raw, issues) {
   const plugin = asRecord(raw["plugin"]);
   if (plugin && "displayName" in plugin) {
-    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: plugin.displayName`));
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: plugin.displayName`));
   }
   const renderers = asRecordArray(raw["attachmentRenderers"]);
   for (let i = 0; i < renderers.length; i++) {
     for (const field of LEGACY_RENDERER_FIELDS) {
       if (field in renderers[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: attachmentRenderers[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: attachmentRenderers[${i}].${field}`));
       }
     }
   }
@@ -80,7 +97,7 @@ function validateLegacyFields(raw, issues) {
   for (let i = 0; i < detectors.length; i++) {
     for (const field of LEGACY_DETECTOR_FIELDS) {
       if (field in detectors[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: detectors[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: detectors[${i}].${field}`));
       }
     }
   }
@@ -88,7 +105,7 @@ function validateLegacyFields(raw, issues) {
   for (let i = 0; i < actions.length; i++) {
     for (const field of LEGACY_ACTION_FIELDS) {
       if (field in actions[i]) {
-        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v2: actions[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v3: actions[${i}].${field}`));
       }
     }
   }
@@ -104,9 +121,9 @@ function validateCanonicalItemTypeSpellings(raw, issues) {
   }
   for (const action of asRecordArray(raw["actions"])) {
     const actionID = asString(action["id"]) ?? "";
-    for (const value of asStringArray(action["supportedItemTypes"])) {
+    for (const value of asStringArray(action["supportedInputKinds"])) {
       if (!CANONICAL_ITEM_TYPES.includes(value)) {
-        issues.push(issue("actionInvalidSupportedItemType", `Action supported item types contain unsupported value: ${actionID} -> ${value}`));
+        issues.push(issue("actionInvalidSupportedInputKind", `Action supported input kinds contain unsupported value: ${actionID} -> ${value}`));
       }
     }
   }
@@ -155,9 +172,9 @@ function validateActions(actions, issues) {
     if (title.trim().length === 0) {
       issues.push(issue("actionTitleEmpty", `Action title is empty: ${id}`));
     }
-    const supportedItemTypes = asStringArray(action["supportedItemTypes"]);
-    if (supportedItemTypes.length === 0) {
-      issues.push(issue("actionMissingSupportedItemTypes", `Action is missing supported item types: ${id}`));
+    const supportedInputKinds = asStringArray(action["supportedInputKinds"]);
+    if (supportedInputKinds.length === 0) {
+      issues.push(issue("actionMissingSupportedInputKinds", `Action is missing supported input kinds: ${id}`));
     }
   }
 }
@@ -205,6 +222,8 @@ function validateManifest(manifest, options = {}) {
   const pluginTitle = asString(plugin["title"]) ?? "";
   if (pluginID.trim().length === 0) {
     issues.push(issue("emptyPluginID", "Plugin id is empty"));
+  } else if (!isValidPluginID(pluginID)) {
+    issues.push(issue("invalidPluginID", `Invalid plugin id: ${pluginID}`));
   }
   if (pluginTitle.trim().length === 0) {
     issues.push(issue("emptyPluginTitle", "Plugin title is empty"));

package/docs/authoring.md

@@ -156,9 +156,9 @@ UI 端完整 topic/verb 列表见 [API.md](../API.md)。
 ### resolveSession 入参
 
 ```ts
-input.item                    // PluginClipboardItem
+input.sourceItem              // 原始 PluginClipboardItem 身份
 input.content                 // PluginContentEnvelope
-input.attachments             // PluginAttachmentRef[]
+input.attachments             // SDK 0.9.0 中 Action 当前固定为 []
 ```
 
 ### resolveSession 返回值
@@ -179,11 +179,16 @@ return {
 ### runAutoAction 入参
 
 ```ts
-input.item                    // PluginClipboardItem
+input.sourceItem              // 原始 PluginClipboardItem 身份
 input.content                 // PluginContentEnvelope
-input.attachments             // PluginAttachmentRef[]
+input.attachments             // SDK 0.9.0 中 Action 当前固定为 []
 ```
 
+`sourceItem` 始终指向打开 Action Panel 时的原始 item；`content` 是当前
+级联值，可能已经从 text 变成 image 或 path_reference。Action 的适用性
+和处理逻辑必须以 `content.kind` 为准，item mutation 仍作用于
+`sourceItem.id`。
+
 ### runAutoAction 返回值（用 `actionResult`）
 
 ```ts
@@ -196,6 +201,12 @@ actionResult.text('hello world', { userMessage: 'Copied' });
 // image 结果（注意：第一个参数是 imageTempPath 字符串，不是对象）
 actionResult.image(imageTempPath, { imageFormatHint: 'png', userMessage: 'Saved' });
 
+// path_reference：复用当前输入，或返回 host 分配的文件
+actionResult.path_reference([
+  { source: 'input', inputIndex: 0 },
+  { source: 'allocated_file', path: outputPath, displayName: 'result.txt' },
+]);
+
 // 仅副作用，无输出
 actionResult.none({ userMessage: 'Applied' });
 ```
@@ -205,6 +216,7 @@ actionResult.none({ userMessage: 'Applied' });
 ```ts
 actionResult.text(text: string, options?: { userMessage?: string })
 actionResult.image(imageTempPath: string, options?: { imageFormatHint?: string; userMessage?: string })
+actionResult.path_reference(entries: PluginActionPathResultEntry[], options?: { userMessage?: string })
 actionResult.none(options?: { userMessage?: string })
 ```
 
@@ -221,6 +233,9 @@ interface MyDraft { subject: string; note: string; }
 const initial = clipbus.action.draft.current() as MyDraft | undefined;
 const form = reactive({ subject: initial?.subject ?? '', note: initial?.note ?? '' });
 
+// 当前级联输入；path_reference 只含 kind/displayName，不暴露 path
+const currentInput = clipbus.action.input.current();
+
 // 订阅 host 推送的后续更新（罕见；通常 initialDraft 之后就由 UI 接管）
 clipbus.action.draft.on(next => {
   Object.assign(form, next);
@@ -247,6 +262,9 @@ async function handleApply() {
 }
 ```
 
+Draft 完成后宿主展示结果供复制或关闭，但不会把结果移交到下一个 Action；
+只有 auto-run Action 的非 `none` 成功结果可以继续级联。
+
 ### Draft Action：UI 需要 runtime 协助时
 
 `clipbus.action.complete` 接收 `{result: {resultKind: 'text' | 'image' | 'none', …}}`。**image 结果的 `imageTempPath` 必须由 runtime 端通过 `host.action.allocateImageTempPath` 分配**（UI 端没有这个能力），所以图片类 draft 的典型流程是：
@@ -285,4 +303,16 @@ async function handleApplyImage(prompt: string) {
 
 > **不要**尝试通过 `runtime.invoke` 把图片字节传回 UI。postMessage 经 base64 + JSON 双重序列化，几 MB 图片就会卡顿数百 ms。让 runtime 直接写文件、只把路径返回给 UI。
 
+### Action 当前图片与安全文件结果
+
+读取当前 Action 图片使用 `ctx.host.action.materializeInputImagePath()`，不要
+用 `ctx.host.item.materializeImagePath()`：后者读取原始 item 图片，而级联
+后的当前值可能来自上一步 Action。
+
+普通文件结果必须先调用
+`ctx.host.action.allocateOutputFilePath({suggestedName})`，写入返回路径，再
+通过 `{source: 'allocated_file', path, displayName}` 返回。若只是保留当前
+path_reference 的某一项，使用 `{source: 'input', inputIndex}`。任意绝对
+路径不会被宿主接受。
+
 RPC 机制（`defineMessage` / `messageHandlers`）的完整说明见 [rpc.md](./rpc.md)。入参结构（`PluginContentEnvelope`、`PluginClipboardItem`）详见 [item-context.md](./item-context.md)。

package/docs/capability-detection.md

@@ -60,7 +60,7 @@ import type { PluginActionHandler } from '@clipbus/plugin-sdk/runtime';
 const action: PluginActionHandler = {
   async runAutoAction(input, ctx) {
     if (ctx.host.capabilities.has('item.setTags')) {
-      await ctx.host.item.setTags({ itemID: input.item.id, tags: ['processed'] });
+      await ctx.host.item.setTags({ tags: ['processed'] });
     }
     // 不支持时跳过，不报错
   },
@@ -73,7 +73,7 @@ Node 侧错误来自**跨进程 IPC**，抛出的是反序列化的普通对象
 
 ```ts
 try {
-  await ctx.host.item.setTags({ itemID: input.item.id, tags: ['processed'] });
+  await ctx.host.item.setTags({ tags: ['processed'] });
 } catch (err: unknown) {
   const e = err as { name?: string; data?: { capability?: string } };
   if (e.name === 'PluginCapabilityUnsupported') {

package/docs/entry.md

@@ -34,10 +34,10 @@ import { PluginContextError } from '@clipbus/plugin-sdk/ui';
 | Namespace | 形态 | 说明 |
 |---|---|---|
 | `clipbus.item` | Topic | `current()`, `on()`, `readAttachment()`，子 OptionalTopic `clipbus.item.attachment` |
-| `clipbus.asset` | Verb | `currentItemImageUrl()`、`pathReferenceImageUrl({index})` —— 按身份取本地图片的 `clipbus-asset://` URL 供 WebView `<img>` 渲染（真实路径不出宿主）；Node 产图经 `host.asset.registerImage({path})` |
+| `clipbus.asset` | Verb | renderer 使用 `currentItemImageUrl()` / `pathReferenceImageUrl({index})`；Action 使用 `currentActionInputImageUrl()` / `currentActionInputPathReferenceImageUrl({index})`。均返回不透明 `clipbus-asset://` URL |
 | `clipbus.theme` | Topic | `current()`, `on()` |
 | `clipbus.pluginContext` | Topic | `current()`, `on()`，返回 `{mode, pluginID}` |
-| `clipbus.action` | Verb + OptionalTopic | action 上下文专属；`setButtons`、`complete`、`draft`、`onHostInvoke` |
+| `clipbus.action` | Verb + Topic | action 上下文专属；`setButtons`、`complete`、`draft`、`input`、`onHostInvoke` |
 | `clipbus.attachmentRenderer` | Verb + Stream | attachment 上下文专属；`setButtons`、`onHostInvoke` |
 | `clipbus.window` | Verb | `setHeight`, `autoFit` |
 | `clipbus.clipboard` | Verb | `copyText` |