@handstage/core 0.0.1 → 0.0.3

package/dist/v3/index.js

@@ -3,11 +3,11 @@ 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 Stagehand } from "./v3";
-const StagehandDefault = {
+export { V3, V3 as Handstages } from "./v3";
+const HandstagesDefault = {
     ...PublicApi,
     V3,
-    Stagehand: V3,
+    Handstages: V3,
     __internalMaybeRunShutdownSupervisorFromArgv: maybeRunShutdownSupervisorFromArgv,
 };
-export default StagehandDefault;
+export default HandstagesDefault;

package/dist/v3/launch/local.js

@@ -79,9 +79,7 @@ function probeWebSocket(wsUrl, timeoutMs) {
             try {
                 ws.terminate();
             }
-            catch {
-                // best-effort cleanup
-            }
+            catch { }
             if (error) {
                 reject(error);
                 return;

package/dist/v3/logger.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createConsoleLogger } from "./types/public/consoleLogger";
 /**
- * Stagehand V3 per-instance log routing (AsyncLocalStorage).
+ * Handstages 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/cleanupLocal.js

@@ -12,9 +12,7 @@ export async function cleanupLocalBrowser(opts) {
         try {
             await opts.killChrome();
         }
-        catch {
-            // best-effort
-        }
+        catch { }
     }
     if (opts.createdTempProfile &&
         !opts.preserveUserDataDir &&
@@ -22,8 +20,6 @@ export async function cleanupLocalBrowser(opts) {
         try {
             fs.rmSync(opts.userDataDir, { recursive: true, force: true });
         }
-        catch {
-            // ignore cleanup errors
-        }
+        catch { }
     }
 }

package/dist/v3/shutdown/supervisor.js

@@ -17,9 +17,7 @@ const exit = (code = 0) => {
     try {
         process.exit(code);
     }
-    catch {
-        // ignore
-    }
+    catch { }
 };
 // Best-effort two-phase kill: SIGTERM first, then SIGKILL after timeout.
 // Treat only ESRCH as "already gone"; other errors should not imply dead.
@@ -55,9 +53,7 @@ const politeKill = async (pid) => {
     try {
         process.kill(pid, "SIGKILL");
     }
-    catch {
-        // best-effort
-    }
+    catch { }
 };
 let pidPollTimer = null;
 // Local-only fallback: if Chrome dies while parent still lives, run cleanup and exit.
@@ -142,13 +138,11 @@ export const runShutdownSupervisor = (initialConfig) => {
     // Stdin is the lifeline; losing it means parent is gone.
     try {
         process.stdin.resume();
-        process.stdin.on("end", () => onLifelineClosed("Stagehand process completed"));
-        process.stdin.on("close", () => onLifelineClosed("Stagehand process completed"));
-        process.stdin.on("error", () => onLifelineClosed("Stagehand process crashed or was killed"));
-    }
-    catch {
-        // ignore
+        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"));
     }
+    catch { }
 };
 export const maybeRunShutdownSupervisorFromArgv = (argv = process.argv.slice(2)) => {
     const parsed = parseConfigFromArgv(argv);

package/dist/v3/shutdown/supervisorClient.js

@@ -24,7 +24,7 @@ const isSeaRuntime = () => {
     }
 };
 // SEA: re-exec current binary with supervisor args.
-// Non-SEA: execute Stagehand CLI entrypoint with supervisor args.
+// Non-SEA: execute Handstages 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 Stagehand CLI entrypoint)."), "resolve");
+        opts?.onError?.(new ShutdownSupervisorResolveError("Shutdown supervisor entry missing (expected Handstages CLI entrypoint)."), "resolve");
         return null;
     }
     const child = spawn(resolved.command, resolved.args, {
@@ -80,9 +80,7 @@ export function startShutdownSupervisor(config, opts) {
         try {
             child.kill("SIGTERM");
         }
-        catch {
-            // ignore
-        }
+        catch { }
     };
     return { stop };
 }

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

@@ -1,5 +1,5 @@
 /**
- * Severity for Stagehand log lines. Maps 1:1 to `console.error` / `console.info` / `console.debug`.
+ * Severity for Handstages 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 { STAGEHAND_VERSION } from "../../../version";
-export class StagehandError extends Error {
+import { HANDSTAGES_VERSION } from "../../../version";
+export class HandstagesError extends Error {
     cause;
     constructor(message, cause) {
         super(message);
@@ -10,146 +10,139 @@ export class StagehandError extends Error {
         }
     }
 }
-export class StagehandDefaultError extends StagehandError {
+export class HandstagesDefaultError extends HandstagesError {
     constructor(error) {
-        if (error instanceof Error || error instanceof StagehandError) {
-            super(`\nHey! We're sorry you ran into an error. \nStagehand version: ${STAGEHAND_VERSION} \nIf you need help, please open a Github issue or reach out to us on Discord: https://stagehand.dev/discord\n\nFull error:\n${error.message}`);
+        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}`);
         }
     }
 }
-export class StagehandEnvironmentError extends StagehandError {
+export class HandstagesEnvironmentError extends HandstagesError {
     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 StagehandError {
+export class MissingEnvironmentVariableError extends HandstagesError {
     constructor(missingEnvironmentVariable, feature) {
         super(`${missingEnvironmentVariable} is required to use ${feature}.` +
             `Please set ${missingEnvironmentVariable} in your environment.`);
     }
 }
-export class UnsupportedModelError extends StagehandError {
+export class UnsupportedModelError extends HandstagesError {
     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.stagehand.dev/v3/configuration/models#configuration-setup`;
+            `\n\nFor a complete list of supported models and providers, see: https://docs.handstages.dev/v3/configuration/models#configuration-setup`;
         super(`${message}${guidance}`);
     }
 }
-export class UnsupportedModelProviderError extends StagehandError {
+export class UnsupportedModelProviderError extends HandstagesError {
     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 StagehandError {
+export class UnsupportedAISDKModelProviderError extends HandstagesError {
     constructor(provider, supportedProviders) {
         super(`${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`);
     }
 }
-export class InvalidAISDKModelFormatError extends StagehandError {
+export class InvalidAISDKModelFormatError extends HandstagesError {
     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 StagehandNotInitializedError extends StagehandError {
-    constructor(prop) {
-        super(`You seem to be calling \`${prop}\` on a page in an uninitialized \`Stagehand\` object. ` +
-            `Ensure you are running \`await stagehand.init()\` on the Stagehand object before ` +
-            `referencing the \`page\` object.`);
-    }
-}
-export class CaptchaTimeoutError extends StagehandError {
+export class CaptchaTimeoutError extends HandstagesError {
     constructor() {
         super("Captcha timeout");
     }
 }
-export class MissingLLMConfigurationError extends StagehandError {
+export class MissingLLMConfigurationError extends HandstagesError {
     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 StagehandError {
+export class HandlerNotInitializedError extends HandstagesError {
     constructor(handlerType) {
         super(`${handlerType} handler not initialized`);
     }
 }
-export class StagehandInvalidArgumentError extends StagehandError {
+export class HandstagesInvalidArgumentError extends HandstagesError {
     constructor(message) {
         super(`InvalidArgumentError: ${message}`);
     }
 }
-export class CookieValidationError extends StagehandError {
+export class CookieValidationError extends HandstagesError {
     constructor(message) {
         super(message);
     }
 }
-export class CookieSetError extends StagehandError {
+export class CookieSetError extends HandstagesError {
     constructor(message) {
         super(message);
     }
 }
-export class StagehandElementNotFoundError extends StagehandError {
+export class HandstagesElementNotFoundError extends HandstagesError {
     constructor(xpaths) {
         super(`Could not find an element for the given xPath(s): ${xpaths}`);
     }
 }
-export class AgentScreenshotProviderError extends StagehandError {
+export class AgentScreenshotProviderError extends HandstagesError {
     constructor(message) {
         super(`ScreenshotProviderError: ${message}`);
     }
 }
-export class StagehandMissingArgumentError extends StagehandError {
+export class HandstagesMissingArgumentError extends HandstagesError {
     constructor(message) {
         super(`MissingArgumentError: ${message}`);
     }
 }
-export class CreateChatCompletionResponseError extends StagehandError {
+export class CreateChatCompletionResponseError extends HandstagesError {
     constructor(message) {
         super(`CreateChatCompletionResponseError: ${message}`);
     }
 }
-export class StagehandEvalError extends StagehandError {
+export class HandstagesEvalError extends HandstagesError {
     constructor(message) {
-        super(`StagehandEvalError: ${message}`);
+        super(`HandstagesEvalError: ${message}`);
     }
 }
-export class StagehandDomProcessError extends StagehandError {
+export class HandstagesDomProcessError extends HandstagesError {
     constructor(message) {
         super(`Error Processing Dom: ${message}`);
     }
 }
-export class StagehandLocatorError extends StagehandError {
+export class HandstagesLocatorError extends HandstagesError {
     constructor(action, selector, message) {
         super(`Error ${action} Element with selector: ${selector} Reason: ${message}`);
     }
 }
-export class StagehandClickError extends StagehandError {
+export class HandstagesClickError extends HandstagesError {
     constructor(message, selector) {
         super(`Error Clicking Element with selector: ${selector} Reason: ${message}`);
     }
 }
-export class LLMResponseError extends StagehandError {
+export class LLMResponseError extends HandstagesError {
     constructor(primitive, message) {
         super(`${primitive} LLM response error: ${message}`);
     }
 }
-export class StagehandIframeError extends StagehandError {
+export class HandstagesIframeError extends HandstagesError {
     constructor(frameUrl, message) {
         super(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
     }
 }
-export class ContentFrameNotFoundError extends StagehandError {
+export class ContentFrameNotFoundError extends HandstagesError {
     constructor(selector) {
         super(`Unable to obtain a content frame for selector: ${selector}`);
     }
 }
-export class XPathResolutionError extends StagehandError {
+export class XPathResolutionError extends HandstagesError {
     constructor(xpath) {
         super(`XPath "${xpath}" does not resolve in the current page or frames`);
     }
@@ -170,76 +163,76 @@ ${JSON.stringify(issues, null, 2)}`);
         this.name = "ZodSchemaValidationError";
     }
 }
-export class StagehandInitError extends StagehandError {
+export class HandstagesInitError extends HandstagesError {
     constructor(message) {
         super(message);
     }
 }
-export class StagehandShadowRootMissingError extends StagehandError {
+export class HandstagesShadowRootMissingError extends HandstagesError {
     constructor(detail) {
         super(`No shadow root present on the resolved host` +
             (detail ? `: ${detail}` : ""));
     }
 }
-export class StagehandShadowSegmentEmptyError extends StagehandError {
+export class HandstagesShadowSegmentEmptyError extends HandstagesError {
     constructor() {
         super(`Empty selector segment after shadow-DOM hop ("//")`);
     }
 }
-export class StagehandShadowSegmentNotFoundError extends StagehandError {
+export class HandstagesShadowSegmentNotFoundError extends HandstagesError {
     constructor(segment, hint) {
         super(`Shadow segment '${segment}' matched no element inside shadow root` +
             (hint ? ` ${hint}` : ""));
     }
 }
-export class ElementNotVisibleError extends StagehandError {
+export class ElementNotVisibleError extends HandstagesError {
     constructor(selector) {
         super(`Element not visible (no box model): ${selector}`);
     }
 }
-export class ResponseBodyError extends StagehandError {
+export class ResponseBodyError extends HandstagesError {
     constructor(message) {
         super(`Failed to retrieve response body: ${message}`);
     }
 }
-export class ResponseParseError extends StagehandError {
+export class ResponseParseError extends HandstagesError {
     constructor(message) {
         super(`Failed to parse response: ${message}`);
     }
 }
-export class TimeoutError extends StagehandError {
+export class TimeoutError extends HandstagesError {
     constructor(operation, timeoutMs) {
         super(`${operation} timed out after ${timeoutMs}ms`);
     }
 }
-export class PageNotFoundError extends StagehandError {
+export class PageNotFoundError extends HandstagesError {
     constructor(identifier) {
         super(`No Page found for ${identifier}`);
     }
 }
-export class ConnectionTimeoutError extends StagehandError {
+export class ConnectionTimeoutError extends HandstagesError {
     constructor(message) {
         super(`Connection timeout: ${message}`);
     }
 }
-export class StagehandClosedError extends StagehandError {
+export class HandstagesClosedError extends HandstagesError {
     constructor() {
-        super("Stagehand session was closed");
+        super("Handstages session was closed");
     }
 }
-export class CdpConnectionClosedError extends StagehandError {
+export class CDPConnectionClosedError extends HandstagesError {
     constructor(reason) {
         super(`CDP connection closed: ${reason}`);
     }
 }
-export class StagehandSetExtraHTTPHeadersError extends StagehandError {
+export class HandstagesSetExtraHTTPHeadersError extends HandstagesError {
     failures;
     constructor(failures) {
         super(`setExtraHTTPHeaders failed for ${failures.length} session(s): ${failures.join(", ")}`);
         this.failures = failures;
     }
 }
-export class StagehandSnapshotError extends StagehandError {
+export class HandstagesSnapshotError extends HandstagesError {
     constructor(cause) {
         const suffix = cause instanceof Error
             ? `: ${cause.message}`
@@ -249,7 +242,7 @@ export class StagehandSnapshotError extends StagehandError {
         super(`error taking snapshot${suffix}`, cause);
     }
 }
-export class UnderstudyCommandException extends StagehandError {
+export class UnderstudyCommandException extends HandstagesError {
     constructor(message, cause) {
         super(message, cause);
         this.name = "UnderstudyCommandException";

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

@@ -87,9 +87,7 @@ export function decorateRoles(nodes, opts) {
             try {
                 encodedId = opts.encode(n.backendDOMNodeId);
             }
-            catch {
-                //
-            }
+            catch { }
         }
         let role = asRole(n);
         const domIsScrollable = encodedId

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

@@ -39,9 +39,7 @@ export async function computeActiveElementXpath(page) {
                 break;
             }
         }
-        catch {
-            //
-        }
+        catch { }
     }
     if (!focusedFrameId)
         focusedFrameId = page.mainFrameId();
@@ -78,9 +76,7 @@ export async function computeActiveElementXpath(page) {
             try {
                 await focusedSession.send("Runtime.releaseObject", { objectId });
             }
-            catch {
-                //
-            }
+            catch { }
             const xp = result?.value || "";
             return typeof xp === "string" && xp ? xp : null;
         }
@@ -88,9 +84,7 @@ export async function computeActiveElementXpath(page) {
             try {
                 await focusedSession.send("Runtime.releaseObject", { objectId });
             }
-            catch {
-                //
-            }
+            catch { }
             return null;
         }
     })();
@@ -111,9 +105,7 @@ export async function computeActiveElementXpath(page) {
                     prefix = prefix ? prefixXPath(prefix, xp) : normalizeXPath(xp);
             }
         }
-        catch {
-            //
-        }
+        catch { }
         cur = parent;
     }
     return prefix ? prefixXPath(prefix, leafXPath) : normalizeXPath(leafXPath);

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

@@ -196,9 +196,7 @@ export async function collectPerFrameMaps(page, context, sessionToIndex, options
                         docRootBe = cdBe;
                 }
             }
-            catch {
-                //
-            }
+            catch { }
         }
         const tagNameMap = {};
         const xpathMap = {};

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

@@ -42,9 +42,7 @@ export async function resolveXpathForLocation(page, x, y) {
                 sx = Number(result?.value?.sx ?? 0);
                 sy = Number(result?.value?.sy ?? 0);
             }
-            catch {
-                //
-            }
+            catch { }
             const xi = Math.max(0, Math.floor(curX + sx));
             const yi = Math.max(0, Math.floor(curY + sy));
             let res;
@@ -110,9 +108,7 @@ export async function resolveXpathForLocation(page, x, y) {
                         .catch(() => { });
                 }
             }
-            catch {
-                //
-            }
+            catch { }
             curX = Math.max(0, curX - left);
             curY = Math.max(0, curY - top);
             curFrameId = matchedChild;

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

@@ -1,4 +1,4 @@
-import { StagehandDomProcessError } from "../../../types/public/sdkErrors";
+import { HandstagesDomProcessError } 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 StagehandDomProcessError.
+ * decreasing depths. Any non-CBOR failure is surfaced as a HandstagesDomProcessError.
  */
 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 StagehandDomProcessError(`Failed to expand DOM node ${identifier}: ${String(err)}`);
+                    throw new HandstagesDomProcessError(`Failed to expand DOM node ${identifier}: ${String(err)}`);
                 }
             }
             if (!expanded) {
                 const identifier = nodeId ?? backendId ?? "unknown";
-                throw new StagehandDomProcessError(`Unable to expand DOM node ${identifier} after describeNode depth retries`);
+                throw new HandstagesDomProcessError(`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 StagehandDomProcessError(lastCborMessage
+    throw new HandstagesDomProcessError(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 { StagehandIframeError } from "../../../types/public/sdkErrors";
+import { HandstagesIframeError } 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 StagehandIframeError(selectorForIframe, "Failed to resolve iframe element by XPath");
+            throw new HandstagesIframeError(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 StagehandIframeError(selectorForIframe, "Could not map iframe to child frameId");
+                throw new HandstagesIframeError(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 StagehandIframeError(parts[i], "Failed to resolve iframe via CSS hop");
+            throw new HandstagesIframeError(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 StagehandIframeError(parts[i], "Could not map CSS iframe hop to child frameId");
+                throw new HandstagesIframeError(parts[i], "Could not map CSS iframe hop to child frameId");
             ctxFrameId = childFrameId;
         }
         finally {