npm - @ericmhalvorsen/aperture - Versions diffs - 0.2.1 - Mend

@ericmhalvorsen/aperture 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

package/README.md +148 -0
package/dist/bin.d.ts +2 -0
package/dist/bin.js +64 -0
package/dist/client/handlers.d.ts +2 -0
package/dist/client/handlers.js +171 -0
package/dist/client/patches.d.ts +18 -0
package/dist/client/patches.js +56 -0
package/dist/client/storage.d.ts +5 -0
package/dist/client/storage.js +31 -0
package/dist/client/ui.d.ts +26 -0
package/dist/client/ui.js +600 -0
package/dist/client.d.ts +60 -0
package/dist/client.js +435 -0
package/dist/frameworks/next.d.ts +3 -0
package/dist/frameworks/next.js +12 -0
package/dist/frameworks/shared.d.ts +1 -0
package/dist/frameworks/shared.js +61 -0
package/dist/frameworks/vite.d.ts +10 -0
package/dist/frameworks/vite.js +22 -0
package/dist/index.d.ts +7 -0
package/dist/index.js +5 -0
package/dist/mcp-server.d.ts +39 -0
package/dist/mcp-server.js +237 -0
package/dist/react.d.ts +8 -0
package/dist/react.js +20 -0
package/dist/register.d.ts +1 -0
package/dist/register.js +2 -0
package/dist/server.d.ts +25 -0
package/dist/server.js +315 -0
package/dist/tools.d.ts +165 -0
package/dist/tools.js +161 -0
package/dist/transports.d.ts +29 -0
package/dist/transports.js +86 -0
package/dist/types.d.ts +50 -0
package/dist/types.js +1 -0
package/dist-browser/client.js +457 -0
package/package.json +123 -0

package/README.md ADDED Viewed

@@ -0,0 +1,148 @@
+# @ericmhalvorsen/aperture
+> Let Agent see browser. Agent build better stuff. Perchance
+No extensions. No CORS hacks. Auto-connect your local dev browser to Claude Code, Cursor, OpenCode, or any other MCP-capable agent.
+## 5-Minute Quickstart
+### 1. Install
+```bash
+npm install -D @ericmhalvorsen/aperture
+```
+### 2. Add to your app
+**Next.js:**
+```ts
+// next.config.ts
+import { withAperture } from "@ericmhalvorsen/aperture/next";
+export default withAperture({
+  // your existing config
+});
+```
+**Vite:**
+```ts
+// vite.config.ts
+import { aperture } from "@ericmhalvorsen/aperture/vite";
+export default {
+  plugins: [aperture()],
+};
+```
+**Other frameworks:**
+```bash
+# Run in a separate terminal
+npx @ericmhalvorsen/aperture
+```
+### 3. Add the client
+**React/Next.js:**
+```tsx
+import { Aperture } from "@ericmhalvorsen/aperture/react";
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        {process.env.NODE_ENV === "development" && <Aperture />}
+      </body>
+    </html>
+  );
+}
+```
+**Vite/Vanilla:**
+```typescript
+// In your main entry file
+import "@ericmhalvorsen/aperture/register";
+```
+**No bundler:**
+```html
+<script src="http://localhost:3456/aperture.js"></script>
+```
+### 4. Start your dev server
+```bash
+npm run dev
+```
+You should see:
+- A green dot badge in the bottom-right of your page
+- Console output: `[Aperture] Server running on port 3456`
+### 5. Connect your agent
+Add to your agent's MCP config:
+```json
+{
+  "mcpServers": {
+    "aperture": {
+      "url": "http://localhost:3456/mcp"
+    }
+  }
+}
+```
+When the agent makes its first request, you'll see an approval dialog in your browser. Click "Allow" to grant access.
+### More
+- [How It Works](./docs/how-it-works.md)
+- [MCP Capabilities](./docs/capabilities.md)
+- [Security Model](./docs/security.md)
+- [Architecture](./docs/architecture.md)
+- [Debugging](./docs/debugging.md)
+- [Chrome Extension Plan](./docs/plans/EXTENSION.md)
+---
+## AI Development Policy
+This project is developed in part using AI. When submitting pull requests, you may use AI but please review your submission carefully. The pull request will be treated as if it was written by you.
+---
+## Local Development
+```bash
+# Install
+pnpm install
+# Watch compilation
+pnpm dev
+# Build
+pnpm build
+# Lint & format
+pnpm run check
+pnpm run format
+```
+### Link for local testing
+```bash
+# In the aperture directory:
+pnpm link --global
+# In your test project:
+pnpm link --global @ericmhalvorsen/aperture
+```
+After editing Aperture source, run `pnpm build` in the aperture directory. The consuming project (linked) will pick up the changes on restart.
+---
+## License
+MIT

package/dist/bin.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ #!/usr/bin/env node
2	+ export {};

package/dist/bin.js ADDED Viewed

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import pc from "picocolors";
+import { ApertureServer } from "./server.js";
+const { values, positionals } = parseArgs({
+    options: {
+        port: { type: "string", short: "p" },
+        verbose: { type: "boolean", short: "v" },
+        help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+});
+if (values.help) {
+    console.log(`
+  ${pc.cyan(pc.bold("Aperture MCP Server"))}
+  ${pc.bold("Usage:")}
+    $ aperture [options] [command...]
+  ${pc.bold("Options:")}
+    -p, --port <port>    Port to run the MCP server on (default: 3456)
+    -v, --verbose        Enable verbose logging of MCP traffic
+    -h, --help           Show this help message
+  ${pc.bold("Examples:")}
+    $ aperture                           # Run standalone MCP server
+    $ aperture stdin                     # Run standalone MCP server via stdin/stdout
+    $ aperture -p 4000                   # Run on port 4000
+    $ aperture next dev                  # Run MCP server and spawn "next dev"
+`);
+    process.exit(0);
+}
+const port = Number(values.port || process.env.APERTURE_PORT) || 3456;
+const verbose = Boolean(values.verbose);
+const isStdioMode = positionals[0] === "stdin";
+if (isStdioMode) {
+    new ApertureServer(port, { verbose, silentStartup: true, stdio: true });
+    console.error(pc.cyan(`\n● Aperture MCP Server initialized (stdio mode)`));
+    console.error(`${pc.dim("├")} MCP Endpoint:   ${pc.green(`ws://localhost:${port}/mcp`)}`);
+    console.error(`${pc.dim("└")} Browser Script: ${pc.blue(`http://localhost:${port}/aperture.js`)}\n`);
+}
+else {
+    new ApertureServer(port, { verbose, silentStartup: true });
+    console.log(pc.cyan(`\n● Aperture MCP Server initialized`));
+    console.log(`${pc.dim("├")} MCP Endpoint:   ${pc.green(`ws://localhost:${port}/mcp`)}`);
+    console.log(`${pc.dim("└")} Browser Script: ${pc.blue(`http://localhost:${port}/aperture.js`)}\n`);
+    if (positionals.length > 0) {
+        const [command, ...args] = positionals;
+        console.log(pc.dim(`> Spawning wrapped command: ${command} ${args.join(" ")}\n`));
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            shell: true,
+            env: { ...process.env, APERTURE_PORT: port.toString() },
+        });
+        child.on("exit", (code) => {
+            process.exit(code ?? 0);
+        });
+    }
+    else {
+        console.log(pc.dim("Waiting for connections... (Press Ctrl+C to stop)"));
+    }
+}

package/dist/client/handlers.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import type { ApertureClient } from "../client.js";
2	+ export declare const TOOL_HANDLERS: Record<string, (client: ApertureClient, args: Record<string, any>) => any \| Promise<any>>;

package/dist/client/handlers.js ADDED Viewed

@@ -0,0 +1,171 @@
+import { getConsoleBuffer, getNetworkBuffer } from "./patches.js";
+export const TOOL_HANDLERS = {
+    browser_dom_query: (_client, { selector, includeHtml = false }) => {
+        const elements = Array.from(document.querySelectorAll(String(selector)));
+        return elements.map((el) => ({
+            tag: el.tagName.toLowerCase(),
+            text: el.textContent?.slice(0, 200) || "",
+            visible: !!el.offsetParent,
+            attributes: Object.fromEntries(Array.from(el.attributes).map((a) => [a.name, a.value])),
+            html: includeHtml ? el.outerHTML.slice(0, 500) : undefined,
+        }));
+    },
+    browser_network_requests: (_client, { limit = 20 }) => {
+        return getNetworkBuffer().slice(-Number(limit));
+    },
+    browser_page_info: (_client, { logLimit = 20, logLevel = "all" }) => {
+        let logs = getConsoleBuffer();
+        if (logLevel !== "all") {
+            logs = logs.filter((e) => e.level === logLevel);
+        }
+        return {
+            url: window.location.href,
+            title: document.title,
+            width: window.innerWidth,
+            height: window.innerHeight,
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+            userAgent: navigator.userAgent,
+            logs: logs.slice(-Number(logLimit)),
+        };
+    },
+    browser_storage_get: (_client, { type, key, prefix, name }) => {
+        if (type === "localStorage") {
+            const result = {};
+            if (key) {
+                result[String(key)] = localStorage.getItem(String(key));
+            }
+            if (prefix) {
+                for (let i = 0; i < localStorage.length; i++) {
+                    const k = localStorage.key(i);
+                    if (k?.startsWith(String(prefix))) {
+                        result[k] = localStorage.getItem(k);
+                    }
+                }
+            }
+            return result;
+        }
+        if (type === "cookie") {
+            const cookies = {};
+            const docCookies = document.cookie;
+            if (docCookies) {
+                for (const cookie of docCookies.split(";")) {
+                    const [k, v] = cookie.split("=").map((s) => s.trim());
+                    if (k)
+                        cookies[k] = decodeURIComponent(v || "");
+                }
+            }
+            if (name) {
+                const targetName = String(name);
+                return { [targetName]: cookies[targetName] || null };
+            }
+            return cookies;
+        }
+        return { error: `Unknown type: ${type}. Use 'localStorage' or 'cookie'.` };
+    },
+    browser_screenshot: async (client) => {
+        try {
+            const dataUrl = await client.captureScreenshotFromStream();
+            return { base64: dataUrl.split(",")[1], format: "png" };
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    },
+    browser_evaluate: (_client, { expression }) => {
+        // biome-ignore lint/security/noGlobalEval: developer-only bridge, gated by approval
+        const result = window.eval(String(expression));
+        return {
+            result: typeof result === "object" ? JSON.stringify(result) : String(result),
+        };
+    },
+    browser_click: (_client, { selector }) => {
+        const element = document.querySelector(String(selector));
+        if (!element) {
+            return { error: `Element not found matching selector: ${selector}` };
+        }
+        element.focus();
+        const events = [
+            "pointerdown",
+            "mousedown",
+            "pointerup",
+            "mouseup",
+            "click",
+        ];
+        for (const name of events) {
+            const ev = new MouseEvent(name, {
+                bubbles: true,
+                cancelable: true,
+            });
+            element.dispatchEvent(ev);
+        }
+        return { success: true };
+    },
+    browser_type: (_client, { selector, text }) => {
+        const element = document.querySelector(String(selector));
+        if (!element) {
+            return { error: `Element not found matching selector: ${selector}` };
+        }
+        const isInput = element instanceof HTMLInputElement;
+        const isTextArea = element instanceof HTMLTextAreaElement;
+        if (isInput || isTextArea) {
+            const proto = isInput
+                ? HTMLInputElement.prototype
+                : HTMLTextAreaElement.prototype;
+            const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+            if (setter) {
+                setter.call(element, String(text));
+            }
+            else {
+                element.value =
+                    String(text);
+            }
+        }
+        else if (element.isContentEditable) {
+            element.textContent = String(text);
+        }
+        else {
+            return {
+                error: `Element is not an input, textarea, or contenteditable.`,
+            };
+        }
+        element.dispatchEvent(new Event("input", { bubbles: true }));
+        element.dispatchEvent(new Event("change", { bubbles: true }));
+        return { success: true };
+    },
+    browser_scroll: (_client, { selector, x, y, scrollIntoView }) => {
+        if (selector) {
+            const element = document.querySelector(String(selector));
+            if (!element) {
+                return { error: `Element not found matching selector: ${selector}` };
+            }
+            if (scrollIntoView) {
+                element.scrollIntoView({
+                    behavior: "smooth",
+                    block: "center",
+                    inline: "nearest",
+                });
+                return { success: true };
+            }
+            if (x !== undefined)
+                element.scrollLeft = Number(x);
+            if (y !== undefined)
+                element.scrollTop = Number(y);
+            return {
+                success: true,
+                scrollLeft: element.scrollLeft,
+                scrollTop: element.scrollTop,
+            };
+        }
+        else {
+            const posX = x !== undefined ? Number(x) : window.scrollX;
+            const posY = y !== undefined ? Number(y) : window.scrollY;
+            window.scrollTo({ left: posX, top: posY, behavior: "smooth" });
+            return {
+                success: true,
+                scrollX: window.scrollX,
+                scrollY: window.scrollY,
+            };
+        }
+    },
+};

package/dist/client/patches.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+export interface ConsoleEntry {
+    level: string;
+    message: string;
+    timestamp: number;
+}
+export interface NetworkEntry {
+    url: string;
+    method: string;
+    start: number;
+    end: number;
+    status: number;
+    responseText: string;
+    error?: string;
+}
+export declare function getConsoleBuffer(): ConsoleEntry[];
+export declare function getNetworkBuffer(): NetworkEntry[];
+export declare function patchConsole(): void;
+export declare function patchFetch(): void;

package/dist/client/patches.js ADDED Viewed

@@ -0,0 +1,56 @@
+const consoleBuffer = [];
+const networkBuffer = [];
+export function getConsoleBuffer() {
+    return consoleBuffer;
+}
+export function getNetworkBuffer() {
+    return networkBuffer;
+}
+export function patchConsole() {
+    const levels = ["log", "warn", "error", "info", "debug"];
+    for (const level of levels) {
+        const orig = console[level];
+        console[level] = (...args) => {
+            const message = args
+                .map((a) => (typeof a === "string" ? a : JSON.stringify(a)))
+                .join(" ");
+            consoleBuffer.push({ level, message, timestamp: Date.now() });
+            if (consoleBuffer.length > 500)
+                consoleBuffer.shift();
+            orig(...args);
+        };
+    }
+}
+export function patchFetch() {
+    const origFetch = window.fetch;
+    window.fetch = async (...args) => {
+        const entry = {
+            url: String(args[0]),
+            method: "GET",
+            start: Date.now(),
+            end: 0,
+            status: 0,
+            responseText: "",
+        };
+        if (args[1]) {
+            entry.method = args[1].method || "GET";
+        }
+        try {
+            const res = await origFetch(...args);
+            entry.status = res.status;
+            entry.end = Date.now();
+            networkBuffer.push(entry);
+            if (networkBuffer.length > 100)
+                networkBuffer.shift();
+            return res;
+        }
+        catch (err) {
+            entry.end = Date.now();
+            entry.error = String(err);
+            networkBuffer.push(entry);
+            if (networkBuffer.length > 100)
+                networkBuffer.shift();
+            throw err;
+        }
+    };
+}

package/dist/client/storage.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export declare const storage: {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+};

package/dist/client/storage.js ADDED Viewed

@@ -0,0 +1,31 @@
+export const storage = {
+    get(key) {
+        if (typeof window === "undefined" || typeof localStorage === "undefined") {
+            return null;
+        }
+        try {
+            return localStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    },
+    set(key, value) {
+        if (typeof window === "undefined" || typeof localStorage === "undefined") {
+            return;
+        }
+        try {
+            localStorage.setItem(key, value);
+        }
+        catch { }
+    },
+    remove(key) {
+        if (typeof window === "undefined" || typeof localStorage === "undefined") {
+            return;
+        }
+        try {
+            localStorage.removeItem(key);
+        }
+        catch { }
+    },
+};

package/dist/client/ui.d.ts ADDED Viewed

@@ -0,0 +1,26 @@
+export declare function injectStyles(): void;
+export declare function requestDisplayMedia(): Promise<MediaStream | null>;
+export declare function showApprovalDialog(agentName: string, onApprovalStateChange: (state: {
+    stream?: MediaStream | null;
+    capabilities?: string[];
+}) => void): Promise<{
+    approved: boolean;
+    capabilities: string[];
+    ttlMs?: number;
+    dismissed?: boolean;
+}>;
+export declare function showStatusDialog(options: {
+    wsReadyState: number;
+    approved: boolean;
+    denied: boolean;
+    capabilities: string[];
+    isBadgeHidden: () => boolean;
+    showBadge: () => void;
+    hideBadgeFor24h: () => void;
+    revokeApproval: () => void;
+    onApprovalStateChange: (state: {
+        approved: boolean;
+        capabilities: string[];
+        stream?: MediaStream | null;
+    }) => void;
+}): void;