@clipbus/plugin-sdk 0.9.9 → 0.10.0

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**: 33
+- **Capabilities**: 35
 - **Host events**: 11
 - **Node IPC methods**: 6
-- **Named types**: 31
+- **Named types**: 40
 
 ## 2. Capabilities
 
@@ -92,6 +92,14 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Payload**: { index: `int` }
 - **Response**: { url?: `string` }
 
+#### `asset.allocateImageTempPath`
+
+- **Side**: runtime
+- **Context**: any
+- **Path**: `asset.allocateImageTempPath`
+- **Payload**: { formatHint: `string` }
+- **Response**: { path: `string` }
+
 #### `asset.registerImage`
 
 - **Side**: runtime
@@ -130,6 +138,14 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 - **Payload**: { level: [`PluginConsoleLogLevel`](#pluginconsoleloglevel), message: `string` }
 - **Response**: {  }
 
+#### `console.diagnostic`
+
+- **Side**: both
+- **Context**: any
+- **Path**: `console.diagnostic`
+- **Payload**: { level: [`PluginConsoleLogLevel`](#pluginconsoleloglevel), event: [`PluginDiagnosticEvent`](#plugindiagnosticevent), reason: [`PluginDiagnosticReason`](#plugindiagnosticreason), count: `int`, durationMs: `int` }
+- **Response**: {  }
+
 ### infoPanel
 
 #### `infoPanel.open`
@@ -311,26 +327,27 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | Capability | UI path | Runtime path | Context |
 | --- | --- | --- | --- |
 | `runtime.invoke` | `clipbus.runtime.invoke` | — | any |
-| `item.setTags` | — | `host.item.setTags` | any |
-| `item.addTags` | — | `host.item.addTags` | any |
-| `item.removeTags` | — | `host.item.removeTags` | any |
-| `item.setPinned` | — | `host.item.setPinned` | any |
-| `item.setAttachments` | — | `host.item.setAttachments` | any |
-| `item.setSearchExtension` | — | `host.item.setSearchExtension` | any |
-| `item.materializeImagePath` | — | `host.item.materializeImagePath` | any |
-| `item.readAttachment` | `clipbus.item.readAttachment` | `host.item.readAttachment` | any |
+| `item.setTags` | — | `ctx.host.item.setTags` | any |
+| `item.addTags` | — | `ctx.host.item.addTags` | any |
+| `item.removeTags` | — | `ctx.host.item.removeTags` | any |
+| `item.setPinned` | — | `ctx.host.item.setPinned` | any |
+| `item.setAttachments` | — | `ctx.host.item.setAttachments` | any |
+| `item.setSearchExtension` | — | `ctx.host.item.setSearchExtension` | any |
+| `item.materializeImagePath` | — | `ctx.host.item.materializeImagePath` | any |
+| `item.readAttachment` | `clipbus.item.readAttachment` | `ctx.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 |
+| `asset.allocateImageTempPath` | — | `ctx.host.asset.allocateImageTempPath` | any |
+| `asset.registerImage` | — | `ctx.host.asset.registerImage` | any |
+| `clipboard.copyText` | `clipbus.clipboard.copyText` | `ctx.host.clipboard.copyText` | any |
+| `navigation.openUrl` | `clipbus.navigation.openUrl` | `ctx.host.navigation.openUrl` | any |
+| `navigation.revealInFinder` | `clipbus.navigation.revealInFinder` | `ctx.host.navigation.revealInFinder` | any |
+| `navigation.openFilePath` | `clipbus.navigation.openFilePath` | `ctx.host.navigation.openFilePath` | any |
+| `action.allocateImageTempPath` | — | `ctx.host.action.allocateImageTempPath` | action |
+| `action.materializeInputImagePath` | — | `ctx.host.action.materializeInputImagePath` | action |
+| `action.allocateOutputFilePath` | — | `ctx.host.action.allocateOutputFilePath` | action |
 | `action.setButtons` | `clipbus.action.setButtons` | — | action |
 | `action.complete` | `clipbus.action.complete` | — | action |
 | `attachmentRenderer.setButtons` | `clipbus.attachmentRenderer.setButtons` | — | attachmentRenderer |
@@ -338,11 +355,12 @@ Every entry below maps 1:1 to a catalog descriptor — there is no hidden surfac
 | `window.autoFit` | `clipbus.window.autoFit` | — | any |
 | `infoPanel.open` | `clipbus.infoPanel.open` | — | any |
 | `infoPanel.close` | `clipbus.infoPanel.close` | — | any |
-| `settings.get` | `clipbus.settings.get` | `host.settings.get` | any |
-| `settings.getAll` | `clipbus.settings.getAll` | `host.settings.getAll` | any |
-| `console.log` | `clipbus.console.log` | `host.console.log` | any |
+| `settings.get` | `clipbus.settings.get` | `ctx.host.settings.get` | any |
+| `settings.getAll` | `clipbus.settings.getAll` | `ctx.host.settings.getAll` | any |
+| `console.log` | `clipbus.console.log` | `ctx.host.console.log` | any |
+| `console.diagnostic` | `clipbus.console.diagnostic` | `ctx.host.console.diagnostic` | any |
 | `textInput.stateChanged` | `clipbus.textInput.stateChanged` | — | any |
-| `locale.get` | — | `host.locale.get` | any |
+| `locale.get` | — | `ctx.host.locale.get` | any |
 
 ## 4. Host Events
 
@@ -560,6 +578,14 @@ Discriminated union on `type`: { type: `'label'`, text: `string` } | { type: `'t
 
 Union: `'debug'` | `'info'` | `'warn'` | `'error'`
 
+### `PluginDiagnosticEvent`
+
+Union: `'action_started'` | `'action_completed'` | `'action_failed'` | `'renderer_ready'` | `'renderer_failed'` | `'detector_completed'` | `'detector_failed'` | `'runtime_ready'` | `'runtime_failed'`
+
+### `PluginDiagnosticReason`
+
+Union: `'none'` | `'invalid_input'` | `'unsupported'` | `'timeout'` | `'unavailable'` | `'failed'`
+
 ### `PluginClipboardItem`
 
 - `id`: `string`
@@ -689,6 +715,46 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 - `result`: [`PluginActionResult`](#pluginactionresult)
 - `userMessage?`: `string`
 
+### `PluginNodeIPCRequestFrame`
+
+- `id`: `string`
+- `method`: `string`
+- `request`: `json`
+
+### `PluginNodeIPCResponseFrame`
+
+- `id?`: `string`
+- `response?`: `json`
+- `error?`: `json`
+
+### `PluginNodeIPCErrorFrame`
+
+- `name`: `string`
+- `message`: `string`
+- `data?`: `json`
+
+### `PluginRuntimePluginDescriptor`
+
+- `id`: `string`
+- `title`: `string`
+- `version`: `string`
+
+### `PluginRuntimeHostPlatform`
+
+Union: `'macos'` | `'windows'`
+
+### `PluginRuntimeHostDescriptor`
+
+- `platform`: [`PluginRuntimeHostPlatform`](#pluginruntimehostplatform)
+- `hostVersion`: `string`
+- `devMode`: `bool`
+
+### `PluginRuntimeLaunchContext`
+
+- `plugin`: [`PluginRuntimePluginDescriptor`](#pluginruntimeplugindescriptor)
+- `host`: [`PluginRuntimeHostDescriptor`](#pluginruntimehostdescriptor)
+- `supportedCapabilities`: `string`[]
+
 ## 9. Wire Constants
 
 - `__clipbus_structured_error__:` — prefix used by the runtime error envelope.
@@ -709,11 +775,12 @@ Discriminated union on `kind`: { kind: `'text'`, text: `string` } | { kind: `'im
 
 | Concept | Generated file (TS) | Generated file (Swift) |
 | --- | --- | --- |
-| Capability payload/response types | `capabilityClients.generated.ts` | `PluginCapabilityPayloads.generated.swift` |
+| Capability payload/response types + method map | `capabilities.generated.ts` | `PluginCapabilityPayloads.generated.swift` |
 | UI capability tree | `ui.clipbus.generated.ts` | — |
-| Runtime host tree | `runtime.host.generated.ts`, `hostClients.generated.ts` | — |
-| Host event subscribers | `topicSubscribers.generated.ts` | `PluginHostTopicEmitter.generated.swift` |
-| Node IPC server | `nodeIPCServer.generated.ts` | `PluginNodeIPCClient.generated.swift` |
+| Runtime host client (`ctx.host`) | `hostClients.generated.ts` | — |
+| Host events (payloads, window globals, bootstrap sets) | `hostEvents.generated.ts` | `PluginHostTopicEmitter.generated.swift` |
+| Node IPC types + handler routes | `nodeIPC.generated.ts` | `PluginNodeIPCClient.generated.swift` |
 | Named types | `data.generated.ts` | `PluginCommonTypes.generated.swift` |
 | Handler interfaces | `runtime.handlers.generated.ts` | `PluginUIHostHandler.generated.swift`, `PluginRuntimeHostHandler.generated.swift` |
-| `definePlugin` + registry | `runtime.definePlugin.generated.ts` | — |
+| Registry / setup types | `runtime.registry.generated.ts` | — |
+| Wire constants | `wireConstants.generated.ts` | `PluginWireConstants.generated.swift` |

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+Release notes for `@clipbus/plugin-sdk`, newest first. Each version is also published at https://github.com/scubers/clipbus-release/releases?q=%22Clipbus+Plugin+SDK%22&expanded=true
+
+## 0.10.0
+
+### New
+
+- **Session-owned temporary paths for generated images**: `ctx.host.asset.allocateImageTempPath({ formatHint })` allocates an image path owned by the current session in any runtime context. Write the image there, then call `ctx.host.asset.registerImage({ path })` to get a URL the WebView can render. The path expires with its owning session; neither method is callable from the WebView.
+- **Structured diagnostics**: `clipbus.console.diagnostic(...)` (UI) and `ctx.host.console.diagnostic(...)` (runtime) take `{ level, event, reason, count, durationMs }`, where `event` and `reason` come from the closed `PluginDiagnosticEvent` / `PluginDiagnosticReason` vocabularies. Use it for anything you need to see in the Log Console:
+
+  ```ts
+  await clipbus.console.diagnostic({ level: 'info', event: 'action_completed', reason: 'none', count: 1, durationMs: 42 });
+  ```
+
+  Hosts that support it record only the level and byte count of `console.log`, not the message text. Diagnostic volume is bounded and excess calls may be rejected.
+- **Runtime type exports**: `@clipbus/plugin-sdk/runtime` now exports `PluginRegistry`, `PluginSetup`, `MessageHandler`, `MessageHandlerContext`, `HostClient` (the type of `ctx.host`) and `PluginRuntimeLaunchContext`. The `context` argument of `definePlugin({ setup(context) { ... } })` is now typed and carries `plugin`, `host` and `supportedCapabilities`.
+
+### Breaking changes
+
+- **The `host` export of `@clipbus/plugin-sdk/runtime` is removed.** It was never connected to the Host and threw on every call. Use `ctx.host` from the handler context instead; in ESM, a remaining `import { host }` makes the module fail to load.
+
+  ```ts
+  // Before
+  import { host } from '@clipbus/plugin-sdk/runtime';
+  await host.clipboard.copyText({ text });
+
+  // After
+  async runAutoAction(input, ctx) {
+    await ctx?.host?.clipboard.copyText({ text });
+    // ...
+  }
+  ```
+
+### Compatibility
+
+- `asset.allocateImageTempPath` and `console.diagnostic` require Clipbus for macOS 1.6.0 or Clipbus for Windows 0.1.0 or later. Older Hosts reject them with `CapabilityUnsupportedError`; check `clipbus.capabilities.has(...)` or the launch context's `supportedCapabilities` first.
+- Everything else takes effect by upgrading the npm package.
+
+### Other
+
+- The npm package now ships `CHANGELOG.md`, and every version's notes are published as [Plugin SDK releases](https://github.com/scubers/clipbus-release/releases?q=%22Clipbus+Plugin+SDK%22&expanded=true). The package `homepage` and `repository` now point to that release repository.
+
+<details>
+<summary>简体中文</summary>
+
+### 新增
+
+- **运行时生成图片的会话临时路径**：`ctx.host.asset.allocateImageTempPath({ formatHint })` 在任意运行时上下文中分配一个归属当前会话的图片路径，写入图片后再调用 `ctx.host.asset.registerImage({ path })` 获得 WebView 可渲染的 URL。路径随所属会话一起失效；WebView 侧不能调用这两个方法。
+- **结构化诊断日志**：新增 `clipbus.console.diagnostic(...)`（UI）与 `ctx.host.console.diagnostic(...)`（运行时），参数为 `{ level, event, reason, count, durationMs }`，`event` / `reason` 取自封闭枚举 `PluginDiagnosticEvent` / `PluginDiagnosticReason`。需要在 Log Console 中查看的信息请改用它：
+
+  ```ts
+  await clipbus.console.diagnostic({ level: 'info', event: 'action_completed', reason: 'none', count: 1, durationMs: 42 });
+  ```
+
+  支持该能力的 Host 只记录 `console.log` 的级别与字节数，不记录消息正文；诊断调用量有上限，超出可能被拒绝。
+- **运行时类型导出**：`@clipbus/plugin-sdk/runtime` 现在导出 `PluginRegistry`、`PluginSetup`、`MessageHandler`、`MessageHandlerContext`、`HostClient`（即 `ctx.host` 的类型）以及 `PluginRuntimeLaunchContext`。`definePlugin({ setup(context) { ... } })` 中的 `context` 有了类型，包含 `plugin`、`host` 与 `supportedCapabilities`。
+
+### 不兼容变更
+
+- **移除 `@clipbus/plugin-sdk/runtime` 的 `host` 导出**。该对象从未接通 Host，任何调用都会抛错。请改用处理函数上下文中的 `ctx.host`；在 ESM 中保留 `import { host }` 会导致模块加载失败。
+
+  ```ts
+  // 之前
+  import { host } from '@clipbus/plugin-sdk/runtime';
+  await host.clipboard.copyText({ text });
+
+  // 之后
+  async runAutoAction(input, ctx) {
+    await ctx?.host?.clipboard.copyText({ text });
+    // ...
+  }
+  ```
+
+### 兼容性
+
+- `asset.allocateImageTempPath` 与 `console.diagnostic` 需要 Clipbus macOS 1.6.0 或 Windows 0.1.0 及以上版本。较旧的 Host 会以 `CapabilityUnsupportedError` 拒绝，可先用 `clipbus.capabilities.has(...)` 或启动上下文中的 `supportedCapabilities` 检测。
+- 其余变更只需升级 npm 包即可生效。
+
+### 其他
+
+- npm 包内新增 `CHANGELOG.md`，各版本说明同时发布在 [Plugin SDK releases](https://github.com/scubers/clipbus-release/releases?q=%22Clipbus+Plugin+SDK%22&expanded=true)；包的 `homepage` 与 `repository` 改为指向该发布仓库。
+
+</details>

package/README.md

@@ -2,6 +2,8 @@
 
 Standalone, publishable SDK for Clipbus plugins. Provides typed helpers for the runtime (Node.js) and UI (WebView) sides of a plugin.
 
+Release notes for every version are published as [Plugin SDK releases](https://github.com/scubers/clipbus-release/releases?q=%22Clipbus+Plugin+SDK%22&expanded=true) and ship in this package as `CHANGELOG.md`.
+
 ## Installation
 
 Install from npm:
@@ -288,7 +290,7 @@ Returns opaque `clipbus-asset://` URLs so a WebView can render local images in `
 | `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.
+Generated images are minted only on the runtime side: allocate a session-owned path with `ctx.host.asset.allocateImageTempPath({formatHint})`, write the image, then call `ctx.host.asset.registerImage({path})`. The WebView cannot call either method or mint a URL for a local file.
 
 ```ts
 import { clipbus } from '@clipbus/plugin-sdk/ui';
@@ -462,18 +464,21 @@ clipbus.infoPanel.onClose.on(({ panelID }) => { /* clean up */ });
 
 | Member | Shape | Description |
 |---|---|---|
-| `clipbus.console.log({level, message})` | `Verb` | Write a log line to the host log (`level: 'debug' \| 'info' \| 'warn' \| 'error'`) |
+| `clipbus.console.log({level, message})` | `Verb` | Send legacy console output; the host records only level and UTF-8 byte count, not the message text |
+| `clipbus.console.diagnostic({level, event, reason, count, durationMs})` | `Verb` | Record a structured, privacy-safe diagnostic using the closed event/reason vocabulary in `API.md` |
 | `clipbus.textInput.stateChanged({isFocused, isComposing})` | `Verb` | Notify host that a text input's focus / IME state changed |
 | `clipbus.pluginContext.current()` | Topic | `{ mode: 'attachmentRenderer' \| 'action', pluginID }` — read which kind of WebView this code is running in |
 | `clipbus.pluginContext.on(fn)` | Topic | Subscribe (rare; context doesn't normally change after bootstrap) |
 
 > Strict wire shape: every verb takes a single object parameter (`{text}`, `{url}`, etc.), never a bare value. The single source of truth for every payload / response shape is [API.md](./API.md), generated from `protocol/plugin/src/catalog.ts`.
 
+Use `console.diagnostic` for information you need in the Log Console. For example, `await clipbus.console.diagnostic({ level: 'info', event: 'action_completed', reason: 'none', count: 1, durationMs: 42 })`. Do not put clipboard content, paths, identifiers, or secrets into log messages; the structured channel has no field for them. The host bounds diagnostic volume and may reject excess calls.
+
 ---
 
 ## Types
 
-All public types live in the generated `data.generated.ts` / `capabilityClients.generated.ts` and carry the `Plugin` prefix. The pre-`plugin-api-shrink` aliases without the prefix have been removed.
+All public types live in the generated `data.generated.ts` / `capabilities.generated.ts` (plus `hostClients.generated.ts` and `runtime.registry.generated.ts` for the runtime entry) and carry the `Plugin` prefix. The pre-`plugin-api-shrink` aliases without the prefix have been removed.
 
 ```ts
 // Data types — re-exported from both /runtime and /ui
@@ -513,8 +518,11 @@ import type {
 // definePlugin types — runtime side only
 import type {
   PluginRegistry,
+  PluginSetup,
+  PluginRuntimeLaunchContext,      // setup(context) argument
   MessageHandler,
   MessageHandlerContext,
+  HostClient,                      // the type of ctx.host
 } from '@clipbus/plugin-sdk/runtime';
 ```
 

package/SPECIFICATION.md

@@ -179,6 +179,7 @@ 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; 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 |
+| Allocate session image path | `asset.allocateImageTempPath` | `ctx.host.asset.allocateImageTempPath({formatHint})` | — | Runtime-only, any context with a temporary-resource owner; path expires with that owner |
 | 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 |
@@ -273,7 +274,7 @@ The plugin wire is fully codegen-driven. Choosing between `defineCapability` and
 
 6. **Test** — add host bridge tests for the new method. Do not write pure UI unit tests; codegen snapshot tests cover the surface.
 
-7. **Verify locally** — `./scripts/checks/check-plugin-contract.sh` and the host platform test flow must both exit 0.
+7. **Verify locally** — `cd protocol/plugin && npm test`, `./scripts/checks/check-plugin-contract.sh` and the host platform test flow must all exit 0.
 
 8. **PR** — see Chapter 5 for the PR checklist.
 
@@ -366,7 +367,7 @@ Before merging any PR that touches `sdk/`:
 - [ ] `npm run build` passes in `sdk/`
 - [ ] `npm test` passes in `sdk/` (runtime + ui + surface)
 - [ ] Surface snapshot updated with `SNAPSHOT_UPDATE=1` and golden files committed
-- [ ] No references to host-internal paths, WebKit handler names, or host implementation class names in any `*.md` file under `sdk/` (run the doc-grep CI step to verify)
+- [ ] No references to host-internal paths, WebKit handler names, or host implementation class names in any `*.md` file under `sdk/` (checked in review)
 - [ ] PR description cites the SPECIFICATION.md chapter number justifying shape choice
 - [ ] `npm test` passes in `plugins/template-plugin/` (template plugin integration tests)
 - [ ] `./scripts/checks/check-plugin-contract.sh` exits 0

package/dist/dom/index.cjs

@@ -30,6 +30,14 @@ module.exports = __toCommonJS(index_exports);
 // src/generated/wireConstants.generated.ts
 var STRUCTURED_ERROR_PREFIX = "__clipbus_structured_error__:";
 var CAPABILITY_UNSUPPORTED_ERROR_NAME = "PluginCapabilityUnsupported";
+var PLUGIN_CALL_HANDLER_NAME = "clipbusPluginCall";
+var WIRE_ERROR_NAMES = {
+  methodNotFound: "PluginRuntimeMethodNotFound",
+  handlerNotFound: "PluginRuntimeHandlerNotFound",
+  invocationExpired: "PluginRuntimeInvocationExpired",
+  hostCallLimitExceeded: "PluginRuntimeHostCallLimitExceeded",
+  hostBridgeUnavailable: "PluginHostBridgeUnavailable"
+};
 
 // src/internal/capabilities.ts
 var CapabilityUnsupportedError = class extends Error {
@@ -51,20 +59,29 @@ function mapToCapabilityError(err, unsupportedName) {
   return err;
 }
 
-// src/internal/runtimeInvokeClient.ts
+// src/internal/pluginCall.ts
+async function callPluginMethod(method, payload) {
+  const handler = globalThis.webkit?.messageHandlers?.[PLUGIN_CALL_HANDLER_NAME];
+  if (!handler) {
+    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
+    err.name = WIRE_ERROR_NAMES.hostBridgeUnavailable;
+    throw err;
+  }
+  const normalized = JSON.parse(JSON.stringify(payload));
+  try {
+    return await handler.postMessage({ method, payload: normalized });
+  } catch (err) {
+    throw parseReplyError(err);
+  }
+}
 function parseReplyError(raw) {
   const message = extractMessage(raw);
   if (message.startsWith(STRUCTURED_ERROR_PREFIX)) {
-    const json = message.slice(STRUCTURED_ERROR_PREFIX.length);
     try {
-      const parsed = JSON.parse(json);
+      const parsed = JSON.parse(message.slice(STRUCTURED_ERROR_PREFIX.length));
       const err = new Error(typeof parsed.message === "string" ? parsed.message : "");
-      if (typeof parsed.name === "string" && parsed.name.length > 0) {
-        err.name = parsed.name;
-      }
-      if (parsed.data !== void 0) {
-        err.data = parsed.data;
-      }
+      if (typeof parsed.name === "string" && parsed.name.length > 0) err.name = parsed.name;
+      if (parsed.data !== void 0) err.data = parsed.data;
       return mapToCapabilityError(err, CAPABILITY_UNSUPPORTED_ERROR_NAME);
     } catch {
       return new Error(message);
@@ -82,28 +99,6 @@ function extractMessage(raw) {
   return String(raw);
 }
 
-// src/generated/capabilityClients.generated.ts
-var HANDLER_NAME = "clipbusPluginCall";
-async function callPluginMethod(method, payload) {
-  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME];
-  if (!handler) {
-    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
-    err.name = "PluginHostBridgeUnavailable";
-    throw err;
-  }
-  const normalized = JSON.parse(JSON.stringify(payload));
-  let reply;
-  try {
-    reply = await handler.postMessage({ method, payload: normalized });
-  } catch (err) {
-    throw parseReplyError(err);
-  }
-  return reply;
-}
-var callWindowSetHeight = (payload) => callPluginMethod("window.setHeight", payload);
-var callConsoleLog = (payload) => callPluginMethod("console.log", payload);
-var callTextInputStateChanged = (payload) => callPluginMethod("textInput.stateChanged", payload);
-
 // src/internal/internalConsole.ts
 function pick(method) {
   if (typeof globalThis === "undefined") return () => {
@@ -137,7 +132,7 @@ function autoFit(options) {
       pending = false;
       const raw = target.scrollHeight;
       const clamped = Math.min(max, Math.max(min, raw));
-      callWindowSetHeight({ height: clamped }).catch((err) => {
+      callPluginMethod("window.setHeight", { height: clamped }).catch((err) => {
         internalConsole.warn("[clipbus-sdk] autoFit: window.setHeight failed:", err);
       });
     });
@@ -163,7 +158,7 @@ function patchConsole() {
     original(...args);
     if (_inFlight > 0) return;
     _inFlight++;
-    Promise.resolve().then(() => callConsoleLog({ level, message: args.map(String).join(" ") })).catch((err) => {
+    Promise.resolve().then(() => callPluginMethod("console.log", { level, message: args.map(String).join(" ") })).catch((err) => {
       internalConsole.warn("[clipbus-sdk] consolePatch: forward to host failed:", err);
     }).finally(() => {
       _inFlight--;
@@ -182,7 +177,7 @@ function patchTextInputState() {
   let isFocused = false;
   let isComposing = false;
   function post() {
-    callTextInputStateChanged({ isFocused, isComposing }).catch((err) => {
+    callPluginMethod("textInput.stateChanged", { isFocused, isComposing }).catch((err) => {
       internalConsole.warn("[clipbus-sdk] textInputState: dispatch failed:", err);
     });
   }

package/dist/dom/index.js

@@ -1,6 +1,14 @@
 // src/generated/wireConstants.generated.ts
 var STRUCTURED_ERROR_PREFIX = "__clipbus_structured_error__:";
 var CAPABILITY_UNSUPPORTED_ERROR_NAME = "PluginCapabilityUnsupported";
+var PLUGIN_CALL_HANDLER_NAME = "clipbusPluginCall";
+var WIRE_ERROR_NAMES = {
+  methodNotFound: "PluginRuntimeMethodNotFound",
+  handlerNotFound: "PluginRuntimeHandlerNotFound",
+  invocationExpired: "PluginRuntimeInvocationExpired",
+  hostCallLimitExceeded: "PluginRuntimeHostCallLimitExceeded",
+  hostBridgeUnavailable: "PluginHostBridgeUnavailable"
+};
 
 // src/internal/capabilities.ts
 var CapabilityUnsupportedError = class extends Error {
@@ -22,20 +30,29 @@ function mapToCapabilityError(err, unsupportedName) {
   return err;
 }
 
-// src/internal/runtimeInvokeClient.ts
+// src/internal/pluginCall.ts
+async function callPluginMethod(method, payload) {
+  const handler = globalThis.webkit?.messageHandlers?.[PLUGIN_CALL_HANDLER_NAME];
+  if (!handler) {
+    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
+    err.name = WIRE_ERROR_NAMES.hostBridgeUnavailable;
+    throw err;
+  }
+  const normalized = JSON.parse(JSON.stringify(payload));
+  try {
+    return await handler.postMessage({ method, payload: normalized });
+  } catch (err) {
+    throw parseReplyError(err);
+  }
+}
 function parseReplyError(raw) {
   const message = extractMessage(raw);
   if (message.startsWith(STRUCTURED_ERROR_PREFIX)) {
-    const json = message.slice(STRUCTURED_ERROR_PREFIX.length);
     try {
-      const parsed = JSON.parse(json);
+      const parsed = JSON.parse(message.slice(STRUCTURED_ERROR_PREFIX.length));
       const err = new Error(typeof parsed.message === "string" ? parsed.message : "");
-      if (typeof parsed.name === "string" && parsed.name.length > 0) {
-        err.name = parsed.name;
-      }
-      if (parsed.data !== void 0) {
-        err.data = parsed.data;
-      }
+      if (typeof parsed.name === "string" && parsed.name.length > 0) err.name = parsed.name;
+      if (parsed.data !== void 0) err.data = parsed.data;
       return mapToCapabilityError(err, CAPABILITY_UNSUPPORTED_ERROR_NAME);
     } catch {
       return new Error(message);
@@ -53,28 +70,6 @@ function extractMessage(raw) {
   return String(raw);
 }
 
-// src/generated/capabilityClients.generated.ts
-var HANDLER_NAME = "clipbusPluginCall";
-async function callPluginMethod(method, payload) {
-  const handler = globalThis.webkit?.messageHandlers?.[HANDLER_NAME];
-  if (!handler) {
-    const err = new Error("clipbus." + method + " is only available inside a Clipbus plugin WebView");
-    err.name = "PluginHostBridgeUnavailable";
-    throw err;
-  }
-  const normalized = JSON.parse(JSON.stringify(payload));
-  let reply;
-  try {
-    reply = await handler.postMessage({ method, payload: normalized });
-  } catch (err) {
-    throw parseReplyError(err);
-  }
-  return reply;
-}
-var callWindowSetHeight = (payload) => callPluginMethod("window.setHeight", payload);
-var callConsoleLog = (payload) => callPluginMethod("console.log", payload);
-var callTextInputStateChanged = (payload) => callPluginMethod("textInput.stateChanged", payload);
-
 // src/internal/internalConsole.ts
 function pick(method) {
   if (typeof globalThis === "undefined") return () => {
@@ -108,7 +103,7 @@ function autoFit(options) {
       pending = false;
       const raw = target.scrollHeight;
       const clamped = Math.min(max, Math.max(min, raw));
-      callWindowSetHeight({ height: clamped }).catch((err) => {
+      callPluginMethod("window.setHeight", { height: clamped }).catch((err) => {
         internalConsole.warn("[clipbus-sdk] autoFit: window.setHeight failed:", err);
       });
     });
@@ -134,7 +129,7 @@ function patchConsole() {
     original(...args);
     if (_inFlight > 0) return;
     _inFlight++;
-    Promise.resolve().then(() => callConsoleLog({ level, message: args.map(String).join(" ") })).catch((err) => {
+    Promise.resolve().then(() => callPluginMethod("console.log", { level, message: args.map(String).join(" ") })).catch((err) => {
       internalConsole.warn("[clipbus-sdk] consolePatch: forward to host failed:", err);
     }).finally(() => {
       _inFlight--;
@@ -153,7 +148,7 @@ function patchTextInputState() {
   let isFocused = false;
   let isComposing = false;
   function post() {
-    callTextInputStateChanged({ isFocused, isComposing }).catch((err) => {
+    callPluginMethod("textInput.stateChanged", { isFocused, isComposing }).catch((err) => {
       internalConsole.warn("[clipbus-sdk] textInputState: dispatch failed:", err);
     });
   }

package/dist/dom/topicAdapter.d.ts

@@ -2,7 +2,7 @@
  * Framework-agnostic helper for binding a SDK topic to any reactive state
  * system (Vue, React, Svelte, plain callbacks, …).
  *
- * `Topic<T>` is the interface from sdk/src/internal/topic.ts.
+ * `Topic<T>` is the interface from src/internal/topic.ts.
  * We intentionally replicate the minimal shape here (structural typing) so this
  * file has zero runtime imports — it works equally well in Node test runners and
  * browser bundles.