@harborclient/sdk 1.4.5 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 1.5.0 - 2026-08-01
+
+- feat(live-page): introduce live page functionality and refactor related components. (`16f1f304`)
+
 ## 1.4.5 - 2026-08-01
 
 - feat(websites): implement Add Live Page modal and import functionality. (`1bdbf8a4`)

package/dist/runtime/createBridgedPluginContext.js

@@ -5,9 +5,9 @@ import {
   registerContributionHeaderActions
 } from './contributionRegistry.js';
 import { bridgeInvoke, bridgeOn } from './hcBridge.js';
+import { openLivePage } from './livePageHandle.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();
@@ -354,7 +354,7 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
   const assertAi = () => assertPermission('ai');
 
   /**
-   * Asserts browser permission for embedded webpage control.
+   * Asserts browser permission for embedded live page control.
    */
   const assertBrowser = () => assertPermission('browser');
 
@@ -364,43 +364,56 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
   const assertLiveServer = () => assertPermission('live-server');
 
   /**
-   * Invokes a webpage session op on the host renderer via the plugin bridge.
+   * Asserts live-pages permission for saved live page (website) APIs.
+   */
+  const assertLivePages = () => assertPermission('live-pages');
+
+  /**
+   * Invokes a livePage session op on the host renderer via the plugin bridge.
    *
-   * @param {Record<string, unknown>} req - ScriptWebpageRequest-shaped payload.
+   * @param {Record<string, unknown>} req - ScriptLivePageRequest-shaped payload.
    * @returns {Promise<unknown>} Host session result.
    */
-  const callWebpage = async (req) => {
+  const callLivePage = async (req) => {
     const op = String(req.op ?? '');
     switch (op) {
       case 'open':
-        return bridgeInvoke('webpage.open', { url: req.url, reuse: req.reuse });
+        return bridgeInvoke('livePage.open', { url: req.url, reuse: req.reuse });
       case 'focus':
-        return bridgeInvoke('webpage.focus', { tabId: req.tabId });
+        return bridgeInvoke('livePage.focus', { tabId: req.tabId });
       case 'close':
-        return bridgeInvoke('webpage.close', { tabId: req.tabId });
+        return bridgeInvoke('livePage.close', { tabId: req.tabId });
       case 'query':
-        return bridgeInvoke('webpage.query', {
+        return bridgeInvoke('livePage.query', {
           tabId: req.tabId,
           selector: req.selector,
           all: req.all,
           maxElements: req.maxElements
         });
       case 'evaluate':
-        return bridgeInvoke('webpage.evaluate', {
+        return bridgeInvoke('livePage.evaluate', {
           tabId: req.tabId,
           expression: req.expression
         });
       case 'injectScript':
-        return bridgeInvoke('webpage.injectScript', { tabId: req.tabId, source: req.source });
+        return bridgeInvoke('livePage.injectScript', { tabId: req.tabId, source: req.source });
       case 'injectStylesheet':
-        return bridgeInvoke('webpage.injectStylesheet', { tabId: req.tabId, css: req.css });
+        return bridgeInvoke('livePage.injectStylesheet', { tabId: req.tabId, css: req.css });
       case 'screenshot':
-        return bridgeInvoke('webpage.screenshot', {
+        return bridgeInvoke('livePage.screenshot', {
           tabId: req.tabId,
           fullPage: req.fullPage === true
         });
+      case 'goBack':
+        return bridgeInvoke('livePage.goBack', { tabId: req.tabId });
+      case 'goForward':
+        return bridgeInvoke('livePage.goForward', { tabId: req.tabId });
+      case 'reload':
+        return bridgeInvoke('livePage.reload', { tabId: req.tabId });
+      case 'navigate':
+        return bridgeInvoke('livePage.navigate', { tabId: req.tabId, url: req.url });
       default:
-        throw new Error(`Unsupported webpage bridge op: ${op}`);
+        throw new Error(`Unsupported livePage bridge op: ${op}`);
     }
   };
 
@@ -860,6 +873,28 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
           });
         });
       },
+      registerLivePageChromeAction: (action) => {
+        assertManifestContribution('livePageChromeActions', action.id);
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        void bridgeInvoke('registerContribution', {
+          kind: 'livePageChromeActions',
+          contribution: {
+            pluginId,
+            id: action.id,
+            title: action.title,
+            command: action.command,
+            icon: action.icon
+          }
+        });
+        return track(() => {
+          void bridgeInvoke('unregisterContribution', {
+            kind: 'livePageChromeActions',
+            contributionId: action.id
+          });
+        });
+      },
       registerScriptEditorAction: (action) => {
         assertManifestContribution('scriptEditorActions', action.id);
         if (!isAgent) {
@@ -1341,6 +1376,28 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         });
       }
     },
+    livePages: {
+      list: async () => {
+        assertLivePages();
+        return bridgeInvoke('livePages.list');
+      },
+      get: async (idOrUuid) => {
+        assertLivePages();
+        return bridgeInvoke('livePages.get', { idOrUuid });
+      },
+      create: async (input) => {
+        assertLivePages();
+        return bridgeInvoke('livePages.create', { input });
+      },
+      update: async (input) => {
+        assertLivePages();
+        return bridgeInvoke('livePages.update', { input });
+      },
+      delete: async (id) => {
+        assertLivePages();
+        await bridgeInvoke('livePages.delete', { id });
+      }
+    },
     ai: {
       registerChatPointer: (config) => {
         assertAi();
@@ -1375,13 +1432,13 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
     /**
      * Opens or reuses an embedded browser tab and returns a control handle.
      *
-     * Requires the `browser` permission. Same semantics as request-script `hc.webpage`.
+     * Requires the `browser` permission. Same semantics as request-script `hc.livePage`.
      *
      * @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.
+     * @returns {Promise<import('../types').PluginLivePageHandle>} Webpage handle.
      */
-    webpage: async (url, options) => {
+    livePage: async (url, options) => {
       assertBrowser();
       /**
        * Writes screenshot PNG bytes via the plugin filesystem bridge.
@@ -1394,11 +1451,11 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         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');
+          throw new Error('hc.livePage().screenshot failed to resolve write path');
         }
         return result;
       };
-      return openWebpage(callWebpage, url, options, writeScreenshotBytes);
+      return openLivePage(callLivePage, url, options, writeScreenshotBytes);
     }
   };
 }

package/dist/runtime/livePageHandle.d.ts

@@ -0,0 +1,50 @@
+import type { PluginLivePageHandle } from '../types';
+
+/**
+ * Throws when a live-page 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 unwrapLivePageBridgeResult(result: unknown): unknown;
+
+/**
+ * Normalizes the optional second argument to `hc.livePage(url, options)`.
+ *
+ * @param options - User-provided options.
+ * @returns Normalized open options.
+ */
+export function normalizeLivePageOpenOptions(options?: unknown): { reuse?: boolean };
+
+/**
+ * Builds a live-page handle whose methods call the host live-page bridge.
+ *
+ * @param tab - Opened tab metadata from the bridge.
+ * @param callLivePage - Bridge transport.
+ * @returns Plain-object handle for the plugin world.
+ */
+export function createLivePageHandle(
+  tab: {
+    tabId: string;
+    url: string;
+    title: string;
+    canGoBack?: boolean;
+    canGoForward?: boolean;
+  },
+  callLivePage: (req: Record<string, unknown>) => Promise<unknown>
+): PluginLivePageHandle;
+
+/**
+ * Opens or reuses an embedded browser tab and returns a control handle.
+ *
+ * @param callLivePage - Bridge transport that accepts ScriptLivePageRequest-shaped payloads.
+ * @param url - Optional URL; omit to bind the active browser tab.
+ * @param openOptions - Optional `{ reuse }` (default true).
+ * @returns Live-page handle.
+ */
+export function openLivePage(
+  callLivePage: (req: Record<string, unknown>) => Promise<unknown>,
+  url?: unknown,
+  openOptions?: unknown
+): Promise<PluginLivePageHandle>;

package/dist/runtime/{webpageHandle.js → livePageHandle.js}

@@ -1,11 +1,11 @@
 /**
- * Throws when a webpage bridge result is an `{ error }` object.
+ * Throws when a live-page 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) {
+export function unwrapLivePageBridgeResult(result) {
   if (
     result != null &&
     typeof result === 'object' &&
@@ -20,54 +20,54 @@ export function unwrapWebpageBridgeResult(result) {
 }
 
 /**
- * Normalizes the optional second argument to `hc.webpage(url, options)`.
+ * Normalizes the optional second argument to `hc.livePage(url, options)`.
  *
  * @param {unknown} [options] - User-provided options.
  * @returns {{ reuse?: boolean }} Normalized open options.
  */
-export function normalizeWebpageOpenOptions(options) {
+export function normalizeLivePageOpenOptions(options) {
   if (options == null) {
     return {};
   }
   if (typeof options !== 'object' || Array.isArray(options)) {
-    throw new Error('hc.webpage options must be an object');
+    throw new Error('hc.livePage 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');
+    throw new Error('hc.livePage options.reuse must be a boolean');
   }
   return { reuse: raw.reuse };
 }
 
 /**
- * Normalizes optional `hc.webpage().screenshot` options.
+ * Normalizes optional `hc.livePage().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) {
+export function normalizeLivePageScreenshotOptions(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');
+    throw new Error('hc.livePage().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');
+    throw new Error('hc.livePage().screenshot options.fullPage must be a boolean');
   }
   return { fullPage: raw.fullPage };
 }
 
 /**
- * Builds a webpage handle whose methods call the host webpage bridge.
+ * Builds a live-page handle whose methods call the host live page bridge.
  *
  * @param {{
  *   tabId: string;
@@ -76,14 +76,15 @@ export function normalizeWebpageScreenshotOptions(options) {
  *   canGoBack?: boolean;
  *   canGoForward?: boolean;
  * }} tab - Opened tab metadata from the bridge.
- * @param {(req: Record<string, unknown>) => Promise<unknown>} callWebpage - Bridge transport.
+ * @param {(req: Record<string, unknown>) => Promise<unknown>} callLivePage - 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.
+ * @returns {import('../types').PluginLivePageHandle} Plain-object handle for the plugin world.
  */
-export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
+export function createLivePageHandle(tab, callLivePage, writeScreenshotBytes) {
   const tabId = tab.tabId;
-  return {
+  /** @type {import('../types').PluginLivePageHandle} */
+  const handle = {
     tabId,
     url: tab.url,
     title: tab.title,
@@ -95,7 +96,7 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
      * @returns {Promise<void>} Resolves when the tab is focused.
      */
     focus: async () => {
-      unwrapWebpageBridgeResult(await callWebpage({ op: 'focus', tabId }));
+      unwrapLivePageBridgeResult(await callLivePage({ op: 'focus', tabId }));
     },
     /**
      * Closes this browser tab, honoring page leave prompts.
@@ -104,10 +105,59 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
      */
     close: async () => {
       const result = /** @type {{ closed: boolean }} */ (
-        unwrapWebpageBridgeResult(await callWebpage({ op: 'close', tabId }))
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'close', tabId }))
       );
       return result.closed === true;
     },
+    /**
+     * Navigates history back one entry and waits for load.
+     *
+     * @returns {Promise<void>} Resolves when load finishes.
+     */
+    goBack: async () => {
+      applyLivePageNavSnapshot(
+        handle,
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'goBack', tabId }))
+      );
+    },
+    /**
+     * Navigates history forward one entry and waits for load.
+     *
+     * @returns {Promise<void>} Resolves when load finishes.
+     */
+    goForward: async () => {
+      applyLivePageNavSnapshot(
+        handle,
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'goForward', tabId }))
+      );
+    },
+    /**
+     * Reloads the current page and waits for load.
+     *
+     * @returns {Promise<void>} Resolves when load finishes.
+     */
+    reload: async () => {
+      applyLivePageNavSnapshot(
+        handle,
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'reload', tabId }))
+      );
+    },
+    /**
+     * Loads a URL in this tab and waits for load.
+     *
+     * @param {unknown} url - Absolute http(s) or about:blank URL.
+     * @returns {Promise<void>} Resolves when load finishes.
+     */
+    navigate: async (url) => {
+      const urlText = String(url ?? '').trim();
+      if (!urlText) {
+        throw new Error('hc.livePage().navigate requires a non-empty url');
+      }
+      applyLivePageNavSnapshot(
+        handle,
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'navigate', tabId, url: urlText }))
+      );
+    },
     /**
      * Captures the visible viewport (or full page) as PNG and writes it via the filesystem bridge.
      *
@@ -116,19 +166,19 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
      * @returns {Promise<{ path: string }>} Absolute path of the written file.
      */
     screenshot: async (path, screenshotOptions) => {
-      const { fullPage } = normalizeWebpageScreenshotOptions(screenshotOptions);
+      const { fullPage } = normalizeLivePageScreenshotOptions(screenshotOptions);
       const pathText = String(path ?? '').trim();
       if (!pathText) {
-        throw new Error('hc.webpage().screenshot requires a path');
+        throw new Error('hc.livePage().screenshot requires a path');
       }
       if (!writeScreenshotBytes) {
-        throw new Error('hc.webpage().screenshot requires hc.fs.writeBytes');
+        throw new Error('hc.livePage().screenshot requires hc.fs.writeBytes');
       }
       const capture = /** @type {{ pngBase64?: string }} */ (
-        unwrapWebpageBridgeResult(await callWebpage({ op: 'screenshot', tabId, fullPage }))
+        unwrapLivePageBridgeResult(await callLivePage({ op: 'screenshot', tabId, fullPage }))
       );
       if (!capture || typeof capture.pngBase64 !== 'string' || !capture.pngBase64) {
-        throw new Error('hc.webpage().screenshot did not return image data');
+        throw new Error('hc.livePage().screenshot did not return image data');
       }
       const absolutePath = await writeScreenshotBytes(pathText, capture.pngBase64);
       return { path: absolutePath };
@@ -144,31 +194,33 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
       query: async (selector, queryOptions) => {
         const selectorText = String(selector ?? '').trim();
         if (!selectorText) {
-          throw new Error('hc.webpage().dom.query requires a selector');
+          throw new Error('hc.livePage().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');
+            throw new Error('hc.livePage().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');
+              throw new Error('hc.livePage().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');
+              throw new Error(
+                'hc.livePage().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 })
+          unwrapLivePageBridgeResult(
+            await callLivePage({ op: 'query', tabId, selector: selectorText, all, maxElements })
           )
         );
       },
@@ -181,11 +233,11 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
       evaluate: async (expression) => {
         const expressionText = String(expression ?? '').trim();
         if (!expressionText) {
-          throw new Error('hc.webpage().dom.evaluate requires an expression');
+          throw new Error('hc.livePage().dom.evaluate requires an expression');
         }
         const result = /** @type {{ value: unknown }} */ (
-          unwrapWebpageBridgeResult(
-            await callWebpage({ op: 'evaluate', tabId, expression: expressionText })
+          unwrapLivePageBridgeResult(
+            await callLivePage({ op: 'evaluate', tabId, expression: expressionText })
           )
         );
         return result.value;
@@ -199,11 +251,11 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
       injectScript: async (source) => {
         const sourceText = String(source ?? '');
         if (!sourceText.trim()) {
-          throw new Error('hc.webpage().dom.injectScript requires source');
+          throw new Error('hc.livePage().dom.injectScript requires source');
         }
         const result = /** @type {{ value: unknown }} */ (
-          unwrapWebpageBridgeResult(
-            await callWebpage({ op: 'injectScript', tabId, source: sourceText })
+          unwrapLivePageBridgeResult(
+            await callLivePage({ op: 'injectScript', tabId, source: sourceText })
           )
         );
         return result.value;
@@ -217,37 +269,63 @@ export function createWebpageHandle(tab, callWebpage, writeScreenshotBytes) {
       injectStylesheet: async (css) => {
         const cssText = String(css ?? '');
         if (!cssText.trim()) {
-          throw new Error('hc.webpage().dom.injectStylesheet requires css');
+          throw new Error('hc.livePage().dom.injectStylesheet requires css');
         }
         const result = /** @type {{ key: string }} */ (
-          unwrapWebpageBridgeResult(
-            await callWebpage({ op: 'injectStylesheet', tabId, css: cssText })
+          unwrapLivePageBridgeResult(
+            await callLivePage({ op: 'injectStylesheet', tabId, css: cssText })
           )
         );
         return result.key;
       }
     }
   };
+  return handle;
+}
+
+/**
+ * Copies navigation fields from a bridge result onto a live-page handle.
+ *
+ * @param {import('../types').PluginLivePageHandle} handle - Mutable handle to update.
+ * @param {unknown} result - Bridge result with url/title/history flags.
+ */
+function applyLivePageNavSnapshot(handle, result) {
+  if (result == null || typeof result !== 'object' || Array.isArray(result)) {
+    return;
+  }
+  const snapshot = /** @type {Record<string, unknown>} */ (result);
+  if (typeof snapshot.url === 'string') {
+    handle.url = snapshot.url;
+  }
+  if (typeof snapshot.title === 'string') {
+    handle.title = snapshot.title;
+  }
+  if (typeof snapshot.canGoBack === 'boolean') {
+    handle.canGoBack = snapshot.canGoBack;
+  }
+  if (typeof snapshot.canGoForward === 'boolean') {
+    handle.canGoForward = snapshot.canGoForward;
+  }
 }
 
 /**
  * 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 {(req: Record<string, unknown>) => Promise<unknown>} callLivePage - Bridge transport
+ *   that accepts ScriptLivePageRequest-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.
+ * @returns {Promise<import('../types').PluginLivePageHandle>} Live-page handle.
  */
-export async function openWebpage(callWebpage, url, openOptions, writeScreenshotBytes) {
-  const normalizedOptions = normalizeWebpageOpenOptions(openOptions);
+export async function openLivePage(callLivePage, url, openOptions, writeScreenshotBytes) {
+  const normalizedOptions = normalizeLivePageOpenOptions(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');
+      throw new Error('hc.livePage requires a non-empty url when provided');
     }
     openUrl = trimmed;
   }
@@ -258,8 +336,8 @@ export async function openWebpage(callWebpage, url, openOptions, writeScreenshot
     canGoBack?: boolean;
     canGoForward?: boolean;
   }} */ (
-    unwrapWebpageBridgeResult(
-      await callWebpage({
+    unwrapLivePageBridgeResult(
+      await callLivePage({
         op: 'open',
         url: openUrl,
         reuse: normalizedOptions.reuse
@@ -267,7 +345,7 @@ export async function openWebpage(callWebpage, url, openOptions, writeScreenshot
     )
   );
   if (!opened || typeof opened.tabId !== 'string') {
-    throw new Error('hc.webpage open did not return a tab');
+    throw new Error('hc.livePage open did not return a tab');
   }
-  return createWebpageHandle(opened, callWebpage, writeScreenshotBytes);
+  return createLivePageHandle(opened, callLivePage, writeScreenshotBytes);
 }

package/dist/snippets.d.ts

@@ -271,9 +271,9 @@ interface HcSendRequestResponse {
 }
 
 /**
- * Live DOM helpers on a webpage handle from hc.webpage.
+ * Live DOM helpers on a live-page handle from hc.livePage.
  */
-interface HcWebpageDom {
+interface HcLivePageDom {
   /**
    * Queries the live page DOM with a CSS selector.
    */
@@ -299,15 +299,19 @@ interface HcWebpageDom {
 }
 
 /**
- * Handle returned by hc.webpage for an embedded browser tab.
+ * Handle returned by hc.livePage for an embedded browser tab.
  */
-interface HcWebpageHandle {
+interface HcLivePageHandle {
   readonly tabId: string;
-  readonly url: string;
-  readonly title: string;
-  readonly canGoBack: boolean;
-  readonly canGoForward: boolean;
-  readonly dom: HcWebpageDom;
+  /** Current page URL. Updated after navigate / goBack / goForward / reload. */
+  url: string;
+  /** Document title. Updated after navigate / goBack / goForward / reload. */
+  title: string;
+  /** Whether history can go back. Updated after navigation helpers. */
+  canGoBack: boolean;
+  /** Whether history can go forward. Updated after navigation helpers. */
+  canGoForward: boolean;
+  readonly dom: HcLivePageDom;
   /**
    * Focuses this browser tab in the tab bar.
    */
@@ -316,6 +320,24 @@ interface HcWebpageHandle {
    * Closes this browser tab. Returns false when the user cancels a leave prompt.
    */
   close(): Promise<boolean>;
+  /**
+   * Navigates history back one entry and waits for load. Updates url/title/history flags.
+   */
+  goBack(): Promise<void>;
+  /**
+   * Navigates history forward one entry and waits for load. Updates url/title/history flags.
+   */
+  goForward(): Promise<void>;
+  /**
+   * Reloads the current page and waits for load. Updates url/title/history flags.
+   */
+  reload(): Promise<void>;
+  /**
+   * Loads a URL in this tab and waits for load. Updates url/title/history flags.
+   *
+   * @param url - Absolute http(s) or about:blank URL.
+   */
+  navigate(url: string): Promise<void>;
   /**
    * Captures the visible viewport as PNG and writes it under the script file access root.
    *
@@ -465,13 +487,13 @@ interface HcScriptApi {
   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.
+   * Requires Settings → General → Allow script live page 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.
+   * @throws When live-page access is disabled or unavailable in this context.
    */
-  webpage(url?: string, options?: { reuse?: boolean }): Promise<HcWebpageHandle>;
+  livePage(url?: string, options?: { reuse?: boolean }): Promise<HcLivePageHandle>;
   /**
    * Resolves after the given delay. Use for pacing between script steps.
    *