@handstage/core 0.0.3 → 0.0.4

package/README.md

@@ -1,2 +1,3 @@
 # @handstage/core
 
+Core browser automation engine for Handstage. Manages browser connections, Chrome DevTools Protocol (CDP) communication, page context, frame locators, and script injection for reliable browser automation.

package/dist/v3/index.js

@@ -1,13 +1,11 @@
-import { maybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
+import { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
 import * as PublicApi from "./types/public/index";
 import { V3 } from "./v3";
-export { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from "./shutdown/supervisor";
 export * from "./types/public/index";
-export { V3, V3 as Handstages } from "./v3";
-const HandstagesDefault = {
+export { __internalMaybeRunShutdownSupervisorFromArgv, V3, V3 as Handstage };
+export default {
     ...PublicApi,
     V3,
-    Handstages: V3,
-    __internalMaybeRunShutdownSupervisorFromArgv: maybeRunShutdownSupervisorFromArgv,
+    Handstage: V3,
+    __internalMaybeRunShutdownSupervisorFromArgv,
 };
-export default HandstagesDefault;

package/dist/v3/logger.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createConsoleLogger } from "./types/public/consoleLogger";
 /**
- * Handstages V3 per-instance log routing (AsyncLocalStorage).
+ * Handstage V3 per-instance log routing (AsyncLocalStorage).
  *
  * - `bindInstanceLogger` / `unbindInstanceLogger`: register the effective logger for an instance id.
  * - `withInstanceLogContext`: run a function with that instance id on the async context.

package/dist/v3/shutdown/supervisor.js

@@ -138,9 +138,9 @@ export const runShutdownSupervisor = (initialConfig) => {
     // Stdin is the lifeline; losing it means parent is gone.
     try {
         process.stdin.resume();
-        process.stdin.on("end", () => onLifelineClosed("Handstages process completed"));
-        process.stdin.on("close", () => onLifelineClosed("Handstages process completed"));
-        process.stdin.on("error", () => onLifelineClosed("Handstages process crashed or was killed"));
+        process.stdin.on("end", () => onLifelineClosed("Handstage process completed"));
+        process.stdin.on("close", () => onLifelineClosed("Handstage process completed"));
+        process.stdin.on("error", () => onLifelineClosed("Handstage process crashed or was killed"));
     }
     catch { }
 };

package/dist/v3/shutdown/supervisorClient.js

@@ -24,7 +24,7 @@ const isSeaRuntime = () => {
     }
 };
 // SEA: re-exec current binary with supervisor args.
-// Non-SEA: execute Handstages CLI entrypoint with supervisor args.
+// Non-SEA: execute Handstage CLI entrypoint with supervisor args.
 const resolveCliPath = () => `${moduleDir}/../cli.js`;
 const resolveSupervisorCommand = (config) => {
     const baseArgs = ["--supervisor", serializeConfigArg(config)];
@@ -55,7 +55,7 @@ const serializeConfigArg = (config) => `--supervisor-config=${JSON.stringify({
 export function startShutdownSupervisor(config, opts) {
     const resolved = resolveSupervisorCommand(config);
     if (!resolved) {
-        opts?.onError?.(new ShutdownSupervisorResolveError("Shutdown supervisor entry missing (expected Handstages CLI entrypoint)."), "resolve");
+        opts?.onError?.(new ShutdownSupervisorResolveError("Shutdown supervisor entry missing (expected Handstage CLI entrypoint)."), "resolve");
         return null;
     }
     const child = spawn(resolved.command, resolved.args, {

package/dist/v3/types/public/logs.js

@@ -1,5 +1,5 @@
 /**
- * Severity for Handstages log lines. Maps 1:1 to `console.error` / `console.info` / `console.debug`.
+ * Severity for Handstage log lines. Maps 1:1 to `console.error` / `console.info` / `console.debug`.
  */
 export var LogLevel;
 (function (LogLevel) {

package/dist/v3/types/public/sdkErrors.js

@@ -1,6 +1,6 @@
 // Avoid .js extension so bundlers resolve TS source
-import { HANDSTAGES_VERSION } from "../../../version";
-export class HandstagesError extends Error {
+import { HANDSTAGE_VERSION } from "../../../version";
+export class HandstageError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
@@ -10,139 +10,139 @@ export class HandstagesError extends Error {
         }
     }
 }
-export class HandstagesDefaultError extends HandstagesError {
+export class HandstageDefaultError extends HandstageError {
     constructor(error) {
-        if (error instanceof Error || error instanceof HandstagesError) {
-            super(`\nHey! We're sorry you ran into an error. \nHandstages version: ${HANDSTAGES_VERSION} \nIf you need help, please open a Github issue or reach out to us on Discord: https://handstages.dev/discord\n\nFull error:\n${error.message}`);
+        if (error instanceof Error || error instanceof HandstageError) {
+            super(`\nHey! We're sorry you ran into an error. \nHandstage version: ${HANDSTAGE_VERSION} \nIf you need help, please open a Github issue or reach out to us on Discord: https://handstage.dev/discord\n\nFull error:\n${error.message}`);
         }
     }
 }
-export class HandstagesEnvironmentError extends HandstagesError {
+export class HandstageEnvironmentError extends HandstageError {
     constructor(currentEnvironment, requiredEnvironment, feature) {
         super(`You seem to be setting the current environment to ${currentEnvironment}.` +
             `Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`);
     }
 }
-export class MissingEnvironmentVariableError extends HandstagesError {
+export class MissingEnvironmentVariableError extends HandstageError {
     constructor(missingEnvironmentVariable, feature) {
         super(`${missingEnvironmentVariable} is required to use ${feature}.` +
             `Please set ${missingEnvironmentVariable} in your environment.`);
     }
 }
-export class UnsupportedModelError extends HandstagesError {
+export class UnsupportedModelError extends HandstageError {
     constructor(supportedModels, feature) {
         const message = feature
             ? `${feature} requires a valid model.`
             : `Unsupported model.`;
         const guidance = `\n\nPlease use the provider/model format (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4-5", "google/gemini-3-flash-preview").` +
-            `\n\nFor a complete list of supported models and providers, see: https://docs.handstages.dev/v3/configuration/models#configuration-setup`;
+            `\n\nFor a complete list of supported models and providers, see: https://docs.handstage.dev/v3/configuration/models#configuration-setup`;
         super(`${message}${guidance}`);
     }
 }
-export class UnsupportedModelProviderError extends HandstagesError {
+export class UnsupportedModelProviderError extends HandstageError {
     constructor(supportedProviders, feature) {
         super(feature
             ? `${feature} requires one of the following model providers: ${supportedProviders}`
             : `please use one of the supported model providers: ${supportedProviders}`);
     }
 }
-export class UnsupportedAISDKModelProviderError extends HandstagesError {
+export class UnsupportedAISDKModelProviderError extends HandstageError {
     constructor(provider, supportedProviders) {
         super(`${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`);
     }
 }
-export class InvalidAISDKModelFormatError extends HandstagesError {
+export class InvalidAISDKModelFormatError extends HandstageError {
     constructor(modelName) {
         super(`${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \`model: 'openai/gpt-4o-mini'\``);
     }
 }
-export class CaptchaTimeoutError extends HandstagesError {
+export class CaptchaTimeoutError extends HandstageError {
     constructor() {
         super("Captcha timeout");
     }
 }
-export class MissingLLMConfigurationError extends HandstagesError {
+export class MissingLLMConfigurationError extends HandstageError {
     constructor() {
         super("No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client " +
             "is required to use act, extract, or observe.");
     }
 }
-export class HandlerNotInitializedError extends HandstagesError {
+export class HandlerNotInitializedError extends HandstageError {
     constructor(handlerType) {
         super(`${handlerType} handler not initialized`);
     }
 }
-export class HandstagesInvalidArgumentError extends HandstagesError {
+export class HandstageInvalidArgumentError extends HandstageError {
     constructor(message) {
         super(`InvalidArgumentError: ${message}`);
     }
 }
-export class CookieValidationError extends HandstagesError {
+export class CookieValidationError extends HandstageError {
     constructor(message) {
         super(message);
     }
 }
-export class CookieSetError extends HandstagesError {
+export class CookieSetError extends HandstageError {
     constructor(message) {
         super(message);
     }
 }
-export class HandstagesElementNotFoundError extends HandstagesError {
+export class HandstageElementNotFoundError extends HandstageError {
     constructor(xpaths) {
         super(`Could not find an element for the given xPath(s): ${xpaths}`);
     }
 }
-export class AgentScreenshotProviderError extends HandstagesError {
+export class AgentScreenshotProviderError extends HandstageError {
     constructor(message) {
         super(`ScreenshotProviderError: ${message}`);
     }
 }
-export class HandstagesMissingArgumentError extends HandstagesError {
+export class HandstageMissingArgumentError extends HandstageError {
     constructor(message) {
         super(`MissingArgumentError: ${message}`);
     }
 }
-export class CreateChatCompletionResponseError extends HandstagesError {
+export class CreateChatCompletionResponseError extends HandstageError {
     constructor(message) {
         super(`CreateChatCompletionResponseError: ${message}`);
     }
 }
-export class HandstagesEvalError extends HandstagesError {
+export class HandstageEvalError extends HandstageError {
     constructor(message) {
-        super(`HandstagesEvalError: ${message}`);
+        super(`HandstageEvalError: ${message}`);
     }
 }
-export class HandstagesDomProcessError extends HandstagesError {
+export class HandstageDomProcessError extends HandstageError {
     constructor(message) {
         super(`Error Processing Dom: ${message}`);
     }
 }
-export class HandstagesLocatorError extends HandstagesError {
+export class HandstageLocatorError extends HandstageError {
     constructor(action, selector, message) {
         super(`Error ${action} Element with selector: ${selector} Reason: ${message}`);
     }
 }
-export class HandstagesClickError extends HandstagesError {
+export class HandstageClickError extends HandstageError {
     constructor(message, selector) {
         super(`Error Clicking Element with selector: ${selector} Reason: ${message}`);
     }
 }
-export class LLMResponseError extends HandstagesError {
+export class LLMResponseError extends HandstageError {
     constructor(primitive, message) {
         super(`${primitive} LLM response error: ${message}`);
     }
 }
-export class HandstagesIframeError extends HandstagesError {
+export class HandstageIframeError extends HandstageError {
     constructor(frameUrl, message) {
         super(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
     }
 }
-export class ContentFrameNotFoundError extends HandstagesError {
+export class ContentFrameNotFoundError extends HandstageError {
     constructor(selector) {
         super(`Unable to obtain a content frame for selector: ${selector}`);
     }
 }
-export class XPathResolutionError extends HandstagesError {
+export class XPathResolutionError extends HandstageError {
     constructor(xpath) {
         super(`XPath "${xpath}" does not resolve in the current page or frames`);
     }
@@ -163,76 +163,76 @@ ${JSON.stringify(issues, null, 2)}`);
         this.name = "ZodSchemaValidationError";
     }
 }
-export class HandstagesInitError extends HandstagesError {
+export class HandstageInitError extends HandstageError {
     constructor(message) {
         super(message);
     }
 }
-export class HandstagesShadowRootMissingError extends HandstagesError {
+export class HandstageShadowRootMissingError extends HandstageError {
     constructor(detail) {
         super(`No shadow root present on the resolved host` +
             (detail ? `: ${detail}` : ""));
     }
 }
-export class HandstagesShadowSegmentEmptyError extends HandstagesError {
+export class HandstageShadowSegmentEmptyError extends HandstageError {
     constructor() {
         super(`Empty selector segment after shadow-DOM hop ("//")`);
     }
 }
-export class HandstagesShadowSegmentNotFoundError extends HandstagesError {
+export class HandstageShadowSegmentNotFoundError extends HandstageError {
     constructor(segment, hint) {
         super(`Shadow segment '${segment}' matched no element inside shadow root` +
             (hint ? ` ${hint}` : ""));
     }
 }
-export class ElementNotVisibleError extends HandstagesError {
+export class ElementNotVisibleError extends HandstageError {
     constructor(selector) {
         super(`Element not visible (no box model): ${selector}`);
     }
 }
-export class ResponseBodyError extends HandstagesError {
+export class ResponseBodyError extends HandstageError {
     constructor(message) {
         super(`Failed to retrieve response body: ${message}`);
     }
 }
-export class ResponseParseError extends HandstagesError {
+export class ResponseParseError extends HandstageError {
     constructor(message) {
         super(`Failed to parse response: ${message}`);
     }
 }
-export class TimeoutError extends HandstagesError {
+export class TimeoutError extends HandstageError {
     constructor(operation, timeoutMs) {
         super(`${operation} timed out after ${timeoutMs}ms`);
     }
 }
-export class PageNotFoundError extends HandstagesError {
+export class PageNotFoundError extends HandstageError {
     constructor(identifier) {
         super(`No Page found for ${identifier}`);
     }
 }
-export class ConnectionTimeoutError extends HandstagesError {
+export class ConnectionTimeoutError extends HandstageError {
     constructor(message) {
         super(`Connection timeout: ${message}`);
     }
 }
-export class HandstagesClosedError extends HandstagesError {
+export class HandstageClosedError extends HandstageError {
     constructor() {
-        super("Handstages session was closed");
+        super("Handstage session was closed");
     }
 }
-export class CDPConnectionClosedError extends HandstagesError {
+export class CDPConnectionClosedError extends HandstageError {
     constructor(reason) {
         super(`CDP connection closed: ${reason}`);
     }
 }
-export class HandstagesSetExtraHTTPHeadersError extends HandstagesError {
+export class HandstageSetExtraHTTPHeadersError extends HandstageError {
     failures;
     constructor(failures) {
         super(`setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(", ")}`);
         this.failures = failures;
     }
 }
-export class HandstagesSnapshotError extends HandstagesError {
+export class HandstageSnapshotError extends HandstageError {
     constructor(cause) {
         const suffix = cause instanceof Error
             ? `: ${cause.message}`
@@ -242,7 +242,7 @@ export class HandstagesSnapshotError extends HandstagesError {
         super(`error taking snapshot${suffix}`, cause);
     }
 }
-export class UnderstudyCommandException extends HandstagesError {
+export class UnderstudyCommandException extends HandstageError {
     constructor(message, cause) {
         super(message, cause);
         this.name = "UnderstudyCommandException";

package/dist/v3/understudy/a11y/snapshot/domTree.js

@@ -1,4 +1,4 @@
-import { HandstagesDomProcessError } from "../../../types/public/sdkErrors";
+import { HandstageDomProcessError } from "../../../types/public/sdkErrors";
 import { buildChildXPathSegments, joinXPath, normalizeXPath, } from "./xpathUtils";
 // starting from infinite depth (-1), exponentially shrink down to 1
 const DOM_DEPTH_ATTEMPTS = [-1, 256, 128, 64, 32, 16, 8, 4, 2, 1];
@@ -37,7 +37,7 @@ export function collectDomTraversalTargets(node) {
 }
 /**
  * Rehydrate a truncated DOM tree by repeatedly calling DOM.describeNode with
- * decreasing depths. Any non-CBOR failure is surfaced as a HandstagesDomProcessError.
+ * decreasing depths. Any non-CBOR failure is surfaced as a HandstageDomProcessError.
  */
 export async function hydrateDomTree(session, root, pierce) {
     const stack = [root];
@@ -86,12 +86,12 @@ export async function hydrateDomTree(session, root, pierce) {
                         continue;
                     }
                     const identifier = nodeId ?? backendId ?? "unknown";
-                    throw new HandstagesDomProcessError(`Failed to expand DOM node ${identifier}: ${String(err)}`);
+                    throw new HandstageDomProcessError(`Failed to expand DOM node ${identifier}: ${String(err)}`);
                 }
             }
             if (!expanded) {
                 const identifier = nodeId ?? backendId ?? "unknown";
-                throw new HandstagesDomProcessError(`Unable to expand DOM node ${identifier} after describeNode depth retries`);
+                throw new HandstageDomProcessError(`Unable to expand DOM node ${identifier} after describeNode depth retries`);
             }
         }
         for (const child of collectDomTraversalTargets(node)) {
@@ -123,7 +123,7 @@ export async function getDomTreeWithFallback(session, pierce) {
             throw err;
         }
     }
-    throw new HandstagesDomProcessError(lastCborMessage
+    throw new HandstageDomProcessError(lastCborMessage
         ? `CDP DOM.getDocument failed after adaptive depth retries: ${lastCborMessage}`
         : "CDP DOM.getDocument failed after adaptive depth retries.");
 }

package/dist/v3/understudy/a11y/snapshot/focusSelectors.js

@@ -1,4 +1,4 @@
-import { HandstagesIframeError } from "../../../types/public/sdkErrors";
+import { HandstageIframeError } from "../../../types/public/sdkErrors";
 import { executionContexts } from "../../executionContextRegistry";
 import { buildLocatorInvocation } from "../../locatorInvocation";
 import { prefixXPath } from "./xpathUtils";
@@ -59,7 +59,7 @@ export async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFram
         const parentSess = page.getSessionForFrame(ctxFrameId);
         const objectId = await resolveObjectIdForXPath(parentSess, selectorForIframe, ctxFrameId);
         if (!objectId)
-            throw new HandstagesIframeError(selectorForIframe, "Failed to resolve iframe element by XPath");
+            throw new HandstageIframeError(selectorForIframe, "Failed to resolve iframe element by XPath");
         try {
             await parentSess.send("DOM.enable").catch(() => { });
             const desc = await parentSess.send("DOM.describeNode", { objectId });
@@ -76,7 +76,7 @@ export async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFram
                 catch { }
             }
             if (!childFrameId)
-                throw new HandstagesIframeError(selectorForIframe, "Could not map iframe to child frameId");
+                throw new HandstageIframeError(selectorForIframe, "Could not map iframe to child frameId");
             absPrefix = prefixXPath(absPrefix || "/", selectorForIframe);
             ctxFrameId = childFrameId;
         }
@@ -108,7 +108,7 @@ export async function resolveCssFocusFrameAndTail(page, rawSelector, parentByFra
         const parentSess = page.getSessionForFrame(ctxFrameId);
         const objectId = await resolveObjectIdForCss(parentSess, parts[i], ctxFrameId);
         if (!objectId)
-            throw new HandstagesIframeError(parts[i], "Failed to resolve iframe via CSS hop");
+            throw new HandstageIframeError(parts[i], "Failed to resolve iframe via CSS hop");
         try {
             await parentSess.send("DOM.enable").catch(() => { });
             const desc = await parentSess.send("DOM.describeNode", { objectId });
@@ -125,7 +125,7 @@ export async function resolveCssFocusFrameAndTail(page, rawSelector, parentByFra
                 catch { }
             }
             if (!childFrameId)
-                throw new HandstagesIframeError(parts[i], "Could not map CSS iframe hop to child frameId");
+                throw new HandstageIframeError(parts[i], "Could not map CSS iframe hop to child frameId");
             ctxFrameId = childFrameId;
         }
         finally {

package/dist/v3/understudy/cdp.js

@@ -1,5 +1,5 @@
 import WebSocket from "ws";
-import { HANDSTAGES_VERSION } from "../../version";
+import { HANDSTAGE_VERSION } from "../../version";
 import { CDPConnectionClosedError, PageNotFoundError, } from "../types/public/sdkErrors";
 export class BaseCDPConnection {
     // Memoize the in-flight enable so concurrent V3Contexts sharing the
@@ -55,6 +55,7 @@ export class CDPConnection extends BaseCDPConnection {
     sessionDispatchWaiters = new Set();
     id = null; // root
     transportCloseHandlers = new Set();
+    _isClosed = false;
     onTransportClosed(handler) {
         this.transportCloseHandlers.add(handler);
     }
@@ -73,11 +74,13 @@ export class CDPConnection extends BaseCDPConnection {
         super();
         this.transport = transport;
         this.transport.onclose = (reason) => {
+            this._isClosed = true;
             const why = `transport-close reason=${String(reason || "")}`;
             this.rejectAllInflight(why);
             this.emitTransportClosed(why);
         };
         this.transport.onerror = (err) => {
+            this._isClosed = true;
             const why = `transport-error ${err?.message ?? String(err)}`;
             this.rejectAllInflight(why);
             this.emitTransportClosed(why);
@@ -88,7 +91,7 @@ export class CDPConnection extends BaseCDPConnection {
         // Include User-Agent header for server-side observability and version tracking
         // Merge user-provided headers, letting them override defaults
         const headers = {
-            "User-Agent": `Handstages/${HANDSTAGES_VERSION}`,
+            "User-Agent": `Handstage/${HANDSTAGE_VERSION}`,
             ...options?.headers,
         };
         const ws = new WebSocket(wsUrl, { headers });
@@ -115,6 +118,9 @@ export class CDPConnection extends BaseCDPConnection {
         return new CDPConnection(transport);
     }
     async send(method, params) {
+        if (this._isClosed) {
+            return Promise.reject(new CDPConnectionClosedError(`Cannot send ${method}: connection is closed`));
+        }
         const id = this.nextId++;
         const payload = { id, method, params };
         const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");
@@ -145,6 +151,7 @@ export class CDPConnection extends BaseCDPConnection {
             set.delete(handler);
     }
     async close() {
+        this._isClosed = true;
         this.transport.close();
     }
     rejectAllInflight(why) {
@@ -276,6 +283,9 @@ export class CDPConnection extends BaseCDPConnection {
         }
     }
     _sendViaSession(sessionId, method, params) {
+        if (this._isClosed) {
+            return Promise.reject(new CDPConnectionClosedError(`Cannot send ${method}: connection is closed`));
+        }
         const id = this.nextId++;
         const payload = { id, method, params, sessionId };
         const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");

package/dist/v3/understudy/context.js

@@ -2,7 +2,7 @@ import { v3ScriptContent } from "@handstage/dom/build/scriptV3Content";
 import { v3Logger } from "../logger";
 import { getEnvTimeoutMs } from "../timeoutConfig";
 import { LogLevel } from "../types/public/logs";
-import { CookieSetError, HandstagesSetExtraHTTPHeadersError, PageNotFoundError, TimeoutError, } from "../types/public/sdkErrors";
+import { CookieSetError, HandstageSetExtraHTTPHeadersError, PageNotFoundError, TimeoutError, } from "../types/public/sdkErrors";
 import { CDPConnection, } from "./cdp";
 import { cookieMatchesFilter, filterCookies, normalizeCookieParams, toCDPCookieParam, } from "./cookies";
 import { executionContexts } from "./executionContextRegistry";
@@ -41,7 +41,7 @@ function isTopLevelPage(info) {
 }
 const DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS = 5000;
 const CI_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS = 30000;
-const FIRST_TOP_LEVEL_PAGE_TIMEOUT_ENV = "HANDSTAGES_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS";
+const FIRST_TOP_LEVEL_PAGE_TIMEOUT_ENV = "HANDSTAGE_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS";
 const WAIT_FOR_FIRST_TOP_LEVEL_PAGE_OPERATION = "waitForFirstTopLevelPage (no top-level Page)";
 function getFirstTopLevelPageTimeoutMs() {
     return (getEnvTimeoutMs(FIRST_TOP_LEVEL_PAGE_TIMEOUT_ENV) ??
@@ -225,9 +225,7 @@ export class V3Context {
                     return probe.browserContextId;
             }
             finally {
-                await conn
-                    .send("Target.closeTarget", { targetId })
-                    .catch((err) => {
+                await conn.send("Target.closeTarget", { targetId }).catch((err) => {
                     v3Logger({
                         category: "ctx",
                         message: "Failed to close temporary discovery target; it will remain until the browser exits",
@@ -485,7 +483,7 @@ export class V3Context {
             return `session=${sid} error=${message}`;
         });
         if (failures.length) {
-            throw new HandstagesSetExtraHTTPHeadersError(failures);
+            throw new HandstageSetExtraHTTPHeadersError(failures);
         }
     }
     /**

package/dist/v3/understudy/deepLocator.js

@@ -1,4 +1,4 @@
-import { HandstagesInvalidArgumentError } from "../types/public/sdkErrors";
+import { HandstageInvalidArgumentError } from "../types/public/sdkErrors";
 import { IFRAME_STEP_RE } from "./a11y/snapshot/focusSelectors";
 import { frameLocatorFromFrame } from "./frameLocator";
 import { Locator } from "./locator";
@@ -151,7 +151,7 @@ export class DeepLocatorDelegate {
     nth(index) {
         const value = Number(index);
         if (!Number.isFinite(value) || value < 0) {
-            throw new HandstagesInvalidArgumentError("deepLocator().nth() expects a non-negative index");
+            throw new HandstageInvalidArgumentError("deepLocator().nth() expects a non-negative index");
         }
         const nextIndex = Math.floor(value);
         if (nextIndex === this.nthIndex)

package/dist/v3/understudy/fileUploadUtils.js

@@ -1,7 +1,7 @@
 import { Buffer } from "buffer";
 import { promises as fs } from "fs";
 import path from "path";
-import { HandstagesInvalidArgumentError } from "../types/public/sdkErrors";
+import { HandstageInvalidArgumentError } from "../types/public/sdkErrors";
 const DEFAULT_MIME_TYPE = "application/octet-stream";
 /**
  * Normalize user-provided setInputFiles arguments into in-memory payloads.
@@ -26,7 +26,7 @@ export async function normalizeInputFiles(files, opts = {}) {
                 : path.resolve(baseDir, entry);
             const stat = await statFile(absolutePath);
             if (!stat.isFile()) {
-                throw new HandstagesInvalidArgumentError(`setInputFiles(): expected a file but received directory or special entry at ${absolutePath}`);
+                throw new HandstageInvalidArgumentError(`setInputFiles(): expected a file but received directory or special entry at ${absolutePath}`);
             }
             const buffer = await fs.readFile(absolutePath);
             normalized.push({
@@ -51,7 +51,7 @@ export async function normalizeInputFiles(files, opts = {}) {
             });
             continue;
         }
-        throw new HandstagesInvalidArgumentError("setInputFiles(): expected file path(s) or payload object(s)");
+        throw new HandstageInvalidArgumentError("setInputFiles(): expected file path(s) or payload object(s)");
     }
     return normalized;
 }
@@ -62,7 +62,7 @@ async function statFile(absolutePath) {
     catch (error) {
         const code = error?.code;
         if (code === "ENOENT") {
-            throw new HandstagesInvalidArgumentError(`setInputFiles(): file not found at ${absolutePath}`);
+            throw new HandstageInvalidArgumentError(`setInputFiles(): file not found at ${absolutePath}`);
         }
         throw error;
     }
@@ -76,5 +76,5 @@ export function toBuffer(data) {
         return Buffer.from(data);
     if (data instanceof ArrayBuffer)
         return Buffer.from(new Uint8Array(data));
-    throw new HandstagesInvalidArgumentError("Unsupported file payload buffer type");
+    throw new HandstageInvalidArgumentError("Unsupported file payload buffer type");
 }

package/dist/v3/understudy/frame.js

@@ -1,4 +1,4 @@
-import { HandstagesEvalError } from "../types/public/sdkErrors";
+import { HandstageEvalError } from "../types/public/sdkErrors";
 import { executionContexts } from "./executionContextRegistry";
 import { Locator } from "./locator";
 /**
@@ -45,10 +45,10 @@ export class Frame {
         const { root } = await this.session.send("DOM.getDocument");
         const { nodeId } = await this.session.send("DOM.querySelector", { nodeId: root.nodeId, selector });
         const { model } = await this.session.send("DOM.getBoxModel", { nodeId });
-        const x = model.content[0];
-        const y = model.content[1];
-        const width = model.width;
-        const height = model.height;
+        const x = model.content[0] ?? 0;
+        const y = model.content[1] ?? 0;
+        const width = model.width ?? 0;
+        const height = model.height ?? 0;
         return { x, y, width, height };
     }
     /** Accessibility.getFullAXTree (+ recurse into child frames if requested) */
@@ -128,7 +128,7 @@ export class Frame {
             });
         }
         if (res.exceptionDetails) {
-            throw new HandstagesEvalError(res.exceptionDetails.text ?? "Evaluation failed");
+            throw new HandstageEvalError(res.exceptionDetails.text ?? "Evaluation failed");
         }
         return res.result.value;
     }

package/dist/v3/understudy/frameLocator.js

@@ -1,4 +1,4 @@
-import { ContentFrameNotFoundError, HandstagesInvalidArgumentError, } from "../types/public/sdkErrors";
+import { ContentFrameNotFoundError, HandstageInvalidArgumentError, } from "../types/public/sdkErrors";
 import { executionContexts } from "./executionContextRegistry";
 /**
  * FrameLocator: resolves iframe elements to their child Frames and allows
@@ -117,7 +117,7 @@ class LocatorDelegate {
     nth(index) {
         const value = Number(index);
         if (!Number.isFinite(value) || value < 0) {
-            throw new HandstagesInvalidArgumentError("locator().nth() expects a non-negative index");
+            throw new HandstageInvalidArgumentError("locator().nth() expects a non-negative index");
         }
         const nextIndex = Math.floor(value);
         if (nextIndex === this.nthIndex)