@ticktockbent/charlotte 0.4.1 → 0.5.0

package/dist/tools/tool-helpers.js

@@ -1,5 +1,15 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
 import { CharlotteError, CharlotteErrorCode } from "../types/errors.js";
 import { diffRepresentations } from "../state/differ.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Boolean schema that accepts both native booleans and string representations
+ * ("true"/"false"). Some MCP clients send boolean parameters as strings,
+ * causing Zod validation to reject them. This handles the coercion.
+ */
+export const coercedBoolean = z.preprocess((val) => (val === "true" ? true : val === "false" ? false : val), z.boolean());
 /**
  * Render the active page, attach console/network errors, and optionally
  * push a snapshot to the store.
@@ -68,13 +78,15 @@ export async function resolveElement(deps, elementId) {
     // Step 1: Check current map
     let backendNodeId = deps.elementIdGenerator.resolveId(elementId);
     if (backendNodeId !== null) {
-        return { page, backendNodeId };
+        const frameId = deps.elementIdGenerator.resolveFrame(elementId);
+        return { page, backendNodeId, frameId };
     }
     // Step 2: Re-render and check again (map was invalidated)
     const freshRepresentation = await renderActivePage(deps, { detail: "minimal" });
     backendNodeId = deps.elementIdGenerator.resolveId(elementId);
     if (backendNodeId !== null) {
-        return { page, backendNodeId };
+        const frameId = deps.elementIdGenerator.resolveFrame(elementId);
+        return { page, backendNodeId, frameId };
     }
     // Step 3: Element is genuinely gone — suggest similar
     const similar = deps.elementIdGenerator.findSimilar(elementId, freshRepresentation.interactive);
@@ -83,6 +95,23 @@ export async function resolveElement(deps, elementId) {
         : `Element '${elementId}' not found. Call charlotte:observe to get current page state.`;
     throw new CharlotteError(CharlotteErrorCode.ELEMENT_NOT_FOUND, `Element '${elementId}' not found on page.`, suggestion);
 }
+/**
+ * Get the appropriate CDP session for an element.
+ * Returns the frame-specific session for iframe elements, or the main page session.
+ */
+export async function getSessionForElement(deps, resolved) {
+    if (resolved.frameId) {
+        // Find the frame by ID and get its session
+        const allFrames = resolved.page.frames();
+        const targetFrame = allFrames.find((f) => deps.cdpSessionManager.getFrameId(f) === resolved.frameId);
+        if (targetFrame) {
+            return deps.cdpSessionManager.getFrameSession(targetFrame);
+        }
+        // Fallback to main session if frame not found (frame may have navigated away)
+        logger.warn(`Frame ${resolved.frameId} not found, falling back to main session`);
+    }
+    return deps.cdpSessionManager.getSession(resolved.page);
+}
 /**
  * Render after an interaction action and attach a delta diff.
  * Captures the pre-action snapshot (latest in store), renders post-action
@@ -142,6 +171,10 @@ export function stripEmptyFields(representation) {
         }
         cleaned.structure = structure;
     }
+    // Strip empty iframes
+    if (!representation.iframes || representation.iframes.length === 0) {
+        delete cleaned.iframes;
+    }
     // Strip absent pending_dialog
     if (!cleaned.pending_dialog) {
         delete cleaned.pending_dialog;
@@ -201,4 +234,71 @@ export function handleToolError(error) {
     const sessionError = new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
     return formatErrorResponse(sessionError);
 }
+/**
+ * Resolve an output file path from the `output_file` parameter.
+ * If the path is relative, it is resolved against `config.outputDir`
+ * (or cwd if outputDir is not set). Ensures the parent directory exists.
+ *
+ * Security: the resolved path must fall within `outputDir` (or
+ * `allowedWorkspaceRoot` when outputDir is unset). Symlinks are
+ * resolved after mkdir to catch traversal via symlinked parents.
+ */
+export async function resolveOutputPath(outputFile, config) {
+    const baseDir = config.outputDir ?? config.allowedWorkspaceRoot ?? process.cwd();
+    const resolved = path.isAbsolute(outputFile)
+        ? outputFile
+        : path.resolve(baseDir, outputFile);
+    // Normalize the path (resolve . and .. segments) without touching the filesystem.
+    // This catches obvious traversal attempts before any side effects (mkdir).
+    const normalized = path.resolve(resolved);
+    if (!normalized.startsWith(baseDir + path.sep) && normalized !== baseDir) {
+        throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Output path '${outputFile}' resolves outside the allowed directory '${baseDir}'.`, "Use a relative path or configure output_dir to an appropriate directory.");
+    }
+    // Ensure baseDir exists (may not have been created yet when set via --output-dir)
+    await fs.mkdir(baseDir, { recursive: true });
+    // Ensure parent directory exists (safe — we validated it's within baseDir)
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    // Resolve symlinks to get the real path and catch symlink-based traversal
+    const realParent = await fs.realpath(path.dirname(resolved));
+    const realResolved = path.join(realParent, path.basename(resolved));
+    const realBase = await fs.realpath(baseDir);
+    if (!realResolved.startsWith(realBase + path.sep) && realResolved !== realBase) {
+        throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Output path '${outputFile}' resolves outside the allowed directory '${baseDir}'.`, "Use a relative path or configure output_dir to an appropriate directory.");
+    }
+    return realResolved;
+}
+/**
+ * Write text content to a file and return a brief confirmation response.
+ */
+export async function writeOutputFile(filePath, content) {
+    await fs.writeFile(filePath, content, "utf-8");
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    output_file: filePath,
+                    size: Buffer.byteLength(content, "utf-8"),
+                }),
+            },
+        ],
+    };
+}
+/**
+ * Write binary content to a file and return a brief confirmation response.
+ */
+export async function writeBinaryOutputFile(filePath, data) {
+    await fs.writeFile(filePath, data);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    output_file: filePath,
+                    size: data.length,
+                }),
+            },
+        ],
+    };
+}
 //# sourceMappingURL=tool-helpers.js.map

package/dist/tools/tool-helpers.js.map

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

package/dist/types/config.d.ts

@@ -8,6 +8,12 @@ export interface CharlotteConfig {
     dialogAutoDismiss: DialogAutoDismiss;
     /** Directory for persistent screenshot artifacts. Defaults to OS temp dir. */
     screenshotDir?: string;
+    /** Directory for large tool output files. When set, tools with output_file support write here. */
+    outputDir?: string;
+    /** Whether to include iframe content in page representations. Default: false. */
+    includeIframes: boolean;
+    /** Maximum iframe nesting depth to traverse. Default: 3. */
+    iframeDepth: number;
 }
 export declare function createDefaultConfig(): CharlotteConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,cAAc,GAAG,QAAQ,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,CAAC;AAExF,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CAOrD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,cAAc,GAAG,QAAQ,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,CAAC;AAExF,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,cAAc,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CASrD"}

package/dist/types/config.js

@@ -4,6 +4,8 @@ export function createDefaultConfig() {
         autoSnapshot: "every_action",
         dialogAutoDismiss: "none",
         allowedWorkspaceRoot: process.cwd(), // Default to cwd for universal safety
+        includeIframes: false,
+        iframeDepth: 3,
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,aAAa,EAAE,EAAE;QACjB,YAAY,EAAE,cAAc;QAC5B,iBAAiB,EAAE,MAAM;QACzB,oBAAoB,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,sCAAsC;KAC5E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,aAAa,EAAE,EAAE;QACjB,YAAY,EAAE,cAAc;QAC5B,iBAAiB,EAAE,MAAM;QACzB,oBAAoB,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,sCAAsC;QAC3E,cAAc,EAAE,KAAK;QACrB,WAAW,EAAE,CAAC;KACf,CAAC;AACJ,CAAC"}

package/dist/types/page-representation.d.ts

@@ -9,11 +9,15 @@ export interface Landmark {
     role: string;
     label: string;
     bounds: Bounds;
+    /** Source frame URL. Omitted for main frame. */
+    frame?: string;
 }
 export interface Heading {
     level: 1 | 2 | 3 | 4 | 5 | 6;
     text: string;
     id: string;
+    /** Source frame URL. Omitted for main frame. */
+    frame?: string;
 }
 export interface ElementState {
     enabled?: boolean;
@@ -36,6 +40,8 @@ export interface InteractiveElement {
     placeholder?: string;
     value?: string;
     options?: string[];
+    /** Source frame URL. Omitted for main frame. */
+    frame?: string;
 }
 export interface FormRepresentation {
     id: string;
@@ -43,6 +49,8 @@ export interface FormRepresentation {
     method?: string;
     fields: string[];
     submit: string | null;
+    /** Source frame URL. Omitted for main frame. */
+    frame?: string;
 }
 export interface PageStructure {
     landmarks: Landmark[];
@@ -68,6 +76,11 @@ export interface PendingDialog {
     default_value?: string;
     timestamp: string;
 }
+export interface IframeInfo {
+    frame_id: string;
+    url: string;
+    bounds: Bounds | null;
+}
 export interface PageRepresentation {
     url: string;
     title: string;
@@ -92,6 +105,7 @@ export interface PageRepresentation {
         }>;
     };
     interactive_summary?: InteractiveSummary;
+    iframes?: IframeInfo[];
     reload_event?: ReloadEvent;
     pending_dialog?: PendingDialog;
     delta?: import("./snapshot.js").SnapshotDiff;

package/dist/types/page-representation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page-representation.d.ts","sourceRoot":"","sources":["../../src/types/page-representation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"page-representation.d.ts","sourceRoot":"","sources":["../../src/types/page-representation.ts"],"names":[],"mappings":"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"}

package/dist/utils/wait.js

@@ -38,7 +38,7 @@ async function evaluateCondition(page, condition) {
         const jsExpression = condition.js;
         try {
             const result = await page.evaluate((expression) => {
-                return !!new Function('return ' + expression)();
+                return !!new Function("return " + expression)();
             }, jsExpression);
             if (!result)
                 return false;

package/dist/utils/wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/utils/wait.ts"],"names":[],"mappings":"AAkBA,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,SAAwB,EACxB,OAAoB;IAEpB,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,wBAAwB,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3D,IAAI,SAAS;YAAE,OAAO,IAAI,CAAC;QAE3B,MAAM,aAAa,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5C,IAAI,aAAa,IAAI,CAAC;YAAE,MAAM;QAE9B,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,iBAAiB,CAC9B,IAAU,EACV,SAAwB;IAExB,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;IAC7B,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE;YAC/C,OAAO,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;QACjE,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;IAC3B,CAAC;IAED,IAAI,SAAS,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,YAAY,GAAG,SAAS,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE;gBAChD,OAAO,CAAC,CAAC,IAAI,QAAQ,CAAC,SAAS,GAAG,UAAU,CAAC,EAAE,CAAC;YAClD,CAAC,EAAE,YAAY,CAAC,CAAC;YACjB,IAAI,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/utils/wait.ts"],"names":[],"mappings":"AAkBA,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,SAAwB,EACxB,OAAoB;IAEpB,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,wBAAwB,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAE9C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3D,IAAI,SAAS;YAAE,OAAO,IAAI,CAAC;QAE3B,MAAM,aAAa,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5C,IAAI,aAAa,IAAI,CAAC;YAAE,MAAM;QAE9B,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,iBAAiB,CAAC,IAAU,EAAE,SAAwB;IACnE,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;IAC7B,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE;YAC/C,OAAO,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC;QACjE,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;IAC3B,CAAC;IAED,IAAI,SAAS,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,YAAY,GAAG,SAAS,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,EAAE;gBAChD,OAAO,CAAC,CAAC,IAAI,QAAQ,CAAC,SAAS,GAAG,UAAU,CAAC,EAAE,CAAC;YAClD,CAAC,EAAE,YAAY,CAAC,CAAC;YACjB,IAAI,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ticktockbent/charlotte",
-  "version": "0.4.1",
-  "description": "MCP server that renders web pages into structured, agent-readable representations",
+  "version": "0.5.0",
+  "description": "Token-efficient browser MCP server — structured web pages for AI agents, not raw accessibility dumps",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,14 +20,19 @@
   "homepage": "https://github.com/ticktockbent/charlotte#readme",
   "keywords": [
     "mcp",
+    "mcp-server",
+    "browser-mcp",
     "model-context-protocol",
-    "web",
-    "accessibility",
+    "browser-automation",
+    "web-scraping",
+    "ai-agent",
+    "token-efficient",
+    "structured-browsing",
+    "playwright-alternative",
+    "accessibility-tree",
     "headless-browser",
     "puppeteer",
-    "ai-agent",
-    "web-scraping",
-    "browser-automation"
+    "web-testing"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
@@ -36,7 +41,12 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:unit": "vitest run tests/unit/",
-    "test:integration": "vitest run tests/integration/"
+    "test:integration": "vitest run tests/integration/",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts'"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -46,10 +56,16 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@types/express": "^4.17.0",
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^3.0.0"
   },
   "files": [