@clipbus/plugin-sdk 0.8.7 → 0.9.1

package/API.md

@@ -9,10 +9,10 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 
 ## 1. Overview
 
-- **Capabilities**: 29
-- **Host events**: 10
+- **Capabilities**: 33
+- **Host events**: 11
 - **Node IPC methods**: 6
-- **Named types**: 28
+- **Named types**: 31
 
 ## 2. Capabilities
 
@@ -26,6 +26,22 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Payload**: { formatHint: `string` }
 - **Response**: { path: `string` }
 
+#### `action.materializeInputImagePath`
+
+- **Side**: runtime
+- **Context**: action
+- **Path**: `action.materializeInputImagePath`
+- **Payload**: {  }
+- **Response**: { path: `string` }
+
+#### `action.allocateOutputFilePath`
+
+- **Side**: runtime
+- **Context**: action
+- **Path**: `action.allocateOutputFilePath`
+- **Payload**: { suggestedName?: `string` }
+- **Response**: { path: `string` }
+
 #### `action.setButtons`
 
 - **Side**: ui
@@ -60,6 +76,22 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Payload**: { index: `int` }
 - **Response**: { url?: `string` }
 
+#### `asset.currentActionInputImageUrl`
+
+- **Side**: ui
+- **Context**: action
+- **Path**: `asset.currentActionInputImageUrl`
+- **Payload**: {  }
+- **Response**: { url?: `string` }
+
+#### `asset.currentActionInputPathReferenceImageUrl`
+
+- **Side**: ui
+- **Context**: action
+- **Path**: `asset.currentActionInputPathReferenceImageUrl`
+- **Payload**: { index: `int` }
+- **Response**: { url?: `string` }
+
 #### `asset.registerImage`
 
 - **Side**: runtime
@@ -289,12 +321,16 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | `item.readAttachment` | `clipbus.item.readAttachment` | `host.item.readAttachment` | any |
 | `asset.currentItemImageUrl` | `clipbus.asset.currentItemImageUrl` | — | any |
 | `asset.pathReferenceImageUrl` | `clipbus.asset.pathReferenceImageUrl` | — | any |
+| `asset.currentActionInputImageUrl` | `clipbus.asset.currentActionInputImageUrl` | — | action |
+| `asset.currentActionInputPathReferenceImageUrl` | `clipbus.asset.currentActionInputPathReferenceImageUrl` | — | action |
 | `asset.registerImage` | — | `host.asset.registerImage` | any |
 | `clipboard.copyText` | `clipbus.clipboard.copyText` | `host.clipboard.copyText` | any |
 | `navigation.openUrl` | `clipbus.navigation.openUrl` | `host.navigation.openUrl` | any |
 | `navigation.revealInFinder` | `clipbus.navigation.revealInFinder` | `host.navigation.revealInFinder` | any |
 | `navigation.openFilePath` | `clipbus.navigation.openFilePath` | `host.navigation.openFilePath` | any |
 | `action.allocateImageTempPath` | — | `host.action.allocateImageTempPath` | action |
+| `action.materializeInputImagePath` | — | `host.action.materializeInputImagePath` | action |
+| `action.allocateOutputFilePath` | — | `host.action.allocateOutputFilePath` | action |
 | `action.setButtons` | `clipbus.action.setButtons` | — | action |
 | `action.complete` | `clipbus.action.complete` | — | action |
 | `attachmentRenderer.setButtons` | `clipbus.attachmentRenderer.setButtons` | — | attachmentRenderer |
@@ -342,6 +378,14 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Context**: action
 - **Payload**: record<`json`>
 
+### `clipbus-plugin-action-input`
+
+- **Window global**: `__CLIPBUS_PLUGIN_ACTION_INPUT__`
+- **Topic**: `action.input`
+- **Shape**: topic
+- **Context**: action
+- **Payload**: [`PluginActionUIInput`](#pluginactionuiinput)
+
 ### `clipbus-plugin-theme`
 
 - **Window global**: `__CLIPBUS_PLUGIN_THEME__`
@@ -394,6 +438,7 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | `clipbus-plugin-item` | item | topic | `__CLIPBUS_PLUGIN_ITEM__` | any |
 | `clipbus-plugin-attachment` | item.attachment | topic | `__CLIPBUS_PLUGIN_ATTACHMENT__` | attachmentRenderer |
 | `clipbus-plugin-draft` | action.draft | topic | `__CLIPBUS_PLUGIN_DRAFT__` | action |
+| `clipbus-plugin-action-input` | action.input | topic | `__CLIPBUS_PLUGIN_ACTION_INPUT__` | action |
 | `clipbus-plugin-theme` | theme | topic | `__CLIPBUS_PLUGIN_THEME__` | any |
 | `clipbus-plugin-attachment-host-invoke` | attachmentRenderer.onHostInvoke | stream | — | attachmentRenderer |
 | `clipbus-plugin-action-host-invoke` | action.onHostInvoke | stream | — | action |
@@ -471,9 +516,13 @@ export interface PluginRegistry {
 - `label?`: `string`
 - `updatedAtMs?`: `int`
 
+### `PluginActionPathResultEntry`
+
+Discriminated union on `source`: { source: `'input'`, inputIndex: `int` } | { source: `'allocated_file'`, path: `string`, displayName: `string` }
+
 ### `PluginActionResult`
 
-Discriminated union on `resultKind`: { resultKind: `'text'`, text: `string` } | { resultKind: `'image'`, imageTempPath: `string`, imageFormatHint?: `string` } | { resultKind: `'none'` }
+Discriminated union on `resultKind`: { resultKind: `'text'`, text: `string` } | { resultKind: `'image'`, imageTempPath: `string`, imageFormatHint?: `string` } | { resultKind: `'path_reference'`, entries: [`PluginActionPathResultEntry`](#pluginactionpathresultentry)[] } | { resultKind: `'none'` }
 
 ### `PluginInfoPanelTextStyle`
 
@@ -532,6 +581,15 @@ Union: `'debug'` | `'info'` | `'warn'` | `'error'`
 - `item`: [`PluginClipboardItem`](#pluginclipboarditem)
 - `attachment`: [`PluginAttachmentEntry`](#pluginattachmententry)
 
+### `PluginActionUIPathEntry`
+
+- `kind`: `'file'` \| `'folder'`
+- `displayName`: `string`
+
+### `PluginActionUIInput`
+
+Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'image'`, width: `int`, height: `int`, format: `string`, bytes: `int` } | { kind: `'path_reference'`, entries: [`PluginActionUIPathEntry`](#pluginactionuipathentry)[] }
+
 ### `PluginThemeTokens`
 
 - `surface`: `string`
@@ -611,7 +669,7 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 
 ### `PluginResolveActionSessionInput`
 
-- `item`: [`PluginClipboardItem`](#pluginclipboarditem)
+- `sourceItem`: [`PluginClipboardItem`](#pluginclipboarditem)
 - `content`: [`PluginContentEnvelope`](#plugincontentenvelope)
 - `attachments`: [`PluginAttachmentRef`](#pluginattachmentref)[]
 
@@ -624,7 +682,7 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 
 ### `PluginAutoRunActionInput`
 
-- `item`: [`PluginClipboardItem`](#pluginclipboarditem)
+- `sourceItem`: [`PluginClipboardItem`](#pluginclipboarditem)
 - `content`: [`PluginContentEnvelope`](#plugincontentenvelope)
 - `attachments`: [`PluginAttachmentRef`](#pluginattachmentref)[]
 
@@ -645,6 +703,7 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 | `__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_LOCALE__` | `clipbus-plugin-locale` |
 

package/README.md

@@ -13,7 +13,7 @@ npm install @clipbus/plugin-sdk
 ```json
 {
   "dependencies": {
-    "@clipbus/plugin-sdk": "^0.1.0"
+    "@clipbus/plugin-sdk": "^0.9.0"
   }
 }
 ```
@@ -58,12 +58,12 @@ Returns a locked `{ result: { resultKind: 'text', text }, userMessage }` shape.
 
 | Param | Type | Description |
 |---|---|---|
-| `value` | `unknown` | Coerced to string. `null`/`undefined` → `""`. |
+| `value` | `string` | Text result passed to the next auto Action or copied by the user. |
 | `options.userMessage` | `string?` | Optional message shown to the user. |
 
 ### `actionResult.none(options?)`
 
-Returns `{ result: { resultKind: 'none', text: null }, userMessage }`.
+Returns `{ result: { resultKind: 'none' }, userMessage }`. A `none` result cannot advance the Action cascade.
 
 ### `actionResult.image(value, options?)`
 
@@ -71,12 +71,28 @@ Returns a locked `{ result: { resultKind: 'image', imageTempPath, imageFormatHin
 
 | Param | Type | Description |
 |---|---|---|
-| `value.imageTempPath` | `string` | Path returned by `allocateImageTempPath`. |
-| `value.imageFormatHint` | `string?` | Optional format hint (e.g. `"png"`, `"jpeg"`). |
+| `value` | `string` | Path returned by `allocateImageTempPath`. |
+| `options.imageFormatHint` | `string?` | Optional format hint (e.g. `"png"`, `"jpeg"`). |
 | `options.userMessage` | `string?` | Optional message shown to the user. |
 
+### `actionResult.path_reference(entries, options?)`
+
+Returns a safe path-reference result. Entries must either reuse a current input
+entry (`{source: 'input', inputIndex}`) or reference a path allocated by
+`ctx.host.action.allocateOutputFilePath()` (`{source: 'allocated_file', path, displayName}`).
+Arbitrary filesystem paths are rejected by the host.
+
 ---
 
+### Action input: source identity vs current value
+
+Action handlers receive `{ sourceItem, content, attachments }`.
+`sourceItem` remains the original clipboard item identity used by item mutation
+verbs; `content` is the current cascade value and may change kind after every
+auto Action. The Action `attachments` field is reserved for wire stability and
+is currently always `[]` in SDK 0.9.0. Draft Actions can display and copy their
+result, but do not advance to another Action.
+
 ### `messageHandlers` — handle UI → Runtime RPC calls
 
 Register handlers that respond to calls made from UI via `clipbus.runtime.invoke`. Each key is a string; the value is an async function receiving `(request, ctx)`.
@@ -142,7 +158,9 @@ These verbs are available on the `ctx.host` object passed to every runtime handl
 
 | Method | Returns | Description |
 |---|---|---|
-| `allocateImageTempPath({formatHint?})` | `Promise<{path: string}>` | Allocates a unique writable path for an image result. Consumed by `actionResult.image({imageTempPath})`. Cleaned up when invocation scope closes. |
+| `allocateImageTempPath({formatHint?})` | `Promise<{path: string}>` | Allocates a unique writable path for an image result. Pass the returned path to `actionResult.image(imageTempPath, options)`. Cleaned up when invocation scope closes. |
+| `materializeInputImagePath()` | `Promise<{path: string}>` | Materializes the current Action image value, even when `sourceItem` was originally text or a path reference. |
+| `allocateOutputFilePath({suggestedName?})` | `Promise<{path: string}>` | Allocates a host-owned path for a file result. Return it only through an `allocated_file` path-reference entry. |
 
 #### `ctx.host.asset`
 
@@ -259,6 +277,8 @@ Returns opaque `clipbus-asset://` URLs so a WebView can render local images in `
 |---|---|---|
 | `clipbus.asset.currentItemImageUrl()` | `Verb → {url?: string}` | URL of the current item's own image. `url` is absent when the item is not an image. |
 | `clipbus.asset.pathReferenceImageUrl({index})` | `Verb → {url?: string}` | URL of the current item's `path_reference` entry at `index`. `url` is absent when out of range or the entry is not an image. |
+| `clipbus.asset.currentActionInputImageUrl()` | `Verb → {url?: string}` | Action-context URL for the current image value, independent of `sourceItem.type`. |
+| `clipbus.asset.currentActionInputPathReferenceImageUrl({index})` | `Verb → {url?: string}` | Action-context URL for a current path-reference entry. |
 
 Arbitrary / generated images are minted only on the runtime side via `ctx.host.asset.registerImage({path})` (see above), so a WebView XSS cannot turn an arbitrary file into a renderable URL.
 
@@ -303,6 +323,17 @@ Namespace of verbs and sub-topics scoped to the action WebView. `clipbus.action`
 | `clipbus.action.complete({result, userMessage?})` | `Verb` | Submit draft action result to host; triggers phase transition to `.success` |
 | `clipbus.action.onHostInvoke(fn)` | `Stream` | Subscribe to host-dispatched button clicks; callback receives `{ buttonID }` |
 
+#### `clipbus.action.input` — Topic\<PluginActionUIInput\>
+
+The sanitized current Action value. Text is available directly; image exposes
+metadata; path-reference entries expose only `kind` and `displayName`. Real
+paths never enter the WebView.
+
+| Member | Shape | Description |
+|---|---|---|
+| `clipbus.action.input.current()` | `() → PluginActionUIInput \| undefined` | Read the current cascade input. |
+| `clipbus.action.input.on(fn)` | `(fn) → Unsubscribe` | Subscribe when the host replaces the current input. |
+
 #### `clipbus.action.draft` — OptionalTopic\<Record\<string, unknown\>\>
 
 Draft is **read-only** from the UI. The host pushes `initialDraft` (returned by `resolveSession`) as the topic value; the UI keeps form state locally and submits the final result via `clipbus.action.complete(...)`.
@@ -455,7 +486,9 @@ import type {
   PluginActionResolveResult,
   PluginAutoRunActionInput,
   PluginActionOperationResult,
-  PluginActionResult,              // discriminated union: text | image | none
+  PluginActionResult,              // discriminated union: text | image | path_reference | none
+  PluginActionPathResultEntry,
+  PluginActionUIInput,
   PluginActionButton,
   PluginThemeTokens,
   PluginThemeTokenSnapshot,
@@ -508,7 +541,7 @@ Unlike the host validator (which stops at the first error), this function collec
 
 ### `MANIFEST_VALIDATION_CODES`
 
-`readonly string[]` — all 26 error code strings, each a verbatim camelCase name that
+`readonly string[]` — all 27 error code strings, each a verbatim camelCase name that
 matches the corresponding host error. Use for exhaustive handling or parity checks.
 
 ### CLI: `clipbus-validate-manifest`

package/SPECIFICATION.md

@@ -102,6 +102,13 @@ Both methods are required on the type. The **lifecycle in `manifest.json`** deci
 
 There is no `PluginDraftActionHandler` convenience type — both lifecycles use the same interface.
 
+Both Action inputs use `{ sourceItem, content, attachments }`. `sourceItem`
+preserves the original clipboard identity for item mutations; `content` is the
+current cascade value and can change kind between Actions. The Action
+`attachments` field is reserved for wire stability and is currently always `[]`
+in SDK 0.9.0. Draft results are terminal and are never forwarded to another
+Action.
+
 ### Strongly typed drafts
 
 `clipbus.action.draft.current()` returns `Record<string, unknown> | undefined`. Cast at the call site:
@@ -168,6 +175,9 @@ Capabilities are split by catalog `surface.side`: runtime capabilities are expos
 | Replace action button list | `action.setButtons` | — | `clipbus.action.setButtons({buttons})` | Verb; buttons have `isEnabled?: boolean` field |
 | Submit draft result | `action.complete` | — | `clipbus.action.complete({result, userMessage?})` | Verb; draft lifecycle only |
 | Allocate image temp path | `action.allocateImageTempPath` | `ctx.host.action.allocateImageTempPath({formatHint?})` | — | Verb; runtime-only via user RPC bridge; removed from UI in plugin-api-shrink |
+| Materialize current Action image | `action.materializeInputImagePath` | `ctx.host.action.materializeInputImagePath()` | — | Reads current cascade image, not the original item |
+| Allocate Action output file | `action.allocateOutputFilePath` | `ctx.host.action.allocateOutputFilePath({suggestedName?})` | — | Path may only be returned as an `allocated_file` result entry |
+| Current Action input | action input host event | input param | `clipbus.action.input.current()` | Sanitized Topic; path values omit real paths |
 | UI → Runtime RPC | `runtime.invoke` | — (handler registered via `messageHandlers` in `definePlugin`) | `clipbus.runtime.invoke(key, payload, {timeoutMs?})` | Verb; UI side only; routes to plugin's own Node runtime; default timeout 30 s |
 | Host-side action button click | `clipbus-plugin-action-host-invoke` (host event) | — | `clipbus.action.onHostInvoke(fn)` | Stream; receives `{ buttonID }` |
 | Copy text | `clipboard.copyText` | `ctx.host.clipboard.copyText({text})` | `clipbus.clipboard.copyText({text})` | Verb; strict wire shape |
@@ -209,7 +219,7 @@ Node IPC inbound router rejects any UI-only method names at `PluginRuntimeHostMe
 
 ---
 
-## Chapter 2.5: Host Events (the canonical 7)
+## Chapter 2.5: Host Events
 
 Host events declared in the catalog drive every state Topic / Stream the SDK exposes to plugin authors. Each event optionally carries a `windowGlobal` (host injects JSON for synchronous `.current()` read at WebView startup) and a `surface.feed` with `topic` (SDK Topic key) + `shape` (`'topic'` for state, `'stream'` for fire-and-forget events) + `context`.
 
@@ -219,6 +229,7 @@ Host events declared in the catalog drive every state Topic / Stream the SDK exp
 | `clipbus-plugin-item` | `clipbus.item` | `__CLIPBUS_PLUGIN_ITEM__` | topic | any | `PluginClipboardItem` |
 | `clipbus-plugin-attachment` | `clipbus.item.attachment` | `__CLIPBUS_PLUGIN_ATTACHMENT__` | topic | attachmentRenderer | `PluginAttachmentPayload` |
 | `clipbus-plugin-draft` | `clipbus.action.draft` | `__CLIPBUS_PLUGIN_DRAFT__` | topic | action | `Record<string, unknown>` |
+| `clipbus-plugin-action-input` | `clipbus.action.input` | `__CLIPBUS_PLUGIN_ACTION_INPUT__` | topic | action | `PluginActionUIInput` |
 | `clipbus-plugin-theme` | `clipbus.theme` | `__CLIPBUS_PLUGIN_THEME__` | topic | any | `PluginThemeTokenSnapshot` |
 | `clipbus-plugin-locale` | `clipbus.locale` | `__CLIPBUS_PLUGIN_LOCALE__` | topic | any | `PluginLocalePayload` |
 | `clipbus-plugin-attachment-host-invoke` | `clipbus.attachmentRenderer.onHostInvoke` | — | stream | attachmentRenderer | `{ buttonID: string }` |

package/dist/generated/capabilityClients.generated.d.ts

@@ -68,6 +68,17 @@ export interface PluginAssetPathReferenceImageUrlPayload {
 export interface PluginAssetPathReferenceImageUrlResponse {
     url?: string;
 }
+export interface PluginAssetCurrentActionInputImageUrlPayload {
+}
+export interface PluginAssetCurrentActionInputImageUrlResponse {
+    url?: string;
+}
+export interface PluginAssetCurrentActionInputPathReferenceImageUrlPayload {
+    index: number;
+}
+export interface PluginAssetCurrentActionInputPathReferenceImageUrlResponse {
+    url?: string;
+}
 export interface PluginAssetRegisterImagePayload {
     path: string;
 }
@@ -100,6 +111,17 @@ export interface PluginActionAllocateImageTempPathPayload {
 export interface PluginActionAllocateImageTempPathResponse {
     path: string;
 }
+export interface PluginActionMaterializeInputImagePathPayload {
+}
+export interface PluginActionMaterializeInputImagePathResponse {
+    path: string;
+}
+export interface PluginActionAllocateOutputFilePathPayload {
+    suggestedName?: string;
+}
+export interface PluginActionAllocateOutputFilePathResponse {
+    path: string;
+}
 export interface PluginActionSetButtonsPayload {
     buttons: {
         id: string;
@@ -172,7 +194,7 @@ export interface PluginLocaleGetPayload {
 export interface PluginLocaleGetResponse {
     locale: string;
 }
-export declare const CAPABILITY_METHOD_NAMES: readonly ["runtime.invoke", "item.setTags", "item.addTags", "item.removeTags", "item.setPinned", "item.setAttachments", "item.setSearchExtension", "item.materializeImagePath", "item.readAttachment", "asset.currentItemImageUrl", "asset.pathReferenceImageUrl", "asset.registerImage", "clipboard.copyText", "navigation.openUrl", "navigation.revealInFinder", "navigation.openFilePath", "action.allocateImageTempPath", "action.setButtons", "action.complete", "attachmentRenderer.setButtons", "window.setHeight", "window.autoFit", "infoPanel.open", "infoPanel.close", "settings.get", "settings.getAll", "console.log", "textInput.stateChanged", "locale.get"];
+export declare const CAPABILITY_METHOD_NAMES: readonly ["runtime.invoke", "item.setTags", "item.addTags", "item.removeTags", "item.setPinned", "item.setAttachments", "item.setSearchExtension", "item.materializeImagePath", "item.readAttachment", "asset.currentItemImageUrl", "asset.pathReferenceImageUrl", "asset.currentActionInputImageUrl", "asset.currentActionInputPathReferenceImageUrl", "asset.registerImage", "clipboard.copyText", "navigation.openUrl", "navigation.revealInFinder", "navigation.openFilePath", "action.allocateImageTempPath", "action.materializeInputImagePath", "action.allocateOutputFilePath", "action.setButtons", "action.complete", "attachmentRenderer.setButtons", "window.setHeight", "window.autoFit", "infoPanel.open", "infoPanel.close", "settings.get", "settings.getAll", "console.log", "textInput.stateChanged", "locale.get"];
 export type CapabilityMethodName = (typeof CAPABILITY_METHOD_NAMES)[number];
 export declare const callRuntimeInvoke: (payload: PluginRuntimeInvokePayload) => Promise<PluginRuntimeInvokeResponse>;
 export declare const callItemSetTags: (payload: PluginItemSetTagsPayload) => Promise<PluginItemSetTagsResponse>;
@@ -185,12 +207,16 @@ export declare const callItemMaterializeImagePath: () => Promise<PluginItemMater
 export declare const callItemReadAttachment: (payload: PluginItemReadAttachmentPayload) => Promise<PluginItemReadAttachmentResponse>;
 export declare const callAssetCurrentItemImageUrl: () => Promise<PluginAssetCurrentItemImageUrlResponse>;
 export declare const callAssetPathReferenceImageUrl: (payload: PluginAssetPathReferenceImageUrlPayload) => Promise<PluginAssetPathReferenceImageUrlResponse>;
+export declare const callAssetCurrentActionInputImageUrl: () => Promise<PluginAssetCurrentActionInputImageUrlResponse>;
+export declare const callAssetCurrentActionInputPathReferenceImageUrl: (payload: PluginAssetCurrentActionInputPathReferenceImageUrlPayload) => Promise<PluginAssetCurrentActionInputPathReferenceImageUrlResponse>;
 export declare const callAssetRegisterImage: (payload: PluginAssetRegisterImagePayload) => Promise<PluginAssetRegisterImageResponse>;
 export declare const callClipboardCopyText: (payload: PluginClipboardCopyTextPayload) => Promise<PluginClipboardCopyTextResponse>;
 export declare const callNavigationOpenUrl: (payload: PluginNavigationOpenUrlPayload) => Promise<PluginNavigationOpenUrlResponse>;
 export declare const callNavigationRevealInFinder: (payload: PluginNavigationRevealInFinderPayload) => Promise<PluginNavigationRevealInFinderResponse>;
 export declare const callNavigationOpenFilePath: (payload: PluginNavigationOpenFilePathPayload) => Promise<PluginNavigationOpenFilePathResponse>;
 export declare const callActionAllocateImageTempPath: (payload: PluginActionAllocateImageTempPathPayload) => Promise<PluginActionAllocateImageTempPathResponse>;
+export declare const callActionMaterializeInputImagePath: () => Promise<PluginActionMaterializeInputImagePathResponse>;
+export declare const callActionAllocateOutputFilePath: (payload: PluginActionAllocateOutputFilePathPayload) => Promise<PluginActionAllocateOutputFilePathResponse>;
 export declare const callActionSetButtons: (payload: PluginActionSetButtonsPayload) => Promise<PluginActionSetButtonsResponse>;
 export declare const callActionComplete: (payload: PluginActionCompletePayload) => Promise<PluginActionCompleteResponse>;
 export declare const callAttachmentRendererSetButtons: (payload: PluginAttachmentRendererSetButtonsPayload) => Promise<PluginAttachmentRendererSetButtonsResponse>;

package/dist/generated/data.generated.d.ts

@@ -11,6 +11,16 @@ export interface PluginSearchExtensionEntry {
     label?: string;
     updatedAtMs?: number;
 }
+export interface PluginActionPathResultEntryInput {
+    source: 'input';
+    inputIndex: number;
+}
+export interface PluginActionPathResultEntryAllocated_file {
+    source: 'allocated_file';
+    path: string;
+    displayName: string;
+}
+export type PluginActionPathResultEntry = PluginActionPathResultEntryInput | PluginActionPathResultEntryAllocated_file;
 export interface PluginActionResultText {
     resultKind: 'text';
     text: string;
@@ -20,10 +30,14 @@ export interface PluginActionResultImage {
     imageTempPath: string;
     imageFormatHint?: string;
 }
+export interface PluginActionResultPath_reference {
+    resultKind: 'path_reference';
+    entries: PluginActionPathResultEntry[];
+}
 export interface PluginActionResultNone {
     resultKind: 'none';
 }
-export type PluginActionResult = PluginActionResultText | PluginActionResultImage | PluginActionResultNone;
+export type PluginActionResult = PluginActionResultText | PluginActionResultImage | PluginActionResultPath_reference | PluginActionResultNone;
 export type PluginInfoPanelTextStyle = 'body' | 'mono' | 'muted';
 export type PluginInfoPanelCodeLanguage = 'plain' | 'json';
 export interface PluginInfoPanelField {
@@ -92,6 +106,26 @@ export interface PluginAttachmentPayload {
     item: PluginClipboardItem;
     attachment: PluginAttachmentEntry;
 }
+export interface PluginActionUIPathEntry {
+    kind: 'file' | 'folder';
+    displayName: string;
+}
+export interface PluginActionUIInputText {
+    kind: 'text';
+    text: string;
+}
+export interface PluginActionUIInputImage {
+    kind: 'image';
+    width: number;
+    height: number;
+    format: string;
+    bytes: number;
+}
+export interface PluginActionUIInputPath_reference {
+    kind: 'path_reference';
+    entries: PluginActionUIPathEntry[];
+}
+export type PluginActionUIInput = PluginActionUIInputText | PluginActionUIInputImage | PluginActionUIInputPath_reference;
 export interface PluginThemeTokens {
     surface: string;
     surfaceElevated: string;
@@ -172,7 +206,7 @@ export interface PluginDetectorArtifact {
     updatedAtMs?: number;
 }
 export interface PluginResolveActionSessionInput {
-    item: PluginClipboardItem;
+    sourceItem: PluginClipboardItem;
     content: PluginContentEnvelope;
     attachments: PluginAttachmentRef[];
 }
@@ -183,7 +217,7 @@ export interface PluginActionResolveResult {
     initialDraft: Record<string, unknown>;
 }
 export interface PluginAutoRunActionInput {
-    item: PluginClipboardItem;
+    sourceItem: PluginClipboardItem;
     content: PluginContentEnvelope;
     attachments: PluginAttachmentRef[];
 }

package/dist/generated/hostBootstrap.generated.d.ts

@@ -1,4 +1,4 @@
-import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
 export interface PluginContextPayload {
     mode: 'attachmentRenderer' | 'action';
     pluginID: string;
@@ -17,6 +17,7 @@ export declare function emitActionBootstrap(p: {
     context?: PluginContextPayload;
     item?: PluginClipboardItem;
     draft?: Record<string, unknown>;
+    actionInput?: PluginActionUIInput;
     theme?: PluginThemeTokenSnapshot;
     locale?: PluginLocalePayload;
 }): void;

package/dist/generated/hostClients.generated.d.ts

@@ -1,10 +1,12 @@
-import type { PluginActionAllocateImageTempPathPayload, PluginActionAllocateImageTempPathResponse, PluginAssetRegisterImagePayload, PluginAssetRegisterImageResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginItemAddTagsPayload, PluginItemAddTagsResponse, PluginItemMaterializeImagePathResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginItemRemoveTagsPayload, PluginItemRemoveTagsResponse, PluginItemSetAttachmentsPayload, PluginItemSetAttachmentsResponse, PluginItemSetPinnedPayload, PluginItemSetPinnedResponse, PluginItemSetSearchExtensionPayload, PluginItemSetSearchExtensionResponse, PluginItemSetTagsPayload, PluginItemSetTagsResponse, PluginLocaleGetResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
+import type { PluginActionAllocateImageTempPathPayload, PluginActionAllocateImageTempPathResponse, PluginActionAllocateOutputFilePathPayload, PluginActionAllocateOutputFilePathResponse, PluginActionMaterializeInputImagePathResponse, PluginAssetRegisterImagePayload, PluginAssetRegisterImageResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginItemAddTagsPayload, PluginItemAddTagsResponse, PluginItemMaterializeImagePathResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginItemRemoveTagsPayload, PluginItemRemoveTagsResponse, PluginItemSetAttachmentsPayload, PluginItemSetAttachmentsResponse, PluginItemSetPinnedPayload, PluginItemSetPinnedResponse, PluginItemSetSearchExtensionPayload, PluginItemSetSearchExtensionResponse, PluginItemSetTagsPayload, PluginItemSetTagsResponse, PluginLocaleGetResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
 export interface IPCBus {
     request<Req, Resp>(method: string, payload: Req): Promise<Resp>;
 }
 export interface HostClient {
     action: {
         allocateImageTempPath(payload: PluginActionAllocateImageTempPathPayload): Promise<PluginActionAllocateImageTempPathResponse>;
+        materializeInputImagePath(): Promise<PluginActionMaterializeInputImagePathResponse>;
+        allocateOutputFilePath(payload: PluginActionAllocateOutputFilePathPayload): Promise<PluginActionAllocateOutputFilePathResponse>;
     };
     asset: {
         registerImage(payload: PluginAssetRegisterImagePayload): Promise<PluginAssetRegisterImageResponse>;

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

@@ -1,3 +1,4 @@
+import type { PluginActionPathResultEntry } from './data.generated.js';
 export interface ActionResultOptions {
     userMessage?: string;
 }
@@ -19,6 +20,13 @@ export declare const actionResult: {
         };
         userMessage: string | undefined;
     };
+    path_reference: (entries: PluginActionPathResultEntry[], options?: ActionResultOptions) => {
+        result: {
+            resultKind: "path_reference";
+            entries: PluginActionPathResultEntry[];
+        };
+        userMessage: string | undefined;
+    };
     none: (options?: ActionResultOptions) => {
         result: {
             resultKind: "none";

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

@@ -1,4 +1,4 @@
-import type { PluginActionAllocateImageTempPathPayload, PluginActionAllocateImageTempPathResponse, PluginAssetRegisterImagePayload, PluginAssetRegisterImageResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginItemAddTagsPayload, PluginItemAddTagsResponse, PluginItemMaterializeImagePathResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginItemRemoveTagsPayload, PluginItemRemoveTagsResponse, PluginItemSetAttachmentsPayload, PluginItemSetAttachmentsResponse, PluginItemSetPinnedPayload, PluginItemSetPinnedResponse, PluginItemSetSearchExtensionPayload, PluginItemSetSearchExtensionResponse, PluginItemSetTagsPayload, PluginItemSetTagsResponse, PluginLocaleGetResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
+import type { PluginActionAllocateImageTempPathPayload, PluginActionAllocateImageTempPathResponse, PluginActionAllocateOutputFilePathPayload, PluginActionAllocateOutputFilePathResponse, PluginActionMaterializeInputImagePathResponse, PluginAssetRegisterImagePayload, PluginAssetRegisterImageResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginItemAddTagsPayload, PluginItemAddTagsResponse, PluginItemMaterializeImagePathResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginItemRemoveTagsPayload, PluginItemRemoveTagsResponse, PluginItemSetAttachmentsPayload, PluginItemSetAttachmentsResponse, PluginItemSetPinnedPayload, PluginItemSetPinnedResponse, PluginItemSetSearchExtensionPayload, PluginItemSetSearchExtensionResponse, PluginItemSetTagsPayload, PluginItemSetTagsResponse, PluginLocaleGetResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
 export declare const host: {
     item: {
         setTags: (payload: PluginItemSetTagsPayload) => Promise<PluginItemSetTagsResponse>;
@@ -23,6 +23,8 @@ export declare const host: {
     };
     action: {
         allocateImageTempPath: (payload: PluginActionAllocateImageTempPathPayload) => Promise<PluginActionAllocateImageTempPathResponse>;
+        materializeInputImagePath: () => Promise<PluginActionMaterializeInputImagePathResponse>;
+        allocateOutputFilePath: (payload: PluginActionAllocateOutputFilePathPayload) => Promise<PluginActionAllocateOutputFilePathResponse>;
     };
     settings: {
         get: (payload: PluginSettingsGetPayload) => Promise<PluginSettingsGetResponse>;

package/dist/generated/topicSubscribers.generated.d.ts

@@ -1,4 +1,4 @@
-import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
 export interface PluginContextPayload {
     mode: 'attachmentRenderer' | 'action';
     pluginID: string;
@@ -11,6 +11,8 @@ export declare function onAttachment(listener: (payload: PluginAttachmentPayload
 export declare function getAttachmentSnapshot(): PluginAttachmentPayload | undefined;
 export declare function onDraft(listener: (payload: Record<string, unknown>) => void): () => void;
 export declare function getDraftSnapshot(): Record<string, unknown> | undefined;
+export declare function onActionInput(listener: (payload: PluginActionUIInput) => void): () => void;
+export declare function getActionInputSnapshot(): PluginActionUIInput | undefined;
 export declare function onTheme(listener: (payload: PluginThemeTokenSnapshot) => void): () => void;
 export declare function getThemeSnapshot(): PluginThemeTokenSnapshot | undefined;
 export interface PluginAttachmentHostInvokePayload {

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

@@ -1,9 +1,10 @@
-import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
 import type { PluginActionHostInvokePayload, PluginAttachmentHostInvokePayload, PluginContextPayload, PluginInfoPanelOnActionPayload, PluginInfoPanelOnClosePayload, PluginLocalePayload } from './topicSubscribers.generated.js';
 export declare const _pluginContextTopic: import("../internal/topic.js").MutableTopic<PluginContextPayload>;
 export declare const _itemTopic: import("../internal/topic.js").MutableTopic<PluginClipboardItem>;
 export declare const _itemAttachmentTopic: import("../internal/topic.js").MutableTopic<PluginAttachmentPayload>;
 export declare const _actionDraftTopic: import("../internal/topic.js").MutableTopic<Record<string, unknown>>;
+export declare const _actionInputTopic: import("../internal/topic.js").MutableTopic<PluginActionUIInput>;
 export declare const _themeTopic: import("../internal/topic.js").MutableTopic<PluginThemeTokenSnapshot>;
 export declare const _attachmentRendererOnHostInvokeStream: import("../internal/topic.js").MutableStream<PluginAttachmentHostInvokePayload>;
 export declare const _actionOnHostInvokeStream: import("../internal/topic.js").MutableStream<PluginActionHostInvokePayload>;

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

@@ -1,5 +1,5 @@
-import type { PluginActionCompletePayload, PluginActionCompleteResponse, PluginActionSetButtonsPayload, PluginActionSetButtonsResponse, PluginAssetCurrentItemImageUrlResponse, PluginAssetPathReferenceImageUrlPayload, PluginAssetPathReferenceImageUrlResponse, PluginAttachmentRendererSetButtonsPayload, PluginAttachmentRendererSetButtonsResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginInfoPanelClosePayload, PluginInfoPanelCloseResponse, PluginInfoPanelOpenPayload, PluginInfoPanelOpenResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginRuntimeInvokePayload, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse, PluginTextInputStateChangedPayload, PluginTextInputStateChangedResponse, PluginWindowAutoFitResponse, PluginWindowSetHeightPayload, PluginWindowSetHeightResponse } from './capabilityClients.generated.js';
-import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
+import type { PluginActionCompletePayload, PluginActionCompleteResponse, PluginActionSetButtonsPayload, PluginActionSetButtonsResponse, PluginAssetCurrentActionInputImageUrlResponse, PluginAssetCurrentActionInputPathReferenceImageUrlPayload, PluginAssetCurrentActionInputPathReferenceImageUrlResponse, PluginAssetCurrentItemImageUrlResponse, PluginAssetPathReferenceImageUrlPayload, PluginAssetPathReferenceImageUrlResponse, PluginAttachmentRendererSetButtonsPayload, PluginAttachmentRendererSetButtonsResponse, PluginClipboardCopyTextPayload, PluginClipboardCopyTextResponse, PluginConsoleLogPayload, PluginConsoleLogResponse, PluginInfoPanelClosePayload, PluginInfoPanelCloseResponse, PluginInfoPanelOpenPayload, PluginInfoPanelOpenResponse, PluginItemReadAttachmentPayload, PluginItemReadAttachmentResponse, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginRuntimeInvokePayload, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse, PluginTextInputStateChangedPayload, PluginTextInputStateChangedResponse, PluginWindowAutoFitResponse, PluginWindowSetHeightPayload, PluginWindowSetHeightResponse } from './capabilityClients.generated.js';
+import type { PluginActionUIInput, PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
 import type { PluginActionHostInvokePayload, PluginAttachmentHostInvokePayload, PluginContextPayload, PluginInfoPanelOnActionPayload, PluginInfoPanelOnClosePayload, PluginLocalePayload } from './topicSubscribers.generated.js';
 export declare const clipbus: {
     capabilities: import("../internal/capabilities.js").CapabilitiesApi;
@@ -18,6 +18,8 @@ export declare const clipbus: {
     asset: {
         currentItemImageUrl: () => Promise<PluginAssetCurrentItemImageUrlResponse>;
         pathReferenceImageUrl: (payload: PluginAssetPathReferenceImageUrlPayload) => Promise<PluginAssetPathReferenceImageUrlResponse>;
+        currentActionInputImageUrl: () => Promise<PluginAssetCurrentActionInputImageUrlResponse>;
+        currentActionInputPathReferenceImageUrl: (payload: PluginAssetCurrentActionInputPathReferenceImageUrlPayload) => Promise<PluginAssetCurrentActionInputPathReferenceImageUrlResponse>;
     };
     clipboard: {
         copyText: (payload: PluginClipboardCopyTextPayload) => Promise<PluginClipboardCopyTextResponse>;
@@ -34,6 +36,10 @@ export declare const clipbus: {
             current: () => Record<string, unknown> | undefined;
             on: (fn: (payload: Record<string, unknown>) => void) => import("../internal/topic.js").Unsubscribe;
         };
+        input: {
+            current: () => PluginActionUIInput | undefined;
+            on: (fn: (payload: PluginActionUIInput) => void) => import("../internal/topic.js").Unsubscribe;
+        };
         onHostInvoke: {
             on: (fn: (payload: PluginActionHostInvokePayload) => void) => import("../internal/topic.js").Unsubscribe;
         };

package/dist/preview/index.cjs

@@ -1373,6 +1373,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 }));
@@ -1410,6 +1414,7 @@ function computeWirePayloads(scenario, themeKey = DEFAULT_THEME_KEY) {
     context,
     item: scenario.item,
     draft: scenario.draft ?? {},
+    actionInput: scenario.actionInput,
     theme,
     locale
   };
@@ -1428,6 +1433,7 @@ function injectWire(_target, payloads) {
       context: payloads.context,
       item: payloads.item,
       draft: payloads.draft,
+      actionInput: payloads.actionInput,
       theme: payloads.theme,
       locale: payloads.locale
     });
@@ -1484,6 +1490,12 @@ function classifyWireSections(payloads) {
       defaultOpen: true,
       value: payloads.draft
     });
+    sections.push({
+      key: "actionInput",
+      kind: "content",
+      defaultOpen: true,
+      value: payloads.actionInput
+    });
   }
   sections.push({
     key: "theme",