@clipbus/plugin-sdk 0.8.4 → 0.8.6

package/README.md

@@ -526,6 +526,27 @@ Exits 0 on success, 1 if any issues are found.
 
 ---
 
+## Preview harness (`@clipbus/plugin-sdk/preview`)
+
+Framework-neutral development-time workbench for iterating on plugin UI without a real macOS host process. Provides wire injection (host → plugin bootstrap), a bidirectional fake host (plugin → host calls go to a call log panel), and viewport height tracking via `clipbus.window.setHeight`.
+
+```js
+import { createPreviewWorkbench } from '@clipbus/plugin-sdk/preview';
+
+createPreviewWorkbench(document.getElementById('app')!, {
+  scenarios,
+  mount(slotEl, { scenario }) {
+    const app = createApp(MyPlugin);
+    app.mount(slotEl);
+    return () => app.unmount();
+  },
+});
+```
+
+See [`docs/preview.md`](./docs/preview.md) for `PreviewScenario` / `PreviewViewport` field reference and full harness API.
+
+---
+
 ## See also
 
 - [API.md](./API.md) — autoritative API reference, regenerated from `protocol/plugin/src/catalog.ts`

package/dist/generated/hostBootstrap.generated.d.ts

@@ -0,0 +1,22 @@
+import type { PluginAttachmentPayload, PluginClipboardItem, PluginThemeTokenSnapshot } from './data.generated.js';
+export interface PluginContextPayload {
+    mode: 'attachmentRenderer' | 'action';
+    pluginID: string;
+}
+export interface PluginLocalePayload {
+    locale: string;
+}
+export declare function emitAttachmentBootstrap(p: {
+    context?: PluginContextPayload;
+    item?: PluginClipboardItem;
+    attachment?: PluginAttachmentPayload;
+    theme?: PluginThemeTokenSnapshot;
+    locale?: PluginLocalePayload;
+}): void;
+export declare function emitActionBootstrap(p: {
+    context?: PluginContextPayload;
+    item?: PluginClipboardItem;
+    draft?: Record<string, unknown>;
+    theme?: PluginThemeTokenSnapshot;
+    locale?: PluginLocalePayload;
+}): void;

package/dist/generated/wireConstants.generated.d.ts

@@ -1,3 +1,5 @@
 export declare const STRUCTURED_ERROR_PREFIX: "__clipbus_structured_error__:";
 export declare const CAPABILITIES_GLOBAL: "__CLIPBUS_PLUGIN_CAPABILITIES__";
 export declare const CAPABILITY_UNSUPPORTED_ERROR_NAME: "PluginCapabilityUnsupported";
+export declare const PLUGIN_CALL_HANDLER_NAME: "clipbusPluginCall";
+export declare const WINDOW_SET_HEIGHT_METHOD: "window.setHeight";

package/dist/preview/chrome.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure DOM workbench chrome — no framework dependencies.
+ *
+ * Responsibilities:
+ * - Header: Wire Bench wordmark + controls console
+ *   (Surface toggle, Scenario select, Theme select, Width slider)
+ * - Stage: workspace hero (left) + dock (right, position:sticky)
+ *   - Workspace: ws-head label + ws-surface holding the frozen specimen card
+ *     subtree (card shell → viewport → webview slot) + dims readout + growth floor
+ *   - Dock: IN attachment card (Wire Input mount point) over OUT attachment card
+ *     (Native Calls single-open accordion)
+ * - Viewport centered in workspace; width driven by range slider per mode
+ * - Fixed-height viewport driven by setHeight calls
+ * - Host button strip; click dispatches host-invoke events
+ * - clipbus-plugin-set-buttons listener (updates button strip from plugin)
+ * - Native Calls OUT panel: single-open accordion, newest auto-opens
+ */
+import type { PreviewScenario, PreviewWorkbenchOptions } from './types.js';
+import type { PreviewThemePreset } from './theme.js';
+/**
+ * Group scenarios by mode, preserving original order within each group.
+ * Returns only groups that have at least one scenario.
+ */
+export declare function groupScenariosByMode(scenarios: PreviewScenario[]): {
+    mode: 'attachmentRenderer' | 'action';
+    scenarios: PreviewScenario[];
+}[];
+/**
+ * Resolve effective viewport width settings for a scenario.
+ * scenario.viewport.width / widthMin / widthMax override mode defaults.
+ */
+export declare function resolveViewportWidth(scenario: PreviewScenario): {
+    width: number;
+    min: number;
+    max: number;
+};
+/**
+ * Clamp a width value within [min, max].
+ */
+export declare function clampWidth(value: number, min: number, max: number): number;
+export interface ChromeHandlers {
+    /**
+     * Scenario or view switched — full (re)activation; remount expected.
+     * Second arg is the active theme preset key (string, e.g. 'graphite').
+     */
+    onActivate(scenario: PreviewScenario, presetKey: string): void;
+    /**
+     * Theme picker changed — re-inject wire so theme subscribers receive the new
+     * scheme. No remount: theme.onChange is designed to restyle in place.
+     * Second arg is the new active preset key.
+     */
+    onThemeChange(scenario: PreviewScenario, presetKey: string): void;
+}
+export interface ChromeResult {
+    /** The <div> slot where the plugin UI should be mounted. */
+    slotEl: HTMLElement;
+    /**
+     * The scroll container of the IN attachment card where renderWireInput()
+     * should mount the Wire Input collapsible sections.
+     */
+    inputContainer: HTMLElement;
+    setViewportHeight(height: number): void;
+    /** Update the viewport width imperatively (also moves the slider thumb). */
+    setViewportWidth(px: number): void;
+    appendLogEntry(method: string, payload: unknown): void;
+    /**
+     * Update the host button strip. Called when the mounted plugin invokes a
+     * `*.setButtons` host verb so the strip reflects the plugin's real titles.
+     */
+    applyButtons(buttons: {
+        id: string;
+        title: string;
+        isEnabled?: boolean;
+    }[], defaultButtonID?: string | null): void;
+    /**
+     * Write preset CSS variables to the workbench root and set data-theme-scheme /
+     * data-theme-key attributes. Called internally by start() and on theme change;
+     * exposed for external callers that need to force a theme update.
+     */
+    applyTheme(preset: PreviewThemePreset): void;
+    /**
+     * Trigger the first scenario activation. Must be called by the caller AFTER
+     * it has finished destructuring this result and wired up any hooks — calling
+     * onActivate inline during renderChrome would access `slotEl` in its TDZ.
+     */
+    start(): void;
+    /** Clean up any window-level listeners (reserved for future use). */
+    destroy(): void;
+}
+/**
+ * Render the Wire Bench chrome into `root` and return imperative handles.
+ *
+ * DOM structure:
+ *   .cbp-wb
+ *     .cbp-wb__header  (brand + controls console)
+ *     .cbp-wb__rule    (separator)
+ *     .cbp-wb__stage
+ *       .cbp-wb__workspace  (hero — fills left column)
+ *         .cbp-wb__ws-head
+ *         .cbp-wb__ws-surface
+ *           .cbp-wb__specimen-wrap
+ *             .cbp-wb__card-shell [frozen]
+ *               .cbp-wb__viewport [frozen]
+ *                 .cbp-wb__webview [frozen slotEl]
+ *               .cbp-wb__strip [frozen]
+ *           .cbp-wb__ws-dims
+ *           .cbp-wb__ws-floor
+ *       .cbp-wb__dock  (sticky right column)
+ *         .cbp-wb__att.cbp-wb__att--in   (Wire Input — inputContainer)
+ *         .cbp-wb__att.cbp-wb__att--out  (Native Calls accordion)
+ *
+ * @param root - Container element (e.g. document.body or a div).
+ * @param scenarios - Full list of scenarios.
+ * @param opts - Workbench options (for defaultViewport).
+ * @param handlers - `onActivate` fires immediately with the initial scenario and
+ *   again on scenario/view switch; `onThemeChange` fires when the theme picker
+ *   changes. Both carry the current preset key.
+ */
+export declare function renderChrome(root: HTMLElement, scenarios: PreviewScenario[], opts: Pick<PreviewWorkbenchOptions, 'defaultViewport'>, handlers: ChromeHandlers): ChromeResult;

package/dist/preview/fakeHost.d.ts

@@ -0,0 +1,30 @@
+/** Button spec carried by the `*.setButtons` host verbs. */
+export interface FakeHostButton {
+    id: string;
+    title: string;
+    isEnabled?: boolean;
+}
+export interface FakeHostHooks {
+    onCall(method: string, payload: unknown): void;
+    onSetHeight(height: number): void;
+    /**
+     * Fired for `attachmentRenderer.setButtons` / `action.setButtons` so the host
+     * chrome can reflect the plugin's real button titles. The wire contract does
+     * not carry a default button id, so `defaultButtonID` is null unless a payload
+     * defensively supplies one.
+     */
+    onSetButtons(buttons: FakeHostButton[], defaultButtonID: string | null): void;
+}
+/**
+ * Install a fake webkit.messageHandlers bridge on `target`.
+ *
+ * Intercepts all plugin→host calls:
+ * - Invokes hooks.onCall(method, payload) for every call.
+ * - Invokes hooks.onSetHeight(height) when method === WINDOW_SET_HEIGHT_METHOD.
+ * - Invokes hooks.onSetButtons(...) when method ends with `.setButtons`.
+ * - Returns per-verb default replies so plugin awaits never deadlock or crash.
+ *
+ * Handler name and setHeight method name come from generated wire constants —
+ * no hardcoded strings here.
+ */
+export declare function installFakeHost(target: Window, hooks: FakeHostHooks): void;