@clipbus/plugin-sdk 0.7.0

package/SPECIFICATION.md

@@ -0,0 +1,355 @@
+# Clipbus Plugin SDK — Specification
+
+## Chapter 1: Wire Shapes and Strict API Form
+
+The SDK exposes API calls in strict wire shape (no sugar). Every public symbol belongs to exactly one of four shapes.
+
+### 1.1 Topic\<T\>
+
+A Topic holds a current value and notifies listeners when it changes.
+
+```
+topic.current()            → T          read current value synchronously
+topic.on(listener)         → Unsubscribe  register a change listener; returns unsub fn
+```
+
+Use a Topic when the plugin needs to both read the current value and react to future changes (e.g. `clipbus.item`, `clipbus.theme`).
+
+### 1.2 OptionalTopic\<T\>
+
+Like Topic but the value may be absent until the host provides it.
+
+```
+topic.current()            → T | undefined
+topic.on(listener)         → Unsubscribe
+```
+
+Use an OptionalTopic when a value is context-dependent and may never be set in the current run (e.g. `clipbus.item.attachment` in an action context, `clipbus.action` in an attachment renderer context).
+
+### 1.3 Stream\<T\>
+
+A Stream has no current value; it only fans out discrete events to listeners.
+
+```
+stream.on(listener)        → Unsubscribe
+```
+
+Use a Stream for one-shot or repeated events with no persistent state (e.g. `clipbus.attachmentRenderer.onHostInvoke`).
+
+### 1.4 Verb
+
+A Verb is an async function that triggers a side-effect or host operation.
+
+```
+verb()                     → Promise<Result>
+verb(args)                 → Promise<Result>
+```
+
+Verbs that are illegal in the current context (e.g. calling `clipbus.action.complete` from an attachment renderer) reject immediately with `PluginContextError`.
+
+### 1.5 Applicability Decision Flow
+
+```
+Does the value have persistent state the plugin can read synchronously?
+  No  → Stream (events only)
+  Yes → Does it exist in every context this module loads in?
+          Yes → Topic
+          No  → OptionalTopic
+
+Is this a side-effect/operation rather than state?
+  Yes → Verb
+```
+
+---
+
+## Chapter 1.6: Shared Type Re-exports
+
+The SDK runtime and UI modules re-export core data types for plugin author convenience:
+
+### From `@clipbus/plugin-sdk/runtime` and `@clipbus/plugin-sdk/ui`
+
+```ts
+// Strong content and item types
+export type { PluginContentEnvelope, TextContent, ImageContent, PathReferenceContent } from '@clipbus/plugin-sdk/runtime';
+export type { PluginClipboardItem, ItemContext, AttachmentRef } from '@clipbus/plugin-sdk/runtime';
+```
+
+Use these directly in plugin payload and draft type definitions instead of declaring plugin-local wrapper types.
+
+Note: The convenience aliases `ContentEnvelope`, `PathEntry`, `ClipboardItem`, and `DetectorArtifact`
+were removed in the plugin-api-shrink rollout. Use the canonical `Plugin*`-prefixed names:
+`PluginContentEnvelope`, `PluginClipboardItem`, `PluginDetectorArtifact`.
+`PathEntry` has no replacement — decode `payload: unknown` directly from `path_reference` content.
+
+---
+
+## Chapter 1.7: Action Handler Shape and Typed Drafts
+
+The SDK exposes a **single** action handler interface, generated from the catalog:
+
+```ts
+// Generated in runtime.handlers.generated.ts
+export interface PluginAutoRunActionHandler {
+  resolveSession(input: PluginResolveActionSessionInput, ctx?: { host?: HostClient }): Promise<PluginActionResolveResult>;
+  runAutoAction(input: PluginAutoRunActionInput, ctx?: { host?: HostClient }): Promise<PluginActionOperationResult>;
+}
+```
+
+Both methods are required on the type. The **lifecycle in `manifest.json`** decides which method the host actually calls:
+
+- `lifecycle: 'auto-run'` → host calls `runAutoAction`; `resolveSession` is invoked once for session initialization if present
+- `lifecycle: 'draft'` → host calls `resolveSession` to seed `initialDraft` + buttons; `runAutoAction` is never called for draft lifecycle (you can `throw` from it to make the contract explicit, or leave it as a no-op)
+
+There is no `PluginDraftActionHandler` convenience type — both lifecycles use the same interface.
+
+### Strongly typed drafts
+
+`clipbus.action.draft.current()` returns `Record<string, unknown> | undefined`. Cast at the call site:
+
+```ts
+import { clipbus } from '@clipbus/plugin-sdk/ui';
+
+interface MyDraft {
+  title: string;
+  note: string;
+}
+
+const draft = clipbus.action.draft.current() as MyDraft | undefined;
+```
+
+`clipbus.action.draft` has **no `update()` verb** in the current SDK. The UI manages its own form state from `initialDraft`, then submits the final result via `clipbus.action.complete({result, userMessage?})`. If a runtime-side step is required (e.g. allocating an image temp path), the UI calls `clipbus.runtime.invoke(...)` against its own `messageHandlers`.
+
+### Canonical type names
+
+All publicly exported types carry the `Plugin` prefix. The pre-`plugin-api-shrink` aliases without the prefix (`DraftActionHandler`, `AutoRunActionHandler`, `DetectorHandler`, `AttachmentRendererHandler`, `ActionOperationResult`, `ResolveAttachmentInput`, etc.) **have been removed**. Use the canonical names:
+
+| Use this | Not this (removed alias) |
+|---|---|
+| `PluginAutoRunActionHandler` | `AutoRunActionHandler` / `DraftActionHandler` |
+| `PluginDetectorHandler` | `DetectorHandler` |
+| `PluginAttachmentRendererHandler` | `AttachmentRendererHandler` |
+| `PluginActionOperationResult` | `ActionOperationResult` |
+| `PluginActionResolveResult` | `ActionResolveResult` |
+| `PluginResolveAttachmentInput` | `ResolveAttachmentInput` |
+| `PluginClipboardItem` | `ClipboardItem` |
+| `PluginAttachmentPayload` | `AttachmentPayload` |
+| `PluginContentEnvelope` | `ContentEnvelope` |
+| `PluginPathEntry` | `PathEntry` |
+| `PluginDetectorArtifact` | `DetectorArtifact` |
+
+---
+
+## Chapter 2: Capability Mirror Table
+
+Capabilities are split by catalog `surface.side`: runtime capabilities are exposed through `ctx.host.*`, UI capabilities are exposed through `clipbus.*`, and `side:'both'` capabilities appear in both trees. All calls use strict wire shape (no sugar).
+
+> The **authoritative, auto-generated** list of every capability with its full payload / response shape lives in [API.md §2 Capabilities](./API.md#2-capabilities) and the alphabetical matrix in [§3 Capability Matrix](./API.md#3-capability-matrix). The mirror table below adds a "Notes" column with migration-related rationale (which APIs were removed, permission gates, etc.). If the two disagree, **API.md wins** — file a doc-fix PR.
+
+| Capability | Wire method | Runtime (ctx.host) | UI (clipbus. | Notes |
+|---|---|---|---|---|
+| Read clipboard item | — | `ctx.host` input param | `clipbus.item.current()` | Topic |
+| Subscribe item changes | — | — | `clipbus.item.on(fn)` | Topic |
+| Set tags | `item.setTags` | `ctx.host.item.setTags({tags})` | — | Verb; runtime-only via user RPC bridge; removed from UI in plugin-api-shrink |
+| Add tags | `item.addTags` | `ctx.host.item.addTags({tags})` | — | Verb; runtime-only via user RPC bridge |
+| Remove tags | `item.removeTags` | `ctx.host.item.removeTags({tags})` | — | Verb; runtime-only via user RPC bridge |
+| Pin/unpin | `item.setPinned` | `ctx.host.item.setPinned({pinned})` | — | Verb; runtime-only via user RPC bridge |
+| Set attachments | `item.setAttachments` | `ctx.host.item.setAttachments(p)` | — | Verb; runtime-only via user RPC bridge; `owner` and `attachmentType` now required |
+| Set search extension | `item.setSearchExtension` | `ctx.host.item.setSearchExtension(p)` | — | Verb; runtime-only via user RPC bridge; `owner` now required |
+| Materialize image | `item.materializeImagePath` | `ctx.host.item.materializeImagePath()` | — | Verb; runtime only; returns `{path}` |
+| Read attachment | `item.readAttachment` | `ctx.host.item.readAttachment({type, key})` | `clipbus.item.readAttachment({type, key})` | Verb; UI-callable; returns `{payloadJson?}` |
+| Attachment payload | — | `input.attachment.payloadJson` | `clipbus.item.attachment.current()` | OptionalTopic |
+| Replace renderer button list | `attachmentRenderer.setButtons` | — | `clipbus.attachmentRenderer.setButtons({buttons})` | Verb; buttons have `isEnabled?: boolean` field |
+| Host-side renderer button click | `clipbus-plugin-attachment-host-invoke` (host event) | — | `clipbus.attachmentRenderer.onHostInvoke(fn)` | Stream; receives `{ buttonID }` |
+| Theme snapshot | theme host event | via `__CLIPBUS_PLUGIN_THEME__` | `clipbus.theme.current()` | Topic |
+| Theme change | `themeHostEvent` | — | `clipbus.theme.on(fn)` | Topic (via host event) |
+| Window height | `window.setHeight` | — | `clipbus.window.setHeight({px})` | Verb; strict wire shape |
+| 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 |
+| 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 |
+| 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 |
+| Open URL | `navigation.openUrl` | `ctx.host.navigation.openUrl({url})` | `clipbus.navigation.openUrl({url})` | Verb; strict wire shape |
+| Reveal in Finder | `navigation.revealInFinder` | `ctx.host.navigation.revealInFinder({path})` | `clipbus.navigation.revealInFinder({path})` | Verb; strict wire shape |
+| 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 |
+
+### 2.1 `side:'both'` symmetry
+
+Every capability whose catalog declares `surface: { side: 'both', ... }` is **callable from either process** with identical behavior:
+
+- **Runtime side** — `ctx.host.<domain>.<verb>(payload)` (Node IPC wire). Returns `Promise<Response>`; permission errors reject.
+- **UI side** — `clipbus.<domain>.<verb>(payload)` (WebView Call wire). Same payload shape, same response, same permission gate.
+
+Both sides go through the same base host bridge; there is no parallel runtime-only or UI-only code path.
+
+**plugin-api-shrink changes**: `item.setTags`, `item.addTags`, `item.removeTags`, `item.setPinned`,
+`item.setAttachments`, `item.setSearchExtension`, `item.materializeImagePath`, and
+`action.allocateImageTempPath` were moved to **runtime-only** (`side:'runtime'`). Their UI-side
+`clipbus.*` wrappers were removed. Plugins that need to invoke these from a UI context must route
+through `clipbus.runtime.invoke(key, payload)` → their own Node runtime messageHandler.
+
+The remaining UI-only capabilities are **surface-bound** to specific WebView panes and are exposed only on the UI tree (`clipbus.*`):
+
+| Wire method | UI path | Why UI-only |
+|---|---|---|
+| `runtime.invoke` | `clipbus.runtime.invoke(key, payload, opts?)` | UI initiates a call to its own Node runtime; no runtime-side wire exposure needed |
+| `action.setButtons` | `clipbus.action.setButtons` | Targets action workspace native button bar |
+| `action.complete` | `clipbus.action.complete` | Submits draft lifecycle, action workspace only |
+| `attachmentRenderer.setButtons` | `clipbus.attachmentRenderer.setButtons` | Targets attachment renderer native button bar |
+| `window.setHeight` | `clipbus.window.setHeight` | WebView size only meaningful in WebView |
+| `window.autoFit` | `clipbus.window.autoFit` | Same |
+| `textInput.stateChanged` | `clipbus.textInput.stateChanged` | Notifies WebView native text-input focus chain |
+
+Node IPC inbound router rejects any UI-only method names at `PluginRuntimeHostMethod(rawValue:)` parse time with reply `"Unknown method <name>"`; they cannot be dispatched even if a runtime entry attempts to invoke them by raw method name.
+
+---
+
+## Chapter 2.5: Host Events (the canonical 7)
+
+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`.
+
+| Wire name | SDK Topic / Stream | Window global | Shape | Context | Payload |
+|---|---|---|---|---|---|
+| `clipbus-plugin-context` | `clipbus.pluginContext` | `__CLIPBUS_PLUGIN_CONTEXT__` | topic | any | `{ mode: 'attachmentRenderer' \| 'action', pluginID: string }` |
+| `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-theme` | `clipbus.theme` | `__CLIPBUS_PLUGIN_THEME__` | topic | any | `PluginThemeTokenSnapshot` |
+| `clipbus-plugin-attachment-host-invoke` | `clipbus.attachmentRenderer.onHostInvoke` | — | stream | attachmentRenderer | `{ buttonID: string }` |
+| `clipbus-plugin-action-host-invoke` | `clipbus.action.onHostInvoke` | — | stream | action | `{ buttonID: string }` |
+
+The previous "bootstrap vs change-event" split was removed in plugin-api-shrink: every Topic now uses the same `windowGlobal` for synchronous initial read **and** a CustomEvent for subsequent updates. The SDK wires both ends — plugin authors only see Topic / OptionalTopic / Stream.
+
+The canonical list is regenerated into [`API.md` §4 and §5](./API.md#4-host-events) from `protocol/plugin/src/catalog.ts` — if a name in this chapter ever diverges from API.md, API.md wins.
+
+---
+
+## Chapter 3: Process for Adding New Capabilities or Host Events
+
+The plugin wire is fully codegen-driven. Choosing between `defineCapability` and `defineHostEvent`:
+
+- **Use `defineCapability`** when the plugin requests an action from the host (e.g. set tags, copy text, open URL).
+- **Use `defineHostEvent`** when the host pushes state or events to the plugin (e.g. theme tokens, button clicks, attachment updates). Decorate with `surface.feed` to wire 1:1 to SDK Topic.
+
+### Adding a Capability
+
+1. **Declare the contract** — add a `defineCapability({name, payload, response, surface})` call in `protocol/plugin/src/domains/<domain>.ts`. Choose a `<domain>.<verb>` name and describe payload / response via `t.*` schema primitives.
+   - For typed maps, use `t.record(T)` (e.g. `t.record(t.json())` for `Record<string, JSONValue>`).
+   - Prefer `t.object` and `t.discriminatedUnion` for nested structures; use `t.json()` only as an escape hatch.
+   - Set `surface: {side: 'ui' | 'runtime' | 'both', path: '<domain>.<verb>', context?: 'any' | 'action' | 'attachment', optimisticUpdate?: {topic, fromPayload}}`
+
+2. **Register in the catalog** — append the descriptor to `protocol/plugin/src/catalog.ts` (`capabilities` array).
+
+3. **Regenerate** — `cd protocol/plugin && npm run codegen`. The host sync target and the SDK sync target under `packages/plugin-sdk/src/generated/` are auto-updated. Generated call clients (`callItemSetTags`, etc.) and clipbus.tree are produced automatically.
+
+4. **Implement the host method** — add the implementation on the host bridge per `surface.side`:
+   - `'both'`: implement on the base host bridge (satisfies `PluginRuntimeHostHandler` and inherits into `PluginUIHostBridge`).
+   - `'ui'`: implement on the UI host bridge (satisfies `PluginUIHostHandler`).
+   - `'runtime'`: implement on the base host bridge (satisfies `PluginRuntimeHostHandler`).
+   The host build will refuse to compile until the corresponding handler protocol is satisfied.
+
+5. **Wire the SDK surface** — SDK surface is fully codegen-generated. No hand-wrapping needed; `clipbus.<domain>.<verb>` and `ctx.host.<domain>.<verb>` automatically appear in the generated index files.
+
+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.
+
+8. **PR** — see Chapter 5 for the PR checklist.
+
+### Adding a Host Event
+
+1. **Declare the contract** — add a `defineHostEvent({name, payload, windowGlobal, surface})` call in `protocol/plugin/src/domains/<domain>.ts`. Specify:
+   - `name`: plugin-internal identifier (mapped to wire `windowGlobal` name via codegen)
+   - `payload`: shape via `t.*` schema primitives
+   - `windowGlobal` (optional): if set, host injects JSON to this window global for sync read (e.g. `__CLIPBUS_PLUGIN_ITEM__`)
+   - `surface.feed`: `{topic: '<domain>' | '<domain>.<subdomain>', shape: 'topic' | 'stream', context?: 'any' | 'action' | 'attachment'}`
+
+2. **Register in the catalog** — append the descriptor to `protocol/plugin/src/catalog.ts` (`hostEvents` array).
+
+3. **Regenerate** — same as capability step 3.
+
+4. **Implement host dispatch** — call the codegen-emitted emitter for the event's surface shape: `PluginHostBootstrapEmitter.generated.swift` for `windowGlobal` bootstrap and `PluginHostTopicEmitter.generated.swift` for topic/stream feeds. Codegen provides the `emitX(payload)` methods and payload types.
+
+5. **Wire the SDK surface** — codegen automatically emits SDK bootstrap wiring. `clipbus.<domain>.on(fn)`, `.current()` are generated; no hand-wrapping needed.
+
+6. **Test** — add tests for event dispatch. Snapshot tests cover SDK wiring.
+
+7. **Verify locally** — same as capability step 7.
+
+8. **PR** — same as capability step 8.
+
+---
+
+## Chapter 4: Naming Rules
+
+### 4.1 Plugin Type Prefix
+
+All codegen-emitted type names carry the `Plugin` prefix:
+
+**带 Plugin 前缀（仅 type 名）：**
+- Wire payload / response interface: `PluginItemSetTagsPayload` / `PluginItemSetTagsResponse`
+- `defineType` named types: `PluginAttachmentRef` / `PluginClipboardItem` / `PluginDetectorArtifact` / `PluginAttachmentMutationEntry` / `PluginSearchExtensionEntry` / `PluginConsoleLogLevel` / etc. (必须以 Plugin 开头，DSL validation 校验)
+- Handler interfaces: `PluginDetectorHandler` / `PluginAttachmentRendererHandler` / `PluginAutoRunActionHandler` (the single action handler covers both `auto-run` and `draft` lifecycles; see Chapter 1.7)
+- Host event payload alias: `PluginItemPayload` / `PluginAttachmentPayload` / `PluginThemeTokenSnapshot` / etc.
+- Host-side Codable struct / enum: `PluginItemSetTagsPayload` / `PluginContentEnvelope` / etc. (已有，保持)
+
+**已删除的 typeRef**（plugin-api-shrink）：
+- `PluginActionSession` — 随 `clipbus-plugin-action-session` host event 一起删除
+- `PluginActionDescriptor` — 同上
+- `PluginActionInvocationTrigger` — 同上
+
+**不加 Plugin 前缀（动词 / 值命名空间）：**
+- TS 函数名: `callItemSetTags` / `onItemEvent` / `guardContext` — 动词前缀足够区分
+- 主机端 method 名: `emitItem` / `setBootstrap` — 同上
+- TS 顶层值导出: `clipbus` / `actionResult` — 是值不是类型
+- 主机端 enum case 名: `itemSetTags`（在 `PluginUIHostMethod` / `PluginRuntimeHostMethod` enum 里）— enum 自身带 Plugin 前缀
+
+### 4.2 Module namespaces
+
+Top-level namespaces on `clipbus.*` mirror the host capability domain:
+- `clipbus.item` — clipboard item data and mutations
+- `clipbus.theme` — appearance tokens
+- `clipbus.action` — draft action session and controls (optional topic in action context)
+- `clipbus.window` — WebView layout (height, auto-fit)
+- `clipbus.clipboard` — system clipboard write
+- `clipbus.navigation` — navigation and file operations
+- `clipbus.settings` — plugin settings read access
+
+### 4.3 Method names
+
+- Topics: `current()` to read, `on(fn)` to subscribe (matches Vue's reactive conventions)
+- Verbs: strict wire shape with single object parameter: `setTags({tags})`, `addTags({tags})`, `update({draft?, defaultButtonID?})`
+- Streams: `onHostInvoke` — `on` prefix + noun phrase
+
+### 4.4 Forbidden patterns
+
+- No `get` prefix on Topics (use `current()` instead)
+- No `subscribe` — use `on()`
+- No `dispatch` — use `emit()` internally, `invoke()` or named verbs externally
+- No `bridge` in public names — that's an implementation detail
+- No sugar wrapping (parameter unwrapping, response unwrapping) — strict wire shapes only
+
+### 4.5 Error naming
+
+Context errors throw `PluginContextError` (exported from `@clipbus/plugin-sdk/ui`). All other SDK errors use `Error` with descriptive messages prefixed `[clipbus.sdk]`.
+
+---
+
+## Chapter 5: PR Checklist
+
+Before merging any PR that touches `sdk/`:
+
+- [ ] New capability is documented in Chapter 2 mirror table
+- [ ] TypeScript types added to `ctx.ts` and/or module interface
+- [ ] Failing test written first (TDD), then implementation
+- [ ] `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)
+- [ ] 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/autoFit.d.ts

@@ -0,0 +1,15 @@
+export interface AutoFitOptions {
+    /** Minimum height in px (default: 0). */
+    min?: number;
+    /** Maximum height in px (default: Infinity). */
+    max?: number;
+    /** Element to observe. Defaults to document.body. */
+    target?: HTMLElement | null;
+}
+/**
+ * Attach ResizeObserver + MutationObserver to track content height and
+ * call window.setHeight automatically.
+ *
+ * @returns A disconnect function. Call it in onUnmounted to clean up.
+ */
+export declare function autoFit(options?: AutoFitOptions): () => void;

package/dist/dom/consolePatch.d.ts

@@ -0,0 +1 @@
+export declare function patchConsole(): void;

package/dist/dom/index.cjs

@@ -0,0 +1,211 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/dom/index.ts
+var index_exports = {};
+__export(index_exports, {
+  autoFit: () => autoFit,
+  bindTopicTo: () => bindTopicTo,
+  patchConsole: () => patchConsole,
+  patchTextInputState: () => patchTextInputState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/generated/wireConstants.generated.ts
+var STRUCTURED_ERROR_PREFIX = "__clipbus_structured_error__:";
+var CAPABILITY_UNSUPPORTED_ERROR_NAME = "PluginCapabilityUnsupported";
+
+// src/internal/capabilities.ts
+var CapabilityUnsupportedError = class extends Error {
+  capability;
+  constructor(capability) {
+    super(`Capability not supported by host: ${capability}`);
+    this.name = "CapabilityUnsupportedError";
+    this.capability = capability;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function mapToCapabilityError(err, unsupportedName) {
+  if (err.name === unsupportedName) {
+    const cap = err.data?.capability ?? "";
+    return new CapabilityUnsupportedError(cap);
+  }
+  const m = /^Unknown method:\s*(.+)$/.exec(err.message);
+  if (m) return new CapabilityUnsupportedError(m[1]);
+  return err;
+}
+
+// src/internal/runtimeInvokeClient.ts
+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 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;
+      }
+      return mapToCapabilityError(err, CAPABILITY_UNSUPPORTED_ERROR_NAME);
+    } catch {
+      return new Error(message);
+    }
+  }
+  return mapToCapabilityError(new Error(message), CAPABILITY_UNSUPPORTED_ERROR_NAME);
+}
+function extractMessage(raw) {
+  if (typeof raw === "string") return raw;
+  if (raw instanceof Error) return raw.message;
+  if (raw && typeof raw === "object" && "message" in raw) {
+    const m = raw.message;
+    if (typeof m === "string") return m;
+  }
+  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 () => {
+  };
+  const g = globalThis;
+  const fn = g.console?.[method];
+  if (typeof fn !== "function") return () => {
+  };
+  return fn.bind(g.console);
+}
+var internalConsole = Object.freeze({
+  log: pick("log"),
+  warn: pick("warn"),
+  error: pick("error")
+});
+
+// src/dom/autoFit.ts
+function autoFit(options) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {
+    };
+  }
+  const min = options?.min ?? 0;
+  const max = options?.max ?? Infinity;
+  const target = options?.target ?? document.body;
+  let pending = false;
+  function post() {
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(() => {
+      pending = false;
+      const raw = target.scrollHeight;
+      const clamped = Math.min(max, Math.max(min, raw));
+      callWindowSetHeight({ height: clamped }).catch((err) => {
+        internalConsole.warn("[clipbus-sdk] autoFit: window.setHeight failed:", err);
+      });
+    });
+  }
+  const ro = new ResizeObserver(post);
+  ro.observe(target);
+  const mo = new MutationObserver(post);
+  mo.observe(target, { childList: true, subtree: true, characterData: true, attributes: true });
+  post();
+  return () => {
+    ro.disconnect();
+    mo.disconnect();
+  };
+}
+
+// src/dom/consolePatch.ts
+var _patched = false;
+var _inFlight = 0;
+function patchConsole() {
+  if (_patched) return;
+  _patched = true;
+  const wrap = (level, original) => (...args) => {
+    original(...args);
+    if (_inFlight > 0) return;
+    _inFlight++;
+    Promise.resolve().then(() => callConsoleLog({ level, message: args.map(String).join(" ") })).catch((err) => {
+      internalConsole.warn("[clipbus-sdk] consolePatch: forward to host failed:", err);
+    }).finally(() => {
+      _inFlight--;
+    });
+  };
+  console.log = wrap("info", internalConsole.log);
+  console.warn = wrap("warn", internalConsole.warn);
+  console.error = wrap("error", internalConsole.error);
+}
+
+// src/dom/textInputState.ts
+var _patched2 = false;
+function patchTextInputState() {
+  if (_patched2 || typeof window === "undefined") return;
+  _patched2 = true;
+  let isFocused = false;
+  let isComposing = false;
+  function post() {
+    callTextInputStateChanged({ isFocused, isComposing }).catch((err) => {
+      internalConsole.warn("[clipbus-sdk] textInputState: dispatch failed:", err);
+    });
+  }
+  document.addEventListener("focusin", () => {
+    isFocused = true;
+    post();
+  });
+  document.addEventListener("focusout", () => {
+    isFocused = false;
+    post();
+  });
+  document.addEventListener("compositionstart", () => {
+    isComposing = true;
+    post();
+  });
+  document.addEventListener("compositionend", () => {
+    isComposing = false;
+    post();
+  });
+}
+
+// src/dom/topicAdapter.ts
+function bindTopicTo(topic, set) {
+  set(topic.current());
+  return topic.on((value) => set(value));
+}

package/dist/dom/index.d.cts

@@ -0,0 +1,6 @@
+export { autoFit } from './autoFit.js';
+export type { AutoFitOptions } from './autoFit.js';
+export { patchConsole } from './consolePatch.js';
+export { patchTextInputState } from './textInputState.js';
+export { bindTopicTo } from './topicAdapter.js';
+export type { TopicLike } from './topicAdapter.js';

package/dist/dom/index.d.ts

@@ -0,0 +1,6 @@
+export { autoFit } from './autoFit.js';
+export type { AutoFitOptions } from './autoFit.js';
+export { patchConsole } from './consolePatch.js';
+export { patchTextInputState } from './textInputState.js';
+export { bindTopicTo } from './topicAdapter.js';
+export type { TopicLike } from './topicAdapter.js';