@handstage/core 0.0.7 → 0.0.8

package/README.md

@@ -1,3 +1,45 @@
 # @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.
+Core browser automation engine for Handstage. Manages CDP connections,
+target routing, page/frame lifecycle, and script injection for reliable
+browser automation.
+
+## Connection ownership
+
+`V3` (alias `Handstage`) owns the CDP connection it constructs:
+
+- `V3.connectLocal({ cdpUrl?, ... })` — opens (or attaches via WS) and owns
+  the connection. `close()` closes the WebSocket.
+- `V3.connectTransport(transport)` — wraps and owns a raw `CDPTransport`.
+  Wrapping the same `transport` again throws
+  `HandstageTransportAlreadyOwnedError`.
+- `V3.connectSession(session)` — wraps and owns an `ExternalCDPSession`.
+  Same ownership rule as transports.
+- `V3.connectConnection(existingConnection)` — explicit sharing entrypoint.
+  V3 does NOT close the connection on `close()`; the caller does.
+
+`V3Context.close()` only ever calls `Target.disposeBrowserContext` (for
+dedicated contexts). It never tears down the underlying CDP connection —
+that responsibility lives with `V3` or, for shared connections, the caller.
+
+## Default-context attach
+
+Handstage creates instances containing the `defaultBrowserContext()` by default (which aligns with Puppeteer's `puppeteer.connect` and `puppeteer.launch`).
+Two Handstage clients on the same CDP websocket therefore share the default browser context natively without breaking. If you want isolation, call `v3.createBrowserContext()`, which returns an isolated browser context. Targets owned by other browser contexts are resumed/detached at the target router rather than left paused.
+
+To intentionally attach to the shared default context (and accept that
+other actors may race with you on a shared tab), simply use the default browser context (i.e. `v3.newPage()`).
+
+## Active page is gone
+
+Contexts no longer auto-create an initial page and there is no
+`context.activePage()` / `setActivePage()` / `awaitActivePage()`. Track
+`Page` references yourself (from `newPage()` / `pages()`) and call
+`page.bringToFront()` if you want to foreground a tab.
+
+## Per-instance logging
+
+Pass `logger:` to any `V3.connect*` factory and that logger receives every
+log from that V3's contexts / pages / network managers / target-router
+delegate. Two V3 instances on a shared connection each receive router-level
+debug lines via broadcast.

package/dist/v3/logger.js

@@ -1,37 +1,28 @@
-import { AsyncLocalStorage } from "node:async_hooks";
 import { createConsoleLogger } from "./types/public/consoleLogger";
+import { LogLevel, shouldEmitLogLine } from "./types/public/logs";
 /**
- * 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.
- * - `v3Logger`: emit a line for the current instance, or fall back to `createConsoleLogger()` when no context.
+ * Build a level-filtered logger from the caller-supplied logger (or a
+ * console fallback).  Used by V3 at construction time to wrap the user's
+ * raw logger into one that already respects `verbose`.
  */
-const logContext = new AsyncLocalStorage();
-const instanceLoggers = new Map();
-const fallbackLogger = createConsoleLogger();
-export function bindInstanceLogger(instanceId, logger) {
-    instanceLoggers.set(instanceId, logger);
+export function createFilteredLogger(rawLogger, verbose) {
+    const sink = rawLogger ?? createConsoleLogger();
+    const minLevel = verbose ?? LogLevel.Info;
+    return (line) => {
+        if (!shouldEmitLogLine(line.level, minLevel))
+            return;
+        sink({ ...line, level: line.level ?? LogLevel.Info });
+    };
 }
-export function unbindInstanceLogger(instanceId) {
-    instanceLoggers.delete(instanceId);
-}
-export function withInstanceLogContext(instanceId, fn) {
-    return logContext.run(instanceId, fn);
-}
-export function v3Logger(line) {
-    const id = logContext.getStore();
-    if (id) {
-        const fn = instanceLoggers.get(id);
-        if (fn) {
-            try {
-                fn(line);
-                return;
-            }
-            catch {
-                // fall through to fallback
-            }
-        }
+/**
+ * Lazily-constructed console fallback used for code paths that fire before
+ * a real logger is plumbed in (e.g. the few static utility functions that
+ * still take an optional logger arg).
+ */
+let _defaultLogger = null;
+export function defaultLogger() {
+    if (!_defaultLogger) {
+        _defaultLogger = createFilteredLogger(undefined, LogLevel.Info);
     }
-    fallbackLogger(line);
+    return _defaultLogger;
 }

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

@@ -1,4 +1,5 @@
 // Export api.ts under namespace to avoid name collisions
+export { CDPConnection, } from "../../understudy/cdp";
 export * as Api from "./api";
 export * from "./consoleLogger";
 export * from "./context";

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

@@ -10,68 +10,6 @@ export class HandstageError extends Error {
         }
     }
 }
-export class HandstageDefaultError extends HandstageError {
-    constructor(error) {
-        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 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 HandstageError {
-    constructor(missingEnvironmentVariable, feature) {
-        super(`${missingEnvironmentVariable} is required to use ${feature}.` +
-            `Please set ${missingEnvironmentVariable} in your environment.`);
-    }
-}
-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.handstage.dev/v3/configuration/models#configuration-setup`;
-        super(`${message}${guidance}`);
-    }
-}
-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 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 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 HandstageError {
-    constructor() {
-        super("Captcha timeout");
-    }
-}
-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 HandstageError {
-    constructor(handlerType) {
-        super(`${handlerType} handler not initialized`);
-    }
-}
 export class HandstageInvalidArgumentError extends HandstageError {
     constructor(message) {
         super(`InvalidArgumentError: ${message}`);
@@ -92,21 +30,6 @@ export class HandstageElementNotFoundError extends HandstageError {
         super(`Could not find an element for the given xPath(s): ${xpaths}`);
     }
 }
-export class AgentScreenshotProviderError extends HandstageError {
-    constructor(message) {
-        super(`ScreenshotProviderError: ${message}`);
-    }
-}
-export class HandstageMissingArgumentError extends HandstageError {
-    constructor(message) {
-        super(`MissingArgumentError: ${message}`);
-    }
-}
-export class CreateChatCompletionResponseError extends HandstageError {
-    constructor(message) {
-        super(`CreateChatCompletionResponseError: ${message}`);
-    }
-}
 export class HandstageEvalError extends HandstageError {
     constructor(message) {
         super(`HandstageEvalError: ${message}`);
@@ -122,16 +45,6 @@ export class HandstageLocatorError extends HandstageError {
         super(`Error ${action} Element with selector: ${selector} Reason: ${message}`);
     }
 }
-export class HandstageClickError extends HandstageError {
-    constructor(message, selector) {
-        super(`Error Clicking Element with selector: ${selector} Reason: ${message}`);
-    }
-}
-export class LLMResponseError extends HandstageError {
-    constructor(primitive, message) {
-        super(`${primitive} LLM response error: ${message}`);
-    }
-}
 export class HandstageIframeError extends HandstageError {
     constructor(frameUrl, message) {
         super(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
@@ -142,49 +55,6 @@ export class ContentFrameNotFoundError extends HandstageError {
         super(`Unable to obtain a content frame for selector: ${selector}`);
     }
 }
-export class XPathResolutionError extends HandstageError {
-    constructor(xpath) {
-        super(`XPath "${xpath}" does not resolve in the current page or frames`);
-    }
-}
-export class ZodSchemaValidationError extends Error {
-    received;
-    issues;
-    constructor(received, issues) {
-        super(`Zod schema validation failed
-
-— Received —
-${JSON.stringify(received, null, 2)}
-
-— Issues —
-${JSON.stringify(issues, null, 2)}`);
-        this.received = received;
-        this.issues = issues;
-        this.name = "ZodSchemaValidationError";
-    }
-}
-export class HandstageInitError extends HandstageError {
-    constructor(message) {
-        super(message);
-    }
-}
-export class HandstageShadowRootMissingError extends HandstageError {
-    constructor(detail) {
-        super(`No shadow root present on the resolved host` +
-            (detail ? `: ${detail}` : ""));
-    }
-}
-export class HandstageShadowSegmentEmptyError extends HandstageError {
-    constructor() {
-        super(`Empty selector segment after shadow-DOM hop ("//")`);
-    }
-}
-export class HandstageShadowSegmentNotFoundError extends HandstageError {
-    constructor(segment, hint) {
-        super(`Shadow segment '${segment}' matched no element inside shadow root` +
-            (hint ? ` ${hint}` : ""));
-    }
-}
 export class ElementNotVisibleError extends HandstageError {
     constructor(selector) {
         super(`Element not visible (no box model): ${selector}`);
@@ -215,16 +85,33 @@ export class ConnectionTimeoutError extends HandstageError {
         super(`Connection timeout: ${message}`);
     }
 }
-export class HandstageClosedError extends HandstageError {
-    constructor() {
-        super("Handstage session was closed");
-    }
-}
 export class CDPConnectionClosedError extends HandstageError {
     constructor(reason) {
         super(`CDP connection closed: ${reason}`);
     }
 }
+/**
+ * Raised when a caller tries to wrap a `CDPTransport` (via
+ * `new CDPConnection(transport)` / `V3.connectTransport`) or an
+ * `ExternalCDPSession` (via `V3.connectSession`) that is already owned by
+ * another `CDPConnection` / `ExternalConnectionAdapter`.
+ *
+ * Silently double-wrapping would clobber `transport.onmessage` / `.onclose` /
+ * `.onerror` and stall the first owner.  If you actually want two `V3`
+ * instances sharing one CDP connection, construct the connection once and
+ * use `V3.connectConnection(existingConnection)` for both instances.
+ */
+export class HandstageTransportAlreadyOwnedError extends HandstageError {
+    constructor(kind) {
+        super(kind === "transport"
+            ? "CDPTransport already owned by another CDPConnection. " +
+                "Construct the CDPConnection once and share it via V3.connectConnection() " +
+                "instead of wrapping the same transport twice."
+            : "ExternalCDPSession already owned by another ExternalConnectionAdapter. " +
+                "Construct the adapter once and share the resulting CDPConnectionLike via " +
+                "V3.connectConnection() instead of calling connectSession twice with the same session.");
+    }
+}
 export class HandstageSetExtraHTTPHeadersError extends HandstageError {
     failures;
     constructor(failures) {
@@ -242,9 +129,3 @@ export class HandstageSnapshotError extends HandstageError {
         super(`error taking snapshot${suffix}`, cause);
     }
 }
-export class UnderstudyCommandException extends HandstageError {
-    constructor(message, cause) {
-        super(message, cause);
-        this.name = "UnderstudyCommandException";
-    }
-}

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

@@ -1,4 +1,3 @@
-import { v3Logger } from "../../../logger";
 import { LogLevel } from "../../../types/public/logs";
 import { a11yForFrame } from "./a11yTree";
 import { buildSessionDomIndex, domMapsForSession, relativizeXPath, } from "./domTree";
@@ -71,7 +70,7 @@ export async function tryScopedSnapshot(page, options, context, pierce) {
     if (!requestedFocus)
         return null;
     const logScopeFallback = () => {
-        v3Logger({
+        page.logger({
             message: `Unable to narrow scope with selector. Falling back to using full DOM`,
             level: LogLevel.Info,
             attributes: {

package/dist/v3/understudy/cdp.js

@@ -1,5 +1,29 @@
 import { HANDSTAGE_VERSION } from "../../version";
-import { CDPConnectionClosedError, PageNotFoundError, } from "../types/public/sdkErrors";
+import { CDPConnectionClosedError, HandstageTransportAlreadyOwnedError, PageNotFoundError, } from "../types/public/sdkErrors";
+/**
+ * Marker placed on a `CDPTransport` once a `CDPConnection` has bound its
+ * `onmessage` / `onclose` / `onerror` callbacks.  A second wrap throws so
+ * the caller can't silently destroy the first owner.  Use `Symbol.for(...)`
+ * so the marker survives across module realms (rare, but cheap to guard).
+ */
+const TRANSPORT_OWNED = Symbol.for("handstage.cdp.transportOwned");
+/**
+ * Same marker as {@link TRANSPORT_OWNED} but for `ExternalCDPSession`
+ * wrapped by `ExternalConnectionAdapter`.
+ */
+const SESSION_OWNED = Symbol.for("handstage.cdp.sessionOwned");
+function invokeEventHandler(handler, params) {
+    try {
+        const result = handler(params);
+        if (result &&
+            typeof result === "object" &&
+            "then" in result &&
+            typeof result.then === "function") {
+            void result.catch(() => { });
+        }
+    }
+    catch { }
+}
 export class BaseCDPConnection {
     // Memoize the in-flight enable so concurrent V3Contexts sharing the
     // connection don't all re-fire setAutoAttach on the browser session.
@@ -71,6 +95,12 @@ export class CDPConnection extends BaseCDPConnection {
     }
     constructor(transport) {
         super();
+        const owned = transport[TRANSPORT_OWNED];
+        if (owned) {
+            throw new HandstageTransportAlreadyOwnedError("transport");
+        }
+        ;
+        transport[TRANSPORT_OWNED] = this;
         this.transport = transport;
         this.transport.onclose = (reason) => {
             this._isClosed = true;
@@ -154,7 +184,18 @@ export class CDPConnection extends BaseCDPConnection {
     }
     async close() {
         this._isClosed = true;
-        this.transport.close();
+        try {
+            this.transport.close();
+        }
+        finally {
+            // Release ownership so a future caller could re-wrap a fresh
+            // transport with the same identity (rare; mainly relevant in
+            // long-running tests that reuse fake transports).
+            try {
+                delete this.transport[TRANSPORT_OWNED];
+            }
+            catch { }
+        }
     }
     rejectAllInflight(why) {
         for (const [id, entry] of this.inflight.entries()) {
@@ -272,14 +313,14 @@ export class CDPConnection extends BaseCDPConnection {
                         const handlers = this.eventHandlers.get(method);
                         if (handlers)
                             for (const h of handlers)
-                                h(params);
+                                invokeEventHandler(h, params);
                     }
                     return;
                 }
                 const handlers = this.eventHandlers.get(method);
                 if (handlers)
                     for (const h of handlers)
-                        h(params);
+                        invokeEventHandler(h, params);
             };
             dispatch();
         }
@@ -339,7 +380,7 @@ export class CDPConnection extends BaseCDPConnection {
         const handlers = this.eventHandlers.get(key);
         if (handlers)
             for (const h of handlers)
-                h(params);
+                invokeEventHandler(h, params);
     }
 }
 export class ExternalConnectionAdapter extends BaseCDPConnection {
@@ -353,6 +394,13 @@ export class ExternalConnectionAdapter extends BaseCDPConnection {
     constructor(externalSession) {
         super();
         this.externalSession = externalSession;
+        const owned = externalSession[SESSION_OWNED];
+        if (owned) {
+            throw new HandstageTransportAlreadyOwnedError("session");
+        }
+        ;
+        externalSession[SESSION_OWNED] =
+            this;
         // Listen for flattened child session events if the external wrapper passes them
         this.on("Target.attachedToTarget", (params) => {
             if (params?.sessionId && !this.sessions.has(params.sessionId)) {
@@ -390,21 +438,23 @@ export class ExternalConnectionAdapter extends BaseCDPConnection {
                     const childHandlers = this.eventHandlers.get(childKey);
                     if (childHandlers) {
                         for (const h of childHandlers)
-                            h(params);
+                            invokeEventHandler(h, params);
                     }
                     // Forward target lifecycle events to root listeners as well.
                     if (event.startsWith("Target.")) {
                         const rootHandlers = this.eventHandlers.get(event);
-                        if (rootHandlers)
+                        if (rootHandlers) {
                             for (const h of rootHandlers)
-                                h(params);
+                                invokeEventHandler(h, params);
+                        }
                     }
                 }
                 else {
                     const rootHandlers = this.eventHandlers.get(event);
-                    if (rootHandlers)
+                    if (rootHandlers) {
                         for (const h of rootHandlers)
-                            h(params);
+                            invokeEventHandler(h, params);
+                    }
                 }
             };
             this.rootEventHandlers.set(event, rootHandler);
@@ -441,6 +491,10 @@ export class ExternalConnectionAdapter extends BaseCDPConnection {
         if (this.externalSession.onclose) {
             this.externalSession.onclose = undefined;
         }
+        try {
+            delete this.externalSession[SESSION_OWNED];
+        }
+        catch { }
         // If external session has a close method, invoke it, otherwise no-op.
         if (typeof this.externalSession.close === "function") {
             await this.externalSession.close();