@clipbus/plugin-sdk 0.8.1 → 0.8.3

package/API.md

@@ -9,8 +9,8 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 
 ## 1. Overview
 
-- **Capabilities**: 28
-- **Host events**: 9
+- **Capabilities**: 29
+- **Host events**: 10
 - **Node IPC methods**: 6
 - **Named types**: 28
 
@@ -182,6 +182,16 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Payload**: { attachmentType: `string`, attachmentKey: `string` }
 - **Response**: { payloadJson?: `string` }
 
+### locale
+
+#### `locale.get`
+
+- **Side**: runtime
+- **Context**: any
+- **Path**: `locale.get`
+- **Payload**: {  }
+- **Response**: { locale: `string` }
+
 ### navigation
 
 #### `navigation.openUrl`
@@ -296,6 +306,7 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | `settings.getAll` | `clipbus.settings.getAll` | `host.settings.getAll` | any |
 | `console.log` | `clipbus.console.log` | `host.console.log` | any |
 | `textInput.stateChanged` | `clipbus.textInput.stateChanged` | — | any |
+| `locale.get` | — | `host.locale.get` | any |
 
 ## 4. Host Events
 
@@ -367,6 +378,14 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Context**: any
 - **Payload**: { panelID: `string` }
 
+### `clipbus-plugin-locale`
+
+- **Window global**: `__CLIPBUS_PLUGIN_LOCALE__`
+- **Topic**: `locale`
+- **Shape**: topic
+- **Context**: any
+- **Payload**: { locale: `string` }
+
 ## 5. Host Event Matrix
 
 | Event | Topic | Shape | Window global | Context |
@@ -380,6 +399,7 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | `clipbus-plugin-action-host-invoke` | action.onHostInvoke | stream | — | action |
 | `clipbus-plugin-info-panel-on-action` | infoPanel.onAction | stream | — | any |
 | `clipbus-plugin-info-panel-on-close` | infoPanel.onClose | stream | — | any |
+| `clipbus-plugin-locale` | locale | topic | `__CLIPBUS_PLUGIN_LOCALE__` | any |
 
 ## 6. Node IPC
 
@@ -626,6 +646,7 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 | `__CLIPBUS_PLUGIN_ATTACHMENT__` | `clipbus-plugin-attachment` |
 | `__CLIPBUS_PLUGIN_DRAFT__` | `clipbus-plugin-draft` |
 | `__CLIPBUS_PLUGIN_THEME__` | `clipbus-plugin-theme` |
+| `__CLIPBUS_PLUGIN_LOCALE__` | `clipbus-plugin-locale` |
 
 ## 11. Generated Symbol Map
 

package/README.md

@@ -161,6 +161,12 @@ These verbs are available on the `ctx.host` object passed to every runtime handl
 | `settings.get({key})` | `Promise<{value: string \| null}>` | Read a single plugin setting |
 | `settings.getAll()` | `Promise<{settings: Record<string, string>}>` | Read all plugin settings |
 
+#### `ctx.host.locale`
+
+| Method | Returns | Description |
+|---|---|---|
+| `locale.get()` | `Promise<{locale: string}>` | Read the host's current interface locale. Values: `"en"`, `"ja"`, `"zh-Hans"`. Wrap in try/catch when targeting older hosts that may not support this capability. |
+
 ---
 
 ## DOM utilities (`@clipbus/plugin-sdk/dom`)
@@ -232,6 +238,19 @@ There is **no** `clipbus.theme.refresh()` or `clipbus.theme.getThemeSnapshot()`
 
 ---
 
+### `clipbus.locale` — Topic\<PluginLocalePayload\>
+
+| Member | Shape | Description |
+|---|---|---|
+| `clipbus.locale.current()` | `() → PluginLocalePayload \| undefined` | Read current locale. The host injects `__CLIPBUS_PLUGIN_LOCALE__` at WebView startup, so this is synchronously available in practice. |
+| `clipbus.locale.on(fn)` | `(fn) → Unsubscribe` | Subscribe to the `clipbus-plugin-locale` host event. The host locale is fixed per app session (changing it requires a restart), so this rarely fires after the initial value — it exists for parity with other topics. |
+
+Locale values: `"en"`, `"ja"`, `"zh-Hans"` (the host's current interface language).
+
+`current()` may return `undefined` when the host has not yet injected the value. Defend with a fallback at the call site: `clipbus.locale.current()?.locale ?? 'en'`.
+
+---
+
 ### `clipbus.asset` — local image URLs for `<img>` (any context)
 
 Returns opaque `clipbus-asset://` URLs so a WebView can render local images in `<img>` without ever seeing a real file path (the WebView sandbox blocks `file://`). The host resolves the token internally; tokens are session-scoped and invalidated when the owner is released.

package/SPECIFICATION.md

@@ -176,6 +176,7 @@ Capabilities are split by catalog `surface.side`: runtime capabilities are expos
 | Open file | `navigation.openFilePath` | `ctx.host.navigation.openFilePath({path})` | `clipbus.navigation.openFilePath({path})` | Verb; strict wire shape |
 | Settings get | `settings.get` | `ctx.host.settings.get({key})` | `clipbus.settings.get({key})` | Verb; strict wire shape |
 | Settings get all | `settings.getAll` | `ctx.host.settings.getAll()` | `clipbus.settings.getAll()` | Verb |
+| Locale get | `locale.get` | `ctx.host.locale.get()` | — | Verb; returns `{ locale: string }`, values: `"en" \| "ja" \| "zh-Hans"`; runtime-only |
 
 ### 2.1 `side:'both'` symmetry
 
@@ -219,6 +220,7 @@ Host events declared in the catalog drive every state Topic / Stream the SDK exp
 | `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-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 }` |
 | `clipbus-plugin-action-host-invoke` | `clipbus.action.onHostInvoke` | — | stream | action | `{ buttonID: string }` |
 

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

@@ -167,7 +167,12 @@ export interface PluginTextInputStateChangedPayload {
 }
 export interface PluginTextInputStateChangedResponse {
 }
-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"];
+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 type CapabilityMethodName = (typeof CAPABILITY_METHOD_NAMES)[number];
 export declare const callRuntimeInvoke: (payload: PluginRuntimeInvokePayload) => Promise<PluginRuntimeInvokeResponse>;
 export declare const callItemSetTags: (payload: PluginItemSetTagsPayload) => Promise<PluginItemSetTagsResponse>;
@@ -197,3 +202,4 @@ export declare const callSettingsGet: (payload: PluginSettingsGetPayload) => Pro
 export declare const callSettingsGetAll: () => Promise<PluginSettingsGetAllResponse>;
 export declare const callConsoleLog: (payload: PluginConsoleLogPayload) => Promise<PluginConsoleLogResponse>;
 export declare const callTextInputStateChanged: (payload: PluginTextInputStateChangedPayload) => Promise<PluginTextInputStateChangedResponse>;
+export declare const callLocaleGet: () => Promise<PluginLocaleGetResponse>;

package/dist/generated/hostClients.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, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
+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';
 export interface IPCBus {
     request<Req, Resp>(method: string, payload: Req): Promise<Resp>;
 }
@@ -25,6 +25,9 @@ export interface HostClient {
         materializeImagePath(): Promise<PluginItemMaterializeImagePathResponse>;
         readAttachment(payload: PluginItemReadAttachmentPayload): Promise<PluginItemReadAttachmentResponse>;
     };
+    locale: {
+        get(): Promise<PluginLocaleGetResponse>;
+    };
     navigation: {
         openUrl(payload: PluginNavigationOpenUrlPayload): Promise<PluginNavigationOpenUrlResponse>;
         revealInFinder(payload: PluginNavigationRevealInFinderPayload): Promise<PluginNavigationRevealInFinderResponse>;

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, PluginNavigationOpenFilePathPayload, PluginNavigationOpenFilePathResponse, PluginNavigationOpenUrlPayload, PluginNavigationOpenUrlResponse, PluginNavigationRevealInFinderPayload, PluginNavigationRevealInFinderResponse, PluginSettingsGetAllResponse, PluginSettingsGetPayload, PluginSettingsGetResponse } from './capabilityClients.generated.js';
+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';
 export declare const host: {
     item: {
         setTags: (payload: PluginItemSetTagsPayload) => Promise<PluginItemSetTagsResponse>;
@@ -31,4 +31,7 @@ export declare const host: {
     console: {
         log: (payload: PluginConsoleLogPayload) => Promise<PluginConsoleLogResponse>;
     };
+    locale: {
+        get: () => Promise<PluginLocaleGetResponse>;
+    };
 };

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

@@ -30,3 +30,8 @@ export interface PluginInfoPanelOnClosePayload {
     panelID: string;
 }
 export declare function onInfoPanelOnClose(listener: (payload: PluginInfoPanelOnClosePayload) => void): () => void;
+export interface PluginLocalePayload {
+    locale: string;
+}
+export declare function onLocale(listener: (payload: PluginLocalePayload) => void): () => void;
+export declare function getLocaleSnapshot(): PluginLocalePayload | undefined;

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

@@ -1,5 +1,5 @@
 import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
-import type { PluginActionHostInvokePayload, PluginAttachmentHostInvokePayload, PluginContextPayload, PluginInfoPanelOnActionPayload, PluginInfoPanelOnClosePayload } from './topicSubscribers.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>;
@@ -9,6 +9,7 @@ export declare const _attachmentRendererOnHostInvokeStream: import("../internal/
 export declare const _actionOnHostInvokeStream: import("../internal/topic.js").MutableStream<PluginActionHostInvokePayload>;
 export declare const _infoPanelOnActionStream: import("../internal/topic.js").MutableStream<PluginInfoPanelOnActionPayload>;
 export declare const _infoPanelOnCloseStream: import("../internal/topic.js").MutableStream<PluginInfoPanelOnClosePayload>;
+export declare const _localeTopic: import("../internal/topic.js").MutableTopic<PluginLocalePayload>;
 export declare class PluginContextError extends Error {
     constructor(message: string);
 }

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

@@ -1,6 +1,6 @@
 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 { PluginActionHostInvokePayload, PluginAttachmentHostInvokePayload, PluginContextPayload, PluginInfoPanelOnActionPayload, PluginInfoPanelOnClosePayload } from './topicSubscribers.generated.js';
+import type { PluginActionHostInvokePayload, PluginAttachmentHostInvokePayload, PluginContextPayload, PluginInfoPanelOnActionPayload, PluginInfoPanelOnClosePayload, PluginLocalePayload } from './topicSubscribers.generated.js';
 export declare const clipbus: {
     capabilities: import("../internal/capabilities.js").CapabilitiesApi;
     runtime: {
@@ -76,4 +76,8 @@ export declare const clipbus: {
         current: () => PluginThemeTokenSnapshot | undefined;
         on: (fn: (payload: PluginThemeTokenSnapshot) => void) => import("../internal/topic.js").Unsubscribe;
     };
+    locale: {
+        current: () => PluginLocalePayload | undefined;
+        on: (fn: (payload: PluginLocalePayload) => void) => import("../internal/topic.js").Unsubscribe;
+    };
 };

package/dist/runtime/index.cjs

@@ -87,6 +87,9 @@ var host = {
   },
   console: {
     log: (payload) => ipcBus.request("console.log", payload)
+  },
+  locale: {
+    get: () => ipcBus.request("locale.get", {})
   }
 };
 

package/dist/runtime/index.js

@@ -57,6 +57,9 @@ var host = {
   },
   console: {
     log: (payload) => ipcBus.request("console.log", payload)
+  },
+  locale: {
+    get: () => ipcBus.request("locale.get", {})
   }
 };
 

package/dist/ui/index.cjs

@@ -237,6 +237,11 @@ function onInfoPanelOnClose(listener) {
   globalThis.addEventListener("clipbus-plugin-info-panel-on-close", handler);
   return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-close", handler);
 }
+function onLocale(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-locale", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-locale", handler);
+}
 
 // src/generated/ui.bootstrap.generated.ts
 var _pluginContextTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_CONTEXT__"));
@@ -257,6 +262,8 @@ var _infoPanelOnActionStream = createStream();
 onInfoPanelOnAction((p) => _infoPanelOnActionStream.emit(p));
 var _infoPanelOnCloseStream = createStream();
 onInfoPanelOnClose((p) => _infoPanelOnCloseStream.emit(p));
+var _localeTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_LOCALE__"));
+onLocale((p) => _localeTopic.set(p));
 var PluginContextError = class extends Error {
   constructor(message) {
     super(message);
@@ -350,6 +357,10 @@ var clipbus = {
   theme: {
     current: () => _themeTopic.current(),
     on: (fn) => _themeTopic.on(fn)
+  },
+  locale: {
+    current: () => _localeTopic.current(),
+    on: (fn) => _localeTopic.on(fn)
   }
 };
 

package/dist/ui/index.js

@@ -208,6 +208,11 @@ function onInfoPanelOnClose(listener) {
   globalThis.addEventListener("clipbus-plugin-info-panel-on-close", handler);
   return () => globalThis.removeEventListener("clipbus-plugin-info-panel-on-close", handler);
 }
+function onLocale(listener) {
+  const handler = (e) => listener(e.detail);
+  globalThis.addEventListener("clipbus-plugin-locale", handler);
+  return () => globalThis.removeEventListener("clipbus-plugin-locale", handler);
+}
 
 // src/generated/ui.bootstrap.generated.ts
 var _pluginContextTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_CONTEXT__"));
@@ -228,6 +233,8 @@ var _infoPanelOnActionStream = createStream();
 onInfoPanelOnAction((p) => _infoPanelOnActionStream.emit(p));
 var _infoPanelOnCloseStream = createStream();
 onInfoPanelOnClose((p) => _infoPanelOnCloseStream.emit(p));
+var _localeTopic = createTopic(readWindowGlobal("__CLIPBUS_PLUGIN_LOCALE__"));
+onLocale((p) => _localeTopic.set(p));
 var PluginContextError = class extends Error {
   constructor(message) {
     super(message);
@@ -321,6 +328,10 @@ var clipbus = {
   theme: {
     current: () => _themeTopic.current(),
     on: (fn) => _themeTopic.on(fn)
+  },
+  locale: {
+    current: () => _localeTopic.current(),
+    on: (fn) => _localeTopic.on(fn)
   }
 };
 

package/dist/validate/index.cjs

@@ -286,7 +286,11 @@ function validateManifest(manifest, options = {}) {
     issues.push(issue("missingRuntimeEntry", `Missing runtime entry: ${nodeEntry}`));
   }
   const uiRootAbs = import_node_path.default.resolve(rootDir, uiRoot);
-  if (!(0, import_node_fs.existsSync)(uiRootAbs)) {
+  const declaresUISurface = renderers.length > 0 || asRecordArray(raw["actions"]).some((a) => {
+    const entry = asString(a["uiEntry"])?.trim();
+    return entry !== void 0 && entry.length > 0;
+  });
+  if (declaresUISurface && !(0, import_node_fs.existsSync)(uiRootAbs)) {
     issues.push(issue("missingUIRoot", `Missing UI root: ${uiRoot}`));
   }
   for (const renderer of renderers) {

package/dist/validate/index.js

@@ -251,7 +251,11 @@ function validateManifest(manifest, options = {}) {
     issues.push(issue("missingRuntimeEntry", `Missing runtime entry: ${nodeEntry}`));
   }
   const uiRootAbs = path.resolve(rootDir, uiRoot);
-  if (!existsSync(uiRootAbs)) {
+  const declaresUISurface = renderers.length > 0 || asRecordArray(raw["actions"]).some((a) => {
+    const entry = asString(a["uiEntry"])?.trim();
+    return entry !== void 0 && entry.length > 0;
+  });
+  if (declaresUISurface && !existsSync(uiRootAbs)) {
     issues.push(issue("missingUIRoot", `Missing UI root: ${uiRoot}`));
   }
   for (const renderer of renderers) {

package/docs/manifest.md

@@ -47,6 +47,8 @@
 | `runtime.nodeEntry` | `string` | 是 | Node runtime 入口（编译后 `.cjs`） |
 | `runtime.uiRoot` | `string` | 是 | UI 根目录；所有 `uiEntry` 相对此目录 |
 
+> **关于 `uiRoot` 目录存在性**：`uiRoot` 是必填*声明*，但其指向目录（如 `dist/ui`）只在插件声明 UI 面时才需在磁盘存在——即有任意 `attachmentRenderers`，或任意带 `uiEntry` 的 `action`。纯 auto-run-action 插件（无 renderer / detector / action uiEntry）构建后无需产出 `dist/ui`，`clipbus-validate-manifest --runtime` 与宿主加载期都不会因其缺失而失败。
+
 ---
 
 ## `permissions`

package/package.json

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