@ticktockbent/charlotte 0.1.0

package/dist/state/differ.d.ts

@@ -0,0 +1,9 @@
+import type { PageRepresentation } from "../types/page-representation.js";
+import type { SnapshotDiff } from "../types/snapshot.js";
+export type DiffScope = "all" | "structure" | "interactive" | "content";
+/**
+ * Compare two PageRepresentations and produce a SnapshotDiff describing
+ * what changed between them.
+ */
+export declare function diffRepresentations(fromRepresentation: PageRepresentation, toRepresentation: PageRepresentation, fromSnapshotId: number, toSnapshotId: number, scope?: DiffScope): SnapshotDiff;
+//# sourceMappingURL=differ.d.ts.map

package/dist/state/differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"differ.d.ts","sourceRoot":"","sources":["../../src/state/differ.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAOnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAExE;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,kBAAkB,EAAE,kBAAkB,EACtC,gBAAgB,EAAE,kBAAkB,EACpC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,SAAiB,GACvB,YAAY,CAyBd"}

package/dist/state/differ.js

@@ -0,0 +1,295 @@
+/**
+ * Compare two PageRepresentations and produce a SnapshotDiff describing
+ * what changed between them.
+ */
+export function diffRepresentations(fromRepresentation, toRepresentation, fromSnapshotId, toSnapshotId, scope = "all") {
+    const changes = [];
+    if (scope === "all" || scope === "structure") {
+        changes.push(...diffLandmarks(fromRepresentation.structure.landmarks, toRepresentation.structure.landmarks));
+        changes.push(...diffHeadings(fromRepresentation.structure.headings, toRepresentation.structure.headings));
+    }
+    if (scope === "all" || scope === "interactive") {
+        changes.push(...diffInteractiveElements(fromRepresentation.interactive, toRepresentation.interactive));
+        changes.push(...diffForms(fromRepresentation.forms, toRepresentation.forms));
+    }
+    if (scope === "all" || scope === "content") {
+        changes.push(...diffContent(fromRepresentation, toRepresentation));
+    }
+    const summary = buildSummary(changes);
+    return {
+        from_snapshot: fromSnapshotId,
+        to_snapshot: toSnapshotId,
+        changes,
+        summary,
+    };
+}
+// ─── Landmark diffing ────────────────────────────────────────────────
+function landmarkKey(landmark) {
+    return `${landmark.role}:${landmark.label}`;
+}
+function diffLandmarks(fromLandmarks, toLandmarks) {
+    const changes = [];
+    const fromByKey = new Map(fromLandmarks.map((landmark) => [landmarkKey(landmark), landmark]));
+    const toByKey = new Map(toLandmarks.map((landmark) => [landmarkKey(landmark), landmark]));
+    // Removed landmarks
+    for (const [key, landmark] of fromByKey) {
+        if (!toByKey.has(key)) {
+            changes.push({
+                type: "removed",
+                detail: `Landmark removed: ${landmark.role} "${landmark.label}"`,
+            });
+        }
+    }
+    // Added landmarks
+    for (const [key, landmark] of toByKey) {
+        if (!fromByKey.has(key)) {
+            changes.push({
+                type: "added",
+                detail: `Landmark added: ${landmark.role} "${landmark.label}"`,
+            });
+        }
+    }
+    // Moved landmarks (same key, different bounds)
+    for (const [key, toLandmark] of toByKey) {
+        const fromLandmark = fromByKey.get(key);
+        if (fromLandmark && !boundsEqual(fromLandmark.bounds, toLandmark.bounds)) {
+            changes.push({
+                type: "moved",
+                detail: `Landmark moved: ${toLandmark.role} "${toLandmark.label}"`,
+                from: fromLandmark.bounds,
+                to: toLandmark.bounds,
+            });
+        }
+    }
+    return changes;
+}
+// ─── Heading diffing ─────────────────────────────────────────────────
+function diffHeadings(fromHeadings, toHeadings) {
+    const changes = [];
+    const fromById = new Map(fromHeadings.map((heading) => [heading.id, heading]));
+    const toById = new Map(toHeadings.map((heading) => [heading.id, heading]));
+    for (const [headingId, heading] of fromById) {
+        if (!toById.has(headingId)) {
+            changes.push({
+                type: "removed",
+                element: headingId,
+                detail: `Heading removed: h${heading.level} "${heading.text}"`,
+            });
+        }
+    }
+    for (const [headingId, heading] of toById) {
+        if (!fromById.has(headingId)) {
+            changes.push({
+                type: "added",
+                element: headingId,
+                detail: `Heading added: h${heading.level} "${heading.text}"`,
+            });
+        }
+        else {
+            const fromHeading = fromById.get(headingId);
+            if (fromHeading.text !== heading.text) {
+                changes.push({
+                    type: "changed",
+                    element: headingId,
+                    property: "text",
+                    from: fromHeading.text,
+                    to: heading.text,
+                });
+            }
+        }
+    }
+    return changes;
+}
+// ─── Interactive element diffing ─────────────────────────────────────
+function diffInteractiveElements(fromElements, toElements) {
+    const changes = [];
+    const fromById = new Map(fromElements.map((element) => [element.id, element]));
+    const toById = new Map(toElements.map((element) => [element.id, element]));
+    // Removed elements
+    for (const [elementId, element] of fromById) {
+        if (!toById.has(elementId)) {
+            changes.push({
+                type: "removed",
+                element: elementId,
+                detail: `${element.type} "${element.label}" removed`,
+            });
+        }
+    }
+    // Added elements
+    for (const [elementId, element] of toById) {
+        if (!fromById.has(elementId)) {
+            changes.push({
+                type: "added",
+                element: elementId,
+                detail: `${element.type} "${element.label}" added`,
+            });
+        }
+    }
+    // Changed/moved elements
+    for (const [elementId, toElement] of toById) {
+        const fromElement = fromById.get(elementId);
+        if (!fromElement)
+            continue;
+        // Check bounds change (moved)
+        if (fromElement.bounds &&
+            toElement.bounds &&
+            !boundsEqual(fromElement.bounds, toElement.bounds)) {
+            changes.push({
+                type: "moved",
+                element: elementId,
+                from: fromElement.bounds,
+                to: toElement.bounds,
+            });
+        }
+        // Check state changes
+        const stateChanges = diffElementState(fromElement.state, toElement.state);
+        for (const stateChange of stateChanges) {
+            changes.push({
+                type: "changed",
+                element: elementId,
+                property: `state.${stateChange.property}`,
+                from: stateChange.from,
+                to: stateChange.to,
+            });
+        }
+        // Check value change
+        if (fromElement.value !== toElement.value) {
+            changes.push({
+                type: "changed",
+                element: elementId,
+                property: "value",
+                from: fromElement.value,
+                to: toElement.value,
+            });
+        }
+        // Check label change
+        if (fromElement.label !== toElement.label) {
+            changes.push({
+                type: "changed",
+                element: elementId,
+                property: "label",
+                from: fromElement.label,
+                to: toElement.label,
+            });
+        }
+    }
+    return changes;
+}
+function diffElementState(fromState, toState) {
+    const statePropertyChanges = [];
+    const stateProperties = [
+        "enabled",
+        "visible",
+        "focused",
+        "checked",
+        "expanded",
+        "selected",
+        "required",
+        "invalid",
+    ];
+    for (const property of stateProperties) {
+        if (fromState[property] !== toState[property]) {
+            statePropertyChanges.push({
+                property,
+                from: fromState[property],
+                to: toState[property],
+            });
+        }
+    }
+    return statePropertyChanges;
+}
+// ─── Form diffing ────────────────────────────────────────────────────
+function diffForms(fromForms, toForms) {
+    const changes = [];
+    const fromById = new Map(fromForms.map((form) => [form.id, form]));
+    const toById = new Map(toForms.map((form) => [form.id, form]));
+    for (const [formId, form] of fromById) {
+        if (!toById.has(formId)) {
+            changes.push({
+                type: "removed",
+                element: formId,
+                detail: `Form removed (${form.fields.length} fields)`,
+            });
+        }
+    }
+    for (const [formId, form] of toById) {
+        if (!fromById.has(formId)) {
+            changes.push({
+                type: "added",
+                element: formId,
+                detail: `Form added (${form.fields.length} fields)`,
+            });
+        }
+        else {
+            const fromForm = fromById.get(formId);
+            // Check field list changes
+            const addedFields = form.fields.filter((field) => !fromForm.fields.includes(field));
+            const removedFields = fromForm.fields.filter((field) => !form.fields.includes(field));
+            if (addedFields.length > 0 || removedFields.length > 0) {
+                changes.push({
+                    type: "changed",
+                    element: formId,
+                    property: "fields",
+                    from: fromForm.fields,
+                    to: form.fields,
+                });
+            }
+        }
+    }
+    return changes;
+}
+// ─── Content diffing ─────────────────────────────────────────────────
+function diffContent(fromRepresentation, toRepresentation) {
+    const changes = [];
+    if (fromRepresentation.structure.content_summary !== toRepresentation.structure.content_summary) {
+        changes.push({
+            type: "changed",
+            property: "content_summary",
+            from: fromRepresentation.structure.content_summary,
+            to: toRepresentation.structure.content_summary,
+        });
+    }
+    if (fromRepresentation.url !== toRepresentation.url) {
+        changes.push({
+            type: "changed",
+            property: "url",
+            from: fromRepresentation.url,
+            to: toRepresentation.url,
+        });
+    }
+    if (fromRepresentation.title !== toRepresentation.title) {
+        changes.push({
+            type: "changed",
+            property: "title",
+            from: fromRepresentation.title,
+            to: toRepresentation.title,
+        });
+    }
+    return changes;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+function boundsEqual(boundsA, boundsB) {
+    return (boundsA.x === boundsB.x &&
+        boundsA.y === boundsB.y &&
+        boundsA.w === boundsB.w &&
+        boundsA.h === boundsB.h);
+}
+function buildSummary(changes) {
+    if (changes.length === 0)
+        return "No changes detected.";
+    const addedCount = changes.filter((change) => change.type === "added").length;
+    const removedCount = changes.filter((change) => change.type === "removed").length;
+    const movedCount = changes.filter((change) => change.type === "moved").length;
+    const changedCount = changes.filter((change) => change.type === "changed").length;
+    const parts = [];
+    if (addedCount > 0)
+        parts.push(`${addedCount} added`);
+    if (removedCount > 0)
+        parts.push(`${removedCount} removed`);
+    if (movedCount > 0)
+        parts.push(`${movedCount} moved`);
+    if (changedCount > 0)
+        parts.push(`${changedCount} changed`);
+    return `${changes.length} changes: ${parts.join(", ")}.`;
+}
+//# sourceMappingURL=differ.js.map

package/dist/state/differ.js.map

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

package/dist/state/snapshot-store.d.ts

@@ -0,0 +1,52 @@
+import type { PageRepresentation } from "../types/page-representation.js";
+import type { Snapshot } from "../types/snapshot.js";
+/**
+ * Ring-buffer store for page snapshots. Snapshots have monotonically
+ * increasing integer IDs and are evicted oldest-first when the buffer
+ * reaches its configured depth.
+ */
+export declare class SnapshotStore {
+    private buffer;
+    private nextSnapshotId;
+    private maxDepth;
+    constructor(depth?: number);
+    /**
+     * Push a new snapshot from a PageRepresentation. Returns the assigned
+     * snapshot ID (also stamped onto the representation).
+     */
+    push(representation: PageRepresentation): number;
+    /**
+     * Retrieve a snapshot by its ID. Returns null if evicted or never existed.
+     */
+    get(snapshotId: number): Snapshot | null;
+    /**
+     * Get the most recent snapshot, or null if the store is empty.
+     */
+    getLatest(): Snapshot | null;
+    /**
+     * Get the second-most-recent snapshot (the one before latest), or null.
+     */
+    getPrevious(): Snapshot | null;
+    /**
+     * Get the oldest snapshot ID still in the buffer, or null if empty.
+     */
+    getOldestId(): number | null;
+    /**
+     * Get the latest snapshot ID that has been assigned (even if evicted).
+     */
+    getLatestId(): number;
+    /**
+     * Current number of snapshots in the buffer.
+     */
+    get size(): number;
+    /**
+     * Resize the ring buffer. Evicts oldest snapshots if the new depth
+     * is smaller than the current size.
+     */
+    setDepth(newDepth: number): void;
+    /**
+     * Clear all snapshots and reset the ID counter.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=snapshot-store.d.ts.map

package/dist/state/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../../src/state/snapshot-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAMrD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAS;gBAEb,KAAK,GAAE,MAAsB;IAIzC;;;OAGG;IACH,IAAI,CAAC,cAAc,EAAE,kBAAkB,GAAG,MAAM;IAwBhD;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAIxC;;OAEG;IACH,SAAS,IAAI,QAAQ,GAAG,IAAI;IAK5B;;OAEG;IACH,WAAW,IAAI,QAAQ,GAAG,IAAI;IAK9B;;OAEG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAK5B;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOhC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/state/snapshot-store.js

@@ -0,0 +1,98 @@
+const DEFAULT_DEPTH = 50;
+const MIN_DEPTH = 5;
+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.
+ */
+export class SnapshotStore {
+    buffer = [];
+    nextSnapshotId = 1;
+    maxDepth;
+    constructor(depth = DEFAULT_DEPTH) {
+        this.maxDepth = Math.max(MIN_DEPTH, Math.min(MAX_DEPTH, depth));
+    }
+    /**
+     * Push a new snapshot from a PageRepresentation. Returns the assigned
+     * snapshot ID (also stamped onto the representation).
+     */
+    push(representation) {
+        const snapshotId = this.nextSnapshotId++;
+        const timestamp = new Date().toISOString();
+        // Stamp the snapshot_id onto the representation so callers see it
+        representation.snapshot_id = snapshotId;
+        representation.timestamp = timestamp;
+        const snapshot = {
+            id: snapshotId,
+            timestamp,
+            representation,
+        };
+        this.buffer.push(snapshot);
+        // Evict oldest if over capacity
+        while (this.buffer.length > this.maxDepth) {
+            this.buffer.shift();
+        }
+        return snapshotId;
+    }
+    /**
+     * Retrieve a snapshot by its ID. Returns null if evicted or never existed.
+     */
+    get(snapshotId) {
+        return this.buffer.find((snapshot) => snapshot.id === snapshotId) ?? null;
+    }
+    /**
+     * Get the most recent snapshot, or null if the store is empty.
+     */
+    getLatest() {
+        if (this.buffer.length === 0)
+            return null;
+        return this.buffer[this.buffer.length - 1];
+    }
+    /**
+     * Get the second-most-recent snapshot (the one before latest), or null.
+     */
+    getPrevious() {
+        if (this.buffer.length < 2)
+            return null;
+        return this.buffer[this.buffer.length - 2];
+    }
+    /**
+     * Get the oldest snapshot ID still in the buffer, or null if empty.
+     */
+    getOldestId() {
+        if (this.buffer.length === 0)
+            return null;
+        return this.buffer[0].id;
+    }
+    /**
+     * Get the latest snapshot ID that has been assigned (even if evicted).
+     */
+    getLatestId() {
+        return this.nextSnapshotId - 1;
+    }
+    /**
+     * Current number of snapshots in the buffer.
+     */
+    get size() {
+        return this.buffer.length;
+    }
+    /**
+     * Resize the ring buffer. Evicts oldest snapshots if the new depth
+     * is smaller than the current size.
+     */
+    setDepth(newDepth) {
+        this.maxDepth = Math.max(MIN_DEPTH, Math.min(MAX_DEPTH, newDepth));
+        while (this.buffer.length > this.maxDepth) {
+            this.buffer.shift();
+        }
+    }
+    /**
+     * Clear all snapshots and reset the ID counter.
+     */
+    clear() {
+        this.buffer = [];
+        this.nextSnapshotId = 1;
+    }
+}
+//# sourceMappingURL=snapshot-store.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolDependencies } from "./tool-helpers.js";
+export declare function registerDevModeTools(server: McpServer, deps: ToolDependencies): void;
+//# sourceMappingURL=dev-mode.d.ts.map

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

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

package/dist/tools/dev-mode.js

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import * as fs from "node:fs";
+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";
+export function registerDevModeTools(server, deps) {
+    // ─── 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"),
+            port: z
+                .number()
+                .optional()
+                .describe("Port to serve on (default: auto-assign)"),
+            watch: z
+                .boolean()
+                .optional()
+                .describe("Auto-reload on file changes (default: true)"),
+        },
+    }, async ({ path: directoryPath, port, watch }) => {
+        try {
+            await deps.browserManager.ensureConnected();
+            if (!deps.devModeState) {
+                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, "Dev mode is not available.", "DevModeState was not initialized.");
+            }
+            // Resolve and validate the directory path
+            const absoluteDirectoryPath = path.resolve(directoryPath);
+            let directoryStats;
+            try {
+                directoryStats = fs.statSync(absoluteDirectoryPath);
+            }
+            catch {
+                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Path does not exist: ${absoluteDirectoryPath}`, "Provide a valid directory path.");
+            }
+            if (!directoryStats.isDirectory()) {
+                throw new CharlotteError(CharlotteErrorCode.SESSION_ERROR, `Path is not a directory: ${absoluteDirectoryPath}`, "Provide a path to a directory, not a file.");
+            }
+            const shouldWatch = watch ?? true;
+            logger.info("Starting dev serve", {
+                directory: absoluteDirectoryPath,
+                port,
+                watch: shouldWatch,
+            });
+            const serverInfo = await deps.devModeState.startServing({
+                directoryPath: absoluteDirectoryPath,
+                port,
+                watch: shouldWatch,
+                pageManager: deps.pageManager,
+            });
+            // Navigate the active page to the served URL
+            const page = deps.pageManager.getActivePage();
+            await page.goto(serverInfo.url, { waitUntil: "load" });
+            const representation = await renderActivePage(deps, {
+                source: "action",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ...representation,
+                            dev_server: {
+                                url: serverInfo.url,
+                                port: serverInfo.port,
+                                directory: serverInfo.directoryPath,
+                                watching: shouldWatch,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ─── 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"),
+            js: z
+                .string()
+                .optional()
+                .describe("JavaScript to execute in the page context"),
+        },
+    }, async ({ css, js }) => {
+        try {
+            await deps.browserManager.ensureConnected();
+            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.");
+            }
+            const page = deps.pageManager.getActivePage();
+            if (css) {
+                await page.addStyleTag({ content: css });
+                logger.info("Injected CSS", {
+                    length: css.length,
+                });
+            }
+            if (js) {
+                await page.evaluate(js);
+                logger.info("Executed injected JS", {
+                    length: js.length,
+                });
+            }
+            // Brief pause to allow DOM updates to settle
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            const representation = await renderAfterAction(deps);
+            return formatPageResponse(representation);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ─── 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
+                .array(z.enum(["a11y", "performance", "seo", "contrast", "links"]))
+                .optional()
+                .describe("Audit categories to run. Options: a11y, performance, seo, contrast, links. Default: all categories."),
+        },
+    }, async ({ checks }) => {
+        try {
+            await deps.browserManager.ensureConnected();
+            const page = deps.pageManager.getActivePage();
+            const session = await page.createCDPSession();
+            const auditor = new Auditor();
+            const categories = checks;
+            logger.info("Running dev audit", {
+                categories: categories ?? "all",
+            });
+            try {
+                const auditResult = await auditor.audit(page, session, categories);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(auditResult, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                await session.detach();
+            }
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=dev-mode.js.map

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

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