@harborclient/sdk 0.6.10 → 0.6.14

package/dist/components/forms/Checkbox.js

@@ -5,7 +5,7 @@ import { checkboxBox, checkboxInput } from './classes.js';
  */
 export function Checkbox({ ref, className, ...props }) {
     const wrapperClasses = className
-        ? `relative inline-flex shrink-0 ${className}`
-        : 'relative inline-flex shrink-0';
+        ? `relative inline-flex h-[18px] w-[18px] shrink-0 leading-none ${className}`
+        : 'relative inline-flex h-[18px] w-[18px] shrink-0 leading-none';
     return (_jsxs("span", { className: wrapperClasses, children: [_jsx("input", { ref: ref, type: "checkbox", className: checkboxInput, ...props }), _jsx("span", { className: checkboxBox, "aria-hidden": true, children: _jsx("svg", { className: "h-3 w-3", viewBox: "0 0 12 12", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("path", { d: "M2.5 6L5 8.5L9.5 3.5", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] }));
 }

package/dist/components/forms/Radio.js

@@ -5,7 +5,7 @@ import { radioCircle, radioInput } from './classes.js';
  */
 export function Radio({ ref, className, ...props }) {
     const wrapperClasses = className
-        ? `relative inline-flex shrink-0 ${className}`
-        : 'relative inline-flex shrink-0';
+        ? `relative inline-flex h-[18px] w-[18px] shrink-0 leading-none ${className}`
+        : 'relative inline-flex h-[18px] w-[18px] shrink-0 leading-none';
     return (_jsxs("span", { className: wrapperClasses, children: [_jsx("input", { ref: ref, type: "radio", className: radioInput, ...props }), _jsx("span", { className: radioCircle, "aria-hidden": true, children: _jsx("span", { className: "h-2 w-2 rounded-full bg-accent" }) })] }));
 }

package/dist/components/forms/classes.d.ts

@@ -16,11 +16,11 @@ export declare const surfaceField = "w-full rounded-md border border-separator b
 /** Transparent overlay checkbox input sized to {@link checkboxBox}. */
 export declare const checkboxInput = "peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed";
 /** Custom checkbox box styled via `peer-checked` / `peer-focus-visible` on {@link checkboxInput}. */
-export declare const checkboxBox = "flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded border border-separator bg-field text-white peer-checked:border-accent peer-checked:bg-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>svg]:opacity-0 peer-checked:[&>svg]:opacity-100";
+export declare const checkboxBox = "pointer-events-none flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded border border-separator bg-field text-white peer-checked:border-accent peer-checked:bg-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>svg]:opacity-0 peer-checked:[&>svg]:opacity-100";
 /** Transparent overlay radio input sized to {@link radioCircle}. */
 export declare const radioInput = "peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed";
 /** Custom radio circle styled via `peer-checked` / `peer-focus-visible` on {@link radioInput}. */
-export declare const radioCircle = "flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-full border border-separator bg-field peer-checked:border-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>span]:opacity-0 peer-checked:[&>span]:opacity-100";
+export declare const radioCircle = "pointer-events-none flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-full border border-separator bg-field peer-checked:border-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>span]:opacity-0 peer-checked:[&>span]:opacity-100";
 /**
  * Merges a field variant preset with optional caller classes.
  *

package/dist/components/forms/classes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../../src/components/forms/classes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,UAAU,gEAAgE,CAAC;AAExF,mEAAmE;AACnE,eAAO,MAAM,KAAK,4FACyE,CAAC;AAE5F,wDAAwD;AACxD,eAAO,MAAM,YAAY,uFAC6D,CAAC;AAEvF,uEAAuE;AACvE,eAAO,MAAM,aAAa,iGACsE,CAAC;AAEjG,qGAAqG;AACrG,eAAO,MAAM,WAAW,iZACwX,CAAC;AAEjZ,oEAAoE;AACpE,eAAO,MAAM,UAAU,iGACyE,CAAC;AAEjG,kGAAkG;AAClG,eAAO,MAAM,WAAW,sXAC6V,CAAC;AAOtX;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM/F"}
+{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../../src/components/forms/classes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,UAAU,gEAAgE,CAAC;AAExF,mEAAmE;AACnE,eAAO,MAAM,KAAK,4FACyE,CAAC;AAE5F,wDAAwD;AACxD,eAAO,MAAM,YAAY,uFAC6D,CAAC;AAEvF,uEAAuE;AACvE,eAAO,MAAM,aAAa,iGACsE,CAAC;AAEjG,qGAAqG;AACrG,eAAO,MAAM,WAAW,qaAC4Y,CAAC;AAEra,oEAAoE;AACpE,eAAO,MAAM,UAAU,iGACyE,CAAC;AAEjG,kGAAkG;AAClG,eAAO,MAAM,WAAW,0YACiX,CAAC;AAO1Y;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM/F"}

package/dist/components/forms/classes.js

@@ -12,11 +12,11 @@ export const surfaceField = 'w-full rounded-md border border-separator bg-field
 /** Transparent overlay checkbox input sized to {@link checkboxBox}. */
 export const checkboxInput = 'peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed';
 /** Custom checkbox box styled via `peer-checked` / `peer-focus-visible` on {@link checkboxInput}. */
-export const checkboxBox = 'flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded border border-separator bg-field text-white peer-checked:border-accent peer-checked:bg-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>svg]:opacity-0 peer-checked:[&>svg]:opacity-100';
+export const checkboxBox = 'pointer-events-none flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded border border-separator bg-field text-white peer-checked:border-accent peer-checked:bg-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>svg]:opacity-0 peer-checked:[&>svg]:opacity-100';
 /** Transparent overlay radio input sized to {@link radioCircle}. */
 export const radioInput = 'peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed';
 /** Custom radio circle styled via `peer-checked` / `peer-focus-visible` on {@link radioInput}. */
-export const radioCircle = 'flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-full border border-separator bg-field peer-checked:border-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>span]:opacity-0 peer-checked:[&>span]:opacity-100';
+export const radioCircle = 'pointer-events-none flex h-[18px] w-[18px] shrink-0 items-center justify-center rounded-full border border-separator bg-field peer-checked:border-accent peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-accent peer-disabled:cursor-not-allowed peer-disabled:opacity-50 [&>span]:opacity-0 peer-checked:[&>span]:opacity-100';
 const VARIANT_CLASSES = {
     control: field,
     surface: surfaceField

package/dist/runtime/contributionRegistry.js

@@ -0,0 +1,83 @@
+/**
+ * In-memory contribution registry for one plugin activation inside an isolated webview.
+ */
+
+/** @type {Map<string, unknown>} */
+const components = new Map();
+
+/** @type {Map<string, unknown>} */
+const indicators = new Map();
+
+/** @type {Map<string, unknown>} */
+const headerActions = new Map();
+
+/**
+ * Stores a UI contribution component keyed by manifest contribution id.
+ *
+ * @param {string} kind - Contribution bucket (requestTabs, sidebarPanels, etc.).
+ * @param {string} contributionId - Manifest contributes.* id.
+ * @param {unknown} component - React component reference.
+ */
+export function registerContributionComponent(kind, contributionId, component) {
+  components.set(`${kind}:${contributionId}`, component);
+}
+
+/**
+ * Stores an optional footer panel indicator component.
+ *
+ * @param {string} contributionId - Manifest footerPanels id.
+ * @param {unknown} component - React indicator component.
+ */
+export function registerContributionIndicator(contributionId, component) {
+  indicators.set(contributionId, component);
+}
+
+/**
+ * Stores an optional sidebar section headerActions component.
+ *
+ * @param {string} contributionId - Manifest sidebarSections id.
+ * @param {unknown} component - React headerActions component.
+ */
+export function registerContributionHeaderActions(contributionId, component) {
+  headerActions.set(contributionId, component);
+}
+
+/**
+ * Returns a registered contribution component.
+ *
+ * @param {string} kind - Contribution bucket.
+ * @param {string} contributionId - Manifest contributes.* id.
+ * @returns {unknown | undefined}
+ */
+export function getContributionComponent(kind, contributionId) {
+  return components.get(`${kind}:${contributionId}`);
+}
+
+/**
+ * Returns a registered footer panel indicator component.
+ *
+ * @param {string} contributionId - Manifest footerPanels id.
+ * @returns {unknown | undefined}
+ */
+export function getContributionIndicator(contributionId) {
+  return indicators.get(contributionId);
+}
+
+/**
+ * Returns a registered sidebar section headerActions component.
+ *
+ * @param {string} contributionId - Manifest sidebarSections id.
+ * @returns {unknown | undefined}
+ */
+export function getContributionHeaderActions(contributionId) {
+  return headerActions.get(contributionId);
+}
+
+/**
+ * Clears all stored contribution components for a fresh activation.
+ */
+export function clearContributionRegistry() {
+  components.clear();
+  indicators.clear();
+  headerActions.clear();
+}

package/dist/runtime/createBridgedPluginContext.js

@@ -0,0 +1,678 @@
+import { bridgeInvoke, bridgeOn } from './hcBridge.js';
+import {
+  getContributionComponent,
+  getContributionHeaderActions,
+  getContributionIndicator,
+  registerContributionComponent,
+  registerContributionHeaderActions,
+  registerContributionIndicator
+} from './contributionRegistry.js';
+import { setHostReact } from './reactHost.js';
+
+/** @type {Map<string, Set<(...args: unknown[]) => void | Promise<void>>>} */
+const commandHandlers = new Map();
+
+/**
+ * Parses a view-host role string into agent vs view contribution id.
+ *
+ * @param {string | null | undefined} role - Role query parameter from the shell URL.
+ * @returns {{ mode: 'agent' | 'view'; contributionId?: string }}
+ */
+export function parseViewHostRole(role) {
+  if (role == null || role === 'agent') {
+    return { mode: 'agent' };
+  }
+  if (role.startsWith('view:')) {
+    return { mode: 'view', contributionId: role.slice('view:'.length) };
+  }
+  if (role === 'view') {
+    return { mode: 'view' };
+  }
+  return { mode: 'agent' };
+}
+
+/**
+ * Builds a disposable handle that removes one command handler registration.
+ *
+ * @param {string} scopedId - Namespaced command id.
+ * @param {(...args: unknown[]) => void | Promise<void>} handler - Handler to remove.
+ * @returns {{ dispose: () => void }}
+ */
+function createCommandDisposable(scopedId, handler) {
+  return {
+    dispose: () => {
+      const handlers = commandHandlers.get(scopedId);
+      if (!handlers) {
+        return;
+      }
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        commandHandlers.delete(scopedId);
+      }
+    }
+  };
+}
+
+/**
+ * Executes a registered plugin command inside this webview realm.
+ *
+ * @param {string} pluginId - Plugin manifest id.
+ * @param {string} commandId - Command id declared in the manifest.
+ * @param {unknown[]} args - Arguments passed to the handler.
+ */
+export async function executeLocalPluginCommand(pluginId, commandId, ...args) {
+  const scopedId = `${pluginId}:${commandId}`;
+  const handlers = commandHandlers.get(scopedId);
+  if (!handlers) {
+    throw new Error(`Unknown plugin command: ${scopedId}`);
+  }
+  for (const handler of handlers) {
+    await handler(...args);
+  }
+}
+
+/**
+ * Creates the plugin activation context backed by the main-process broker.
+ *
+ * @param {object} options - Activation options parsed from the shell URL.
+ * @param {string} options.pluginId - Plugin manifest id.
+ * @param {'agent' | 'view'} options.mode - Agent runs logic; view renders one contribution.
+ * @param {string | undefined} options.contributionId - Manifest contribution id for view mode.
+ * @param {typeof import('react')} options.react - React namespace for this webview realm.
+ * @param {Record<string, unknown>} options.manifest - Parsed plugin manifest.
+ * @returns {import('../types').PluginContext}
+ */
+export function createBridgedPluginContext({ pluginId, mode, contributionId, react, manifest }) {
+  const subscriptions = [];
+  const permissions = new Set(manifest.permissions ?? []);
+  const isAgent = mode === 'agent';
+
+  /**
+   * Asserts that the plugin declared a permission in its manifest.
+   *
+   * @param {string} permission - Required permission flag.
+   */
+  const assertPermission = (permission) => {
+    if (!permissions.has(permission)) {
+      throw new Error(`Plugin ${pluginId} lacks permission: ${permission}`);
+    }
+  };
+
+  /**
+   * Asserts UI permission for contribution registration.
+   */
+  const assertUi = () => assertPermission('ui');
+
+  /**
+   * Returns whether UI registration should run in this webview role.
+   */
+  const canRegisterUi = () => isAgent || mode === 'view';
+
+  /**
+   * Asserts that a contribution id is declared in manifest.contributes.
+   *
+   * @param {string} key - contributes.* key.
+   * @param {string} id - Contribution id.
+   */
+  const assertManifestContribution = (key, id) => {
+    const entries = manifest.contributes?.[key];
+    if (!Array.isArray(entries) || !entries.some((entry) => entry.id === id)) {
+      throw new Error(`Contribution id "${id}" is not declared in manifest.contributes.${key}.`);
+    }
+  };
+
+  /**
+   * Asserts that a menu command is declared in manifest.contributes.menus.
+   *
+   * @param {string} command - Command id referenced by the menu item.
+   */
+  const assertManifestMenuCommand = (command) => {
+    const entries = manifest.contributes?.menus;
+    if (!Array.isArray(entries) || !entries.some((entry) => entry.command === command)) {
+      throw new Error(`Command "${command}" is not declared in manifest.contributes.menus.`);
+    }
+  };
+
+  /**
+   * Registers a UI contribution locally and forwards metadata to the host when agent.
+   *
+   * @param {string} kind - Contribution bucket key.
+   * @param {string} id - Manifest contribution id.
+   * @param {Record<string, unknown>} metadata - Serializable metadata for the host registry.
+   * @param {unknown} component - React component registered in this realm.
+   * @param {object} [options] - Optional indicator/headerActions components.
+   * @param {unknown} [options.indicator] - Footer panel indicator component.
+   * @param {unknown} [options.headerActions] - Sidebar section header actions component.
+   * @returns {{ dispose: () => void }}
+   */
+  const registerUiContribution = (kind, id, metadata, component, options = {}) => {
+    assertUi();
+    registerContributionComponent(kind, id, component);
+    if (options.indicator) {
+      registerContributionIndicator(id, options.indicator);
+    }
+    if (options.headerActions) {
+      registerContributionHeaderActions(id, options.headerActions);
+    }
+
+    if (isAgent) {
+      void bridgeInvoke('registerContribution', {
+        kind,
+        contribution: { pluginId, ...metadata }
+      });
+    }
+
+    return {
+      dispose: () => {
+        if (isAgent) {
+          void bridgeInvoke('unregisterContribution', { kind, contributionId: id });
+        }
+      }
+    };
+  };
+
+  /**
+   * No-op UI registration in view webviews (agent owns metadata).
+   *
+   * @returns {{ dispose: () => void }}
+   */
+  const noopDisposable = () => ({ dispose: () => {} });
+
+  setHostReact(react);
+
+  return {
+    pluginId,
+    react,
+    subscriptions,
+    storage: {
+      get: async (key) => {
+        assertPermission('storage');
+        return bridgeInvoke('storage.get', { key });
+      },
+      set: async (key, value) => {
+        assertPermission('storage');
+        await bridgeInvoke('storage.set', { key, value });
+      }
+    },
+    database: {
+      query: (mode, sql, params, txnId) => {
+        assertPermission('database');
+        return bridgeInvoke('database.query', { mode, sql, params, txnId });
+      },
+      exec: (sql) => {
+        assertPermission('database');
+        return bridgeInvoke('database.exec', { sql });
+      },
+      beginTransaction: () => {
+        assertPermission('database');
+        return bridgeInvoke('database.beginTransaction');
+      },
+      endTransaction: (txnId, action) => {
+        assertPermission('database');
+        return bridgeInvoke('database.endTransaction', { txnId, action });
+      }
+    },
+    fs: {
+      pickFile: async (options) => {
+        assertPermission('filesystem:pick');
+        return bridgeInvoke('fs.pickFile', { options });
+      },
+      pickDirectory: async (defaultPath) => {
+        assertPermission('filesystem:pick');
+        return bridgeInvoke('fs.pickDirectory', { defaultPath: defaultPath ?? '' });
+      },
+      saveFile: async (content, options) => {
+        assertPermission('filesystem:pick');
+        return bridgeInvoke('fs.saveFile', { content, options });
+      },
+      readFile: async (path) => {
+        assertPermission('filesystem:read');
+        return bridgeInvoke('fs.readFile', { path });
+      },
+      writeFile: async (path, content) => {
+        assertPermission('filesystem:write');
+        await bridgeInvoke('fs.writeFile', { path, content });
+      },
+      watchFile: (path, listener) => {
+        assertPermission('filesystem:read');
+        const unsubscribe = bridgeOn(`fs.watch:${path}`, () => {
+          listener(path);
+        });
+        void bridgeInvoke('fs.watchFile', { path });
+        return { dispose: unsubscribe };
+      }
+    },
+    commands: {
+      register: (id, handler) => {
+        assertUi();
+        assertManifestContribution('commands', id);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        const scopedId = `${pluginId}:${id}`;
+        const handlers = commandHandlers.get(scopedId) ?? new Set();
+        handlers.add(handler);
+        commandHandlers.set(scopedId, handlers);
+        return createCommandDisposable(scopedId, handler);
+      },
+      execute: async (id, ...args) => {
+        const [ownerId, commandId] = id.includes(':') ? id.split(':', 2) : [pluginId, id];
+        if (ownerId === pluginId) {
+          await executeLocalPluginCommand(ownerId, commandId, ...args);
+          return;
+        }
+        await bridgeInvoke('commands.executeRemote', { pluginId: ownerId, commandId, args });
+      }
+    },
+    themes: {
+      register: (theme) => {
+        assertUi();
+        assertManifestContribution('themes', theme.id);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        void bridgeInvoke('themes.register', { theme });
+        return {
+          dispose: () => {
+            void bridgeInvoke('themes.unregister', { themeId: theme.id });
+          }
+        };
+      },
+      getActive: async () => bridgeInvoke('themes.getActive'),
+      onDidChange: (listener) => {
+        const unsubscribe = bridgeOn('themes.changed', listener);
+        void bridgeInvoke('themes.getActive').then(listener);
+        return { dispose: unsubscribe };
+      }
+    },
+    ui: {
+      registerSettingsSection: (section) => {
+        assertManifestContribution('settingsSections', section.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'settingsSections',
+          section.id,
+          {
+            id: `plugin:${pluginId}:${section.id}`,
+            title: section.title,
+            contributionId: section.id
+          },
+          section.Component
+        );
+      },
+      registerSidebarPanel: (panel) => {
+        assertManifestContribution('sidebarPanels', panel.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'sidebarPanels',
+          panel.id,
+          {
+            id: `plugin:${pluginId}:${panel.id}`,
+            title: panel.title,
+            icon: panel.icon,
+            order: panel.order,
+            contributionId: panel.id
+          },
+          panel.Component
+        );
+      },
+      registerSidebarSection: (section) => {
+        assertManifestContribution('sidebarSections', section.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'sidebarSections',
+          section.id,
+          {
+            id: `plugin:${pluginId}:${section.id}`,
+            title: section.title,
+            order: section.order,
+            contributionId: section.id,
+            hasHeaderActions: Boolean(section.headerActions)
+          },
+          section.Component,
+          { headerActions: section.headerActions }
+        );
+      },
+      registerMainView: (view) => {
+        assertManifestContribution('mainViews', view.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'mainViews',
+          view.id,
+          { id: `plugin:${pluginId}:${view.id}`, title: view.title, contributionId: view.id },
+          view.Component
+        );
+      },
+      registerRequestTab: (tab) => {
+        assertManifestContribution('requestTabs', tab.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'requestTabs',
+          tab.id,
+          {
+            id: `plugin:${pluginId}:${tab.id}`,
+            title: tab.title,
+            order: tab.order,
+            contributionId: tab.id
+          },
+          tab.Component
+        );
+      },
+      registerResponseTab: (tab) => {
+        assertManifestContribution('responseTabs', tab.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'responseTabs',
+          tab.id,
+          {
+            id: `plugin:${pluginId}:${tab.id}`,
+            title: tab.title,
+            order: tab.order,
+            when: tab.when,
+            contributionId: tab.id
+          },
+          tab.Component
+        );
+      },
+      registerCollectionSettingsTab: (tab) => {
+        assertManifestContribution('collectionSettingsTabs', tab.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'collectionSettingsTabs',
+          tab.id,
+          {
+            id: `plugin:${pluginId}:${tab.id}`,
+            title: tab.title,
+            order: tab.order,
+            contributionId: tab.id
+          },
+          tab.Component
+        );
+      },
+      registerFooterPanel: (panel) => {
+        assertManifestContribution('footerPanels', panel.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'footerPanels',
+          panel.id,
+          {
+            id: `plugin:${pluginId}:${panel.id}`,
+            title: panel.title,
+            contributionId: panel.id,
+            hasIndicator: Boolean(panel.Indicator)
+          },
+          panel.Component,
+          { indicator: panel.Indicator }
+        );
+      },
+      registerMenuItem: (item) => {
+        assertManifestMenuCommand(item.command);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        void bridgeInvoke('registerContribution', {
+          kind: 'menuItems',
+          contribution: {
+            pluginId,
+            menu: item.menu,
+            command: item.command,
+            label: item.label,
+            group: item.group,
+            order: item.order
+          }
+        });
+        return {
+          dispose: () => {
+            void bridgeInvoke('unregisterContribution', {
+              kind: 'menuItems',
+              contributionId: `${item.menu}:${item.command}`
+            });
+          }
+        };
+      },
+      registerRequestToolbarAction: (action) => {
+        assertManifestContribution('requestToolbarActions', action.id);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        void bridgeInvoke('registerContribution', {
+          kind: 'requestToolbarActions',
+          contribution: {
+            pluginId,
+            id: action.id,
+            title: action.title,
+            command: action.command,
+            icon: action.icon,
+            order: action.order
+          }
+        });
+        return {
+          dispose: () => {
+            void bridgeInvoke('unregisterContribution', {
+              kind: 'requestToolbarActions',
+              contributionId: action.id
+            });
+          }
+        };
+      },
+      registerContextMenuItem: (item) => {
+        assertManifestContribution('contextMenus', item.id);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        void bridgeInvoke('registerContribution', {
+          kind: 'contextMenuItems',
+          contribution: {
+            pluginId,
+            id: item.id,
+            title: item.title,
+            command: item.command,
+            when: item.when,
+            group: item.group,
+            order: item.order
+          }
+        });
+        return {
+          dispose: () => {
+            void bridgeInvoke('unregisterContribution', {
+              kind: 'contextMenuItems',
+              contributionId: item.id
+            });
+          }
+        };
+      },
+      registerStatusBarItem: (item) => {
+        assertManifestContribution('statusBarItems', item.id);
+        if (!canRegisterUi()) {
+          return noopDisposable();
+        }
+        return registerUiContribution(
+          'statusBarItems',
+          item.id,
+          {
+            id: `plugin:${pluginId}:${item.id}`,
+            alignment: item.alignment,
+            order: item.order,
+            contributionId: item.id
+          },
+          item.Component
+        );
+      },
+      showToast: (message, options) => {
+        assertUi();
+        void bridgeInvoke('ui.showToast', { message, options });
+      }
+    },
+    http: {
+      onAfterSend: (handler) => {
+        assertPermission('http');
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        const unsubscribe = bridgeOn('http.afterSend', handler);
+        return { dispose: unsubscribe };
+      }
+    },
+    ipc: {
+      invoke: async (channel, ...args) => {
+        assertPermission('ipc');
+        return bridgeInvoke('ipc.invoke', { channel, args });
+      }
+    },
+    host: {
+      openRequestDraft: async (payload) => {
+        assertUi();
+        await bridgeInvoke('host.openRequestDraft', { payload });
+      },
+      loadRequest: async (requestId) => {
+        assertUi();
+        await bridgeInvoke('host.loadRequest', { requestId });
+      },
+      sendRequest: async () => {
+        assertUi();
+        await bridgeInvoke('host.sendRequest');
+      },
+      createEnvironmentWithVariables: async (name, variables) => {
+        assertUi();
+        return bridgeInvoke('host.createEnvironmentWithVariables', { name, variables });
+      },
+      updateEnvironmentVariables: async (environmentId, variables) => {
+        assertUi();
+        await bridgeInvoke('host.updateEnvironmentVariables', { environmentId, variables });
+      },
+      createCollection: async (payload) => {
+        assertUi();
+        return bridgeInvoke('host.createCollection', { payload });
+      },
+      listCollectionRequests: async (collectionId, folderId) => {
+        assertUi();
+        return bridgeInvoke('host.listCollectionRequests', { collectionId, folderId });
+      },
+      getCollectionMetadata: async (collectionId) => {
+        assertUi();
+        return bridgeInvoke('host.getCollectionMetadata', { collectionId });
+      },
+      logRequestToConsole: async (payload) => {
+        assertUi();
+        await bridgeInvoke('host.logRequestToConsole', { payload });
+      },
+      sendHttpRequest: async (input) => {
+        assertUi();
+        return bridgeInvoke('host.sendHttpRequest', { input });
+      },
+      clearResponse: async () => {
+        assertUi();
+        await bridgeInvoke('host.clearResponse');
+      }
+    }
+  };
+}
+
+/**
+ * Maps a manifest contributes key to the contribution registry bucket name.
+ *
+ * @param {string} contributionId - Manifest contribution id for view mode.
+ * @returns {string | undefined}
+ */
+export function resolveContributionKindFromUrl(contributionId, searchParams) {
+  const kind = searchParams.get('kind');
+  return kind ?? undefined;
+}
+
+/**
+ * Mounts one contribution component into the view webview root element.
+ *
+ * @param {object} options - Mount options.
+ * @param {typeof import('react')} options.react - React namespace.
+ * @param {typeof import('react-dom/client')} options.reactDom - React DOM client namespace.
+ * @param {string} options.kind - Contribution bucket.
+ * @param {string} options.contributionId - Manifest contribution id.
+ * @param {HTMLElement} options.root - DOM mount target.
+ * @param {'content' | 'headerActions' | 'indicator'} [options.slot] - Contribution sub-slot.
+ * @returns {() => void} Cleanup function that unmounts the React root.
+ */
+export function mountContributionView({
+  react,
+  reactDom,
+  kind,
+  contributionId,
+  root,
+  slot = 'content'
+}) {
+  let Component;
+  if (slot === 'headerActions') {
+    Component = getContributionHeaderActions(contributionId);
+  } else if (slot === 'indicator') {
+    Component = getContributionIndicator(contributionId);
+  } else {
+    Component = getContributionComponent(kind, contributionId);
+  }
+  if (Component == null) {
+    throw new Error(`Unknown plugin contribution: ${kind}:${contributionId}`);
+  }
+
+  /** @type {unknown} */
+  let currentContext = null;
+
+  const needsContext =
+    kind === 'requestTabs' || kind === 'responseTabs' || kind === 'collectionSettingsTabs';
+
+  const reactRoot = reactDom.createRoot(root);
+
+  /**
+   * Renders the contribution with the latest pushed context snapshot. For
+   * context-bearing contributions the first render is deferred until a context
+   * snapshot is available so the component never receives a null context.
+   */
+  const render = () => {
+    if (needsContext && currentContext == null) {
+      return;
+    }
+    const element = needsContext
+      ? react.createElement(Component, { context: currentContext })
+      : react.createElement(Component);
+    reactRoot.render(element);
+  };
+
+  const unsubscribe = bridgeOn('view.context', (payload) => {
+    currentContext = payload;
+    render();
+  });
+
+  if (needsContext) {
+    // The host pushes context on mount/dom-ready, which can race ahead of this
+    // subscription, so pull the current snapshot now that we are listening.
+    void bridgeInvoke('view.getContext')
+      .then((context) => {
+        if (context != null && currentContext == null) {
+          currentContext = context;
+          render();
+        }
+      })
+      .catch(() => {});
+  }
+
+  render();
+
+  return () => {
+    unsubscribe();
+  };
+}
+
+export { getContributionComponent, getContributionHeaderActions, getContributionIndicator };

package/dist/runtime/hcBridge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Preload bridge exposed to isolated plugin webContents.
+ */
+export interface HcBridgeGlobal {
+  /**
+   * Invokes a permission-checked broker operation in the main process.
+   */
+  invoke(op: string, payload?: unknown): Promise<unknown>;
+
+  /**
+   * Subscribes to preload push events from the main process.
+   */
+  on(channel: string, listener: (payload: unknown) => void): () => void;
+
+  /** @internal Prevents duplicate handler installation. */
+  __handlersInstalled?: boolean;
+}
+
+declare global {
+  /**
+   * Scoped plugin bridge installed by the HarborClient plugin preload.
+   */
+  var hcBridge: HcBridgeGlobal | undefined;
+}
+
+export {};

package/dist/runtime/hcBridge.js

@@ -0,0 +1,104 @@
+/** @type {number} */
+let nextRequestId = 1;
+
+/** @type {Map<number, { resolve: (value: unknown) => void; reject: (reason?: unknown) => void }>} */
+const pendingRequests = new Map();
+
+/** @type {Map<string, Set<(payload: unknown) => void>>} */
+const eventListeners = new Map();
+
+/**
+ * Returns the preload-provided bridge or throws when the plugin preload is missing.
+ *
+ * @returns {import('./hcBridge.d.ts').HcBridgeGlobal}
+ */
+export function requireHcBridge() {
+  const bridge = globalThis.hcBridge;
+  if (bridge == null) {
+    throw new Error('Plugin hcBridge is not available. Is the plugin preload loaded?');
+  }
+  return bridge;
+}
+
+/**
+ * Invokes a permission-checked host operation through the main-process broker.
+ *
+ * @param {string} op - Broker operation name.
+ * @param {unknown} [payload] - Serializable operation payload.
+ * @returns {Promise<unknown>}
+ */
+export async function bridgeInvoke(op, payload) {
+  return requireHcBridge().invoke(op, payload);
+}
+
+/**
+ * Subscribes to broker push events (theme changes, tab context updates, etc.).
+ *
+ * @param {string} channel - Event channel name.
+ * @param {(payload: unknown) => void} listener - Event handler.
+ * @returns {() => void} Unsubscribe function.
+ */
+export function bridgeOn(channel, listener) {
+  const bridge = requireHcBridge();
+  return bridge.on(channel, listener);
+}
+
+/**
+ * Handles correlated replies from the main-process broker.
+ *
+ * @param {{ id: number; ok: boolean; result?: unknown; error?: string }} message - Broker reply.
+ */
+export function handleBridgeReply(message) {
+  const pending = pendingRequests.get(message.id);
+  if (!pending) {
+    return;
+  }
+  pendingRequests.delete(message.id);
+  if (message.ok) {
+    pending.resolve(message.result);
+    return;
+  }
+  pending.reject(new Error(message.error ?? 'Plugin bridge invocation failed.'));
+}
+
+/**
+ * Dispatches a broker push event to registered listeners.
+ *
+ * @param {string} channel - Event channel name.
+ * @param {unknown} payload - Event payload.
+ */
+export function dispatchBridgeEvent(channel, payload) {
+  const listeners = eventListeners.get(channel);
+  if (!listeners) {
+    return;
+  }
+  for (const listener of listeners) {
+    listener(payload);
+  }
+}
+
+/** Guards repeated bootstrap calls without mutating the frozen bridge object. */
+let handlersInstalled = false;
+
+/**
+ * Prepares the bridge for use inside a plugin webview.
+ *
+ * The HarborClient plugin preload exposes a high-level bridge: `invoke` is
+ * promise-based and `on(channel, listener)` dispatches host push events by
+ * channel. `bridgeInvoke` and `bridgeOn` delegate straight to those methods,
+ * so no reply/event correlation layer is needed here.
+ *
+ * The bridge is exposed through Electron `contextBridge`, which makes it
+ * non-extensible with read-only properties. We therefore must not assign to it
+ * (for example `bridge.__handlersInstalled` or reassigning `bridge.on`); doing
+ * so throws "object is not extensible". Idempotency is tracked module-side.
+ *
+ * Called once from the view host bootstrap before plugin activation.
+ */
+export function installBridgeHandlers() {
+  if (handlersInstalled) {
+    return;
+  }
+  requireHcBridge();
+  handlersInstalled = true;
+}

package/dist/runtime/view-host/index.d.ts

@@ -0,0 +1 @@
+export { bootstrapViewHost, applyHostTheme } from '../viewHost.js';

package/dist/runtime/view-host/index.js

@@ -0,0 +1,3 @@
+import { bootstrapViewHost, applyHostTheme } from './viewHost.js';
+
+export { bootstrapViewHost, applyHostTheme };

package/dist/runtime/viewHost.js

@@ -0,0 +1,121 @@
+import { installBridgeHandlers, bridgeOn } from './hcBridge.js';
+import { clearContributionRegistry } from './contributionRegistry.js';
+import {
+  createBridgedPluginContext,
+  executeLocalPluginCommand,
+  mountContributionView,
+  parseViewHostRole,
+  resolveContributionKindFromUrl
+} from './createBridgedPluginContext.js';
+
+/**
+ * Bootstraps an isolated plugin webview shell.
+ *
+ * Loads the plugin renderer bundle, runs activate(hc), and either registers
+ * contributions with the host (agent role) or mounts one UI contribution (view role).
+ *
+ * @param {object} [options] - Bootstrap options; defaults are parsed from location.search.
+ * @param {string} [options.pluginId] - Plugin manifest id from the shell URL hostname.
+ * @param {string | null} [options.role] - Agent or view role query parameter.
+ * @param {string | null} [options.contrib] - Manifest contribution id for view mode.
+ * @param {string | null} [options.kind] - Contribution bucket for view mode.
+ */
+export async function bootstrapViewHost(options = {}) {
+  installBridgeHandlers();
+
+  const url = new URL(globalThis.location.href);
+  const pluginId = options.pluginId ?? url.hostname;
+  const roleParam = options.role ?? url.searchParams.get('role');
+  const contrib = options.contrib ?? url.searchParams.get('contrib');
+  const kind =
+    options.kind ??
+    url.searchParams.get('kind') ??
+    resolveContributionKindFromUrl(contrib, url.searchParams);
+  const slot = url.searchParams.get('slot') ?? 'content';
+
+  const parsedRole = parseViewHostRole(
+    roleParam === 'view' && contrib ? `view:${contrib}` : roleParam
+  );
+  const contributionId = parsedRole.contributionId ?? contrib ?? undefined;
+
+  const [{ default: React }, { default: ReactDOM }, { default: ReactDOMClient }] =
+    await Promise.all([
+      import('harbor-plugin://host/react.js'),
+      import('harbor-plugin://host/react-dom.js'),
+      import('harbor-plugin://host/react-dom-client.js')
+    ]);
+
+  const manifest = await fetch(`harbor-plugin://${pluginId}/manifest.json`).then((response) =>
+    response.json()
+  );
+
+  clearContributionRegistry();
+
+  const bundleUrl = `harbor-plugin://${pluginId}/bundle.js`;
+  const module = await import(/* @vite-ignore */ bundleUrl);
+  if (typeof module.activate !== 'function') {
+    throw new Error(`Plugin ${pluginId} renderer entry must export activate(hc).`);
+  }
+
+  const hc = createBridgedPluginContext({
+    pluginId,
+    mode: parsedRole.mode,
+    contributionId,
+    react: React,
+    manifest
+  });
+
+  await module.activate(hc);
+
+  if (parsedRole.mode === 'agent') {
+    bridgeOn('commands.execute', async (payload) => {
+      const { commandId, args } = payload ?? {};
+      await executeLocalPluginCommand(pluginId, commandId, ...(args ?? []));
+    });
+    await fetch(`harbor-plugin://${pluginId}/agent-ready`, { method: 'POST' });
+    return;
+  }
+
+  if (!contributionId || !kind) {
+    throw new Error('View webviews require contrib and kind query parameters.');
+  }
+  const root = document.getElementById('root');
+  if (!root) {
+    throw new Error('Plugin view shell is missing #root.');
+  }
+  mountContributionView({
+    react: React,
+    reactDom: ReactDOMClient,
+    kind,
+    contributionId,
+    root,
+    slot
+  });
+}
+
+/**
+ * Applies a theme snapshot pushed from the host renderer.
+ *
+ * @param {{ dataTheme?: string | null; cssText?: string | null }} theme - Theme payload.
+ */
+export function applyHostTheme(theme) {
+  if (theme.dataTheme != null) {
+    document.documentElement.setAttribute('data-theme', theme.dataTheme);
+  }
+  if (theme.cssText) {
+    let style = document.getElementById('harbor-plugin-theme-vars');
+    if (!style) {
+      style = document.createElement('style');
+      style.id = 'harbor-plugin-theme-vars';
+      document.head.appendChild(style);
+    }
+    style.textContent = theme.cssText;
+  }
+}
+
+if (typeof globalThis !== 'undefined') {
+  globalThis.__HARBORCLIENT_VIEW_HOST__ = {
+    bootstrapViewHost,
+    applyHostTheme
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborclient/sdk",
-  "version": "0.6.10",
+  "version": "0.6.14",
   "description": "TypeScript SDK for HarborClient plugin development.",
   "keywords": [
     "harborclient",
@@ -100,6 +100,12 @@
       "require": "./dist/runtime/store.js",
       "default": "./dist/runtime/store.js"
     },
+    "./view-host": {
+      "types": "./dist/runtime/view-host/index.d.ts",
+      "import": "./dist/runtime/view-host/index.js",
+      "require": "./dist/runtime/view-host/index.js",
+      "default": "./dist/runtime/view-host/index.js"
+    },
     "./signing": {
       "types": "./dist/signing/index.d.ts",
       "import": "./dist/signing/index.js",