@velork/browser-bridge

v1.2.8

Published

a month ago

Velork Browser Bridge - A complete automation bridge for controlling iframe content with AI-driven browser automation

Downloads

0High
0Medium
0Low

alielroby

automation browser iframe ai testing e2e

@velork/browser-bridge

Velork Browser Bridge - A complete TypeScript automation bridge for controlling iframe content with AI-driven browser automation.

Installation

Via npm/yarn/pnpm

npm install @velork/browser-bridge
# or
yarn add @velork/browser-bridge
# or
pnpm add @velork/browser-bridge

Via CDN (for direct HTML usage)

<!-- ESM version -->
<script
  type="module"
  src="https://unpkg.com/@velork/browser-bridge/dist/index.js"
></script>

<!-- Browser bundle (IIFE) -->
<script src="https://unpkg.com/@velork/browser-bridge/dist/browser.js"></script>

Usage

Option 1: Direct Browser Script Tag (Plain HTML)

For simple HTML pages, use the browser bundle via script tag:

<!DOCTYPE html>
<html>
  <head>
    <title>My Page</title>
    <script src="https://unpkg.com/@velork/browser-bridge/dist/browser.js"></script>
  </head>
  <body>
    <!-- Your content -->

    <script>
      VelorkBrowserBridge.initAutomationBridge({
        allowedOrigins: ["http://localhost:5173", "https://your-main-app.com"],
        maxConsoleBufferSize: 1000,
        enableConsoleCapture: true,
        enableNetworkCapture: true,
      });
    </script>
  </body>
</html>

Option 2: ES Modules (Modern Browsers)

For modern browsers with ES module support:

<!DOCTYPE html>
<html>
  <head>
    <title>My Page</title>
  </head>
  <body>
    <!-- Your content -->

    <script type="module">
      import { initAutomationBridge } from "https://unpkg.com/@velork/browser-bridge/dist/index.js";

      initAutomationBridge({
        allowedOrigins: ["http://localhost:5173", "https://your-main-app.com"],
        maxConsoleBufferSize: 1000,
        enableConsoleCapture: true,
        enableNetworkCapture: true,
      });
    </script>
  </body>
</html>

Option 3: React / Next.js

Install the package and import in your React components:

npm install @velork/browser-bridge

import { useEffect } from "react";
import { initAutomationBridge } from "@velork/browser-bridge";

function MyIframePage() {
  useEffect(() => {
    initAutomationBridge({
      allowedOrigins: [
        process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
        "https://your-main-app.com",
      ],
      maxConsoleBufferSize: 1000,
      enableConsoleCapture: true,
      enableNetworkCapture: true,
    });
  }, []);

  return <div>{/* Your page content */}</div>;
}

export default MyIframePage;

Option 4: Expo / React Native Web

Works seamlessly with Expo and React Native Web:

import { useEffect } from "react";
import { initAutomationBridge } from "@velork/browser-bridge";

export default function WebScreen() {
  useEffect(() => {
    if (typeof window !== "undefined") {
      initAutomationBridge({
        allowedOrigins: ["https://your-main-app.com"],
        maxConsoleBufferSize: 1000,
      });
    }
  }, []);

  return <View>{/* Your content */}</View>;
}

Option 5: Vite / Webpack / Other Bundlers

Works with any modern bundler that supports ES modules:

import { initAutomationBridge } from "@velork/browser-bridge";

initAutomationBridge({
  allowedOrigins: ["http://localhost:5173", "https://your-main-app.com"],
  maxConsoleBufferSize: 1000,
  enableConsoleCapture: true,
  enableNetworkCapture: true,
});

Configuration Options

interface AutomationBridgeConfig {
  allowedOrigins: string[]; // Required: List of allowed parent origins
  maxConsoleBufferSize?: number; // Optional: Max console messages to buffer (default: 1000)
  enableConsoleCapture?: boolean; // Optional: Enable console capture (default: true)
  enableNetworkCapture?: boolean; // Optional: Enable network capture (default: true)
}

Controlling the Bridge (Parent Window)

Once you have the bridge initialized in your iframe, you can control it from the parent window using the Client SDK or React Hook.

Using the Client SDK (Vanilla JavaScript / TypeScript)

import { createBrowserBridgeClient } from "@velork/browser-bridge/client";

// Get reference to your iframe
const iframe = document.querySelector<HTMLIFrameElement>("#my-iframe")!;

// Create client instance
// iframeOrigin is optional - will be extracted from iframe.src automatically
// For better security with cross-origin iframes, provide it explicitly
const client = createBrowserBridgeClient({
  iframe,
  // iframeOrigin: "http://localhost:3001", // Optional: provide explicitly for better security
  timeout: 5000, // Optional: timeout for operations
});

// Wait for bridge to be ready
await client.waitForReady();

// Now you can control the iframe
await client.click({ selector: "#submit-button" });
await client.type({ selector: "#email", text: "[email protected]" });
await client.hover({ selector: "#tooltip-trigger" });

// Get information
const snapshot = await client.snapshot();
const pageInfo = await client.getPageInfo();
const consoleMessages = await client.getConsoleMessages();

// Listen to console messages in real-time
client.onConsoleMessage((entry) => {
  console.log("Console message from iframe:", entry);
});

// Clean up when done
client.dispose();

Using the React Hook

import { useRef, useEffect } from "react";
import { useBrowserBridge } from "@velork/browser-bridge/hooks";

function MyApp() {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  const { client, isReady, error } = useBrowserBridge({
    iframe: iframeRef,
    // iframeOrigin: "http://localhost:3001", // Optional: extracted from iframe.src automatically
    onReady: () => {
      console.log("Bridge is ready!");
    },
    onConsoleMessage: (entry) => {
      console.log("Console from iframe:", entry);
    },
  });

  useEffect(() => {
    if (client && isReady) {
      // Automatically click a button when ready
      client.click({ selector: "#auto-click-button" });
    }
  }, [client, isReady]);

  const handleClick = async () => {
    if (client && isReady) {
      await client.click({ selector: "#my-button" });
    }
  };

  const handleFillForm = async () => {
    if (client && isReady) {
      await client.fillForm({
        fields: {
          "#name": "John Doe",
          "#email": "[email protected]",
          "#message": "Hello world!",
        },
      });
    }
  };

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <iframe
        ref={iframeRef}
        src="http://localhost:3001"
        style={{ width: "100%", height: "600px" }}
      />
      <div>
        <button onClick={handleClick} disabled={!isReady}>
          Click Button in Iframe
        </button>
        <button onClick={handleFillForm} disabled={!isReady}>
          Fill Form
        </button>
      </div>
    </div>
  );
}

Using the Helper Hook (with ensureReady)

import { useRef } from "react";
import { useBrowserBridgeClient } from "@velork/browser-bridge/hooks";

function MyApp() {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  const { client, isReady, ensureReady } = useBrowserBridgeClient({
    iframe: iframeRef,
    // iframeOrigin: "http://localhost:3001", // Optional: extracted automatically
  });

  const handleAction = async () => {
    try {
      await ensureReady(); // Automatically waits if not ready
      if (client) {
        await client.click({ selector: "#button" });
        const snapshot = await client.snapshot();
        console.log("Snapshot:", snapshot);
      }
    } catch (error) {
      console.error("Action failed:", error);
    }
  };

  return (
    <div>
      <iframe ref={iframeRef} src="http://localhost:3001" />
      <button onClick={handleAction}>Perform Action</button>
    </div>
  );
}

Complete Example: Parent App with Iframe Control

// Parent App (React)
import { useRef, useState } from "react";
import { useBrowserBridge } from "@velork/browser-bridge/hooks";

function App() {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const [snapshot, setSnapshot] = useState(null);
  const [consoleMessages, setConsoleMessages] = useState([]);

  const { client, isReady } = useBrowserBridge({
    iframe: iframeRef,
    // iframeOrigin: "http://localhost:3001", // Optional: extracted automatically
    onConsoleMessage: (entry) => {
      setConsoleMessages((prev) => [...prev, entry]);
    },
  });

  const takeSnapshot = async () => {
    if (client && isReady) {
      const snap = await client.snapshot();
      setSnapshot(snap);
    }
  };

  const navigateToPage = async (url: string) => {
    if (client && isReady) {
      await client.navigate({ url });
    }
  };

  return (
    <div style={{ display: "flex", gap: "20px" }}>
      <div style={{ flex: 1 }}>
        <iframe
          ref={iframeRef}
          src="http://localhost:3001"
          style={{ width: "100%", height: "600px", border: "1px solid #ccc" }}
        />
      </div>
      <div style={{ flex: 1 }}>
        <h2>Controls</h2>
        <button onClick={takeSnapshot} disabled={!isReady}>
          Take Snapshot
        </button>
        <button
          onClick={() => navigateToPage("http://localhost:3001/page2")}
          disabled={!isReady}
        >
          Navigate to Page 2
        </button>
        {snapshot && (
          <div>
            <h3>Snapshot:</h3>
            <pre>{JSON.stringify(snapshot, null, 2)}</pre>
          </div>
        )}
        <div>
          <h3>Console Messages ({consoleMessages.length}):</h3>
          {consoleMessages.map((msg, idx) => (
            <div key={idx}>
              [{msg.method}] {msg.args.join(" ")}
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

Features

Navigation

Navigate to URLs
Navigate back in history

Element Interactions

Click elements
Type into inputs
Hover over elements
Select dropdown options
Drag and drop
Press keys
Clear inputs
Scroll to elements

Element Finding

Find by CSS selector
Find by text content
Find by ARIA role
Find by label text
Find by placeholder
Find by multiple criteria
Get all interactive elements
Get all form inputs

Information Gathering

Accessibility snapshots
Element information extraction
Page information (URL, title, viewport, scroll)
Page text content
Form data extraction
Console message capture
Network request monitoring

Advanced

JavaScript evaluation
Screenshots (requires html2canvas)
Wait for elements/text
Fill multiple form fields

Security

Important: Always set allowedOrigins to exact origins in production. Never use "*" as it allows any origin to control your iframe.

TypeScript Support

Full TypeScript support with comprehensive type definitions included.

Build Outputs

The package provides multiple build formats for different use cases:

dist/index.js - ESM bundle for modern bundlers (React, Vite, Webpack, etc.)
dist/browser.js - IIFE bundle for direct browser script tag usage
dist/index.d.ts - TypeScript type definitions

Development

# Build all formats
npm run build

# Build TypeScript types only
npm run build:types

# Build ESM bundle
npm run build:esm

# Build browser bundle (IIFE)
npm run build:browser

# Watch mode for development
npm run dev

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@velork/browser-bridge

Installation

Via npm/yarn/pnpm

Via CDN (for direct HTML usage)

Usage

Option 1: Direct Browser Script Tag (Plain HTML)

Option 2: ES Modules (Modern Browsers)

Option 3: React / Next.js

Option 4: Expo / React Native Web

Option 5: Vite / Webpack / Other Bundlers

Configuration Options

Controlling the Bridge (Parent Window)

Using the Client SDK (Vanilla JavaScript / TypeScript)

Using the React Hook

Using the Helper Hook (with ensureReady)

Complete Example: Parent App with Iframe Control

Features

Navigation

Element Interactions

Element Finding

Information Gathering

Advanced

Security

TypeScript Support

Build Outputs

Development

License