browser-debugger-cli 0.14.0 → 0.16.0

package/dist/commands/dom/helpers/evalResult.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+/**
+ * The `result` of `dom eval --json`, and what was left out of it. A string
+ * `result` with `truncatedFrom` while `type` is `object` is the start of
+ * the value's JSON text, not a string the script returned.
+ */
+export interface BoundedEvalResult {
+    /** The value, its first elements, or the start of its (JSON) text */
+    result: unknown;
+    /** Elements of an array result in the page, set only when it was bounded */
+    count?: number;
+    /** Elements left out of a listed array result */
+    omitted?: number;
+    /**
+     * Length of the string, or of the JSON text of the copied object or array
+     * (which holds at most 1000 entries per list or object), `result` was cut from
+     */
+    truncatedFrom?: number;
+}
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export declare function boundEvalResult(value: unknown, length?: number): BoundedEvalResult;
+//# sourceMappingURL=evalResult.d.ts.map

package/dist/commands/dom/helpers/evalResult.js

@@ -0,0 +1,59 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+import { EVAL_JSON_ARRAY_LIMIT, MAX_VALUE_LENGTH } from '../../../constants.js';
+import { capLength } from '../../../utils/strings.js';
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export function boundEvalResult(value, length) {
+    if (typeof value === 'string') {
+        const { text, truncatedFrom } = capLength(value, MAX_VALUE_LENGTH);
+        return { result: text, ...(truncatedFrom !== undefined && { truncatedFrom }) };
+    }
+    if (Array.isArray(value))
+        return boundArray(value, length ?? value.length);
+    if (value === null || typeof value !== 'object')
+        return { result: value };
+    const json = JSON.stringify(value);
+    return json.length > MAX_VALUE_LENGTH ? jsonStart(json) : { result: value };
+}
+/**
+ * Bound an array result: its first {@link EVAL_JSON_ARRAY_LIMIT} elements,
+ * or the start of its JSON text when even those are over the cap.
+ *
+ * @param value - Array result
+ * @param count - Elements of the array in the page
+ * @returns `result` with `count`, and `omitted` or `truncatedFrom`
+ */
+function boundArray(value, count) {
+    const listed = value.slice(0, EVAL_JSON_ARRAY_LIMIT);
+    const listedJson = JSON.stringify(listed);
+    if (listedJson.length > MAX_VALUE_LENGTH) {
+        const json = listed.length === value.length ? listedJson : JSON.stringify(value);
+        return { ...jsonStart(json), count };
+    }
+    return listed.length < count
+        ? { result: listed, count, omitted: count - listed.length }
+        : { result: value };
+}
+/**
+ * The first {@link MAX_VALUE_LENGTH} characters of a JSON text.
+ *
+ * @param json - JSON text of an object or array over the cap
+ * @returns Its start, and the length of all of it
+ */
+function jsonStart(json) {
+    return { result: capLength(json, MAX_VALUE_LENGTH).text, truncatedFrom: json.length };
+}
+//# sourceMappingURL=evalResult.js.map

package/dist/commands/dom/helpers/index.d.ts

@@ -3,9 +3,9 @@
  * so callers can keep importing from `@/commands/dom/helpers.js`.
  *
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
- * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ * - `screenshot.ts` — page / element capture through the daemon, writing the image
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
-export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
-export type { DomQueryResult, DomGetResult, ScreenshotResult, DomGetOptions, ScreenshotOptions, DomContext, ElementBounds, } from '../../../types.js';
+export { noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
+export { captureScreenshot, screenshotInterrupted } from './screenshot.js';
+export type { DomGetOptions, DomContext } from '../../../types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/dom/helpers/index.js

@@ -3,8 +3,8 @@
  * so callers can keep importing from `@/commands/dom/helpers.js`.
  *
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
- * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ * - `screenshot.ts` — page / element capture through the daemon, writing the image
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
-export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
+export { noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
+export { captureScreenshot, screenshotInterrupted } from './screenshot.js';
 //# sourceMappingURL=index.js.map

package/dist/commands/dom/helpers/query.d.ts

@@ -91,10 +91,10 @@ export declare function getDOMElements(options: DomGetOptions): Promise<DomGetRe
  * Resolve a selector to its first match.
  *
  * @param selector - CSS selector
- * @returns Reference to the first matching node (valid within this command)
+ * @returns Backend node id of the first match
  * @throws CommandError (83) when nothing matches
  */
-export declare function resolveSelector(selector: string): Promise<NodeRef>;
+export declare function resolveSelector(selector: string): Promise<number>;
 /**
  * Resolve selectors to backend node ids (first match each).
  *

package/dist/commands/dom/helpers/query.js

@@ -655,7 +655,7 @@ export async function getDOMElements(options) {
  * Resolve a selector to its first match.
  *
  * @param selector - CSS selector
- * @returns Reference to the first matching node (valid within this command)
+ * @returns Backend node id of the first match
  * @throws CommandError (83) when nothing matches
  */
 export async function resolveSelector(selector) {
@@ -664,7 +664,7 @@ export async function resolveSelector(selector) {
         const err = await noMatchesError(selector);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
-    return { backendNodeId };
+    return backendNodeId;
 }
 /**
  * Resolve selectors to backend node ids (first match each).

package/dist/commands/dom/helpers/screenshot.d.ts

@@ -1,34 +1,29 @@
 /**
- * CDP-relay helpers for screenshot capture.
- *
- * Covers page, element, and element-bounds operations plus the scroll-into-
- * view primitives used by page screenshots with `--scroll`.
+ * Screenshot capture for `bdg dom screenshot`: the daemon measures, captures
+ * and puts back the page's emulation (`dom_screenshot`); this writes the image
+ * it returns.
  */
-import type { ScreenshotResult, ScreenshotOptions, ElementBounds, NodeRef } from '../../../types.js';
+import { type InterruptSignal } from '../../shared/interrupt.js';
+import { CommandError } from '../../../errors/index.js';
+import type { DomScreenshotCommand } from '../../../ipc/protocol/commands.js';
+import type { ScreenshotResult } from '../../../types.js';
 /**
- * Get the bounding box (border box, so padding and border are included) of an
- * element via CDP DOM.getBoxModel.
+ * The error of a screenshot interrupted by Ctrl-C or SIGTERM.
  *
- * @param ref - Node reference
- * @returns Element bounds in CSS pixels
- */
-export declare function getElementBounds(ref: NodeRef): Promise<ElementBounds>;
-/**
- * Capture a screenshot of the page. Auto-resizes oversized pages by default
- * to keep Claude Vision token cost bounded; falls back to viewport capture
- * when the page is taller than the tall-page threshold.
+ * @param signal - The signal
+ * @returns Command error (exit 130, or 143 for SIGTERM)
  */
-export declare function capturePageScreenshot(outputPath: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
+export declare function screenshotInterrupted(signal: InterruptSignal): CommandError;
 /**
- * Capture a screenshot of a single element: its border box, grown to include
- * content overflowing it ({@link captureArea}). The box model is relative to
- * the viewport and the capture clip to the page, so the page scroll is added
- * (the reported bounds are page coordinates, like `dom layout`'s).
+ * Capture the page (or the element `backendNodeId` names) and write the
+ * image.
+ *
+ * @param outputPath - File to write
+ * @param request - What to capture and how
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM: the capture is cancelled
+ * @returns What was captured, with the file's absolute path
+ * @throws CommandError with the daemon's error (Chrome's, when the capture
+ *   failed) and exit code, or 130/143 when interrupted
  */
-export declare function captureElementScreenshot(outputPath: string, ref: NodeRef, options?: {
-    format?: 'png' | 'jpeg';
-    quality?: number;
-    noResize?: boolean;
-    padding?: number;
-}): Promise<ScreenshotResult>;
+export declare function captureScreenshot(outputPath: string, request: DomScreenshotCommand, interrupt?: AbortSignal): Promise<ScreenshotResult>;
 //# sourceMappingURL=screenshot.d.ts.map