@harborclient/sdk 1.3.8 → 1.3.9

package/dist/runtime/createBridgedPluginContext.js

@@ -7,6 +7,7 @@ import {
 import { bridgeInvoke, bridgeOn } from './hcBridge.js';
 import { createPluginDatabaseApi } from './pluginDatabaseApi.js';
 import { setHostReact } from './reactHost.js';
+import { openWebpage } from './webpageHandle.js';
 
 /** @type {Map<string, Set<(...args: unknown[]) => void | Promise<void>>>} */
 const commandHandlers = new Map();
@@ -352,6 +353,52 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
    */
   const assertAi = () => assertPermission('ai');
 
+  /**
+   * Asserts browser permission for embedded webpage control.
+   */
+  const assertBrowser = () => assertPermission('browser');
+
+  /**
+   * Invokes a webpage session op on the host renderer via the plugin bridge.
+   *
+   * @param {Record<string, unknown>} req - ScriptWebpageRequest-shaped payload.
+   * @returns {Promise<unknown>} Host session result.
+   */
+  const callWebpage = async (req) => {
+    const op = String(req.op ?? '');
+    switch (op) {
+      case 'open':
+        return bridgeInvoke('webpage.open', { url: req.url, reuse: req.reuse });
+      case 'focus':
+        return bridgeInvoke('webpage.focus', { tabId: req.tabId });
+      case 'close':
+        return bridgeInvoke('webpage.close', { tabId: req.tabId });
+      case 'query':
+        return bridgeInvoke('webpage.query', {
+          tabId: req.tabId,
+          selector: req.selector,
+          all: req.all,
+          maxElements: req.maxElements
+        });
+      case 'evaluate':
+        return bridgeInvoke('webpage.evaluate', {
+          tabId: req.tabId,
+          expression: req.expression
+        });
+      case 'injectScript':
+        return bridgeInvoke('webpage.injectScript', { tabId: req.tabId, source: req.source });
+      case 'injectStylesheet':
+        return bridgeInvoke('webpage.injectStylesheet', { tabId: req.tabId, css: req.css });
+      case 'screenshot':
+        return bridgeInvoke('webpage.screenshot', {
+          tabId: req.tabId,
+          fullPage: req.fullPage === true
+        });
+      default:
+        throw new Error(`Unsupported webpage bridge op: ${op}`);
+    }
+  };
+
   /**
    * Asserts that a contribution id is declared in manifest.contributes.
    *
@@ -482,6 +529,18 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         assertPermission('filesystem:write');
         await bridgeInvoke('fs.writeFile', { path, content });
       },
+      writeBytes: async (path, bytes) => {
+        assertPermission('filesystem:write');
+        const u8 =
+          bytes instanceof Uint8Array
+            ? bytes
+            : new Uint8Array(/** @type {ArrayLike<number>} */ (bytes));
+        let binary = '';
+        for (let i = 0; i < u8.length; i += 1) {
+          binary += String.fromCharCode(u8[i] ?? 0);
+        }
+        return bridgeInvoke('fs.writeBytes', { path, base64: btoa(binary) });
+      },
       watchFile: (path, listener) => {
         assertPermission('filesystem:read');
         const unsubscribe = bridgeOn(`fs.watch:${path}`, () => {
@@ -1243,6 +1302,34 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
           selection: input?.selection
         });
       }
+    },
+    /**
+     * Opens or reuses an embedded browser tab and returns a control handle.
+     *
+     * Requires the `browser` permission. Same semantics as request-script `hc.webpage`.
+     *
+     * @param {string} [url] - Optional URL; omit to bind the active browser tab.
+     * @param {{ reuse?: boolean }} [options] - Optional `{ reuse }` (default true).
+     * @returns {Promise<import('../types').PluginWebpageHandle>} Webpage handle.
+     */
+    webpage: async (url, options) => {
+      assertBrowser();
+      /**
+       * Writes screenshot PNG bytes via the plugin filesystem bridge.
+       *
+       * @param {string} path - Relative or absolute allowlisted path.
+       * @param {string} pngBase64 - Base64-encoded PNG payload.
+       * @returns {Promise<string>} Absolute written path.
+       */
+      const writeScreenshotBytes = async (path, pngBase64) => {
+        assertPermission('filesystem:write');
+        const result = await bridgeInvoke('fs.writeBytes', { path, base64: pngBase64 });
+        if (typeof result !== 'string' || !result.trim()) {
+          throw new Error('hc.webpage().screenshot failed to resolve write path');
+        }
+        return result;
+      };
+      return openWebpage(callWebpage, url, options, writeScreenshotBytes);
     }
   };
 }

package/dist/runtime/reactHost.d.ts

@@ -0,0 +1,32 @@
+import type * as React from 'react';
+import type * as ReactDOM from 'react-dom';
+
+/**
+ * Installs the HarborClient renderer React instance for plugin JSX and hooks.
+ *
+ * @param react - React namespace from the host.
+ */
+export function setHostReact(react: typeof React): void;
+
+/**
+ * Returns the installed host React instance.
+ *
+ * @returns Host React namespace.
+ * @throws When {@link setHostReact} has not been called yet.
+ */
+export function requireHostReact(): typeof React;
+
+/**
+ * Installs the HarborClient renderer React DOM instance for plugin portals.
+ *
+ * @param reactDom - React DOM namespace from the host shim.
+ */
+export function setHostReactDom(reactDom: typeof ReactDOM): void;
+
+/**
+ * Returns the installed host React DOM instance.
+ *
+ * @returns Host React DOM namespace.
+ * @throws When {@link setHostReactDom} has not been called yet.
+ */
+export function requireHostReactDom(): typeof ReactDOM;

package/dist/runtime/webpageHandle.d.ts

@@ -0,0 +1,50 @@
+import type { PluginWebpageHandle } from '../types';
+
+/**
+ * Throws when a webpage bridge result is an `{ error }` object.
+ *
+ * @param result - Raw bridge result.
+ * @returns The result when it is not an error.
+ * @throws When the bridge returned `{ error: string }`.
+ */
+export function unwrapWebpageBridgeResult(result: unknown): unknown;
+
+/**
+ * Normalizes the optional second argument to `hc.webpage(url, options)`.
+ *
+ * @param options - User-provided options.
+ * @returns Normalized open options.
+ */
+export function normalizeWebpageOpenOptions(options?: unknown): { reuse?: boolean };
+
+/**
+ * Builds a webpage handle whose methods call the host webpage bridge.
+ *
+ * @param tab - Opened tab metadata from the bridge.
+ * @param callWebpage - Bridge transport.
+ * @returns Plain-object handle for the plugin world.
+ */
+export function createWebpageHandle(
+  tab: {
+    tabId: string;
+    url: string;
+    title: string;
+    canGoBack?: boolean;
+    canGoForward?: boolean;
+  },
+  callWebpage: (req: Record<string, unknown>) => Promise<unknown>
+): PluginWebpageHandle;
+
+/**
+ * Opens or reuses an embedded browser tab and returns a control handle.
+ *
+ * @param callWebpage - Bridge transport that accepts ScriptWebpageRequest-shaped payloads.
+ * @param url - Optional URL; omit to bind the active browser tab.
+ * @param openOptions - Optional `{ reuse }` (default true).
+ * @returns Webpage handle.
+ */
+export function openWebpage(
+  callWebpage: (req: Record<string, unknown>) => Promise<unknown>,
+  url?: unknown,
+  openOptions?: unknown
+): Promise<PluginWebpageHandle>;

package/dist/runtime/webpageHandle.js

@@ -0,0 +1,273 @@
+/**
+ * Throws when a webpage bridge result is an `{ error }` object.
+ *
+ * @param {unknown} result - Raw bridge result.
+ * @returns {unknown} The result when it is not an error.
+ * @throws {Error} When the bridge returned `{ error: string }`.
+ */
+export function unwrapWebpageBridgeResult(result) {
+  if (
+    result != null &&
+    typeof result === 'object' &&
+    !Array.isArray(result) &&
+    Object.keys(result).length === 1 &&
+    'error' in result &&
+    typeof (/** @type {{ error: unknown }} */ (result).error) === 'string'
+  ) {
+    throw new Error(/** @type {{ error: string }} */ (result).error);
+  }
+  return result;
+}
+
+/**
+ * Normalizes the optional second argument to `hc.webpage(url, options)`.
+ *
+ * @param {unknown} [options] - User-provided options.
+ * @returns {{ reuse?: boolean }} Normalized open options.
+ */
+export function normalizeWebpageOpenOptions(options) {
+  if (options == null) {
+    return {};
+  }
+  if (typeof options !== 'object' || Array.isArray(options)) {
+    throw new Error('hc.webpage options must be an object');
+  }
+  const raw = /** @type {Record<string, unknown>} */ (options);
+  if (!('reuse' in raw) || raw.reuse === undefined) {
+    return {};
+  }
+  if (typeof raw.reuse !== 'boolean') {
+    throw new Error('hc.webpage options.reuse must be a boolean');
+  }
+  return { reuse: raw.reuse };
+}
+
+/**
+ * Normalizes optional `hc.webpage().screenshot` options.
+ *
+ * @param {unknown} [options] - User-provided options (`fullPage` optional).
+ * @returns {{ fullPage: boolean }} Normalized options (default `fullPage: false`).
+ * @throws {Error} When options is present but not a plain object, or `fullPage` is not a boolean.
+ */
+export function normalizeWebpageScreenshotOptions(options) {
+  if (options == null) {
+    return { fullPage: false };
+  }
+  if (typeof options !== 'object' || Array.isArray(options)) {
+    throw new Error('hc.webpage().screenshot options must be an object');
+  }
+  const raw = /** @type {Record<string, unknown>} */ (options);
+  if (!('fullPage' in raw) || raw.fullPage === undefined) {
+    return { fullPage: false };
+  }
+  if (typeof raw.fullPage !== 'boolean') {
+    throw new Error('hc.webpage().screenshot options.fullPage must be a boolean');
+  }
+  return { fullPage: raw.fullPage };
+}
+
+/**
+ * Builds a webpage handle whose methods call the host webpage bridge.
+ *
+ * @param {{
+ *   tabId: string;
+ *   url: string;
+ *   title: string;
+ *   canGoBack?: boolean;
+ *   canGoForward?: boolean;
+ * }} tab - Opened tab metadata from the bridge.
+ * @param {(req: Record<string, unknown>) => Promise<unknown>} callWebpage - Bridge transport.
+ * @param {(path: string, pngBase64: string) => Promise<string>} [writeScreenshotBytes] - Optional
+ *   writer that saves PNG base64 under an allowlisted path and returns the absolute path.
+ * @returns {import('../types').PluginWebpageHandle} Plain-object handle for the plugin world.
+ */
+export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
+  const tabId = tab.tabId;
+  return {
+    tabId,
+    url: tab.url,
+    title: tab.title,
+    canGoBack: tab.canGoBack === true,
+    canGoForward: tab.canGoForward === true,
+    /**
+     * Focuses this browser tab in the HarborClient tab bar.
+     *
+     * @returns {Promise<void>} Resolves when the tab is focused.
+     */
+    focus: async () => {
+      unwrapWebpageBridgeResult(await callWebpage({ op: 'focus', tabId }));
+    },
+    /**
+     * Closes this browser tab, honoring page leave prompts.
+     *
+     * @returns {Promise<boolean>} True when closed; false when the user chose to stay.
+     */
+    close: async () => {
+      const result = /** @type {{ closed: boolean }} */ (
+        unwrapWebpageBridgeResult(await callWebpage({ op: 'close', tabId }))
+      );
+      return result.closed === true;
+    },
+    /**
+     * Captures the visible viewport (or full page) as PNG and writes it via the filesystem bridge.
+     *
+     * @param {unknown} path - Relative (plugin root) or absolute allowlisted path.
+     * @param {unknown} [screenshotOptions] - Optional `{ fullPage }` (default false).
+     * @returns {Promise<{ path: string }>} Absolute path of the written file.
+     */
+    screenshot: async (path, screenshotOptions) => {
+      const { fullPage } = normalizeWebpageScreenshotOptions(screenshotOptions);
+      const pathText = String(path ?? '').trim();
+      if (!pathText) {
+        throw new Error('hc.webpage().screenshot requires a path');
+      }
+      if (!writeScreenshotBytes) {
+        throw new Error('hc.webpage().screenshot requires hc.fs.writeBytes');
+      }
+      const capture = /** @type {{ pngBase64?: string }} */ (
+        unwrapWebpageBridgeResult(await callWebpage({ op: 'screenshot', tabId, fullPage }))
+      );
+      if (!capture || typeof capture.pngBase64 !== 'string' || !capture.pngBase64) {
+        throw new Error('hc.webpage().screenshot did not return image data');
+      }
+      const absolutePath = await writeScreenshotBytes(pathText, capture.pngBase64);
+      return { path: absolutePath };
+    },
+    dom: {
+      /**
+       * Queries the live page DOM with a CSS selector.
+       *
+       * @param {string} selector - CSS selector.
+       * @param {{ all?: boolean; maxElements?: number }} [queryOptions] - Optional query flags.
+       * @returns {Promise<{ selector: string; matchCount: number; elements: unknown[] }>}
+       */
+      query: async (selector, queryOptions) => {
+        const selectorText = String(selector ?? '').trim();
+        if (!selectorText) {
+          throw new Error('hc.webpage().dom.query requires a selector');
+        }
+        let all;
+        let maxElements;
+        if (queryOptions != null) {
+          if (typeof queryOptions !== 'object' || Array.isArray(queryOptions)) {
+            throw new Error('hc.webpage().dom.query options must be an object');
+          }
+          const raw = /** @type {Record<string, unknown>} */ (queryOptions);
+          if ('all' in raw && raw.all !== undefined) {
+            if (typeof raw.all !== 'boolean') {
+              throw new Error('hc.webpage().dom.query options.all must be a boolean');
+            }
+            all = raw.all;
+          }
+          if ('maxElements' in raw && raw.maxElements !== undefined) {
+            if (typeof raw.maxElements !== 'number' || !Number.isFinite(raw.maxElements)) {
+              throw new Error('hc.webpage().dom.query options.maxElements must be a finite number');
+            }
+            maxElements = raw.maxElements;
+          }
+        }
+        return /** @type {{ selector: string; matchCount: number; elements: unknown[] }} */ (
+          unwrapWebpageBridgeResult(
+            await callWebpage({ op: 'query', tabId, selector: selectorText, all, maxElements })
+          )
+        );
+      },
+      /**
+       * Evaluates JavaScript in the page main world and returns the result.
+       *
+       * @param {string} expression - JavaScript source that returns a JSON-serializable value.
+       * @returns {Promise<unknown>} Evaluation result.
+       */
+      evaluate: async (expression) => {
+        const expressionText = String(expression ?? '').trim();
+        if (!expressionText) {
+          throw new Error('hc.webpage().dom.evaluate requires an expression');
+        }
+        const result = /** @type {{ value: unknown }} */ (
+          unwrapWebpageBridgeResult(
+            await callWebpage({ op: 'evaluate', tabId, expression: expressionText })
+          )
+        );
+        return result.value;
+      },
+      /**
+       * Injects and runs JavaScript source in the page main world.
+       *
+       * @param {string} source - JavaScript source to inject.
+       * @returns {Promise<unknown>} Evaluation result from the injected script.
+       */
+      injectScript: async (source) => {
+        const sourceText = String(source ?? '');
+        if (!sourceText.trim()) {
+          throw new Error('hc.webpage().dom.injectScript requires source');
+        }
+        const result = /** @type {{ value: unknown }} */ (
+          unwrapWebpageBridgeResult(
+            await callWebpage({ op: 'injectScript', tabId, source: sourceText })
+          )
+        );
+        return result.value;
+      },
+      /**
+       * Injects a CSS stylesheet into the page.
+       *
+       * @param {string} css - Stylesheet source.
+       * @returns {Promise<string>} Electron insertion key.
+       */
+      injectStylesheet: async (css) => {
+        const cssText = String(css ?? '');
+        if (!cssText.trim()) {
+          throw new Error('hc.webpage().dom.injectStylesheet requires css');
+        }
+        const result = /** @type {{ key: string }} */ (
+          unwrapWebpageBridgeResult(
+            await callWebpage({ op: 'injectStylesheet', tabId, css: cssText })
+          )
+        );
+        return result.key;
+      }
+    }
+  };
+}
+
+/**
+ * Opens or reuses an embedded browser tab and returns a control handle.
+ *
+ * @param {(req: Record<string, unknown>) => Promise<unknown>} callWebpage - Bridge transport
+ *   that accepts ScriptWebpageRequest-shaped payloads (`op` plus fields).
+ * @param {unknown} [url] - Optional URL; omit to bind the active browser tab.
+ * @param {unknown} [openOptions] - Optional `{ reuse }` (default true).
+ * @param {(path: string, pngBase64: string) => Promise<string>} [writeScreenshotBytes] - Optional
+ *   writer used by `page.screenshot`.
+ * @returns {Promise<import('../types').PluginWebpageHandle>} Webpage handle.
+ */
+export async function openWebpage(callWebpage, url, openOptions, writeScreenshotBytes) {
+  const normalizedOptions = normalizeWebpageOpenOptions(openOptions);
+  let openUrl;
+  if (url !== undefined && url !== null) {
+    const trimmed = String(url).trim();
+    if (!trimmed) {
+      throw new Error('hc.webpage requires a non-empty url when provided');
+    }
+    openUrl = trimmed;
+  }
+  const opened = /** @type {{
+    tabId: string;
+    url: string;
+    title: string;
+    canGoBack?: boolean;
+    canGoForward?: boolean;
+  }} */ (
+    unwrapWebpageBridgeResult(
+      await callWebpage({
+        op: 'open',
+        url: openUrl,
+        reuse: normalizedOptions.reuse
+      })
+    )
+  );
+  if (!opened || typeof opened.tabId !== 'string') {
+    throw new Error('hc.webpage open did not return a tab');
+  }
+  return createWebpageHandle(opened, callWebpage, writeScreenshotBytes);
+}

package/dist/snippets.d.ts

@@ -239,6 +239,8 @@ interface HcInfoApi {
   readonly workflowActionId: string;
   /** 0-based index of the workflow action currently executing, or -1 when not in a workflow. */
   readonly workflowActionIteration: number;
+  /** UUID of the live page (website) for this script run, or empty when not a live page. */
+  readonly livepageId: string;
 }
 
 /**
@@ -266,6 +268,62 @@ interface HcSendRequestResponse {
   json(): unknown;
 }
 
+/**
+ * Live DOM helpers on a webpage handle from hc.webpage.
+ */
+interface HcWebpageDom {
+  /**
+   * Queries the live page DOM with a CSS selector.
+   */
+  query(
+    selector: string,
+    options?: { all?: boolean; maxElements?: number }
+  ): Promise<{ selector: string; matchCount: number; elements: unknown[] }>;
+
+  /**
+   * Evaluates JavaScript in the page main world and returns the result.
+   */
+  evaluate(expression: string): Promise<unknown>;
+
+  /**
+   * Injects and runs JavaScript source in the page main world.
+   */
+  injectScript(source: string): Promise<unknown>;
+
+  /**
+   * Injects a CSS stylesheet into the page.
+   */
+  injectStylesheet(css: string): Promise<string>;
+}
+
+/**
+ * Handle returned by hc.webpage for an embedded browser tab.
+ */
+interface HcWebpageHandle {
+  readonly tabId: string;
+  readonly url: string;
+  readonly title: string;
+  readonly canGoBack: boolean;
+  readonly canGoForward: boolean;
+  readonly dom: HcWebpageDom;
+  /**
+   * Focuses this browser tab in the tab bar.
+   */
+  focus(): Promise<void>;
+  /**
+   * Closes this browser tab. Returns false when the user cancels a leave prompt.
+   */
+  close(): Promise<boolean>;
+  /**
+   * Captures the visible viewport as PNG and writes it under the script file access root.
+   *
+   * @param path - Relative or absolute path under the script file root.
+   * @param options - Optional `{ fullPage }` (default false).
+   * @returns Absolute path of the written PNG.
+   */
+  screenshot(path: string, options?: { fullPage?: boolean }): Promise<{ path: string }>;
+}
+
 /**
  * Element surface exposed by hc.response.document() for HTML bodies.
  */
@@ -403,6 +461,15 @@ interface HcScriptApi {
    *   Omit model (or options) to use the first available model.
    */
   ask(prompt: string, options?: HcAskOptions): Promise<string | null>;
+  /**
+   * Opens or reuses an embedded browser tab and returns a control handle.
+   * Requires Settings → General → Allow script webpage access.
+   *
+   * @param url - Optional URL to open or reuse; omit to bind the active browser tab.
+   * @param options - Optional `{ reuse }` (default true).
+   * @throws When webpage access is disabled or unavailable in this context.
+   */
+  webpage(url?: string, options?: { reuse?: boolean }): Promise<HcWebpageHandle>;
   /**
    * Resolves after the given delay. Use for pacing between script steps.
    *