@clipbus/plugin-sdk 0.9.7 → 0.9.8

package/API.md

@@ -505,7 +505,6 @@ export interface PluginRegistry {
 
 - `attachmentKey`: `string`
 - `payloadJson`: `string`
-- `syncScope`: `string`
 - `createdAtMs?`: `int`
 - `updatedAtMs?`: `int`
 
@@ -663,7 +662,6 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 - `attachmentKey`: `string`
 - `payloadJson`: `string`
 - `searchProjection?`: [`PluginDetectorSearchProjection`](#plugindetectorsearchprojection)
-- `attachmentSyncScope?`: `string`
 - `createdAtMs?`: `int`
 - `updatedAtMs?`: `int`
 

package/README.md

@@ -55,6 +55,9 @@ module.exports = definePlugin({
 ### `actionResult.text(value, options?)`
 
 Returns a locked `{ result: { resultKind: 'text', text }, userMessage }` shape.
+When returned by an auto-run Action, or submitted by a Draft Action through
+`clipbus.action.complete(...)`, a successful value can be explicitly advanced
+by the user as the next Action input.
 
 | Param | Type | Description |
 |---|---|---|
@@ -80,7 +83,8 @@ Returns a locked `{ result: { resultKind: 'image', imageTempPath, imageFormatHin
 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.
+Arbitrary filesystem paths are rejected by the host. Like text and image,
+`path_reference` is a value result that the user can explicitly advance.
 
 ---
 
@@ -89,9 +93,13 @@ Arbitrary filesystem paths are rejected by the host.
 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.
+Action step. The Action `attachments` field is reserved for wire stability and
+is currently always `[]` in SDK 0.9.0. Successful Draft results with `text`,
+`image`, or `path_reference` are shown for confirmation and can be explicitly
+advanced by the user; `none` remains non-continuable. Completion never
+auto-advances or implicitly selects another Action. This is host behavior for
+the existing schema v4 result shapes, so plugins do not need a manifest or
+generated-code update.
 
 ### `messageHandlers` — handle UI → Runtime RPC calls
 
@@ -320,7 +328,7 @@ Namespace of verbs and sub-topics scoped to the action WebView. `clipbus.action`
 | Member | Shape | Description |
 |---|---|---|
 | `clipbus.action.setButtons({buttons})` | `Verb` | Replace native action button list (whole-list replace; first call overrides `resolveSession` seed). Strict wire shape — pass `{buttons: [...]}`. |
-| `clipbus.action.complete({result, userMessage?})` | `Verb` | Submit draft action result to host; triggers phase transition to `.success` |
+| `clipbus.action.complete({result, userMessage?})` | `Verb` | Submit a Draft result and enter the host success presentation; a text/image/path_reference value may then be explicitly advanced by the user, while none cannot advance |
 | `clipbus.action.onHostInvoke(fn)` | `Stream` | Subscribe to host-dispatched button clicks; callback receives `{ buttonID }` |
 
 #### `clipbus.action.input` — Topic\<PluginActionUIInput\>

package/SPECIFICATION.md

@@ -106,8 +106,12 @@ 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.
+in SDK 0.9.0. A Draft `complete(...)` result with `text`, `image`, or
+`path_reference` enters the host's success presentation and can be explicitly
+advanced by the user as the next Action input; `none` cannot advance. Completion
+does not auto-advance or implicitly select another Action. These semantics use
+the existing schema v4 result shapes and require no protocol or generated-code
+change.
 
 ### Strongly typed drafts
 
@@ -173,7 +177,7 @@ Capabilities are split by catalog `surface.side`: runtime capabilities are expos
 | Auto-fit height | `window.autoFit` | — | `clipbus.window.autoFit()` | Verb |
 | Draft | draftHostEvent | input param | `clipbus.action.draft.current()` | OptionalTopic; UI is read-only — no `update()` verb |
 | 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 |
+| Submit draft result | `action.complete` | — | `clipbus.action.complete({result, userMessage?})` | Verb; draft lifecycle only; value results can be explicitly advanced by the user, `none` cannot |
 | 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 |

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

@@ -1,7 +1,6 @@
 export interface PluginAttachmentMutationEntry {
     attachmentKey: string;
     payloadJson: string;
-    syncScope: string;
     createdAtMs?: number;
     updatedAtMs?: number;
 }
@@ -201,7 +200,6 @@ export interface PluginDetectorArtifact {
     attachmentKey: string;
     payloadJson: string;
     searchProjection?: PluginDetectorSearchProjection;
-    attachmentSyncScope?: string;
     createdAtMs?: number;
     updatedAtMs?: number;
 }

package/dist/validate/index.cjs

@@ -99,7 +99,7 @@ function isValidPluginID(id) {
 }
 function validateSchemaVersion(raw, issues) {
   const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
-  if (version !== 3) {
+  if (version !== 4) {
     issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
   }
 }
@@ -118,13 +118,13 @@ var LEGACY_ACTION_FIELDS = [
 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 v3: plugin.displayName`));
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: 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 v3: attachmentRenderers[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: attachmentRenderers[${i}].${field}`));
       }
     }
   }
@@ -132,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 v3: detectors[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: detectors[${i}].${field}`));
       }
     }
   }
@@ -140,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 v3: actions[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: actions[${i}].${field}`));
       }
     }
   }

package/dist/validate/index.js

@@ -64,7 +64,7 @@ function isValidPluginID(id) {
 }
 function validateSchemaVersion(raw, issues) {
   const version = typeof raw["schemaVersion"] === "number" ? raw["schemaVersion"] : 0;
-  if (version !== 3) {
+  if (version !== 4) {
     issues.push(issue("unsupportedSchemaVersion", `Unsupported plugin schema version: ${version}`));
   }
 }
@@ -83,13 +83,13 @@ var LEGACY_ACTION_FIELDS = [
 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 v3: plugin.displayName`));
+    issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: 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 v3: attachmentRenderers[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: attachmentRenderers[${i}].${field}`));
       }
     }
   }
@@ -97,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 v3: detectors[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: detectors[${i}].${field}`));
       }
     }
   }
@@ -105,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 v3: actions[${i}].${field}`));
+        issues.push(issue("legacyFieldNotSupported", `Legacy manifest field is not supported in v4: actions[${i}].${field}`));
       }
     }
   }

package/docs/authoring.md

@@ -28,7 +28,6 @@ const detector: PluginDetectorHandler = {
         attachmentType: 'plugin.example.sample.card',  // 必须已在 manifest 声明
         attachmentKey: `card-${input.item.id}`,        // 稳定 key，不允许空字符串
         payloadJson: JSON.stringify({ text: input.content.text }),
-        attachmentSyncScope: 'syncable',               // 'syncable' | 'local_only'
         searchProjection: {                            // 可选
           scope: 'sample',
           searchText: input.content.text.slice(0, 80),
@@ -45,6 +44,7 @@ const detector: PluginDetectorHandler = {
 - 未命中时返回 `[]`，不要返回半成品 artifact
 - Detector 内不应执行宿主 mutation（标签写入等）；那是 action 的职责
 - `attachmentType` 必须出自 manifest 的 `detectors[].attachmentTypes`（manifest 结构见 [manifest.md](./manifest.md)）
+- Attachment 是当前设备的 detector 派生数据。schema v4 不提供同步范围字段，宿主统一以 `local_only` 持久化；若内容需要在尚未选中 item 时参与跨设备搜索，请显式提供 `searchProjection`
 
 ---
 
@@ -262,12 +262,15 @@ async function handleApply() {
 }
 ```
 
-Draft 完成后宿主展示结果供复制或关闭，但不会把结果移交到下一个 Action；
-只有 auto-run Action 的非 `none` 成功结果可以继续级联。
+Draft 完成后宿主先展示结果供确认、复制或关闭；`text`、`image` 与
+`path_reference` 实际值可由用户显式提交为下一个 Action 的输入，`none`
+不可继续。`complete(...)` 本身不会自动推进，也不会隐式选择其他 Action。
+这是既有 schema v4 结果形状的宿主交互变化，插件无需修改 manifest、
+重新 codegen 或重建。
 
 ### Draft Action：UI 需要 runtime 协助时
 
-`clipbus.action.complete` 接收 `{result: {resultKind: 'text' | 'image' | 'none', …}}`。**image 结果的 `imageTempPath` 必须由 runtime 端通过 `host.action.allocateImageTempPath` 分配**（UI 端没有这个能力），所以图片类 draft 的典型流程是：
+`clipbus.action.complete` 接收 `{result: {resultKind: 'text' | 'image' | 'path_reference' | 'none', …}}`。**image 结果的 `imageTempPath` 必须由 runtime 端通过 `host.action.allocateImageTempPath` 分配**（UI 端没有这个能力），所以图片类 draft 的典型流程是：
 
 ```ts
 // shared/contracts.ts —— 两端共享类型契约

package/docs/manifest.md

@@ -10,7 +10,7 @@
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `schemaVersion` | `number` | 是 | 固定 `3` |
+| `schemaVersion` | `number` | 是 | 固定 `4` |
 | `plugin` | `object` | 是 | 插件身份信息 |
 | `install` | `object` | 否 | 安装期 hook 配置 |
 | `runtime` | `object` | 是 | runtime 与 UI 根目录 |
@@ -109,7 +109,7 @@
 
 ```json
 {
-  "schemaVersion": 3,
+  "schemaVersion": 4,
   "plugin": {
     "id": "plugin.example.sample",
     "title": "Sample Plugin",
@@ -150,10 +150,11 @@
 }
 ```
 
-## 从 schema v2 升级
+## 从 schema v3 升级
 
-schema v3 是有意的 breaking change。将每个 Action 的
-`supportedItemTypes` 改为 `supportedInputKinds`，并移除
-`inputConstraints`、`possibleResultKinds`（若曾自行添加）。宿主不会把
-v2 Action 适配为 v3；已安装或开发插件会显示“需要更新”，直到 manifest
-和构建产物通过 v3 校验。
+schema v4 是 attachment 本机化的 breaking change。Detector artifact 删除
+`attachmentSyncScope`，`item.setAttachments` 的每个 entry 删除 `syncScope`；
+宿主统一以 `local_only` 写入 attachment。Search extension 仍可同步，因此需要
+跨设备预搜索的 detector 文本应继续通过 `searchProjection` 或
+`item.setSearchExtension` 显式写入。宿主不提供 v3/v4 字段兼容层；已安装或开发
+插件会显示“需要更新”，直到 manifest 和构建产物通过 v4 校验。

package/docs/preview.md

@@ -88,7 +88,7 @@ interface PreviewScenario {
 | `viewport` | 该 scenario 的视口配置；未设置时使用 `opts.defaultViewport` |
 | `view` | 透传给 `mount` adapter 的不透明 hint（e.g. `'compact'`/`'expanded'`） |
 
-> **Draft Action 是终点 lifecycle。** `clipbus.action.complete()` 把一个最终结果交回宿主，不会继续进入下一个级联 Action。Preview 因而只模拟 Draft 交互与结果提交，不提供“下一步 Action”状态机。
+> **Preview 不模拟完整宿主级联。** 真实宿主收到 `clipbus.action.complete()` 的 `text`、`image` 或 `path_reference` 结果后，会先展示确认阶段，用户可再显式推进到下一 Action；`none` 不可继续。Preview harness 只模拟 Draft 交互与结果提交并记录 native call，不实现宿主的结果确认、“下一步 Action”、动态过滤、rollback 或焦点状态机。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipbus/plugin-sdk",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "type": "module",
   "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
   "keywords": [