@clipbus/plugin-sdk 0.8.3 → 0.8.5

package/dist/preview/styles.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CSS for the preview workbench chrome.
+ * Injected as a <style> tag at runtime — no framework required.
+ *
+ * All colours are driven by CSS custom properties set by applyTheme():
+ *   --cbp-wb-backdrop       : chrome background base colour
+ *   --cbp-wb-accent         : accent colour (tabs, card border)
+ *   --cbp-wb-surface-elevated: card shell background
+ *   --cbp-wb-border         : subtle border colour
+ *   --cbp-wb-text           : primary text
+ *   --cbp-wb-text-secondary : secondary / label text
+ *
+ * Preset defaults (graphite) are set as initial values so there is no flash of
+ * unstyled content before applyTheme() is called in start().
+ *
+ * Geometry values (padding, radius, border-width) are hardcoded because they
+ * come from native measurements, not from theme tokens.
+ */
+export declare const previewStyles = "\n/* \u2500\u2500 CSS variable defaults (graphite dark) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb {\n  --cbp-wb-backdrop: #16181C;\n  --cbp-wb-accent: #43C6AC;\n  --cbp-wb-surface-elevated: rgba(35,37,42,.78);\n  --cbp-wb-border: rgba(255,255,255,.10);\n  --cbp-wb-text: #F3F4F6;\n  --cbp-wb-text-secondary: #C2C6CF;\n}\n\n/* \u2500\u2500 Root chrome \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb {\n  min-height: 100%;\n  padding: 24px;\n  font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n  font-size: 13px;\n  box-sizing: border-box;\n  color: var(--cbp-wb-text);\n  background: var(--cbp-wb-backdrop);\n}\n\n*, .cbp-wb * {\n  box-sizing: border-box;\n}\n\n/* \u2500\u2500 Theme-aware scrollbars \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n/* The default OS / WebKit scrollbar is an opaque bar (white on dark themes)\n   that reads as jarring. Restyle every scroll area under the workbench \u2014 chrome\n   (log panel) AND plugin content inside the slot \u2014 into a thin, translucent,\n   theme-synced overlay that mirrors the native host's subtle scrollbars. The\n   --cbp-wb-* vars cascade from the workbench root into the plugin slot, so one\n   rule set covers both surfaces and recolours automatically on theme switch. */\n.cbp-wb,\n.cbp-wb * {\n  scrollbar-width: thin;\n  scrollbar-color: color-mix(in srgb, var(--cbp-wb-text-secondary) 30%, transparent) transparent;\n}\n\n.cbp-wb ::-webkit-scrollbar {\n  width: 9px;\n  height: 9px;\n}\n\n.cbp-wb ::-webkit-scrollbar-track {\n  background: transparent;\n}\n\n.cbp-wb ::-webkit-scrollbar-thumb {\n  background-color: color-mix(in srgb, var(--cbp-wb-text-secondary) 30%, transparent);\n  border-radius: 999px;\n  border: 2px solid transparent;\n  background-clip: padding-box;\n}\n\n.cbp-wb ::-webkit-scrollbar-thumb:hover {\n  background-color: color-mix(in srgb, var(--cbp-wb-text-secondary) 50%, transparent);\n  background-clip: padding-box;\n}\n\n.cbp-wb ::-webkit-scrollbar-corner {\n  background: transparent;\n}\n\n/* \u2500\u2500 Controls bar \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__controls {\n  display: flex;\n  gap: 12px;\n  flex-wrap: wrap;\n  align-items: flex-end;\n  margin-bottom: 20px;\n}\n\n.cbp-wb__control {\n  display: grid;\n  gap: 6px;\n}\n\n.cbp-wb__control-label {\n  font-size: 11px;\n  font-weight: 700;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n  color: var(--cbp-wb-text-secondary);\n}\n\n.cbp-wb__control select,\n.cbp-wb__scenario-select {\n  min-width: 160px;\n  padding: 10px 12px;\n  border-radius: 12px;\n  border: 1px solid var(--cbp-wb-border);\n  background: color-mix(in srgb, var(--cbp-wb-backdrop) 70%, transparent);\n  color: var(--cbp-wb-text);\n  font-size: 13px;\n  font-family: inherit;\n}\n\n/* \u2500\u2500 Width slider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__width-slider {\n  width: 140px;\n  accent-color: var(--cbp-wb-accent);\n  cursor: pointer;\n}\n\n/* \u2500\u2500 Canvas layout (host frame on top, native-call log below) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__canvas {\n  display: flex;\n  flex-direction: column;\n  gap: 20px;\n  align-items: center;\n}\n\n/* Host frame hugs the fixed-width viewport (no flex:1 stretch) so a wide\n   browser window leaves neutral backdrop on the sides instead of a large\n   empty framed area \u2014 the centered, native-like card the viewport expects. */\n.cbp-wb__host-frame {\n  min-width: 0;\n  padding: 16px;\n  border-radius: 16px;\n  background: color-mix(in srgb, var(--cbp-wb-surface-elevated) 40%, transparent);\n  border: 1px solid var(--cbp-wb-border);\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n}\n\n/* \u2500\u2500 Frame title \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__frame-title {\n  display: flex;\n  justify-content: space-between;\n  gap: 12px;\n  margin-bottom: 12px;\n  font-size: 12px;\n  font-weight: 700;\n  letter-spacing: 0.04em;\n  color: var(--cbp-wb-text-secondary);\n  width: 100%;\n}\n\n/* \u2500\u2500 Viewport shell: centers the viewport horizontally \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__viewport-shell {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n}\n\n/* Body clip box. NO border-radius of its own \u2014 the card shell (its parent)\n   owns the rounding. A radius here would clip the card's own corners/border. */\n.cbp-wb__viewport {\n  width: 100%;\n  /* Native hard ceiling (AttachmentRenderHeightConstants.ceiling = 800): the\n     body never grows past this even under the 'auto' content-driven policy. */\n  max-height: 800px;\n  /* At the ceiling, content SCROLLS inside the (fixed) card chrome \u2014 it does\n     not clip away or push the card taller. */\n  overflow-y: auto;\n  overflow-x: hidden;\n  transition: height 0.1s ease;\n}\n\n/* \u2500\u2500 Native card shell \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n/* Geometry source: AttachmentRenderCardShell.swift:24-59                    */\n/* 10 pt padding / 7 pt continuous radius / 1 pt accent border / elevated bg */\n/* Outer card: stacks the body (viewport) above the host action strip, like  */\n/* native VStack { body; actions }. Width is set inline; height auto-wraps.   */\n.cbp-wb__card-shell {\n  display: flex;\n  flex-direction: column;\n  gap: 8px; /* native cardSpacing: body \u2194 action strip */\n  padding: 10px; /* native cardPadding */\n  border-radius: 7px; /* native radius.panelInner (replaces the 20px viewport clip) */\n  /* Border tint = the attachment's tintColor (--cbp-wb-card-tint, set per\n     scenario from scenario.accentHex), falling back to the theme accent \u2014\n     mirrors native, where the card border uses record.tintColor. */\n  border: 1px solid color-mix(in srgb, var(--cbp-wb-card-tint, var(--cbp-wb-accent)) 26%, transparent);\n  background: var(--cbp-wb-surface-elevated);\n  /* No box-shadow per native spec */\n}\n\n.cbp-wb__webview {\n  width: 100%;\n  height: 100%;\n  /* Fixed/bounded body shorter than its content \u2192 scroll inside. (Only the one\n     element whose content actually exceeds its box scrolls, so there is never a\n     double scrollbar: in 'auto' the viewport scrolls; in fixed/bounded the\n     webview does.) */\n  overflow-y: auto;\n  overflow-x: hidden;\n}\n\n/* \u2500\u2500 Host button strip (inside the card, below the body) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n/* Native action row: HStack { buttons; Spacer } \u2192 left-aligned, compact.    */\n.cbp-wb__strip {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 10px; /* native action HStack spacing */\n  justify-content: flex-start; /* left-aligned, not centered */\n}\n\n/* No buttons \u2192 no strip box, and the card's flex gap reserves nothing. */\n.cbp-wb__strip:empty {\n  display: none;\n}\n\n.cbp-wb__button {\n  appearance: none;\n  border: 1px solid var(--cbp-wb-border);\n  border-radius: 999px;\n  padding: 4px 10px; /* native actionPadding \u2248 3 v / 8 h \u2014 was 10/16 (too large) */\n  background: color-mix(in srgb, var(--cbp-wb-surface-elevated) 60%, transparent);\n  color: var(--cbp-wb-text-secondary);\n  font-size: 12px;\n  font-weight: 600;\n  font-family: inherit;\n  cursor: pointer;\n}\n\n.cbp-wb__button--primary {\n  background: var(--cbp-wb-accent);\n  color: var(--cbp-wb-backdrop);\n  border-color: var(--cbp-wb-accent);\n}\n\n/* \u2500\u2500 Log panel (fixed-width right column) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\n.cbp-wb__log {\n  width: 100%;\n  max-width: 720px;\n  padding: 14px 16px;\n  border-radius: 16px;\n  background: color-mix(in srgb, var(--cbp-wb-surface-elevated) 50%, transparent);\n  border: 1px solid var(--cbp-wb-border);\n  overflow: hidden;\n  display: flex;\n  flex-direction: column;\n  gap: 0;\n}\n\n.cbp-wb__log-title {\n  margin: 0 0 10px;\n  font-size: 12px;\n  font-weight: 800;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n  color: var(--cbp-wb-text);\n}\n\n.cbp-wb__log-empty {\n  font-size: 12px;\n  color: color-mix(in srgb, var(--cbp-wb-text-secondary) 60%, transparent);\n  font-style: italic;\n}\n\n.cbp-wb__log-list {\n  list-style: none;\n  margin: 0;\n  padding: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  max-height: 220px;\n  overflow-y: auto;\n}\n\n.cbp-wb__log-entry {\n  border-radius: 8px;\n  padding: 8px 10px;\n  background: color-mix(in srgb, var(--cbp-wb-surface-elevated) 60%, transparent);\n  font-family: ui-monospace, \"SFMono-Regular\", Menlo, monospace;\n  font-size: 11px;\n  line-height: 1.5;\n  word-break: break-all;\n}\n\n.cbp-wb__log-entry-method {\n  font-weight: 700;\n  color: var(--cbp-wb-accent);\n}\n\n.cbp-wb__log-entry-seq {\n  font-weight: 400;\n  color: var(--cbp-wb-text-secondary);\n  margin-left: 6px;\n}\n\n.cbp-wb__log-entry-payload {\n  margin-top: 2px;\n  color: var(--cbp-wb-text-secondary);\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n";

package/dist/preview/theme.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Native preview theme presets.
+ *
+ * 4 presets hand-ported from the native macOS AppearanceResolver:
+ *   platform/macos/Sources/Shared/Appearance/AppearanceResolver.swift:43-553
+ * mapped via:
+ *   PluginThemeTokenMapper.swift:14-28
+ *
+ * `backdrop` is not a native PluginThemeToken — it is the underlying window-
+ * material base color added by this preview layer so that semi-transparent
+ * surface tokens composite correctly in the browser (which has no vibrancy).
+ */
+import type { PluginThemeTokens, PluginThemeTokenSnapshot } from '../generated/data.generated.js';
+export interface PreviewThemePreset {
+    key: 'graphite' | 'ember' | 'porcelain' | 'sand';
+    /** Display name shown in the theme selector. */
+    label: string;
+    scheme: 'dark' | 'light';
+    /** Chrome backdrop base color (approximates native window material). */
+    backdrop: string;
+    /** The 12 plugin theme tokens, verbatim from AppearanceResolver. */
+    tokens: PluginThemeTokens;
+}
+/**
+ * The four built-in preview theme presets in display order.
+ * Values are verbatim from AppearanceResolver.swift.
+ */
+export declare const previewThemePresets: readonly PreviewThemePreset[];
+export declare const DEFAULT_THEME_KEY = "graphite";
+/**
+ * Resolve a preset by key, with graceful fallback.
+ *
+ * Backward-compat mappings:
+ *   'dark'  → graphite   (was the only dark theme before presets)
+ *   'light' → porcelain  (was the only light theme before presets)
+ *   undefined → graphite
+ *   unknown key → graphite
+ */
+export declare function getThemePreset(key?: string): PreviewThemePreset;
+export declare const defaultDarkTheme: PluginThemeTokenSnapshot;
+export declare const defaultLightTheme: PluginThemeTokenSnapshot;

package/dist/preview/types.d.ts

@@ -0,0 +1,50 @@
+import type { PluginClipboardItem, PluginAttachmentPayload } from '../generated/data.generated.js';
+export interface PreviewViewport {
+    /** Initial viewport width (px). Defaults to the per-mode width when omitted. */
+    width?: number;
+    heightPolicy: 'fixed' | 'auto' | 'bounded';
+    height?: number;
+    min?: number;
+    max?: number;
+    /** Override the mode-default minimum viewport width (px). */
+    widthMin?: number;
+    /** Override the mode-default maximum viewport width (px). */
+    widthMax?: number;
+}
+export interface PreviewScenario {
+    id: string;
+    label: string;
+    mode: 'attachmentRenderer' | 'action';
+    /**
+     * Plugin identifier surfaced to the plugin via context.pluginID.
+     * Some renderers validate attachment.owner against it, so scenarios that
+     * exercise that path should set it. Defaults to a harness placeholder.
+     */
+    pluginID?: string;
+    accentHex?: string;
+    item: PluginClipboardItem;
+    /** Attachment renderer mode payload. */
+    attachment?: PluginAttachmentPayload;
+    /** Action mode draft payload. */
+    draft?: Record<string, unknown>;
+    buttons?: {
+        id: string;
+        title: string;
+        isEnabled: boolean;
+    }[];
+    defaultButtonID?: string;
+    viewport?: PreviewViewport;
+    /** Opaque hint forwarded to the mount adapter. */
+    view?: string;
+}
+export interface PreviewWorkbenchOptions {
+    scenarios: PreviewScenario[];
+    /**
+     * Called each time a scenario becomes active.
+     * Mount the plugin UI into `slotEl` and return a cleanup function.
+     */
+    mount(slotEl: HTMLElement, ctx: {
+        scenario: PreviewScenario;
+    }): () => void;
+    defaultViewport?: Partial<PreviewViewport>;
+}

package/dist/preview/wire.d.ts

@@ -0,0 +1,67 @@
+import type { PluginThemeTokenSnapshot } from '../generated/data.generated.js';
+import type { PluginContextPayload, PluginLocalePayload } from '../generated/hostBootstrap.generated.js';
+import type { PluginClipboardItem, PluginAttachmentPayload } from '../generated/data.generated.js';
+import type { PreviewScenario } from './types.js';
+/**
+ * Backward-compat alias. Now accepts any preset key string ('graphite', 'ember',
+ * 'porcelain', 'sand') as well as the legacy 'dark' / 'light' shorthands.
+ */
+export type PreviewThemeKey = string;
+export interface WirePayloads {
+    mode: PreviewScenario['mode'];
+    context: PluginContextPayload;
+    item: PluginClipboardItem;
+    attachment?: PluginAttachmentPayload;
+    draft?: Record<string, unknown>;
+    theme: PluginThemeTokenSnapshot;
+    locale: PluginLocalePayload;
+}
+/**
+ * Pure function: derive wire payloads from a scenario.
+ * No side-effects; safe to call multiple times.
+ *
+ * @param themeKey - Preset key ('graphite' | 'ember' | 'porcelain' | 'sand')
+ *   or legacy shorthand ('dark' → graphite, 'light' → porcelain). Selects the
+ *   base token snapshot so switching the theme picker drives the injected theme,
+ *   mirroring how the real host pushes theme over the wire. Defaults to
+ *   DEFAULT_THEME_KEY ('graphite').
+ */
+export declare function computeWirePayloads(scenario: PreviewScenario, themeKey?: string): WirePayloads;
+/**
+ * Inject wire payloads into the target window using the generated emitters.
+ * In v1 (same-document), `target` must be the current window.
+ * The `target` parameter is a forward-looking seam for future iframe support.
+ *
+ * No hardcoded global names or event names — all delegation flows through the
+ * generated emitAttachmentBootstrap / emitActionBootstrap functions.
+ */
+export declare function injectWire(_target: Window, payloads: WirePayloads): void;
+/**
+ * Map of PluginThemeTokens field → CSS custom property name, mirroring the
+ * native host contract (PluginThemeTokenContracts.swift CodingKeys). The real
+ * macOS host applies the theme snapshot as these `:root` CSS variables on the
+ * plugin WebView; the wire theme topic alone does NOT style the DOM. The
+ * preview must apply them too, otherwise plugin `var(--clipbus-*)` references
+ * fall back to their hardcoded light defaults and become unreadable on a dark
+ * host card.
+ */
+export declare const THEME_CSS_VAR_NAMES: {
+    readonly surface: "--clipbus-surface";
+    readonly surfaceElevated: "--clipbus-surface-elevated";
+    readonly textPrimary: "--clipbus-text-primary";
+    readonly textSecondary: "--clipbus-text-secondary";
+    readonly textTertiary: "--clipbus-text-tertiary";
+    readonly accent: "--clipbus-accent";
+    readonly accentContrast: "--clipbus-accent-contrast";
+    readonly border: "--clipbus-border";
+    readonly divider: "--clipbus-divider";
+    readonly success: "--clipbus-success";
+    readonly warning: "--clipbus-warning";
+    readonly danger: "--clipbus-danger";
+};
+/**
+ * Apply a theme snapshot to `target` as `--clipbus-*` CSS variables, mirroring
+ * the native host. Called on every scenario activation and theme change so the
+ * mounted plugin restyles in place (the plugin reads these via `var()`).
+ */
+export declare function applyThemeCssVars(target: HTMLElement, snapshot: PluginThemeTokenSnapshot): void;

package/docs/README.md

@@ -19,6 +19,7 @@
 | [permissions.md](./permissions.md) | 权限模型：manifest 声明、受门控的 verb、最小权限原则 |
 | [capability-detection.md](./capability-detection.md) | 能力检测：`has()` 门控、UI/Node 侧 catch 差异、老宿主降级 |
 | [faq.md](./faq.md) | 常见坑点 Q&A |
+| [preview.md](./preview.md) | 开发期预览 harness（`@clipbus/plugin-sdk/preview`）：`createPreviewWorkbench`、scenario / viewport 配置、fake host、调用日志 |
 
 ## 同包参考
 

package/docs/preview.md

@@ -0,0 +1,259 @@
+# 开发期预览 harness
+
+> 本文档属于 @clipbus/plugin-sdk 开发文档 · 返回[文档地图](./README.md)
+
+`@clipbus/plugin-sdk/preview` 提供**框架中立**（纯 DOM/TypeScript，不依赖 Vue 或任何 UI 框架）的**开发期**预览 harness。无需真实 macOS 宿主进程，即可在浏览器里迭代插件 UI 的外观与行为。
+
+- **宿主 → 插件注入**：wire payload（bootstrap、item、attachment、theme、draft……）由 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。
+
+**这是纯开发期工具**，不打包进线上 plugin 产物。
+
+---
+
+## 快速开始
+
+插件保留自己的 Vite + `index.html` + `npm run dev`。在 preview 入口 `main.ts` 里调用 `createPreviewWorkbench`：
+
+```ts
+import { createPreviewWorkbench } from '@clipbus/plugin-sdk/preview';
+import { createApp } from 'vue';
+import MyApp from '../features/my-feature/app.vue';
+import { myScenarios } from './scenarios';
+
+createPreviewWorkbench(document.getElementById('app')!, {
+  scenarios: myScenarios,
+  mount(slotEl, { scenario }) {
+    // 在 slotEl 里挂载插件 UI，返回 cleanup
+    const app = createApp(MyApp);
+    app.mount(slotEl);
+    return () => app.unmount();
+  },
+});
+```
+
+`mount` 在每次 scenario 激活时由 harness 调用，负责在 `slotEl` 里挂载插件 UI 并返回 cleanup 函数。harness 自动处理：工作台 chrome（两级模式/scenario 导航、4 预设主题切换器、native 卡片壳、宽度滑杆、按钮条）、fake host 安装、wire 注入与 `--clipbus-*` CSS 变量镜像、scenario 切换时的 cleanup 与重挂。
+
+---
+
+## `createPreviewWorkbench(root, opts)`
+
+```ts
+function createPreviewWorkbench(root: HTMLElement, opts: PreviewWorkbenchOptions): void
+```
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `root` | `HTMLElement` | 工作台挂载的容器（通常是 `document.getElementById('app')`） |
+| `opts.scenarios` | `PreviewScenario[]` | scenario 列表；至少一个 |
+| `opts.mount` | `(slotEl, { scenario }) => () => void` | 每次 scenario 激活时调用；在 `slotEl` 里挂载插件 UI，返回 cleanup |
+| `opts.defaultViewport` | `Partial<PreviewViewport>?` | 所有 scenario 的视口默认值；可被 scenario 自身的 `viewport` 字段覆盖 |
+
+---
+
+## `PreviewScenario` 字段参考
+
+```ts
+interface PreviewScenario {
+  id: string;
+  label: string;
+  mode: 'attachmentRenderer' | 'action';
+  pluginID?: string;
+  accentHex?: string;
+  item: PluginClipboardItem;
+  attachment?: PluginAttachmentPayload;  // attachmentRenderer 模式
+  draft?: Record<string, unknown>;       // action 模式
+  buttons?: { id: string; title: string; isEnabled: boolean }[];
+  defaultButtonID?: string;
+  viewport?: PreviewViewport;
+  view?: string;
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `id` | scenario 唯一标识符 |
+| `label` | 选择器里显示的名称 |
+| `mode` | `'attachmentRenderer'`（渲染器 WebView）或 `'action'`（draft action WebView） |
+| `pluginID` | 注入给插件 `context.pluginID` 的插件 ID；若 attachment.owner 校验依赖此字段，应显式设置；未设置时 harness 使用占位符 |
+| `accentHex` | 强调色十六进制字符串（e.g. `'#0f766e'`） |
+| `item` | 当前 clipboard item（`PluginClipboardItem`） |
+| `attachment` | attachmentRenderer 模式的 attachment payload（`PluginAttachmentPayload`） |
+| `draft` | action 模式的 initialDraft（`Record<string, unknown>`） |
+| `buttons` | 按钮条种子：id / title / isEnabled |
+| `defaultButtonID` | 默认高亮按钮的 id |
+| `viewport` | 该 scenario 的视口配置；未设置时使用 `opts.defaultViewport` |
+| `view` | 透传给 `mount` adapter 的不透明 hint（e.g. `'compact'`/`'expanded'`） |
+
+---
+
+## `PreviewViewport` 字段参考
+
+```ts
+interface PreviewViewport {
+  width?: number;
+  heightPolicy: 'fixed' | 'auto' | 'bounded';
+  height?: number;
+  min?: number;
+  max?: number;
+  widthMin?: number;
+  widthMax?: number;
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `width` | 初始视口宽度（px）；未设置时取模式默认（renderer 720 / action 350） |
+| `heightPolicy` | `'fixed'`：高度锁定为 `height`；`'auto'`：完全跟随 `clipbus.window.setHeight` 调用；`'bounded'`：跟随 setHeight，限在 `[min, max]` 范围内 |
+| `height` | `'fixed'` policy 下的高度（px） |
+| `min` | `'bounded'` policy 下的最小高度（px） |
+| `max` | `'bounded'` policy 下的最大高度（px） |
+| `widthMin` | 覆盖该 scenario 的宽度滑杆最小值（px）；未设置时取模式默认（renderer 560 / action 300） |
+| `widthMax` | 覆盖该 scenario 的宽度滑杆最大值（px）；未设置时取模式默认（renderer 900 / action 500） |
+
+**宽度**：由工作台宽度滑杆控制，以 `scenario.viewport.width`（或模式默认）为初始值，在 `[widthMin, widthMax]` 范围内可拖动。**高度**行为贴近 native：插件调用 `clipbus.window.setHeight({height})` 时 harness 立即同步视口高度（`auto`/`bounded` 策略），与 native 行为一致。
+
+---
+
+## 调用日志与 fake host
+
+harness 安装一个最小双向 fake host：
+
+- **host → plugin**：按 scenario 字段生成 wire payload 并注入；bootstrap、item、attachment、theme 等不需要真实宿主
+- **plugin → host**：所有 `clipbus.*` native 调用被拦截，实时追加到「调用日志」面板，格式为 `[method]  JSON payload`；`clipbus.window.setHeight` 额外驱动视口高度；其他调用返回安全默认应答
+
+调用日志让你无需宿主即可验证 `setHeight` / `action.complete` / `clipboard.copyText` 等调用是否在正确时机触发，以及携带正确 payload。
+
+---
+
+## 主题预设
+
+harness 内置 4 套 native 主题预设，覆盖深色/浅色两种配色方案：
+
+| 预设键 | 显示名称 | 配色方案 | accent |
+|---|---|---|---|
+| `graphite`（默认） | Graphite (Dark) | dark | 青绿 `#43C6AC` |
+| `ember` | Ember (Dark) | dark | 暖橙 `#F97316` |
+| `porcelain` | Porcelain (Light) | light | 蓝 `#2563EB` |
+| `sand` | Sand (Light) | light | 暖琥珀 `#D97706` |
+
+每套预设包含 12 个 `PluginThemeTokens`（surface、surfaceElevated、textPrimary/Secondary/Tertiary、accent、accentContrast、border、divider、success、warning、danger），数值直接来自 native `AppearanceResolver.swift`，确保预览与真实 native 渲染一致。
+
+`scenario.accentHex` 可在任意预设基础上覆盖 accent 颜色（如品牌色匹配），其他 token 保持预设值不变。
+
+`defaultDarkTheme` / `defaultLightTheme` 是向后兼容快照，分别由 graphite / porcelain 预设派生。
+
+---
+
+## 工作台 UI
+
+```sh
+npm run dev
+```
+
+Vite 启动后，工作台提供：
+
+- **两级模式导航**：顶层选择器在 **Renderer**（attachmentRenderer）和 **Action** 两种模式间切换；两种模式的 scenario 均用 `<select>` 下拉选择（文案取自 `scenario.label`）。任何时刻只渲染当前选中 scenario。URL query `?view=&scenario=&theme=` 同步，刷新不丢。
+- **主题切换**（4 预设：Graphite · Ember · Porcelain · Sand）：切换同时三重作用：① 重注入 wire 主题 topic，插件已注册的 `clipbus.theme.on()` 回调立即触发；② 重着色工作台背板/卡片/控件；③ 在插件挂载槽上更新 `--clipbus-*` CSS 变量（镜像 native host 在 `:root` 的变量注入）——不触发 remount，与 native `theme.onChange` 行为一致。注意：插件的 `--clipbus-accent` 是**全局主题 accent**；`scenario.accentHex` 是该附件的 **tintColor**，只染**卡片边框**（对应 native `record.tintColor`），不进插件配色。
+- **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]（主面板全宽 workspace 区）；action 初始 350 px、范围 [300,500]（紧凑 action 卡）。`scenario.viewport.width` 可覆盖初始值；`viewport.widthMin`/`widthMax` 可覆盖滑杆范围。
+- **body 高度**：高度**由插件驱动**。native **没有**宿主侧"量内容定高"：`auto` 在 native 解析为 `bounded(80, 800)`，且只认 `clipbus.window.setHeight`——插件**必须**用 SDK `autoFit`（或手动 `setHeight`）自撑，否则卡在 policy 最小高度被裁（gallery-auto 在 native 的坑正源于此）。harness 在插件首个 `setHeight` 前以内容高度做种子（宽松的预览便利，**非** native 行为：native 以 policy 最小高度做种子并裁切，故漏调 `autoFit` 在 preview 看着正常却会在 native 崩）。插件调 `clipbus.window.setHeight`（`auto`/`bounded`）时同步 body 高度，`bounded` 触顶后由插件自身内部滚动。所有策略统一封顶 native 硬上限 **800**（`AttachmentRenderHeightConstants.ceiling`）。
+- **按钮条**：源自 `scenario.buttons`（及插件 `setButtons`），位于**卡片内部、body 下方、左对齐**（native action row 布局）；无按钮时不占位。
+- **调用日志**：实时记录所有 native 调用与 payload，面板置于**预览卡片下方**（全宽）
+- **主题感知滚动条**：工作台内所有滚动区域（chrome 日志面板 + 插件内容及其嵌套滚动器）统一为细、半透明、随主题变色的滚动条，替换突兀的默认（深色主题下发白）OS 滚动条，镜像 native 宿主的低调滚动条
+
+---
+
+## Native 卡片壳与组件去框约定
+
+harness 在 `slotEl` 外提供 native 风格卡片框，模拟真实宿主为插件提供的统一外壳。因此：
+
+> **约定：插件组件不应自绘最外层 `background` / `border` / `border-radius` / `box-shadow` / 外层 `padding`。**
+> 宿主（和 harness）统一提供卡片框；插件在框内布局内容即可。
+
+违反此约定的后果：预览与 native 外观一致，但若宿主后续更换卡片样式，插件自绘的外框会与宿主框冲突（双重描边、背景叠加）。`template-plugin` 的全部 renderer 组件（`preview-renderer`、`expanded-renderer`、3 个 `capability-gallery` renderer）均已遵循此约定。
+
+---
+
+## 超限内滚约定
+
+native 宿主在 `clipbus.window.setHeight` 到上限（800 pt）时**直接裁剪**，不为插件提供外部滚动容器。因此，若插件内容可能超出最大高度，插件需在自身内部处理滚动：
+
+```css
+/* 示例：expanded-renderer 方案 */
+.outer-shell {
+  overflow-y: auto;   /* 超出时内部滚动 */
+  max-height: 100%;   /* 跟随视口高度 */
+}
+```
+
+`template-plugin` 的 `expanded-renderer` 是此约定的参考实现（外层 shell `overflow-y: auto` + 内容区自适应，兼容 `autoFit` 自动高度策略）。
+
+---
+
+## 参考实现
+
+`plugins/template-plugin/src/preview/preview-host/main.ts` 是规范的薄胶水范例——按 `scenario.mode` 和 `scenario.view` 路由到不同 Vue 组件：
+
+```ts
+import { createPreviewWorkbench } from '@clipbus/plugin-sdk/preview';
+import { createApp } from 'vue';
+import { attachmentScenarios } from '../scenarios/attachmentScenarios';
+import { actionScenarios } from '../scenarios/actionScenarios';
+import AttachmentApp from '../../features/preview-renderer/app.vue';
+import ExpandedApp from '../../features/expanded-renderer/app.vue';
+import DraftActionApp from '../../features/capability-gallery/draft-action-ui/app.vue';
+import RendererFixedApp from '../../features/capability-gallery/renderer-fixed-ui/app.vue';
+import RendererAutoApp from '../../features/capability-gallery/renderer-auto-ui/app.vue';
+import RendererBoundedApp from '../../features/capability-gallery/renderer-bounded-ui/app.vue';
+
+createPreviewWorkbench(document.getElementById('app')!, {
+  scenarios: [...attachmentScenarios, ...actionScenarios],
+  mount(slotEl, { scenario }) {
+    const Comp =
+      scenario.mode === 'action'
+        ? DraftActionApp
+        : scenario.view === 'expanded'
+          ? ExpandedApp
+          : scenario.view === 'gallery-fixed'
+            ? RendererFixedApp
+            : scenario.view === 'gallery-auto'
+              ? RendererAutoApp
+              : scenario.view === 'gallery-bounded'
+                ? RendererBoundedApp
+                : AttachmentApp;
+    const app = createApp(Comp);
+    app.mount(slotEl);
+    return () => app.unmount();
+  },
+});
+```
+
+`createPreviewWorkbench` 接管全部工作台基础设施，`mount` 里只有插件自己的框架调用——这就是完整模式。
+
+---
+
+## 高级导出
+
+```ts
+// 供测试与集成场景使用；日常插件开发只需 createPreviewWorkbench
+
+// Wire 工具
+import { computeWirePayloads, injectWire } from '@clipbus/plugin-sdk/preview';
+import { applyThemeCssVars, THEME_CSS_VAR_NAMES } from '@clipbus/plugin-sdk/preview';
+import { installFakeHost } from '@clipbus/plugin-sdk/preview';
+import type { FakeHostHooks, WirePayloads } from '@clipbus/plugin-sdk/preview';
+
+// 主题预设（4 套内置预设）
+import { previewThemePresets, getThemePreset, DEFAULT_THEME_KEY } from '@clipbus/plugin-sdk/preview';
+import type { PreviewThemePreset } from '@clipbus/plugin-sdk/preview';
+// 向后兼容快照（由 graphite/porcelain 派生，保留以兼容旧测试）
+import { defaultDarkTheme, defaultLightTheme } from '@clipbus/plugin-sdk/preview';
+
+// Chrome 纯函数（测试/集成用）
+import { groupScenariosByMode, resolveViewportWidth, clampWidth } from '@clipbus/plugin-sdk/preview';
+
+// Wire 协议常量
+import { PLUGIN_CALL_HANDLER_NAME, WINDOW_SET_HEIGHT_METHOD } from '@clipbus/plugin-sdk/preview';
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipbus/plugin-sdk",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "description": "Typed SDK for authoring Clipbus plugins — runtime (Node.js) and UI (WebView) helpers generated from the Clipbus plugin wire contract.",
   "keywords": [
@@ -58,6 +58,16 @@
         "types": "./dist/validate/index.d.cts",
         "default": "./dist/validate/index.cjs"
       }
+    },
+    "./preview": {
+      "import": {
+        "types": "./dist/preview/index.d.ts",
+        "default": "./dist/preview/index.js"
+      },
+      "require": {
+        "types": "./dist/preview/index.d.cts",
+        "default": "./dist/preview/index.cjs"
+      }
     }
   },
   "bin": {