crossbus: Instructions file for Gemini CLI

GEMINI.md - AI Agent Instructions for CrossBus

For AI Agents: This document contains specific instructions for working effectively with CrossBus.

IMPORTANT GLOBAL RULE:

ALWAYS use English for code, documentation, comments, and websites. Italian is for CHAT ONLY with the user. Even if the user speaks Italian, your output artifacts must be in English.

---

🎯 What is CrossBus

CrossBus is a library for cross-context communication in browsers:

• Iframes ↔ Parent: PostMessageTransport
• Tab ↔ Tab: BroadcastChannelTransport
• Main ↔ Worker: PostMessageTransport
• Browser ↔ Server: WebSocketTransport
• WebView ↔ Native App: NativeBridgeTransport

---

📋 Quick Reference for AI Agents

Hub Pattern (Orchestrator)

import { CrossBus, PostMessageTransport } from 'crossbus';

const hub = new CrossBus({ isHub: true, peerId: 'hub', allowedOrigins: ['*'] });

// Connect iframe
const iframe = document.getElementById('my-iframe');
hub.addTransport(new PostMessageTransport(iframe.contentWindow, {
    targetOrigin: '*'
}), { peerId: 'agent-1' }); // Specify remote peer ID

// Handle requests
hub.handle('getData', async (payload) => {
    return { data: await fetchData(payload.id) };
});

Agent Pattern (Spoke)

import { CrossBus, PostMessageTransport } from 'crossbus';

const agent = new CrossBus({ peerId: 'agent-1', allowedOrigins: ['*'] });
agent.addTransport(new PostMessageTransport(window.parent, {
    targetOrigin: '*'
}), { peerId: 'hub' }); // Specify remote peer (hub)

// Request data from hub
const result = await agent.request('hub', 'getData', { id: 5 });

Multi-Tab Sync Pattern

import { CrossBus, BroadcastChannelTransport } from 'crossbus';

const bus = new CrossBus({ peerId: `tab-${Date.now()}`, allowedOrigins: ['*'] });
bus.addTransport(new BroadcastChannelTransport('my-app-channel'), { peerId: '*' });

bus.on('sync', (event) => console.log('Received:', event.data));
bus.signal('sync', { message: 'Hello tabs!' });