DOCSEARCHbyAlgolia
Submit Docs

Vibium Documentation

repository·main·Indexed 25 days ago

https://github.com/vibiumdev/vibium

A verification layer for coding agents providing browser automation tools. Vibium allows AI agents to navigate pages, interact with elements, and capture data via a CLI, MCP server, or client libraries in JS/TS, Python, and Java. Features include semantic element finding, accessibility tree retrieval, and support for both synchronous and asynchronous APIs.

Tokens
109.4K
Snippets
328
Records
755
Agent score
84%

What's inside Vibium

  1. Overview of Vibium v1 components

    main

    Vibium v1 consists of three core components designed for browser automation driven by AI agents:

    • clicker: A Go binary (~10MB) that launches Chrome, communicates via WebDriver BiDi, and exposes an MCP server.
    • js/ts client: The vibium npm package providing Playwright-level DX for automation.
    • mcp server: Enables MCP-compatible agents (like Claude Code) to drive a browser out of the box.

  2. Understand the storage module and PartitionKey

    main

    The storage module manages data within storage partitions, which are namespaces for persistent data like cookies and local storage. A storage.PartitionKey uniquely identifies a partition and can include standard attributes or vendor-specific extensions.

    Standard storage.PartitionKey attributes:

    • userContext: A user context ID.
    • sourceOrigin: The serialization of the origin of resources that can access the storage partition.

    Vendor extensions must follow the pattern [unique-identifier]: to avoid conflicts.

  3. Understand WebDriver BiDi in Vibium

    main

    Vibium is built on WebDriver BiDi, a W3C standard for browser automation. Unlike the traditional request-response model of WebDriver (HTTP + JSON), WebDriver BiDi uses WebSockets to enable bidirectional communication. This allows the browser to push real-time events (such as console logs, network requests, and DOM changes) to Vibium without being prompted by the client.

    Key benefits of this architecture include:

    • Standards-based: Governed by the W3C rather than proprietary protocols like CDP (Google) or Playwright (Microsoft).
    • Real-time events: The browser pushes events like log.entryAdded directly to the agent.
    • Cross-browser potential: Designed to work across Chrome, Firefox, Edge, and Safari as support matures.

  4. Architecture of a Vibium Client

    main

    A Vibium client operates as a subprocess that communicates with the vibium binary via newline-delimited JSON (ndjson) over stdin/stdout. The binary acts as a bridge between the client and the Chrome browser (via WebDriver BiDi).

    Communication Flow:

    1. Client spawns the vibium pipe command.
    2. Client sends Requests (with an id) to the binary.
    3. Binary sends Success responses (with the matching id), Error responses (with the matching id), or Events (no id) back to the client.
    4. The binary sends a vibium:lifecycle.ready signal on stdout once the browser is launched.

  5. Understand WebDriver BiDi Protocol Architecture

    main

    The WebDriver BiDi protocol enables bidirectional communication between the controlling software (local end) and the user agent (remote end). Unlike standard WebDriver's strict command/response model, BiDi allows events to stream from the browser to the controller, matching the evented nature of the DOM.

    Key architectural concepts:

    • Local End: The controlling software that sends commands and receives responses/events.
    • Remote End: The user agent (browser) that executes commands and emits events.
    • BiDi Session: A WebDriver session where the BiDi flag is set to true.

  6. Understand Vibium Actionability Checks

    main

    Vibium uses actionability checks to ensure elements are ready for interaction before performing actions. This prevents errors caused by asynchronous loading, animations, or overlapping elements. These checks are performed server-side in the Go binary to ensure consistent behavior across all client libraries.

    The Five Core Checks

    CheckDescription
    VisibleElement has non-zero size and is not hidden via CSS (display: none or visibility: hidden).
    StableThe element's bounding box remains unchanged for 50ms (prevents clicking moving targets).
    ReceivesEventsThe element (or a descendant) is the target of elementFromPoint() at its center (ensures no overlays are blocking it).
    EnabledElement is not disabled, aria-disabled="true", or inside a disabled <fieldset>.
    EditableElement accepts text input (e.g., <input>, <textarea>, or contentEditable) and is not readOnly or aria-readonly. (Only checked for Fill actions).

  9. Understand the browsingContext Module

    main

    The browsingContext module manages commands and events related to navigables (contexts). It handles navigation progress, viewport configurations, and various overrides like locale, timezone, and screen settings.

    Key concepts include:

    • Navigable ID: A unique string identifying a navigable. For WebDriver windows, this matches the window handle.
    • Navigation Status: An immutable structure used to communicate the progress of a navigation.
    • Overrides: The module supports various overrides for user contexts and navigables, including devicePixelRatio, viewport, locale, timezone, screen settings, unhandled prompt behavior, and scripting enabled status.

  10. Use Sandboxed Script Execution

    main

    BiDi sessions support sandboxed script execution to allow automation tools to run scripts that access the DOM of a document without being affected by changes made to DOM APIs by other scripts in the same navigable.

    Each sandbox is a unique ECMAScript Realm. The sandbox provides access to platform objects in an existing Window realm via SandboxProxy objects.

    Restrictions of SandboxProxy objects:

    • Property Access: Accessing platform objects returns only Web IDL-defined properties. It prevents access to ECMAScript-defined properties (like "expando" properties) or properties that shadow underlying interface members.
    • Property Setting: Setting a property either triggers Web IDL-defined setter steps or sets the property on the proxy itself. Properties written outside the sandbox are not accessible within it.

  11. Understand Vibium's automation enhancements over raw BiDi

    main

    While raw WebDriver BiDi provides the protocol layer, Vibium abstracts the complexity by providing:

    • Connection Management: Automatically handles browser launching, WebSocket connection, and context ID tracking via browser.start().
    • Actionability Checks: Before interacting (e.g., element.click()), Vibium ensures the element is:
      • Visible: Has non-zero size and is not visibility: hidden.
      • Stable: Position is consistent for 2 consecutive checks (not animating).
      • Receives Events: Not covered by another element.
      • Enabled: Not disabled or aria-disabled.
      • Editable: For typing, not readonly.
    • Auto-Waiting: find() automatically waits for elements to appear, eliminating the need for manual sleep or explicit waits.
    • Improved Error Messages: Replaces cryptic protocol errors with contextual information (e.g., TimeoutError: Element not found: button.submit).

  12. Understand Network Intercepts in WebDriver BiDi

    main
    A network intercept allows remote clients to intercept and modify network requests and responses. In a BiDi session, intercepts are managed via an intercept map (mapping intercept IDs to properties like url patterns, phases, and contexts) and a blocked request map (tracking requests actively being blocked by mapping request id to a struct containing the request, phase, and response).