@ericmhalvorsen/aperture 0.2.1

package/dist/client.js

@@ -0,0 +1,435 @@
+import { TOOL_HANDLERS } from "./client/handlers.js";
+import { patchConsole, patchFetch } from "./client/patches.js";
+import { storage } from "./client/storage.js";
+import { injectStyles, requestDisplayMedia, showApprovalDialog, showStatusDialog, } from "./client/ui.js";
+export class ApertureClient {
+    ws = null;
+    config;
+    approved = false;
+    denied = false;
+    capabilities = [];
+    screenCaptureStream = null;
+    badgeElement = null;
+    focusListenersAdded = false;
+    constructor(config) {
+        this.config = config;
+        window.__apertureInstance__ = this;
+        injectStyles();
+        patchConsole();
+        patchFetch();
+        this.loadCachedApproval();
+        this.registerKeyboardShortcut();
+        if (typeof window !== "undefined") {
+            window.addEventListener("beforeunload", () => {
+                this.stopScreenCapture();
+            });
+        }
+    }
+    registerKeyboardShortcut() {
+        if (typeof document === "undefined")
+            return;
+        document.addEventListener("keydown", (e) => {
+            const isMac = navigator.platform.toLowerCase().includes("mac");
+            const mod = isMac ? e.metaKey : e.ctrlKey;
+            if (mod && e.shiftKey && (e.key === "a" || e.key === "A")) {
+                e.preventDefault();
+                this.openStatusDialog();
+            }
+        });
+    }
+    isBadgeHidden() {
+        const hiddenUntil = storage.get("aperture_badge_hidden_until");
+        if (hiddenUntil) {
+            return Date.now() < Number(hiddenUntil);
+        }
+        return false;
+    }
+    hideBadgeFor24h() {
+        const until = String(Date.now() + 24 * 60 * 60 * 1000);
+        storage.set("aperture_badge_hidden_until", until);
+        if (this.badgeElement) {
+            this.badgeElement.remove();
+            this.badgeElement = null;
+        }
+    }
+    showBadge() {
+        storage.remove("aperture_badge_hidden_until");
+        if (this.ws) {
+            const status = this.ws.readyState === WebSocket.OPEN ? "connected" : "connecting";
+            this.updateBadge(status);
+        }
+    }
+    loadCachedApproval() {
+        const approved = storage.get("aperture_approved");
+        const timestamp = storage.get("aperture_approved_at");
+        const storedTtl = storage.get("aperture_ttl_ms");
+        const defaultTtlMs = 60 * 60 * 1000;
+        const ttlMs = storedTtl ? Number(storedTtl) : defaultTtlMs;
+        const isStale = timestamp ? Date.now() - Number(timestamp) > ttlMs : true;
+        if (approved === "true" && !isStale) {
+            this.approved = true;
+            this.denied = false;
+            this.capabilities = JSON.parse(storage.get("aperture_capabilities") || "[]");
+        }
+        else if (approved === "false") {
+            this.denied = true;
+            this.approved = false;
+        }
+        if (isStale) {
+            storage.remove("aperture_approved");
+            storage.remove("aperture_approved_at");
+            storage.remove("aperture_capabilities");
+            storage.remove("aperture_ttl_ms");
+        }
+    }
+    saveApproval(approved, capabilities, ttlMs) {
+        if (approved) {
+            storage.set("aperture_approved", "true");
+            storage.set("aperture_approved_at", String(Date.now()));
+            storage.set("aperture_capabilities", JSON.stringify(capabilities));
+            if (ttlMs) {
+                storage.set("aperture_ttl_ms", String(ttlMs));
+            }
+        }
+        else {
+            storage.set("aperture_approved", "false");
+            storage.remove("aperture_approved_at");
+            storage.remove("aperture_capabilities");
+            storage.remove("aperture_ttl_ms");
+        }
+    }
+    revokeApproval() {
+        storage.remove("aperture_approved");
+        storage.remove("aperture_approved_at");
+        storage.remove("aperture_capabilities");
+        storage.remove("aperture_ttl_ms");
+        this.approved = false;
+        this.denied = false;
+        this.capabilities = [];
+    }
+    connect() {
+        const url = new URL("/mcp", this.config.serverUrl);
+        url.searchParams.set("type", "browser");
+        this.updateBadge("connecting");
+        this.ws = new WebSocket(url.toString());
+        this.ws.onopen = () => {
+            const customToolsPayload = this.config.customTools
+                ? Object.entries(this.config.customTools).map(([name, def]) => ({
+                    name,
+                    description: def.description,
+                    inputSchema: def.inputSchema,
+                }))
+                : [];
+            this.send({
+                type: "register",
+                url: window.location.href,
+                title: document.title,
+                customTools: customToolsPayload,
+            });
+            console.log("[Aperture] Connected to server");
+            this.updateBadge("connected");
+            if (this.approved) {
+                this.send({
+                    type: "approval",
+                    approved: this.approved,
+                    capabilities: this.capabilities,
+                });
+            }
+            this.reportFocusState();
+            if (typeof window !== "undefined" && !this.focusListenersAdded) {
+                this.focusListenersAdded = true;
+                window.addEventListener("focus", () => this.reportFocusState());
+                window.addEventListener("blur", () => this.reportFocusState());
+            }
+        };
+        this.ws.onmessage = async (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.type === "tool_call") {
+                    await this.handleToolCall(msg);
+                }
+                else if (msg.type === "agent_connected") {
+                    await this.getOrWaitApproval();
+                }
+            }
+            catch { }
+        };
+        this.ws.onclose = () => {
+            console.log("[Aperture] Disconnected. Retrying in 3s...");
+            this.updateBadge("disconnected");
+            this.stopScreenCapture();
+            setTimeout(() => this.connect(), 3000);
+        };
+    }
+    disconnect() {
+        if (this.ws) {
+            this.ws.onclose = null;
+            this.ws.close();
+            this.ws = null;
+        }
+        this.stopScreenCapture();
+        if (this.badgeElement) {
+            this.badgeElement.remove();
+            this.badgeElement = null;
+        }
+    }
+    reportFocusState() {
+        if (typeof document === "undefined")
+            return;
+        const focused = document.hasFocus();
+        this.send({ type: "focus", focused });
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    updateBadge(status) {
+        if (typeof document === "undefined")
+            return;
+        if (this.isBadgeHidden()) {
+            if (this.badgeElement) {
+                this.badgeElement.remove();
+                this.badgeElement = null;
+            }
+            return;
+        }
+        if (!this.badgeElement) {
+            this.badgeElement = document.createElement("div");
+            this.badgeElement.id = "aperture-badge";
+            this.badgeElement.title = "Manage Aperture session (Ctrl+Shift+A)";
+            const dot = document.createElement("span");
+            dot.className = "dot";
+            this.badgeElement.appendChild(dot);
+            this.badgeElement.addEventListener("click", () => {
+                this.openStatusDialog();
+            });
+            document.body.appendChild(this.badgeElement);
+        }
+        const dot = this.badgeElement.querySelector(".dot");
+        if (dot) {
+            dot.className = `dot ${status}`;
+        }
+    }
+    async handleToolCall(msg) {
+        if (this.denied) {
+            this.send({
+                type: "result",
+                requestId: msg.requestId,
+                result: { error: "User denied browser access" },
+            });
+            return;
+        }
+        if (!this.approved) {
+            await this.getOrWaitApproval();
+            if (!this.approved) {
+                this.send({
+                    type: "result",
+                    requestId: msg.requestId,
+                    result: {
+                        error: this.denied
+                            ? "User denied browser access"
+                            : "User dismissed the approval request",
+                    },
+                });
+                return;
+            }
+        }
+        const builtInHandler = TOOL_HANDLERS[msg.tool];
+        const customHandler = this.config.customTools?.[msg.tool]?.handler;
+        const handler = builtInHandler || customHandler;
+        if (!handler) {
+            this.send({
+                type: "result",
+                requestId: msg.requestId,
+                result: { error: `Unknown tool: ${msg.tool}` },
+            });
+            return;
+        }
+        try {
+            const result = await handler(this, msg.args);
+            this.send({ type: "result", requestId: msg.requestId, result });
+        }
+        catch (err) {
+            this.send({
+                type: "result",
+                requestId: msg.requestId,
+                result: { error: err instanceof Error ? err.message : String(err) },
+            });
+        }
+    }
+    approvalPendingPromise = null;
+    getOrWaitApproval() {
+        if (this.approved || this.denied)
+            return Promise.resolve();
+        if (this.approvalPendingPromise)
+            return this.approvalPendingPromise;
+        this.approvalPendingPromise = (async () => {
+            const decision = await this.getApproval("MCP Agent");
+            if (decision.dismissed) {
+                return;
+            }
+            this.approved = decision.approved;
+            this.denied = !decision.approved;
+            this.capabilities = decision.capabilities;
+            this.saveApproval(this.approved, this.capabilities, decision.ttlMs);
+            this.send({
+                type: "approval",
+                approved: this.approved,
+                capabilities: this.capabilities,
+            });
+        })();
+        this.approvalPendingPromise.finally(() => {
+            this.approvalPendingPromise = null;
+        });
+        return this.approvalPendingPromise;
+    }
+    async getApproval(agentName) {
+        if (this.config.onApprovalRequest) {
+            const result = await this.config.onApprovalRequest(agentName);
+            return { ...result, dismissed: false };
+        }
+        return showApprovalDialog(agentName, (state) => {
+            if (state.stream !== undefined) {
+                this.screenCaptureStream = state.stream;
+            }
+        });
+    }
+    async captureScreenshotFromStream() {
+        if (!this.screenCaptureStream?.active) {
+            if (!this.approved || !this.capabilities.includes("screenshot")) {
+                throw new Error("Screenshot access was not granted. Please approve the connection with screenshot capability enabled.");
+            }
+            const stream = await this.requestScreenCapture();
+            if (!stream) {
+                throw new Error("Failed to acquire screen capture. Please try again or re-approve the connection.");
+            }
+            this.screenCaptureStream = stream;
+        }
+        const track = this.screenCaptureStream.getVideoTracks()[0];
+        if (!track) {
+            throw new Error("No video tracks found in screen capture stream.");
+        }
+        const video = document.createElement("video");
+        video.srcObject = this.screenCaptureStream;
+        video.autoplay = true;
+        video.playsInline = true;
+        video.muted = true;
+        await new Promise((resolve) => {
+            video.onloadedmetadata = () => resolve(null);
+        });
+        await video.play().catch(() => null);
+        await new Promise((resolve) => {
+            if (typeof video.requestVideoFrameCallback === "function") {
+                video.requestVideoFrameCallback(() => resolve());
+                setTimeout(() => resolve(), 1000);
+            }
+            else {
+                setTimeout(() => resolve(), 300);
+            }
+        });
+        const canvas = document.createElement("canvas");
+        canvas.width = video.videoWidth || 800;
+        canvas.height = video.videoHeight || 600;
+        const ctx = canvas.getContext("2d");
+        if (!ctx) {
+            throw new Error("Could not get 2D context from canvas");
+        }
+        ctx.drawImage(video, 0, 0);
+        const dataUrl = canvas.toDataURL("image/png");
+        video.srcObject = null;
+        video.load();
+        return dataUrl;
+    }
+    stopScreenCapture() {
+        if (this.screenCaptureStream) {
+            for (const track of this.screenCaptureStream.getTracks()) {
+                track.stop();
+            }
+            this.screenCaptureStream = null;
+        }
+    }
+    setMediaStream(stream) {
+        this.screenCaptureStream = stream;
+    }
+    async requestScreenCapture() {
+        return requestDisplayMedia();
+    }
+    openStatusDialog() {
+        showStatusDialog({
+            wsReadyState: this.ws?.readyState ?? WebSocket.CLOSED,
+            approved: this.approved,
+            denied: this.denied,
+            capabilities: this.capabilities,
+            isBadgeHidden: () => this.isBadgeHidden(),
+            showBadge: () => this.showBadge(),
+            hideBadgeFor24h: () => this.hideBadgeFor24h(),
+            revokeApproval: () => this.revokeApproval(),
+            onApprovalStateChange: (state) => {
+                this.approved = state.approved;
+                if (state.approved) {
+                    this.denied = false;
+                }
+                else {
+                    this.denied = true;
+                }
+                this.capabilities = state.capabilities;
+                if (state.stream !== undefined) {
+                    if (state.stream === null) {
+                        this.stopScreenCapture();
+                    }
+                    else {
+                        this.screenCaptureStream = state.stream;
+                    }
+                }
+                this.saveApproval(this.approved, this.capabilities);
+                this.send({
+                    type: "approval",
+                    approved: this.approved,
+                    capabilities: this.capabilities,
+                });
+            },
+        });
+    }
+}
+export function initAperture(options) {
+    if (typeof window === "undefined")
+        return;
+    const isDev = location.hostname === "localhost" ||
+        location.hostname === "127.0.0.1" ||
+        location.hostname.endsWith(".localhost") ||
+        !!window.__vite_inject__;
+    if (!isDev)
+        return;
+    const port = options?.port || window.__APERTURE_PORT__ || 3456;
+    const serverUrl = options?.serverUrl || `ws://localhost:${port}`;
+    const existing = window.__apertureInstance__;
+    if (existing && typeof existing.disconnect === "function") {
+        existing.disconnect();
+    }
+    const client = new ApertureClient({
+        serverUrl,
+        customTools: options?.customTools,
+    });
+    client.connect();
+    window.__apertureInstance__ = client;
+    return client;
+}
+if (typeof window !== "undefined") {
+    const isDev = location.hostname === "localhost" ||
+        location.hostname === "127.0.0.1" ||
+        location.hostname.endsWith(".localhost") ||
+        !!window.__vite_inject__;
+    if (isDev) {
+        setTimeout(() => {
+            if (!window.__apertureInstance__) {
+                const port = window.__APERTURE_PORT__ || 3456;
+                const serverUrl = window.__APERTURE_URL__ || `ws://localhost:${port}`;
+                console.log("[Aperture] No manual initialization detected. Auto-connecting...");
+                const client = new ApertureClient({ serverUrl });
+                client.connect();
+                window.__apertureInstance__ = client;
+            }
+        }, 500);
+    }
+}

package/dist/frameworks/next.d.ts

@@ -0,0 +1,3 @@
+export declare function withAperture<T = Record<string, unknown>>(nextConfig?: T, options?: {
+    port?: number;
+}): T;

package/dist/frameworks/next.js

@@ -0,0 +1,12 @@
+import { ensureApertureServer } from "./shared.js";
+export function withAperture(nextConfig = {}, options) {
+    const port = options?.port || 3456;
+    ensureApertureServer(port).catch(console.error);
+    const config = { ...nextConfig };
+    const serverExternalPackages = config.serverExternalPackages || [];
+    if (!serverExternalPackages.includes("@ericmhalvorsen/aperture")) {
+        serverExternalPackages.push("@ericmhalvorsen/aperture");
+    }
+    config.serverExternalPackages = serverExternalPackages;
+    return config;
+}

package/dist/frameworks/shared.d.ts

@@ -0,0 +1 @@
+export declare function ensureApertureServer(port?: number): Promise<void>;

package/dist/frameworks/shared.js

@@ -0,0 +1,61 @@
+import { createConnection } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let serverStarting = false;
+let serverStarted = false;
+function getBinPath() {
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(__dirname, "..", "bin.js");
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection(port, "127.0.0.1");
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        setTimeout(() => {
+            socket.destroy();
+            resolve(true);
+        }, 300);
+    });
+}
+export async function ensureApertureServer(port = 3456) {
+    if (serverStarting || serverStarted)
+        return;
+    const free = await isPortFree(port);
+    if (!free) {
+        serverStarted = true;
+        console.log(`[Aperture] Server already running on port ${port}`);
+        return;
+    }
+    serverStarting = true;
+    const binPath = getBinPath();
+    const cp = await import(/* webpackIgnore: true */ "node:child_process");
+    const child = cp.spawn("node", [binPath], {
+        stdio: "ignore",
+        env: { ...process.env, APERTURE_PORT: String(port) },
+    });
+    child.unref();
+    process.on("exit", () => {
+        try {
+            child.kill();
+        }
+        catch { }
+    });
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    const nowFree = await isPortFree(port);
+    if (!nowFree) {
+        serverStarted = true;
+        serverStarting = false;
+        console.log(`[Aperture] Started server on port ${port}`);
+    }
+    else {
+        serverStarting = false;
+        console.error(`[Aperture] Failed to start server on port ${port}`);
+    }
+}

package/dist/frameworks/vite.d.ts

@@ -0,0 +1,10 @@
+export declare function aperture(options?: {
+    port?: number;
+}): {
+    name: string;
+    apply: string;
+    config: () => {
+        define: Record<string, string>;
+    };
+    configureServer: () => Promise<void>;
+};

package/dist/frameworks/vite.js

@@ -0,0 +1,22 @@
+import { ensureApertureServer } from "./shared.js";
+export function aperture(options) {
+    const port = options?.port || Number(process.env.APERTURE_PORT) || 3456;
+    let started = false;
+    return {
+        name: "aperture",
+        apply: "serve",
+        config() {
+            return {
+                define: {
+                    "window.__APERTURE_PORT__": JSON.stringify(port),
+                },
+            };
+        },
+        async configureServer() {
+            if (started)
+                return;
+            started = true;
+            await ensureApertureServer(port);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { CustomToolDefinition } from "./client.js";
+export { ApertureClient } from "./client.js";
+export { withAperture } from "./frameworks/next.js";
+export { Aperture } from "./react.js";
+export { ApertureServer } from "./server.js";
+export type { BrowserToolName } from "./tools.js";
+export { BROWSER_TOOLS } from "./tools.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ApertureClient } from "./client.js";
+export { withAperture } from "./frameworks/next.js";
+export { Aperture } from "./react.js";
+export { ApertureServer } from "./server.js";
+export { BROWSER_TOOLS } from "./tools.js";

package/dist/mcp-server.d.ts

@@ -0,0 +1,39 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { BrowserSession } from "./types.js";
+export interface SharedServerState {
+    mcpInitialized: boolean;
+}
+export declare function createApertureMcpServer(sessions: Map<string, BrowserSession>, pendingRequests: Map<string, (result: unknown) => void>, sharedState: SharedServerState): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;