browser-debugger-cli 0.7.1 → 0.8.0

package/dist/runtime/dom/frameSelection.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which iframe a `bdg dom eval --frame` value names.
+ */
+import { CommandError } from '../../errors/index.js';
+import type { DomFrame } from '../../ipc/protocol/commands.js';
+/**
+ * Pick the frame a `--frame` value names: a 0-based index, an exact `name`
+ * or `id` attribute, or else a case-insensitive part of the URL.
+ *
+ * @param frames - Frames of the page
+ * @param query - Requested frame
+ * @returns The matching frame
+ * @throws CommandError (81) when empty or ambiguous, (83) when nothing matches
+ */
+export declare function selectFrame(frames: DomFrame[], query: string): DomFrame;
+/**
+ * Build a CommandError from a message and suggestion.
+ *
+ * @param err - Message and suggestion
+ * @param exitCode - Exit code
+ * @returns The error
+ */
+export declare function frameError(err: {
+    message: string;
+    suggestion: string;
+}, exitCode: number): CommandError;
+//# sourceMappingURL=frameSelection.d.ts.map

package/dist/runtime/dom/frameSelection.js

@@ -0,0 +1,66 @@
+/**
+ * Which iframe a `bdg dom eval --frame` value names.
+ */
+import { CommandError } from '../../errors/index.js';
+import { ambiguousFrameError, emptyFrameError, frameNotFoundError } from '../../errors/messages.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Pick the frame a `--frame` value names: a 0-based index, an exact `name`
+ * or `id` attribute, or else a case-insensitive part of the URL.
+ *
+ * @param frames - Frames of the page
+ * @param query - Requested frame
+ * @returns The matching frame
+ * @throws CommandError (81) when empty or ambiguous, (83) when nothing matches
+ */
+export function selectFrame(frames, query) {
+    const wanted = query.trim();
+    if (!wanted)
+        throw frameError(emptyFrameError(), EXIT_CODES.INVALID_ARGUMENTS);
+    return single(frames, wanted, candidatesFor(frames, wanted));
+}
+/**
+ * Frames a non-empty `--frame` value matches, by the first rule that applies.
+ *
+ * @param frames - Frames of the page
+ * @param wanted - Requested frame, trimmed
+ * @returns Matching frames
+ */
+function candidatesFor(frames, wanted) {
+    if (/^\d+$/.test(wanted))
+        return frames.filter((frame) => frame.index === Number(wanted));
+    const named = frames.filter((frame) => frame.name === wanted || frame.id === wanted);
+    if (named.length > 0)
+        return named;
+    const needle = wanted.toLowerCase();
+    return frames.filter((frame) => frame.url.toLowerCase().includes(needle));
+}
+/**
+ * The only candidate, or an error listing the frames.
+ *
+ * @param frames - All frames (listed when nothing matches)
+ * @param query - Requested frame
+ * @param candidates - Matching frames
+ * @returns The candidate
+ * @throws CommandError (81) for several candidates, (83) for none
+ */
+function single(frames, query, candidates) {
+    const [first] = candidates;
+    if (candidates.length > 1) {
+        throw frameError(ambiguousFrameError(query, candidates), EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (!first)
+        throw frameError(frameNotFoundError(query, frames), EXIT_CODES.RESOURCE_NOT_FOUND);
+    return first;
+}
+/**
+ * Build a CommandError from a message and suggestion.
+ *
+ * @param err - Message and suggestion
+ * @param exitCode - Exit code
+ * @returns The error
+ */
+export function frameError(err, exitCode) {
+    return new CommandError(err.message, { suggestion: err.suggestion }, exitCode);
+}
+//# sourceMappingURL=frameSelection.js.map

package/dist/runtime/dom/frames.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Iframes of the page for `bdg dom frames` and `bdg dom eval --frame`.
+ *
+ * Works on a short-lived second connection to the page target, so enabling
+ * Runtime (which replays the page's console messages) and attaching to
+ * out-of-process iframes never reach the session's collectors. In-process
+ * frames come from the page's frame tree; out-of-process (cross-site) frames
+ * from flattened auto-attach, each with its own session and frame tree.
+ * Execution context ids are shared by all sessions of a renderer, so a
+ * frame's default (main-world) context is found by enabling Runtime.
+ *
+ * A frame kept busy by its own scripts is recovered through the session's
+ * connection: a session attached while the target is busy gets no answer at
+ * all, not even to `Runtime.terminateExecution`.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import type { DomEvalData, DomFrame } from '../../ipc/protocol/commands.js';
+/**
+ * List the page's iframes.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @returns Iframes in listing order
+ */
+export declare function listFrames(page: CDPConnection, wsUrl: string): Promise<DomFrame[]>;
+/**
+ * Evaluate a `bdg dom eval` script in one iframe, like {@link evaluateScript}
+ * does in the page.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @param script - JavaScript expression
+ * @param query - Requested frame (index, name/id attribute, or part of the URL)
+ * @returns Value, type and the frame's URL
+ * @throws CommandError (81/83) when the frame is ambiguous or missing, else as evaluateScript
+ */
+export declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string): Promise<DomEvalData>;
+//# sourceMappingURL=frames.d.ts.map

package/dist/runtime/dom/frames.js

@@ -0,0 +1,305 @@
+/**
+ * Iframes of the page for `bdg dom frames` and `bdg dom eval --frame`.
+ *
+ * Works on a short-lived second connection to the page target, so enabling
+ * Runtime (which replays the page's console messages) and attaching to
+ * out-of-process iframes never reach the session's collectors. In-process
+ * frames come from the page's frame tree; out-of-process (cross-site) frames
+ * from flattened auto-attach, each with its own session and frame tree.
+ * Execution context ids are shared by all sessions of a renderer, so a
+ * frame's default (main-world) context is found by enabling Runtime.
+ *
+ * A frame kept busy by its own scripts is recovered through the session's
+ * connection: a session attached while the target is busy gets no answer at
+ * all, not even to `Runtime.terminateExecution`.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import { frameNotReadyError } from '../../errors/messages.js';
+import { evaluateScript, withBusyPageRecovery } from './evalHelpers.js';
+import { frameError, selectFrame } from './frameSelection.js';
+import { attachedSessionOf } from '../../telemetry/attachedTargets.js';
+import { senderFor } from '../../telemetry/objectExpander.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+const log = createLogger('dom');
+/** Auto-attach without pausing new targets: only existing frames are needed */
+const AUTO_ATTACH = { autoAttach: true, waitForDebuggerOnStart: false, flatten: true };
+/**
+ * Run `work` on a second connection to the page, closed afterwards.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @param work - What to do with the connection
+ * @returns The work's result
+ */
+async function withFrameConnection(page, wsUrl, work) {
+    const conn = await CDPConnection.create(wsUrl, { maxRetries: 1, logger: log });
+    try {
+        return await work({ conn, page, targets: new Map() });
+    }
+    finally {
+        conn.close();
+    }
+}
+/**
+ * Where to check and recover a session's target when it does not answer:
+ * the session's connection (page, or its attached session for the target).
+ *
+ * @param fc - Frame connection
+ * @param sessionId - Session on the second connection, undefined for the page
+ * @returns Sender to the same target
+ */
+function recoverySender(fc, sessionId) {
+    if (!sessionId)
+        return fc.page;
+    const targetId = fc.targets.get(sessionId);
+    const attached = targetId === undefined ? undefined : attachedSessionOf(fc.page, targetId);
+    return senderFor(attached ? fc.page : fc.conn, attached ?? sessionId);
+}
+/**
+ * Send a command to one session, recovering its target when its scripts
+ * keep it busy.
+ *
+ * @param fc - Frame connection
+ * @param method - CDP method
+ * @param params - Parameters
+ * @param sessionId - Session, undefined for the page
+ * @returns The result
+ * @throws CommandError (102) when the target was busy
+ */
+async function sendToSession(fc, method, params, sessionId) {
+    const command = fc.conn.send(method, params, sessionId);
+    return (await withBusyPageRecovery(recoverySender(fc, sessionId), command));
+}
+/**
+ * Frame tree of a session.
+ *
+ * @param fc - Frame connection
+ * @param sessionId - Session, undefined for the page
+ * @returns The tree
+ */
+async function frameTree(fc, sessionId) {
+    const { frameTree: tree } = await sendToSession(fc, 'Page.getFrameTree', {}, sessionId);
+    return { tree, ...(sessionId && { sessionId }) };
+}
+/**
+ * Attach to the out-of-process iframes directly below a session. Chrome
+ * reports the existing ones before answering `Target.setAutoAttach`.
+ *
+ * @param fc - Frame connection (records each session's target)
+ * @param parentSession - Session to attach below, undefined for the page
+ * @returns Their sessions
+ */
+async function attachChildFrames(fc, parentSession) {
+    const sessions = [];
+    const stop = fc.conn.on('Target.attachedToTarget', ({ sessionId, targetInfo }, eventSession) => {
+        if (eventSession !== parentSession || targetInfo.type !== 'iframe')
+            return;
+        fc.targets.set(sessionId, targetInfo.targetId);
+        sessions.push(sessionId);
+    });
+    try {
+        await fc.conn.send('Target.setAutoAttach', AUTO_ATTACH, parentSession);
+    }
+    finally {
+        stop();
+    }
+    return sessions;
+}
+/**
+ * Frame trees of the out-of-process iframes below a session, nested ones included.
+ *
+ * @param fc - Frame connection
+ * @param parentSession - Session to attach below, undefined for the page
+ * @returns Their trees
+ */
+async function outOfProcessTrees(fc, parentSession) {
+    const sessions = await attachChildFrames(fc, parentSession);
+    const nested = await Promise.all(sessions.map(async (sessionId) => [
+        await frameTree(fc, sessionId),
+        ...(await outOfProcessTrees(fc, sessionId)),
+    ]));
+    return nested.flat();
+}
+/**
+ * All frames of the trees, each with its session.
+ *
+ * @param trees - Frame trees
+ * @returns Frames in tree order
+ */
+function flattenTrees(trees) {
+    const nodes = [];
+    const walk = (tree, sessionId) => {
+        nodes.push({ frame: tree.frame, ...(sessionId && { sessionId }) });
+        tree.childFrames?.forEach((child) => walk(child, sessionId));
+    };
+    trees.forEach(({ tree, sessionId }) => walk(tree, sessionId));
+    return nodes;
+}
+/**
+ * Iframes below the main frame, depth-first.
+ *
+ * @param nodes - All frames
+ * @param mainFrameId - The page's main frame
+ * @returns Iframes in listing order
+ */
+function iframesInOrder(nodes, mainFrameId) {
+    const ordered = [];
+    const visit = (parentId) => {
+        for (const node of nodes.filter((n) => n.frame.parentId === parentId)) {
+            ordered.push(node);
+            visit(node.frame.id);
+        }
+    };
+    visit(mainFrameId);
+    return ordered;
+}
+/**
+ * Value of an attribute in CDP's flat `[name, value, name, value, ...]` list.
+ *
+ * @param attributes - Attribute list
+ * @param key - Attribute name
+ * @returns Its value, undefined when missing
+ */
+function attributeValue(attributes = [], key) {
+    for (let i = 0; i < attributes.length; i += 2) {
+        if (attributes[i] === key)
+            return attributes[i + 1];
+    }
+    return undefined;
+}
+/**
+ * Attributes of the iframe element of a frame (read in its parent's session).
+ *
+ * @param fc - Frame connection
+ * @param frameId - Frame
+ * @param ownerSession - Session of the parent frame
+ * @returns `name` and `id` attributes when set
+ */
+async function ownerAttributes(fc, frameId, ownerSession) {
+    try {
+        const { backendNodeId } = await sendToSession(fc, 'DOM.getFrameOwner', { frameId }, ownerSession);
+        const { node } = await sendToSession(fc, 'DOM.describeNode', { backendNodeId }, ownerSession);
+        const name = attributeValue(node.attributes, 'name');
+        const id = attributeValue(node.attributes, 'id');
+        return { ...(name && { name }), ...(id && { id }) };
+    }
+    catch (error) {
+        log.debug(`No iframe element for frame ${frameId}: ${getErrorMessage(error)}`);
+        return {};
+    }
+}
+/**
+ * Describe an iframe for listing. Chrome names a frame after its element's
+ * `id` when it has no `name`, so such a name is not repeated.
+ *
+ * @param fc - Frame connection
+ * @param node - The frame
+ * @param index - Its position
+ * @param context - The page's origin and the session of each frame
+ * @returns The located frame
+ */
+async function locateFrame(fc, node, index, context) {
+    const { frame, sessionId } = node;
+    const owner = await ownerAttributes(fc, frame.id, context.sessionOf.get(frame.parentId ?? ''));
+    const name = owner.name ?? (frame.name === owner.id ? undefined : frame.name);
+    const info = {
+        index,
+        url: frame.url + (frame.urlFragment ?? ''),
+        ...(name && { name }),
+        ...(owner.id && { id: owner.id }),
+        origin: frame.securityOrigin,
+        crossOrigin: frame.securityOrigin !== context.topOrigin,
+        outOfProcess: sessionId !== undefined,
+    };
+    return { info, frameId: frame.id, ...(sessionId && { sessionId }) };
+}
+/**
+ * Find every iframe of the page, nested and out-of-process ones included.
+ *
+ * @param fc - Frame connection
+ * @returns Iframes in listing order
+ */
+async function discoverFrames(fc) {
+    const [page, outOfProcess] = await Promise.all([frameTree(fc), outOfProcessTrees(fc)]);
+    const nodes = flattenTrees([page, ...outOfProcess]);
+    const sessionOf = new Map(nodes.map((node) => [node.frame.id, node.sessionId]));
+    const context = { topOrigin: page.tree.frame.securityOrigin, sessionOf };
+    const iframes = iframesInOrder(nodes, page.tree.frame.id);
+    return Promise.all(iframes.map((node, index) => locateFrame(fc, node, index, context)));
+}
+/**
+ * The default (main-world) execution context of a frame, so the script sees
+ * the frame's own globals.
+ *
+ * @param fc - Frame connection
+ * @param frame - The frame
+ * @returns The context's unique id
+ * @throws CommandError (83) when the frame has no context yet
+ */
+async function defaultContext(fc, frame) {
+    const contexts = [];
+    const stop = fc.conn.on('Runtime.executionContextCreated', ({ context }, sessionId) => {
+        if (sessionId === frame.sessionId)
+            contexts.push(context);
+    });
+    try {
+        await sendToSession(fc, 'Runtime.enable', {}, frame.sessionId);
+    }
+    finally {
+        stop();
+    }
+    const auxData = (c) => (c.auxData ?? {});
+    const context = contexts.find((c) => auxData(c)['frameId'] === frame.frameId && auxData(c)['isDefault']);
+    if (!context)
+        throw frameError(frameNotReadyError(frame.info.url), EXIT_CODES.RESOURCE_NOT_FOUND);
+    return context.uniqueId;
+}
+/**
+ * List the page's iframes.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @returns Iframes in listing order
+ */
+export async function listFrames(page, wsUrl) {
+    const frames = await withFrameConnection(page, wsUrl, discoverFrames);
+    return frames.map((frame) => frame.info);
+}
+/**
+ * Find the requested frame and its default execution context.
+ *
+ * @param fc - Frame connection
+ * @param query - Requested frame
+ * @returns The frame and its context's unique id
+ * @throws CommandError (81/83) when the frame is ambiguous, missing or has no context
+ */
+async function resolveFrame(fc, query) {
+    const frames = await discoverFrames(fc);
+    const selected = selectFrame(frames.map((frame) => frame.info), query);
+    const frame = frames[selected.index];
+    return { frame, uniqueContextId: await defaultContext(fc, frame) };
+}
+/**
+ * Evaluate a `bdg dom eval` script in one iframe, like {@link evaluateScript}
+ * does in the page.
+ *
+ * @param page - The session's connection
+ * @param wsUrl - WebSocket URL of the page target
+ * @param script - JavaScript expression
+ * @param query - Requested frame (index, name/id attribute, or part of the URL)
+ * @returns Value, type and the frame's URL
+ * @throws CommandError (81/83) when the frame is ambiguous or missing, else as evaluateScript
+ */
+export async function evaluateInFrame(page, wsUrl, script, query) {
+    return withFrameConnection(page, wsUrl, async (fc) => {
+        const { frame, uniqueContextId } = await resolveFrame(fc, query);
+        const result = await evaluateScript(fc.conn, script, {
+            ...(frame.sessionId && { sessionId: frame.sessionId }),
+            uniqueContextId,
+        });
+        return { ...result, frame: frame.info.url };
+    });
+}
+//# sourceMappingURL=frames.js.map

package/dist/runtime/dom/keyMapping.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Key name to CDP key event parameters mapping.
+ *
+ * Maps human-readable key names to Chrome DevTools Protocol Input.dispatchKeyEvent parameters.
+ */
+/**
+ * CDP key event parameters for a specific key.
+ */
+export interface KeyDefinition {
+    /** Physical key code (e.g., "Enter", "KeyA") */
+    code: string;
+    /** Logical key value (e.g., "Enter", "a") */
+    key: string;
+    /** Windows virtual key code */
+    keyCode: number;
+    /** Text the key types (letters, digits, space, Enter); absent for non-text keys */
+    text?: string;
+    /** Text typed with Shift on a US layout, when it is not just the uppercased `text` */
+    shiftText?: string;
+}
+/**
+ * Modifier key bit flags for CDP Input.dispatchKeyEvent
+ * (Alt=1, Ctrl=2, Meta/Command=4, Shift=8).
+ */
+export declare const MODIFIER_FLAGS: {
+    readonly alt: 1;
+    readonly ctrl: 2;
+    readonly meta: 4;
+    readonly shift: 8;
+};
+/**
+ * Get key definition by name (case-insensitive).
+ *
+ * @param keyName - Human-readable key name (e.g., "Enter", "Tab", "a")
+ * @returns Key definition or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const def = getKeyDefinition('Enter');
+ * // { code: 'Enter', key: 'Enter', keyCode: 13 }
+ *
+ * const letterDef = getKeyDefinition('a');
+ * // { code: 'KeyA', key: 'a', keyCode: 65 }
+ * ```
+ */
+export declare function getKeyDefinition(keyName: string): KeyDefinition | undefined;
+/**
+ * Whether a key name needs Shift to produce it (an uppercase letter, or a
+ * symbol on a digit key such as "!").
+ *
+ * @param keyName - Key name as given
+ * @returns True if Shift is implied
+ */
+export declare function impliesShift(keyName: string): boolean;
+/**
+ * Key names closest to an unknown one.
+ *
+ * @param keyName - Unknown key name
+ * @returns Up to three key names, in their usual spelling
+ */
+export declare function similarKeyNames(keyName: string): string[];
+/**
+ * Names in a modifier list that are not recognized.
+ *
+ * @param modifiers - Comma-separated modifier names
+ * @returns Unknown names (empty when all are valid)
+ */
+export declare function findUnknownModifiers(modifiers: string): string[];
+/**
+ * Parse modifier string into CDP modifier flags.
+ *
+ * @param modifiers - Comma-separated modifier names (e.g., "ctrl,shift"; aliases cmd, control, option)
+ * @returns Combined modifier bit flags
+ *
+ * @example
+ * ```typescript
+ * parseModifiers('ctrl,shift'); // Returns 10 (2 + 8)
+ * parseModifiers('cmd');        // Returns 4
+ * parseModifiers('');           // Returns 0
+ * ```
+ */
+export declare function parseModifiers(modifiers: string | undefined): number;
+/**
+ * Human-readable names of set modifier flags.
+ *
+ * @param flags - CDP modifier bit flags
+ * @returns e.g. ["Ctrl", "Shift"]
+ */
+export declare function describeModifiers(flags: number): string[];
+/**
+ * Editor commands a key press triggers, like a physical keyboard does.
+ *
+ * Chrome only runs shortcuts such as Ctrl+A (Cmd+A on macOS) for events it
+ * gets from the OS; for CDP key events the command has to be named. Either
+ * Ctrl or Meta works, so scripts behave the same on every platform; Shift+Z
+ * redoes.
+ *
+ * @param code - Key code, e.g. "KeyA"
+ * @param flags - CDP modifier bit flags
+ * @returns Editor commands for `Input.dispatchKeyEvent`, empty if none
+ */
+export declare function shortcutCommands(code: string, flags: number): string[];
+//# sourceMappingURL=keyMapping.d.ts.map