@ticktockbent/charlotte 0.6.0 → 0.6.1

package/dist/state/snapshot-store.js

@@ -5,9 +5,13 @@ const MAX_DEPTH = 500;
  * Ring-buffer store for page snapshots. Snapshots have monotonically
  * increasing integer IDs and are evicted oldest-first when the buffer
  * reaches its configured depth.
+ *
+ * A secondary Map index provides O(1) lookup by snapshot ID alongside
+ * the ring buffer used for ordered access (latest, previous, oldest).
  */
 export class SnapshotStore {
     buffer = [];
+    index = new Map();
     nextSnapshotId = 1;
     maxDepth;
     constructor(depth = DEFAULT_DEPTH) {
@@ -29,9 +33,13 @@ export class SnapshotStore {
             representation,
         };
         this.buffer.push(snapshot);
+        this.index.set(snapshotId, snapshot);
         // Evict oldest if over capacity
         while (this.buffer.length > this.maxDepth) {
-            this.buffer.shift();
+            const evicted = this.buffer.shift();
+            if (evicted !== undefined) {
+                this.index.delete(evicted.id);
+            }
         }
         return snapshotId;
     }
@@ -39,7 +47,7 @@ export class SnapshotStore {
      * Retrieve a snapshot by its ID. Returns null if evicted or never existed.
      */
     get(snapshotId) {
-        return this.buffer.find((snapshot) => snapshot.id === snapshotId) ?? null;
+        return this.index.get(snapshotId) ?? null;
     }
     /**
      * Get the most recent snapshot, or null if the store is empty.
@@ -84,7 +92,10 @@ export class SnapshotStore {
     setDepth(newDepth) {
         this.maxDepth = Math.max(MIN_DEPTH, Math.min(MAX_DEPTH, newDepth));
         while (this.buffer.length > this.maxDepth) {
-            this.buffer.shift();
+            const evicted = this.buffer.shift();
+            if (evicted !== undefined) {
+                this.index.delete(evicted.id);
+            }
         }
     }
     /**
@@ -92,6 +103,7 @@ export class SnapshotStore {
      */
     clear() {
         this.buffer = [];
+        this.index.clear();
         this.nextSnapshotId = 1;
     }
 }

package/dist/state/snapshot-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot-store.js","sourceRoot":"","sources":["../../src/state/snapshot-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"snapshot-store.js","sourceRoot":"","sources":["../../src/state/snapshot-store.ts"],"names":[],"mappings":"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"}

package/dist/tools/dev-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-mode.d.ts","sourceRoot":"","sources":["../../src/tools/dev-mode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAIzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,gBAAgB,GACrB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAqMhC"}
+{"version":3,"file":"dev-mode.d.ts","sourceRoot":"","sources":["../../src/tools/dev-mode.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAIzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAS1D,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,gBAAgB,GACrB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAqMhC"}

package/dist/tools/dev-mode.js

@@ -4,11 +4,11 @@ import * as path from "node:path";
 import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
 import { logger } from "../utils/logger.js";
 import { Auditor } from "../dev/auditor.js";
-import { renderActivePage, renderAfterAction, formatPageResponse, handleToolError, } from "./tool-helpers.js";
+import { ensureReady, renderActivePage, renderAfterAction, formatPageResponse, handleToolError, } from "./tool-helpers.js";
 export function registerDevModeTools(server, deps) {
     const tools = {};
-    // ─── charlotte:dev_serve ───
-    tools["charlotte:dev_serve"] = server.registerTool("charlotte:dev_serve", {
+    // ─── charlotte_dev_serve ───
+    tools["charlotte_dev_serve"] = server.registerTool("charlotte_dev_serve", {
         description: "Serve a local directory as a static website and optionally watch for file changes. Navigates to the served URL and returns the page representation. File changes trigger automatic reloads and surface as reload_event on the next tool response.",
         inputSchema: {
             path: z.string().describe("Local directory to serve"),
@@ -17,7 +17,7 @@ export function registerDevModeTools(server, deps) {
         },
     }, async ({ path: directoryPath, port, watch }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             if (!deps.devModeState) {
                 throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Dev mode is not available.", "DevModeState was not initialized.");
             }
@@ -72,8 +72,8 @@ export function registerDevModeTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:dev_inject ───
-    tools["charlotte:dev_inject"] = server.registerTool("charlotte:dev_inject", {
+    // ─── charlotte_dev_inject ───
+    tools["charlotte_dev_inject"] = server.registerTool("charlotte_dev_inject", {
         description: "Inject CSS or JavaScript into the current page for testing modifications without editing files. Returns the page representation with a delta showing changes.",
         inputSchema: {
             css: z.string().optional().describe("CSS to inject into the page"),
@@ -81,7 +81,7 @@ export function registerDevModeTools(server, deps) {
         },
     }, async ({ css, js }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             if (!css && !js) {
                 throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "At least one of 'css' or 'js' must be provided.", "Provide CSS to inject, JS to execute, or both.");
             }
@@ -107,8 +107,8 @@ export function registerDevModeTools(server, deps) {
             return handleToolError(error);
         }
     });
-    // ─── charlotte:dev_audit ───
-    tools["charlotte:dev_audit"] = server.registerTool("charlotte:dev_audit", {
+    // ─── charlotte_dev_audit ───
+    tools["charlotte_dev_audit"] = server.registerTool("charlotte_dev_audit", {
         description: "Run accessibility and quality audits on the current page. Returns findings with severity levels and actionable recommendations.",
         inputSchema: {
             checks: z
@@ -118,7 +118,7 @@ export function registerDevModeTools(server, deps) {
         },
     }, async ({ checks }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const page = deps.pageManager.getActivePage();
             const session = await page.createCDPSession();
             const auditor = new Auditor();

package/dist/tools/dev-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev-mode.js","sourceRoot":"","sources":["../../src/tools/dev-mode.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dev-mode.js","sourceRoot":"","sources":["../../src/tools/dev-mode.ts"],"names":[],"mappings":"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"}

package/dist/tools/dialog.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
 import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
 import { logger } from "../utils/logger.js";
-import { renderAfterAction, stripEmptyFields, handleToolError } from "./tool-helpers.js";
+import { ensureReady, renderAfterAction, stripEmptyFields, handleToolError } from "./tool-helpers.js";
 export function registerDialogTools(server, deps) {
     const tools = {};
-    // ─── charlotte:dialog ───
-    tools["charlotte:dialog"] = server.registerTool("charlotte:dialog", {
+    // ─── charlotte_dialog ───
+    tools["charlotte_dialog"] = server.registerTool("charlotte_dialog", {
         description: "Handle a pending JavaScript dialog (alert, confirm, prompt, beforeunload). Accept or dismiss the dialog. Returns page representation after the dialog is resolved.",
         inputSchema: {
             accept: z.boolean().describe("true to accept/OK the dialog, false to dismiss/Cancel"),
@@ -16,11 +16,11 @@ export function registerDialogTools(server, deps) {
         },
     }, async ({ accept, prompt_text }) => {
         try {
-            await deps.browserManager.ensureConnected();
+            await ensureReady(deps);
             const pendingDialog = deps.pageManager.getPendingDialog();
             const pendingDialogInfo = deps.pageManager.getPendingDialogInfo();
             if (!pendingDialog || !pendingDialogInfo) {
-                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "No pending dialog to handle.", "Call charlotte:observe to check page state. Dialogs appear as pending_dialog in the response.");
+                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "No pending dialog to handle.", "Call charlotte_observe to check page state. Dialogs appear as pending_dialog in the response.");
             }
             // Capture dialog info before clearing for the response metadata
             const dialogHandled = {

package/dist/tools/dialog.js.map

@@ -1 +1 @@
-{"version":3,"file":"dialog.js","sourceRoot":"","sources":["../../src/tools/dialog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzF,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,IAAsB;IAEtB,MAAM,KAAK,GAAmC,EAAE,CAAC;IAEjD,2BAA2B;IAC3B,KAAK,CAAC,kBAAkB,CAAC,GAAG,MAAM,CAAC,YAAY,CAC7C,kBAAkB,EAClB;QACE,WAAW,EACT,oKAAoK;QACtK,WAAW,EAAE;YACX,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;YACrF,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,sFAAsF,CACvF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,cAAc,CAAC,eAAe,EAAE,CAAC;YAE5C,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC;YAC1D,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC;YAElE,IAAI,CAAC,aAAa,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACzC,MAAM,IAAI,cAAc,CACtB,kBAAkB,CAAC,aAAa,EAChC,8BAA8B,EAC9B,+FAA+F,CAChG,CAAC;YACJ,CAAC;YAED,gEAAgE;YAChE,MAAM,aAAa,GAAG;gBACpB,IAAI,EAAE,iBAAiB,CAAC,IAAI;gBAC5B,OAAO,EAAE,iBAAiB,CAAC,OAAO;gBAClC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW;aAC1C,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;gBAC7B,IAAI,EAAE,iBAAiB,CAAC,IAAI;gBAC5B,MAAM;gBACN,WAAW;aACZ,CAAC,CAAC;YAEH,+BAA+B;YAC/B,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC1C,CAAC;iBAAM,CAAC;gBACN,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC;YAChC,CAAC;YAED,iCAAiC;YACjC,IAAI,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC;YAEtC,iDAAiD;YACjD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAErD,8CAA8C;YAC9C,MAAM,eAAe,GAAG;gBACtB,cAAc,EAAE,aAAa;gBAC7B,IAAI,EAAE,gBAAgB,CAAC,cAAc,CAAC;aACvC,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"dialog.js","sourceRoot":"","sources":["../../src/tools/dialog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAG5C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtG,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,IAAsB;IAEtB,MAAM,KAAK,GAAmC,EAAE,CAAC;IAEjD,2BAA2B;IAC3B,KAAK,CAAC,kBAAkB,CAAC,GAAG,MAAM,CAAC,YAAY,CAC7C,kBAAkB,EAClB;QACE,WAAW,EACT,oKAAoK;QACtK,WAAW,EAAE;YACX,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;YACrF,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,sFAAsF,CACvF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE;QAChC,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;YAExB,MAAM,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC;YAC1D,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC;YAElE,IAAI,CAAC,aAAa,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACzC,MAAM,IAAI,cAAc,CACtB,kBAAkB,CAAC,aAAa,EAChC,8BAA8B,EAC9B,+FAA+F,CAChG,CAAC;YACJ,CAAC;YAED,gEAAgE;YAChE,MAAM,aAAa,GAAG;gBACpB,IAAI,EAAE,iBAAiB,CAAC,IAAI;gBAC5B,OAAO,EAAE,iBAAiB,CAAC,OAAO;gBAClC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW;aAC1C,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE;gBAC7B,IAAI,EAAE,iBAAiB,CAAC,IAAI;gBAC5B,MAAM;gBACN,WAAW;aACZ,CAAC,CAAC;YAEH,+BAA+B;YAC/B,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC1C,CAAC;iBAAM,CAAC;gBACN,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC;YAChC,CAAC;YAED,iCAAiC;YACjC,IAAI,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC;YAEtC,iDAAiD;YACjD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;YAExD,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAErD,8CAA8C;YAC9C,MAAM,eAAe,GAAG;gBACtB,cAAc,EAAE,aAAa;gBAC7B,IAAI,EAAE,gBAAgB,CAAC,cAAc,CAAC;aACvC,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tools/evaluate.d.ts

@@ -3,7 +3,7 @@ import type { BrowserManager } from "../browser/browser-manager.js";
 import type { PageManager } from "../browser/page-manager.js";
 export interface EvaluateDeps {
     browserManager: BrowserManager;
-    pageManager?: PageManager;
+    pageManager: PageManager;
     getActivePage: () => import("puppeteer").Page;
 }
 export declare function registerEvaluateTools(server: McpServer, deps: EvaluateDeps): Record<string, RegisteredTool>;

package/dist/tools/evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/tools/evaluate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAI9D,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,aAAa,EAAE,MAAM,OAAO,WAAW,EAAE,IAAI,CAAC;CAC/C;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,YAAY,GACjB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAqHhC"}
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/tools/evaluate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAK9D,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,EAAE,MAAM,OAAO,WAAW,EAAE,IAAI,CAAC;CAC/C;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,YAAY,GACjB,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAqHhC"}

package/dist/tools/evaluate.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
 import { logger } from "../utils/logger.js";
+import { ensureReady } from "./tool-helpers.js";
 export function registerEvaluateTools(server, deps) {
     const tools = {};
-    tools["charlotte:evaluate"] = server.registerTool("charlotte:evaluate", {
+    tools["charlotte_evaluate"] = server.registerTool("charlotte_evaluate", {
         description: "Execute JavaScript in page context. Supports single expressions and multi-statement code. Returns the completion value of the last expression-statement.",
         inputSchema: {
             expression: z.string().describe("JS expression or multi-statement code to evaluate"),
@@ -14,7 +15,7 @@ export function registerEvaluateTools(server, deps) {
                 .describe("If the expression returns a Promise, await it before returning (default: true)"),
         },
     }, async ({ expression, timeout, await_promise }) => {
-        await deps.browserManager.ensureConnected();
+        await ensureReady(deps);
         const page = deps.getActivePage();
         const evaluationTimeout = timeout ?? 5000;
         const shouldAwaitPromise = await_promise ?? true;

package/dist/tools/evaluate.js.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/tools/evaluate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../../src/tools/evaluate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,IAAkB;IAElB,MAAM,KAAK,GAAmC,EAAE,CAAC;IAEjD,KAAK,CAAC,oBAAoB,CAAC,GAAG,MAAM,CAAC,YAAY,CAC/C,oBAAoB,EACpB;QACE,WAAW,EACT,0JAA0J;QAC5J,WAAW,EAAE;YACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YACpF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;YACnF,aAAa,EAAE,CAAC;iBACb,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CACP,gFAAgF,CACjF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE;QAC/C,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAElC,MAAM,iBAAiB,GAAG,OAAO,IAAI,IAAI,CAAC;QAC1C,MAAM,kBAAkB,GAAG,aAAa,IAAI,IAAI,CAAC;QAEjD,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBACpC,UAAU,CAAC,IAAI,CAAC,kBAAkB,EAAE;oBAClC,UAAU;oBACV,aAAa,EAAE,IAAI;oBACnB,YAAY,EAAE,kBAAkB;oBAChC,OAAO,EAAE,iBAAiB;iBAC3B,CAAC;gBACF,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,EAClC,iBAAiB,GAAG,GAAG,CACxB,CACF;aACF,CAAC,CAAC;YAEH,uBAAuB;YACvB,IAAI,UAAU,CAAC,gBAAgB,EAAE,CAAC;gBAChC,MAAM,gBAAgB,GACpB,UAAU,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW;oBAClD,UAAU,CAAC,gBAAgB,CAAC,IAAI;oBAChC,0BAA0B,CAAC;gBAC7B,MAAM,IAAI,cAAc,CACtB,kBAAkB,CAAC,gBAAgB,EACnC,qBAAqB,gBAAgB,EAAE,CACxC,CAAC;YACJ,CAAC;YAED,oCAAoC;YACpC,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC;YACvC,MAAM,MAAM,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;YAEnD,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;gBACpC,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;yBACzC;qBACF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1D,MAAM,YAAY,GAAG,IAAI,cAAc,CACrC,kBAAkB,CAAC,OAAO,EAC1B,kCAAkC,iBAAiB,kEAAkE,CACtH,CAAC;gBACF,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC;yBAChD;qBACF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;YACpD,MAAM,YAAY,GAAG,IAAI,cAAc,CACrC,kBAAkB,CAAC,aAAa,EAChC,qBAAqB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9E,CAAC;YACF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC;qBAChD;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,UAAU,CAAC,MAAM,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAS,qBAAqB,CAAC,YAM9B;IACC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,YAAY,CAAC;IAEtE,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACvC,CAAC;IAED,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,WAAW,IAAI,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAClE,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAC5C,OAAO,EAAE,KAAK,EAAE,WAAW,IAAI,QAAQ,EAAE,IAAI,EAAE,SAAS,IAAI,MAAM,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,WAAW,IAAI,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC5D,CAAC;IAED,qFAAqF;IACrF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,wCAAwC;IACxC,OAAO,EAAE,KAAK,EAAE,WAAW,IAAI,IAAI,SAAS,IAAI,IAAI,GAAG,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI,EAAE,CAAC;AACrF,CAAC"}

package/dist/tools/interaction-helpers.d.ts

@@ -0,0 +1,55 @@
+import type { Page, KeyInput } from "puppeteer";
+/** Maps short modifier names to Puppeteer KeyInput values. */
+export declare const MODIFIER_KEY_MAP: Record<string, KeyInput>;
+/**
+ * Click an element by backend node ID using CDP to get coordinates, then click at those coords.
+ */
+export declare function clickElementByBackendNodeId(page: Page, backendNodeId: number, clickType?: "left" | "right" | "double", modifiers?: Array<"ctrl" | "shift" | "alt" | "meta">): Promise<void>;
+/**
+ * Wait for any navigation triggered by an action, or fall back to a brief settle pause.
+ *
+ * Listens for the `framenavigated` CDP event to detect if a click caused navigation.
+ * If navigation is detected within `detectionWindowMs`, waits for the page load event
+ * (up to `loadTimeoutMs`). If no navigation fires, returns after `settleMs`.
+ *
+ * Also races against dialog events — if the action triggers a JavaScript dialog
+ * (alert, confirm, prompt, beforeunload), the action promise will block indefinitely.
+ * This function detects that and returns early so the caller can surface `pending_dialog`.
+ */
+export declare function waitForPossibleNavigation(page: Page, action: () => Promise<void>, { detectionWindowMs, loadTimeoutMs, settleMs }?: {
+    detectionWindowMs?: number | undefined;
+    loadTimeoutMs?: number | undefined;
+    settleMs?: number | undefined;
+}): Promise<void>;
+/**
+ * Focus an element by backend node ID using CDP.
+ */
+export declare function focusElementByBackendNodeId(page: Page, backendNodeId: number): Promise<void>;
+/**
+ * Hover over an element by backend node ID.
+ */
+export declare function hoverElementByBackendNodeId(page: Page, backendNodeId: number): Promise<void>;
+/**
+ * Drag one element to another using mouse primitives.
+ * Sequence: move to source → mousedown → move to target → mouseup
+ * Includes intermediate move steps and delays to ensure drag events fire reliably.
+ */
+export declare function dragElementToElement(page: Page, sourceBackendNodeId: number, targetBackendNodeId: number): Promise<void>;
+/**
+ * Type text into an input element. Uses CDP to focus, optionally clears, then types via keyboard.
+ */
+export declare function typeIntoElement(page: Page, backendNodeId: number, text: string, clearFirst: boolean, pressEnter: boolean, characterDelay?: number): Promise<void>;
+/**
+ * Select a value in a <select> element using CDP to set the value and dispatch change events.
+ */
+export declare function selectOptionByBackendNodeId(page: Page, backendNodeId: number, value: string): Promise<void>;
+/**
+ * Submit a form by backend node ID — calls form.submit() via CDP.
+ */
+export declare function submitFormByBackendNodeId(page: Page, backendNodeId: number): Promise<void>;
+/**
+ * Set files on a file input element using CDP DOM.setFileInputFiles.
+ * Validates that the target element is actually an <input type="file">.
+ */
+export declare function setFileInputFiles(page: Page, backendNodeId: number, filePaths: string[]): Promise<void>;
+//# sourceMappingURL=interaction-helpers.d.ts.map

package/dist/tools/interaction-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/interaction-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAIhD,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAKrD,CAAC;AAEF;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,EAC/C,SAAS,GAAE,KAAK,CAAC,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAM,GACvD,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC3B,EAAE,iBAAuB,EAAE,aAAqB,EAAE,QAAa,EAAE;;;;CAAK,GACrE,OAAO,CAAC,IAAI,CAAC,CAoEf;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAmCD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,mBAAmB,EAAE,MAAM,EAC3B,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,OAAO,EACnB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/tools/interaction-helpers.js

@@ -0,0 +1,312 @@
+import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
+import { logger } from "../utils/logger.js";
+/** Maps short modifier names to Puppeteer KeyInput values. */
+export const MODIFIER_KEY_MAP = {
+    ctrl: "Control",
+    shift: "Shift",
+    alt: "Alt",
+    meta: "Meta",
+};
+/**
+ * Click an element by backend node ID using CDP to get coordinates, then click at those coords.
+ */
+export async function clickElementByBackendNodeId(page, backendNodeId, clickType = "left", modifiers = []) {
+    // Get the element's box model to find clickable coordinates
+    const cdpSession = await page.createCDPSession();
+    try {
+        // First, scroll the element into view
+        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
+        // Get box model for coordinates
+        const { model } = await cdpSession.send("DOM.getBoxModel", {
+            backendNodeId,
+        });
+        if (!model) {
+            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model — it may be hidden or zero-sized.", "Call charlotte_observe to check the element's state.");
+        }
+        // content quad: [x1,y1, x2,y2, x3,y3, x4,y4]
+        const contentQuad = model.content;
+        const centerX = (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4;
+        const centerY = (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4;
+        // Hold down modifier keys before the click
+        for (const modifier of modifiers) {
+            const modifierKey = MODIFIER_KEY_MAP[modifier];
+            await page.keyboard.down(modifierKey);
+        }
+        try {
+            if (clickType === "right") {
+                await page.mouse.click(centerX, centerY, { button: "right" });
+            }
+            else if (clickType === "double") {
+                await page.mouse.click(centerX, centerY, { clickCount: 2 });
+            }
+            else {
+                await page.mouse.click(centerX, centerY);
+            }
+        }
+        finally {
+            // Release modifier keys in reverse order (always release even if click fails)
+            for (const modifier of [...modifiers].reverse()) {
+                const modifierKey = MODIFIER_KEY_MAP[modifier];
+                await page.keyboard.up(modifierKey);
+            }
+        }
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Wait for any navigation triggered by an action, or fall back to a brief settle pause.
+ *
+ * Listens for the `framenavigated` CDP event to detect if a click caused navigation.
+ * If navigation is detected within `detectionWindowMs`, waits for the page load event
+ * (up to `loadTimeoutMs`). If no navigation fires, returns after `settleMs`.
+ *
+ * Also races against dialog events — if the action triggers a JavaScript dialog
+ * (alert, confirm, prompt, beforeunload), the action promise will block indefinitely.
+ * This function detects that and returns early so the caller can surface `pending_dialog`.
+ */
+export async function waitForPossibleNavigation(page, action, { detectionWindowMs = 500, loadTimeoutMs = 10000, settleMs = 50 } = {}) {
+    let navigationDetected = false;
+    let dialogDetected = false;
+    // Listen for navigation start via page event (fires on any navigation)
+    const navigationStartPromise = new Promise((resolve) => {
+        const handler = () => {
+            navigationDetected = true;
+            page.off("framenavigated", handler);
+            resolve();
+        };
+        page.on("framenavigated", handler);
+        // Clean up listener if no navigation fires within detection window
+        setTimeout(() => {
+            page.off("framenavigated", handler);
+            resolve();
+        }, detectionWindowMs);
+    });
+    // Listen for dialog (blocks the action from completing)
+    const dialogPromise = new Promise((resolve) => {
+        const handler = () => {
+            dialogDetected = true;
+            page.off("dialog", handler);
+            resolve();
+        };
+        page.on("dialog", handler);
+        // Clean up on timeout — if no dialog fires, we don't need this listener
+        setTimeout(() => {
+            page.off("dialog", handler);
+            resolve();
+        }, detectionWindowMs);
+    });
+    // Race: action vs dialog
+    const actionPromise = action();
+    await Promise.race([
+        actionPromise.then(() => "action"),
+        dialogPromise.then(() => "dialog"),
+    ]);
+    if (dialogDetected) {
+        // Dialog is blocking the action. Don't await actionPromise — it will
+        // resolve later when the dialog is handled via charlotte_dialog.
+        // Guard against unhandled rejection from the fire-and-forget promise.
+        actionPromise.catch(() => {
+            logger.debug("Post-dialog action promise rejected (expected)");
+        });
+        return;
+    }
+    // Action completed normally — check for navigation
+    await navigationStartPromise;
+    if (navigationDetected) {
+        // Navigation occurred — wait for the page to finish loading
+        try {
+            await page.waitForNavigation({ waitUntil: "load", timeout: loadTimeoutMs });
+        }
+        catch {
+            // Page may have already finished loading before we called waitForNavigation,
+            // or the load timed out. Either way, render what we have.
+            logger.debug("Post-navigation load wait ended (page may already be loaded)");
+        }
+    }
+    else {
+        // No navigation — brief settle for in-page DOM updates
+        await new Promise((resolve) => setTimeout(resolve, settleMs));
+    }
+}
+/**
+ * Focus an element by backend node ID using CDP.
+ */
+export async function focusElementByBackendNodeId(page, backendNodeId) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        await cdpSession.send("DOM.focus", { backendNodeId });
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Hover over an element by backend node ID.
+ */
+export async function hoverElementByBackendNodeId(page, backendNodeId) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
+        const { model } = await cdpSession.send("DOM.getBoxModel", {
+            backendNodeId,
+        });
+        if (!model) {
+            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model for hover.");
+        }
+        const contentQuad = model.content;
+        const centerX = (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4;
+        const centerY = (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4;
+        await page.mouse.move(centerX, centerY);
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Get the center coordinates of an element by backend node ID.
+ * Scrolls the element into view first.
+ */
+async function getElementCenter(page, backendNodeId) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        await cdpSession.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
+        const { model } = await cdpSession.send("DOM.getBoxModel", {
+            backendNodeId,
+        });
+        if (!model) {
+            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Element has no visible box model — it may be hidden or zero-sized.", "Call charlotte_observe to check the element's state.");
+        }
+        const contentQuad = model.content;
+        return {
+            x: (contentQuad[0] + contentQuad[2] + contentQuad[4] + contentQuad[6]) / 4,
+            y: (contentQuad[1] + contentQuad[3] + contentQuad[5] + contentQuad[7]) / 4,
+        };
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Drag one element to another using mouse primitives.
+ * Sequence: move to source → mousedown → move to target → mouseup
+ * Includes intermediate move steps and delays to ensure drag events fire reliably.
+ */
+export async function dragElementToElement(page, sourceBackendNodeId, targetBackendNodeId) {
+    const sourceCenter = await getElementCenter(page, sourceBackendNodeId);
+    const targetCenter = await getElementCenter(page, targetBackendNodeId);
+    // Move to source and press down
+    await page.mouse.move(sourceCenter.x, sourceCenter.y);
+    await page.mouse.down();
+    // Intermediate move to trigger dragstart (some browsers need movement to begin a drag)
+    await page.mouse.move(sourceCenter.x + (targetCenter.x - sourceCenter.x) * 0.25, sourceCenter.y + (targetCenter.y - sourceCenter.y) * 0.25, { steps: 5 });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    // Move to target
+    await page.mouse.move(targetCenter.x, targetCenter.y, { steps: 10 });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    // Release
+    await page.mouse.up();
+}
+/**
+ * Type text into an input element. Uses CDP to focus, optionally clears, then types via keyboard.
+ */
+export async function typeIntoElement(page, backendNodeId, text, clearFirst, pressEnter, characterDelay) {
+    // Focus the element
+    await focusElementByBackendNodeId(page, backendNodeId);
+    if (clearFirst) {
+        // Select all text then delete — works cross-platform
+        await page.keyboard.down("Control");
+        await page.keyboard.press("a");
+        await page.keyboard.up("Control");
+        await page.keyboard.press("Backspace");
+    }
+    // Type the text — with optional per-character delay for sites with
+    // key-by-key event handlers (autocomplete, search-as-you-type, etc.)
+    await page.keyboard.type(text, characterDelay ? { delay: characterDelay } : undefined);
+    if (pressEnter) {
+        await page.keyboard.press("Enter");
+    }
+}
+/**
+ * Select a value in a <select> element using CDP to set the value and dispatch change events.
+ */
+export async function selectOptionByBackendNodeId(page, backendNodeId, value) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        // Resolve the node to get a remote object reference
+        const { object } = await cdpSession.send("DOM.resolveNode", {
+            backendNodeId,
+        });
+        if (!object?.objectId) {
+            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Could not resolve select element.");
+        }
+        // Use Runtime.callFunctionOn to set the value and fire events
+        await cdpSession.send("Runtime.callFunctionOn", {
+            objectId: object.objectId,
+            functionDeclaration: `function(targetValue) {
+        const options = Array.from(this.options);
+        const matchByValue = options.find(o => o.value === targetValue);
+        const matchByText = options.find(o => o.textContent.trim() === targetValue);
+        const match = matchByValue || matchByText;
+        if (match) {
+          this.value = match.value;
+          this.dispatchEvent(new Event('input', { bubbles: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true }));
+        } else {
+          throw new Error('Option "' + targetValue + '" not found');
+        }
+      }`,
+            arguments: [{ value }],
+        });
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Submit a form by backend node ID — calls form.submit() via CDP.
+ */
+export async function submitFormByBackendNodeId(page, backendNodeId) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        const { object } = await cdpSession.send("DOM.resolveNode", {
+            backendNodeId,
+        });
+        if (!object?.objectId) {
+            throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, "Could not resolve form element.");
+        }
+        await cdpSession.send("Runtime.callFunctionOn", {
+            objectId: object.objectId,
+            functionDeclaration: `function() {
+        this.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+      }`,
+        });
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+/**
+ * Set files on a file input element using CDP DOM.setFileInputFiles.
+ * Validates that the target element is actually an <input type="file">.
+ */
+export async function setFileInputFiles(page, backendNodeId, filePaths) {
+    const cdpSession = await page.createCDPSession();
+    try {
+        const { node } = await cdpSession.send("DOM.describeNode", { backendNodeId });
+        const isFileInput = node.nodeName === "INPUT" &&
+            (node.attributes ?? []).some((attr, i, arr) => attr === "type" && arr[i + 1] === "file");
+        if (!isFileInput) {
+            throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Element is not a file input.", "Use charlotte_find to locate file_input elements.");
+        }
+        await cdpSession.send("DOM.setFileInputFiles", {
+            files: filePaths,
+            backendNodeId,
+        });
+    }
+    finally {
+        await cdpSession.detach();
+    }
+}
+//# sourceMappingURL=interaction-helpers.js.map