@clipbus/plugin-sdk 0.9.5 → 0.9.7

package/dist/preview/index.cjs

@@ -900,7 +900,7 @@ function renderChrome(root, scenarios, opts, handlers) {
   header.appendChild(controls);
   const viewOptions = [
     { value: "attachmentRenderer", label: "Renderer" },
-    { value: "action", label: "Action" }
+    { value: "action", label: "Draft Action" }
   ];
   const viewSelect = buildSelect("cbp-wb-view", "Surface", viewOptions, selectedView, controls);
   const scenarioAreaWrapper = div("cbp-wb__control");
@@ -1190,7 +1190,7 @@ function renderChrome(root, scenarios, opts, handlers) {
   }
   function updateWorkspaceHead() {
     const scenario = activeScenario();
-    const modeLabel = scenario.mode === "attachmentRenderer" ? "attachmentRenderer" : "action";
+    const modeLabel = scenario.mode === "attachmentRenderer" ? "attachmentRenderer" : "draftAction";
     wsChip.textContent = `${modeLabel} \xB7 ${scenario.label}`;
     wsDims.textContent = `${currentWidth} \xD7 ${currentBodyHeightLabel()}`;
   }

package/dist/preview/index.js

@@ -857,7 +857,7 @@ function renderChrome(root, scenarios, opts, handlers) {
   header.appendChild(controls);
   const viewOptions = [
     { value: "attachmentRenderer", label: "Renderer" },
-    { value: "action", label: "Action" }
+    { value: "action", label: "Draft Action" }
   ];
   const viewSelect = buildSelect("cbp-wb-view", "Surface", viewOptions, selectedView, controls);
   const scenarioAreaWrapper = div("cbp-wb__control");
@@ -1147,7 +1147,7 @@ function renderChrome(root, scenarios, opts, handlers) {
   }
   function updateWorkspaceHead() {
     const scenario = activeScenario();
-    const modeLabel = scenario.mode === "attachmentRenderer" ? "attachmentRenderer" : "action";
+    const modeLabel = scenario.mode === "attachmentRenderer" ? "attachmentRenderer" : "draftAction";
     wsChip.textContent = `${modeLabel} \xB7 ${scenario.label}`;
     wsDims.textContent = `${currentWidth} \xD7 ${currentBodyHeightLabel()}`;
   }

package/dist/preview/inputPanel.d.ts

@@ -27,7 +27,7 @@ export interface WireSection {
 /**
  * Classify wire payload sections into display order with open/collapsed defaults.
  *
- * Fixed order: context · item · attachment(renderer)/draft+actionInput(action) · theme · locale
+ * Fixed order: context · item · attachment(renderer)/draft+actionInput(Draft Action) · theme · locale
  *   content: item + attachment/draft/actionInput — defaultOpen true
  *   infra:   context + theme + locale — defaultOpen false (plumbing, low signal)
  */

package/dist/preview/types.d.ts

@@ -25,9 +25,12 @@ export interface PreviewScenario {
     item: PluginClipboardItem;
     /** Attachment renderer mode payload. */
     attachment?: PluginAttachmentPayload;
-    /** Action mode draft payload. */
+    /** Draft Action surface payload. */
     draft?: Record<string, unknown>;
-    /** Sanitized current Action value; never include real filesystem paths. */
+    /**
+     * Sanitized current Action value. This may differ in kind from `item`, which
+     * remains the original clipboard item identity. Never include real paths.
+     */
     actionInput?: PluginActionUIInput;
     buttons?: {
         id: string;

package/docs/preview.md

@@ -4,9 +4,9 @@
 
 `@clipbus/plugin-sdk/preview` 提供**框架中立**（纯 DOM/TypeScript，不依赖 Vue 或任何 UI 框架）的**开发期**预览 harness。无需真实 macOS 宿主进程，即可在浏览器里迭代插件 UI 的外观与行为。
 
-- **宿主 → 插件注入**：wire payload（bootstrap、item、attachment、theme、draft……）由 harness 根据 scenario 定义按宿主协议生成，与真实宿主注入方式同源。
+- **宿主 → 插件注入**：wire payload（bootstrap、item、attachment、theme、draft、actionInput……）由 harness 根据 scenario 定义按宿主协议生成，与真实宿主注入方式同源。
 - **插件 → 宿主调用**：所有 `clipbus.*` native 调用被拦截并实时追加到「调用日志」面板；`clipbus.window.setHeight` 额外驱动视口高度；其他调用返回安全默认应答，不抛错。
-- **视口**：宽度按模式默认（renderer 720 / action 350；renderer 取自 native 主面板全宽 workspace 区，action 为紧凑 action 卡宽），可被 `scenario.viewport.width` 覆盖，宽度滑杆按 view 切换范围（renderer [560,900]、action [300,500]）；高度跟随插件真实调用的 `clipbus.window.setHeight`（`auto`/`bounded` 策略，统一封顶 native 硬上限 800），行为贴近 native。
+- **视口**：宽度按模式默认（renderer 720 / Draft Action 350；renderer 取自 native 主面板全宽 workspace 区，Draft Action 为紧凑卡片宽度），可被 `scenario.viewport.width` 覆盖，宽度滑杆按 view 切换范围（renderer [560,900]、Draft Action [300,500]）；高度跟随插件真实调用的 `clipbus.window.setHeight`（`auto`/`bounded` 策略，统一封顶 native 硬上限 800），行为贴近 native。
 
 **这是纯开发期工具**，不打包进线上 plugin 产物。
 
@@ -63,7 +63,8 @@ interface PreviewScenario {
   accentHex?: string;
   item: PluginClipboardItem;
   attachment?: PluginAttachmentPayload;  // attachmentRenderer 模式
-  draft?: Record<string, unknown>;       // action 模式
+  draft?: Record<string, unknown>;       // Draft Action 模式
+  actionInput?: PluginActionUIInput;      // 当前级联值，可与原始 item 类型不同
   buttons?: { id: string; title: string; isEnabled: boolean }[];
   defaultButtonID?: string;
   viewport?: PreviewViewport;
@@ -75,17 +76,20 @@ interface PreviewScenario {
 |---|---|
 | `id` | scenario 唯一标识符 |
 | `label` | 选择器里显示的名称 |
-| `mode` | `'attachmentRenderer'`（渲染器 WebView）或 `'action'`（draft action WebView） |
+| `mode` | `'attachmentRenderer'`（渲染器 WebView）或 `'action'`（Draft Action WebView；内部 wire key 保持 `action`） |
 | `pluginID` | 注入给插件 `context.pluginID` 的插件 ID；若 attachment.owner 校验依赖此字段，应显式设置；未设置时 harness 使用占位符 |
 | `accentHex` | 强调色十六进制字符串（e.g. `'#0f766e'`） |
-| `item` | 当前 clipboard item（`PluginClipboardItem`） |
+| `item` | 原始 clipboard item 身份（`PluginClipboardItem`）；级联过程中保持不变 |
 | `attachment` | attachmentRenderer 模式的 attachment payload（`PluginAttachmentPayload`） |
-| `draft` | action 模式的 initialDraft（`Record<string, unknown>`） |
+| `draft` | Draft Action 模式的 initialDraft（`Record<string, unknown>`） |
+| `actionInput` | 进入当前 Action 的已净化级联值（`PluginActionUIInput`）；类型可以与 `item.type` 不同，路径只允许展示安全引用，不能放真实文件路径 |
 | `buttons` | 按钮条种子：id / title / isEnabled |
 | `defaultButtonID` | 默认高亮按钮的 id |
 | `viewport` | 该 scenario 的视口配置；未设置时使用 `opts.defaultViewport` |
 | `view` | 透传给 `mount` adapter 的不透明 hint（e.g. `'compact'`/`'expanded'`） |
 
+> **Draft Action 是终点 lifecycle。** `clipbus.action.complete()` 把一个最终结果交回宿主，不会继续进入下一个级联 Action。Preview 因而只模拟 Draft 交互与结果提交，不提供“下一步 Action”状态机。
+
 ---
 
 ## `PreviewViewport` 字段参考
@@ -124,11 +128,11 @@ Wire Bench 在右侧 dock 的 IN 卡片中展示**完整 wire 注入内容**（`
 |---|---|---|
 | `context` | infra | 折叠 |
 | `item` | **content** | **展开** |
-| `attachment`（renderer）/ `draft`（action）| **content** | **展开** |
+| `attachment`（renderer）/ `draft` + `actionInput`（Draft Action）| **content** | **展开** |
 | `theme` | infra | 折叠 |
 | `locale` | infra | 折叠 |
 
-- **content 段**（item + attachment/draft）默认展开，方便与右侧 OUT 输出对照。
+- **content 段**（item + attachment，或 item + draft + actionInput）默认展开，方便对照原始 item、当前级联输入与右侧 OUT 输出。
 - **infra 段**（context / theme / locale）默认折叠，减少干扰。
 - 每段独立折叠，互不影响（仅 OUT 是单开 accordion）。
 - `attachment.payloadJson` 字段：若为合法 JSON 字符串则**解析为可读嵌套 JSON**；解析失败回退原样字符串（不静默吞错）。
@@ -140,7 +144,7 @@ Wire Bench 在右侧 dock 的 IN 卡片中展示**完整 wire 注入内容**（`
 
 harness 安装一个最小双向 fake host：
 
-- **host → plugin**：按 scenario 字段生成 wire payload 并注入；bootstrap、item、attachment、theme 等不需要真实宿主
+- **host → plugin**：按 scenario 字段生成 wire payload 并注入；bootstrap、item、attachment、draft、actionInput、theme 等不需要真实宿主
 - **plugin → host**：所有 `clipbus.*` native 调用被拦截，实时追加到右侧 dock 的 OUT 卡片；`clipbus.window.setHeight` 额外驱动视口高度；其他调用返回安全默认应答
 
 OUT 卡片使用**单开 accordion**：
@@ -197,14 +201,14 @@ npm run dev
 
 Vite 启动后，工作台提供：
 
-- **两级模式导航**：顶层 Surface 选择器在 **Renderer**（attachmentRenderer）和 **Action** 两种模式间切换；两种模式的 scenario 均用 `<select>` 下拉选择（文案取自 `scenario.label`）。任何时刻只渲染当前选中 scenario。URL query `?view=&scenario=&theme=` 同步，刷新不丢。
+- **两级模式导航**：顶层 Surface 选择器在 **Renderer**（`attachmentRenderer`）和 **Draft Action**（内部值仍为 `action`）两种 UI surface 间切换；auto-run Action 没有插件 UI，因此不属于 preview surface。两种模式的 scenario 均用 `<select>` 下拉选择（文案取自 `scenario.label`）。任何时刻只渲染当前选中 scenario。URL query `?view=&scenario=&theme=` 同步，刷新不丢。
 - **主题切换**（4 预设：Graphite · Ember · Porcelain · Sand）：切换时三重作用：① 重注入 wire 主题 topic，插件已注册的 `clipbus.theme.on()` 回调立即触发；② 仅重着色**卡片壳与插件内容**（chrome 本身配色保持稳定，见下方[主题解耦](#主题解耦chrome-稳定--卡片跟-native)）；③ 在插件挂载槽上更新 `--clipbus-*` CSS 变量——不触发 remount，与 native `theme.onChange` 行为一致。注意：插件的 `--clipbus-accent` 是**全局主题 accent**；`scenario.accentHex` 是该附件的 **tintColor**，只染**卡片边框**（对应 native `record.tintColor`），不进插件配色。
 - **Workspace（主工作区，左列）**：标本卡（frozen specimen）居中展示，下方有**生长地板**标注 `native ceiling ≈ 800px`，把卡片下方空白变成"到硬上限的余量"这一有意义信息。卡片再高只撑左列，不影响右侧 dock。
 - **Dock（右列，`position:sticky`）**：卡片变高时右侧不被推走——IN / OUT 两张附件卡始终在视野内。
 - **IN · Wire Input 面板**：见[上文 Wire Input 面板](#wire-input-面板in--hostplugin)。
 - **OUT · Native Calls 面板**：见[上文 Native Calls 面板](#native-calls-面板out--pluginhost与-fake-host)。
 - **Native 卡片壳**：卡片框（10 px padding / 7 px 圆角（native `radius.panelInner`）/ 1 px 描边（色取 `scenario.accentHex` 附件 tint，回退主题 accent）/ surfaceElevated 背景）是**外层卡片**，纵向堆叠 **body（插件挂载槽 `slotEl`）+ 按钮条**，对应 native `AttachmentRenderCardShell` 的 `VStack { body; actions }`。卡片宽度由滑杆控制，webview 按卡片 chrome（每边 11 px = 10 padding + 1 border）内嵌；卡片高度自动包裹 body + 按钮条。
-- **宽度滑杆**：拖动**卡片外层宽度**（webview 随之按 chrome 内嵌），范围随 view 切换。模式默认（取自 native）：renderer 初始 720 px、范围 [560,900]；action 初始 350 px、范围 [300,500]。`scenario.viewport.width` 可覆盖初始值；`viewport.widthMin`/`widthMax` 可覆盖滑杆范围。
+- **宽度滑杆**：拖动**卡片外层宽度**（webview 随之按 chrome 内嵌），范围随 view 切换。模式默认（取自 native）：renderer 初始 720 px、范围 [560,900]；Draft Action 初始 350 px、范围 [300,500]。`scenario.viewport.width` 可覆盖初始值；`viewport.widthMin`/`widthMax` 可覆盖滑杆范围。
 - **body 高度**：高度**由插件驱动**。native **没有**宿主侧"量内容定高"：`auto` 在 native 解析为 `bounded(80, 800)`，且只认 `clipbus.window.setHeight`——插件**必须**用 SDK `autoFit`（或手动 `setHeight`）自撑，否则卡在 policy 最小高度被裁。harness 在插件首个 `setHeight` 前以内容高度做种子（宽松的预览便利，**非** native 行为）。所有策略统一封顶 native 硬上限 **800**（`AttachmentRenderHeightConstants.ceiling`）。
 - **按钮条**：源自 `scenario.buttons`（及插件 `setButtons`），位于**卡片内部、body 下方、左对齐**（native action row 布局）；无按钮时不占位。
 - **主题感知滚动条**：工作台内所有滚动区域（dock 面板 + 插件内容）统一为细、半透明的滚动条，使用稳定的 bench 调色（不随主题变色）。

package/package.json

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