vibium 0.0.1 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Vibium
 
-A minimal npm package for now. Just logs a welcome message to the console. More coming!
+Browser automation for AI agents and humans.
 
 ## Installation
 
@@ -8,14 +8,220 @@ A minimal npm package for now. Just logs a welcome message to the console. More
 npm install vibium
 ```
 
-## Usage
+This automatically downloads Chrome for Testing on first install.
 
-```js
-const vibium = require('vibium');
+## Quick Start
 
-vibium(); // Logs: "Welcome to Vibium!"
+### Async API
+
+```javascript
+import { browser } from 'vibium';
+import { writeFile } from 'fs/promises';
+
+const vibe = await browser.launch();
+await vibe.go('https://example.com');
+
+const link = await vibe.find('a');
+console.log(await link.text());
+await link.click();
+
+const screenshot = await vibe.screenshot();
+await writeFile('screenshot.png', screenshot);
+
+await vibe.quit();
+```
+
+### Sync API
+
+```javascript
+import { browserSync } from 'vibium';
+import { writeFileSync } from 'fs';
+
+const vibe = browserSync.launch();
+vibe.go('https://example.com');
+
+const link = vibe.find('a');
+console.log(link.text());
+link.click();
+
+const screenshot = vibe.screenshot();
+writeFileSync('screenshot.png', screenshot);
+
+vibe.quit();
+```
+
+## API Reference
+
+### browser.launch(options?)
+
+Launch a new browser session.
+
+```javascript
+const vibe = await browser.launch({ headless: true });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headless` | boolean | `false` | Run without visible window |
+
+### vibe.go(url)
+
+Navigate to a URL.
+
+```javascript
+await vibe.go('https://example.com');
+```
+
+### vibe.find(selector, options?)
+
+Find an element by CSS selector.
+
+```javascript
+const button = await vibe.find('button.submit');
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | `30000` | Max wait time in ms |
+
+### vibe.screenshot()
+
+Capture a screenshot. Returns a `Buffer` (PNG).
+
+```javascript
+const png = await vibe.screenshot();
+```
+
+### vibe.quit()
+
+Close the browser session.
+
+```javascript
+await vibe.quit();
+```
+
+### element.click(options?)
+
+Click the element. Waits for element to be visible, stable, and enabled.
+
+```javascript
+await element.click();
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | `30000` | Max wait time in ms |
+
+### element.type(text, options?)
+
+Type text into the element. Waits for element to be visible, stable, enabled, and editable.
+
+```javascript
+await element.type('hello@example.com');
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | number | `30000` | Max wait time in ms |
+
+### element.text()
+
+Get the element's text content.
+
+```javascript
+const text = await element.text();
+```
+
+### element.getAttribute(name)
+
+Get an attribute value.
+
+```javascript
+const testId = await element.getAttribute('data-testid');
+```
+
+### element.boundingBox()
+
+Get the element's position and size. Returns `{x, y, width, height}`.
+
+```javascript
+const box = await element.boundingBox();
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VIBIUM_SKIP_BROWSER_DOWNLOAD` | Set to `1` to skip Chrome download on install |
+
+## Claude Code / MCP
+
+Add Vibium to Claude Code:
+
+```bash
+claude mcp add vibium -- npx vibium
+```
+
+### MCP Tools
+
+#### browser_launch
+
+Start a browser session.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `headless` | boolean | `false` | Run without visible window |
+
+#### browser_navigate
+
+Navigate to a URL.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | yes | The URL to navigate to |
+
+#### browser_click
+
+Click an element. Waits for element to be visible, stable, and enabled.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | yes | CSS selector |
+
+#### browser_type
+
+Type text into an element. Waits for element to be visible, stable, enabled, and editable.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | yes | CSS selector |
+| `text` | string | yes | Text to type |
+
+#### browser_screenshot
+
+Capture a screenshot.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `filename` | string | no | Save to file (e.g., screenshot.png) |
+
+#### browser_find
+
+Find an element and return its info (tag, text, bounding box).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | yes | CSS selector |
+
+#### browser_quit
+
+Close the browser session.
+
+## Links
+
+- [GitHub / Documentation](https://github.com/VibiumDev/vibium)
+- [Website](https://vibium.com)
+
 ## License
 
-MIT
+Apache-2.0

package/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Find clicker binary from platform package and run `clicker mcp`
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+function getClickerPath() {
+  const platform = os.platform();
+  const arch = os.arch() === 'x64' ? 'x64' : 'arm64';
+  const packageName = `@vibium/${platform}-${arch}`;
+  const binaryName = platform === 'win32' ? 'clicker.exe' : 'clicker';
+
+  try {
+    const packagePath = require.resolve(`${packageName}/package.json`);
+    return path.join(path.dirname(packagePath), 'bin', binaryName);
+  } catch {
+    console.error(`Could not find clicker binary for ${platform}-${arch}`);
+    process.exit(1);
+  }
+}
+
+const clickerPath = getClickerPath();
+execFileSync(clickerPath, ['mcp'], { stdio: 'inherit' });

package/dist/index.d.mts

@@ -0,0 +1,198 @@
+interface BiDiEvent {
+    method: string;
+    params: Record<string, unknown>;
+}
+
+type EventHandler = (event: BiDiEvent) => void;
+declare class BiDiClient {
+    private connection;
+    private nextId;
+    private pendingCommands;
+    private eventHandler;
+    private constructor();
+    static connect(url: string): Promise<BiDiClient>;
+    private handleResponse;
+    private handleEvent;
+    onEvent(handler: EventHandler): void;
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    close(): Promise<void>;
+}
+
+interface ClickerProcessOptions {
+    port?: number;
+    headless?: boolean;
+    executablePath?: string;
+}
+declare class ClickerProcess {
+    private process;
+    private _port;
+    private _stopped;
+    private constructor();
+    get port(): number;
+    static start(options?: ClickerProcessOptions): Promise<ClickerProcess>;
+    stop(): Promise<void>;
+}
+
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ElementInfo {
+    tag: string;
+    text: string;
+    box: BoundingBox;
+}
+interface ActionOptions {
+    /** Timeout in milliseconds for actionability checks. Default: 30000 */
+    timeout?: number;
+}
+declare class Element {
+    private client;
+    private context;
+    private selector;
+    readonly info: ElementInfo;
+    constructor(client: BiDiClient, context: string, selector: string, info: ElementInfo);
+    /**
+     * Click the element.
+     * Waits for element to be visible, stable, receive events, and enabled.
+     */
+    click(options?: ActionOptions): Promise<void>;
+    /**
+     * Type text into the element.
+     * Waits for element to be visible, stable, receive events, enabled, and editable.
+     */
+    type(text: string, options?: ActionOptions): Promise<void>;
+    text(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    boundingBox(): Promise<BoundingBox>;
+    private getCenter;
+}
+
+interface FindOptions {
+    /** Timeout in milliseconds to wait for element. Default: 30000 */
+    timeout?: number;
+}
+declare class Vibe {
+    private client;
+    private process;
+    private context;
+    constructor(client: BiDiClient, process: ClickerProcess | null);
+    private getContext;
+    go(url: string): Promise<void>;
+    screenshot(): Promise<Buffer>;
+    /**
+     * Execute JavaScript in the page context.
+     */
+    evaluate<T = unknown>(script: string): Promise<T>;
+    /**
+     * Find an element by CSS selector.
+     * Waits for element to exist before returning.
+     */
+    find(selector: string, options?: FindOptions): Promise<Element>;
+    quit(): Promise<void>;
+}
+
+interface LaunchOptions$1 {
+    headless?: boolean;
+    port?: number;
+    executablePath?: string;
+}
+declare const browser: {
+    launch(options?: LaunchOptions$1): Promise<Vibe>;
+};
+
+declare class SyncBridge {
+    private worker;
+    private signal;
+    private commandId;
+    private terminated;
+    private constructor();
+    static create(): SyncBridge;
+    call<T = unknown>(method: string, args?: unknown[]): T;
+    tryQuit(): void;
+    terminate(): void;
+}
+
+declare class ElementSync {
+    private bridge;
+    private elementId;
+    readonly info: ElementInfo;
+    constructor(bridge: SyncBridge, elementId: number, info: ElementInfo);
+    /**
+     * Click the element.
+     * Waits for element to be visible, stable, receive events, and enabled.
+     */
+    click(options?: ActionOptions): void;
+    /**
+     * Type text into the element.
+     * Waits for element to be visible, stable, receive events, enabled, and editable.
+     */
+    type(text: string, options?: ActionOptions): void;
+    text(): string;
+    getAttribute(name: string): string | null;
+    boundingBox(): BoundingBox;
+}
+
+declare class VibeSync {
+    private bridge;
+    constructor(bridge: SyncBridge);
+    go(url: string): void;
+    screenshot(): Buffer;
+    /**
+     * Execute JavaScript in the page context.
+     */
+    evaluate<T = unknown>(script: string): T;
+    /**
+     * Find an element by CSS selector.
+     * Waits for element to exist before returning.
+     */
+    find(selector: string, options?: FindOptions): ElementSync;
+    quit(): void;
+}
+
+interface LaunchOptions {
+    headless?: boolean;
+}
+declare const browserSync: {
+    launch(options?: LaunchOptions): VibeSync;
+};
+
+/**
+ * Custom error types for the Vibium client library.
+ */
+/**
+ * ConnectionError is thrown when connecting to the browser fails.
+ */
+declare class ConnectionError extends Error {
+    url: string;
+    cause?: Error | undefined;
+    constructor(url: string, cause?: Error | undefined);
+}
+/**
+ * TimeoutError is thrown when a wait operation times out.
+ */
+declare class TimeoutError extends Error {
+    selector: string;
+    timeout: number;
+    reason?: string | undefined;
+    constructor(selector: string, timeout: number, reason?: string | undefined);
+}
+/**
+ * ElementNotFoundError is thrown when a selector matches no elements.
+ */
+declare class ElementNotFoundError extends Error {
+    selector: string;
+    constructor(selector: string);
+}
+/**
+ * BrowserCrashedError is thrown when the browser process dies unexpectedly.
+ */
+declare class BrowserCrashedError extends Error {
+    exitCode: number;
+    output?: string | undefined;
+    constructor(exitCode: number, output?: string | undefined);
+}
+
+export { type ActionOptions, type BoundingBox, BrowserCrashedError, ConnectionError, Element, type ElementInfo, ElementNotFoundError, ElementSync, type FindOptions, TimeoutError, Vibe, VibeSync, browser, browserSync };

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+interface BiDiEvent {
+    method: string;
+    params: Record<string, unknown>;
+}
+
+type EventHandler = (event: BiDiEvent) => void;
+declare class BiDiClient {
+    private connection;
+    private nextId;
+    private pendingCommands;
+    private eventHandler;
+    private constructor();
+    static connect(url: string): Promise<BiDiClient>;
+    private handleResponse;
+    private handleEvent;
+    onEvent(handler: EventHandler): void;
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    close(): Promise<void>;
+}
+
+interface ClickerProcessOptions {
+    port?: number;
+    headless?: boolean;
+    executablePath?: string;
+}
+declare class ClickerProcess {
+    private process;
+    private _port;
+    private _stopped;
+    private constructor();
+    get port(): number;
+    static start(options?: ClickerProcessOptions): Promise<ClickerProcess>;
+    stop(): Promise<void>;
+}
+
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ElementInfo {
+    tag: string;
+    text: string;
+    box: BoundingBox;
+}
+interface ActionOptions {
+    /** Timeout in milliseconds for actionability checks. Default: 30000 */
+    timeout?: number;
+}
+declare class Element {
+    private client;
+    private context;
+    private selector;
+    readonly info: ElementInfo;
+    constructor(client: BiDiClient, context: string, selector: string, info: ElementInfo);
+    /**
+     * Click the element.
+     * Waits for element to be visible, stable, receive events, and enabled.
+     */
+    click(options?: ActionOptions): Promise<void>;
+    /**
+     * Type text into the element.
+     * Waits for element to be visible, stable, receive events, enabled, and editable.
+     */
+    type(text: string, options?: ActionOptions): Promise<void>;
+    text(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    boundingBox(): Promise<BoundingBox>;
+    private getCenter;
+}
+
+interface FindOptions {
+    /** Timeout in milliseconds to wait for element. Default: 30000 */
+    timeout?: number;
+}
+declare class Vibe {
+    private client;
+    private process;
+    private context;
+    constructor(client: BiDiClient, process: ClickerProcess | null);
+    private getContext;
+    go(url: string): Promise<void>;
+    screenshot(): Promise<Buffer>;
+    /**
+     * Execute JavaScript in the page context.
+     */
+    evaluate<T = unknown>(script: string): Promise<T>;
+    /**
+     * Find an element by CSS selector.
+     * Waits for element to exist before returning.
+     */
+    find(selector: string, options?: FindOptions): Promise<Element>;
+    quit(): Promise<void>;
+}
+
+interface LaunchOptions$1 {
+    headless?: boolean;
+    port?: number;
+    executablePath?: string;
+}
+declare const browser: {
+    launch(options?: LaunchOptions$1): Promise<Vibe>;
+};
+
+declare class SyncBridge {
+    private worker;
+    private signal;
+    private commandId;
+    private terminated;
+    private constructor();
+    static create(): SyncBridge;
+    call<T = unknown>(method: string, args?: unknown[]): T;
+    tryQuit(): void;
+    terminate(): void;
+}
+
+declare class ElementSync {
+    private bridge;
+    private elementId;
+    readonly info: ElementInfo;
+    constructor(bridge: SyncBridge, elementId: number, info: ElementInfo);
+    /**
+     * Click the element.
+     * Waits for element to be visible, stable, receive events, and enabled.
+     */
+    click(options?: ActionOptions): void;
+    /**
+     * Type text into the element.
+     * Waits for element to be visible, stable, receive events, enabled, and editable.
+     */
+    type(text: string, options?: ActionOptions): void;
+    text(): string;
+    getAttribute(name: string): string | null;
+    boundingBox(): BoundingBox;
+}
+
+declare class VibeSync {
+    private bridge;
+    constructor(bridge: SyncBridge);
+    go(url: string): void;
+    screenshot(): Buffer;
+    /**
+     * Execute JavaScript in the page context.
+     */
+    evaluate<T = unknown>(script: string): T;
+    /**
+     * Find an element by CSS selector.
+     * Waits for element to exist before returning.
+     */
+    find(selector: string, options?: FindOptions): ElementSync;
+    quit(): void;
+}
+
+interface LaunchOptions {
+    headless?: boolean;
+}
+declare const browserSync: {
+    launch(options?: LaunchOptions): VibeSync;
+};
+
+/**
+ * Custom error types for the Vibium client library.
+ */
+/**
+ * ConnectionError is thrown when connecting to the browser fails.
+ */
+declare class ConnectionError extends Error {
+    url: string;
+    cause?: Error | undefined;
+    constructor(url: string, cause?: Error | undefined);
+}
+/**
+ * TimeoutError is thrown when a wait operation times out.
+ */
+declare class TimeoutError extends Error {
+    selector: string;
+    timeout: number;
+    reason?: string | undefined;
+    constructor(selector: string, timeout: number, reason?: string | undefined);
+}
+/**
+ * ElementNotFoundError is thrown when a selector matches no elements.
+ */
+declare class ElementNotFoundError extends Error {
+    selector: string;
+    constructor(selector: string);
+}
+/**
+ * BrowserCrashedError is thrown when the browser process dies unexpectedly.
+ */
+declare class BrowserCrashedError extends Error {
+    exitCode: number;
+    output?: string | undefined;
+    constructor(exitCode: number, output?: string | undefined);
+}
+
+export { type ActionOptions, type BoundingBox, BrowserCrashedError, ConnectionError, Element, type ElementInfo, ElementNotFoundError, ElementSync, type FindOptions, TimeoutError, Vibe, VibeSync, browser, browserSync };