radio-faf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolfe James
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# mcpaas
+
+**Your AI forgets you every session. MCPaaS remembers.**
+
+You re-explain your stack to Claude. Switch to Gemini — re-explain everything. Open Cursor — again. Every session. Every tool. Every time.
+
+That's the drift tax. [$49M/day](https://fafdev.tools/value) burned industry-wide.
+
+This SDK connects you to [MCPaaS](https://mcpaas.live) — persistent AI context that follows you across tools, sessions, and teams.
+
+## Install
+
+```bash
+npm install mcpaas
+```
+
+## Quick Start
+
+```typescript
+import { Radio } from 'mcpaas';
+
+const radio = new Radio('wss://mcpaas.live/beacon/radio');
+await radio.connect();
+
+// Tune to your project's frequency
+await radio.tune('91.0');
+
+// Your context arrives — from any AI, any session
+radio.onBroadcast((frequency, context) => {
+  console.log(`Context update on ${frequency} FM:`, context);
+});
+```
+
+That's it. Your context persists. Zero drift.
+
+## How It Works
+
+MCPaaS uses the **Radio Protocol** — broadcast once, every AI receives.
+
+```
+Traditional (the tax):
+  You → Claude  (send 50KB context)
+  You → Grok    (send 50KB again)
+  You → Gemini  (send 50KB again)
+  = 3x cost, 3x latency, context drift
+
+Radio Protocol (the fix):
+  You → Broadcast to 91.0 FM (send once)
+  Claude  ← tuned to 91.0
+  Grok    ← tuned to 91.0
+  Gemini  ← tuned to 91.0
+  = 1x cost, instant, zero drift
+```
+
+## Multi-AI Example
+
+```typescript
+import { Radio } from 'mcpaas';
+
+const claude = new Radio('wss://mcpaas.live/beacon/radio');
+const grok   = new Radio('wss://mcpaas.live/beacon/radio');
+const gemini = new Radio('wss://mcpaas.live/beacon/radio');
+
+await Promise.all([claude.connect(), grok.connect(), gemini.connect()]);
+await Promise.all([claude.tune('91.0'), grok.tune('91.0'), gemini.tune('91.0')]);
+
+// All three AIs now share the same context, in real time
+claude.onBroadcast((f, ctx) => console.log('Claude:', ctx));
+grok.onBroadcast((f, ctx)   => console.log('Grok:', ctx));
+gemini.onBroadcast((f, ctx) => console.log('Gemini:', ctx));
+```
+
+## API
+
+### Constructor
+
+```typescript
+const radio = new Radio(url: string, options?: {
+  reconnect?: boolean;           // Auto-reconnect (default: true)
+  maxReconnectAttempts?: number; // Max attempts (default: 5)
+  reconnectDelay?: number;       // Delay in ms (default: 1000)
+  heartbeatInterval?: number;    // Ping interval (default: 30000)
+  debug?: boolean;               // Debug logging (default: false)
+});
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to MCPaaS |
+| `tune(frequency)` | Subscribe to a frequency |
+| `untune(frequency)` | Unsubscribe from a frequency |
+| `disconnect()` | Disconnect |
+| `getState()` | `'DISCONNECTED'` \| `'CONNECTING'` \| `'CONNECTED'` \| `'RECONNECTING'` \| `'CLOSED'` |
+| `getTunedFrequencies()` | Set of tuned frequencies |
+
+### Events
+
+| Event | Callback |
+|-------|----------|
+| `onBroadcast(fn)` | `(frequency, context) => void` |
+| `onConnect(fn)` | `() => void` |
+| `onDisconnect(fn)` | `(code?, reason?) => void` |
+| `onError(fn)` | `(error) => void` |
+| `onTuned(fn)` | `(frequency) => void` |
+| `onUntuned(fn)` | `(frequency) => void` |
+
+## Why Bun?
+
+Anthropic acquired Bun in December 2025. Bun now powers Claude Code. This library is built for Bun first — native TypeScript, 7x faster WebSockets, zero config.
+
+## Namepoints
+
+Every frequency maps to a **namepoint** on MCPaaS — your permanent AI identity.
+
+Free namepoints work. But `yourname.mcpaas.live` hits different than `user-38291.mcpaas.live`.
+
+**Claim yours before someone else does:** [mcpaas.live/claim](https://mcpaas.live/claim)
+
+If `mcpaas` has been useful, consider starring the repo — it helps others find it.
+
+## License
+
+MIT
+
+---
+
+Built by [Wolfe James](https://github.com/Wolfe-Jam) | Powered by [MCPaaS](https://mcpaas.live) | Format: [FAF](https://faf.one)

package/dist/index.js

@@ -0,0 +1,223 @@
+// @bun
+// src/radio.ts
+class Radio {
+  url;
+  ws = null;
+  state = "DISCONNECTED";
+  options;
+  handlers = {};
+  reconnectAttempts = 0;
+  heartbeatTimer = null;
+  tunedFrequencies = new Set;
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = {
+      reconnect: options.reconnect ?? true,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 5,
+      reconnectDelay: options.reconnectDelay ?? 1000,
+      heartbeatInterval: options.heartbeatInterval ?? 30000,
+      debug: options.debug ?? false
+    };
+  }
+  async connect() {
+    if (this.state === "CONNECTED" || this.state === "CONNECTING") {
+      this.log("Already connected or connecting");
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.state = "CONNECTING";
+      this.log(`Connecting to ${this.url}...`);
+      try {
+        this.ws = new WebSocket(this.url);
+        this.ws.onopen = () => {
+          this.state = "CONNECTED";
+          this.reconnectAttempts = 0;
+          this.log("Connected to Radio Protocol");
+          this.startHeartbeat();
+          this.handlers.onConnect?.();
+          resolve();
+        };
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event.data);
+        };
+        this.ws.onerror = (event) => {
+          const error = new Error("WebSocket error");
+          this.log("WebSocket error:", event);
+          this.handlers.onError?.(error);
+          reject(error);
+        };
+        this.ws.onclose = (event) => {
+          this.handleClose(event.code, event.reason);
+        };
+      } catch (error) {
+        this.state = "DISCONNECTED";
+        reject(error);
+      }
+    });
+  }
+  async tune(frequency) {
+    this.validateFrequency(frequency);
+    this.ensureConnected();
+    const message = {
+      action: "tune",
+      frequencies: [frequency]
+    };
+    this.send(message);
+    this.tunedFrequencies.add(frequency);
+    this.log(`Tuning to ${frequency} FM...`);
+  }
+  async untune(frequency) {
+    this.validateFrequency(frequency);
+    this.ensureConnected();
+    const message = {
+      action: "untune",
+      frequencies: [frequency]
+    };
+    this.send(message);
+    this.tunedFrequencies.delete(frequency);
+    this.log(`Untuning from ${frequency} FM...`);
+  }
+  disconnect() {
+    this.stopHeartbeat();
+    if (this.ws) {
+      this.state = "CLOSED";
+      this.ws.close();
+      this.ws = null;
+    }
+    this.tunedFrequencies.clear();
+    this.log("Disconnected");
+  }
+  onBroadcast(handler) {
+    this.handlers.onBroadcast = handler;
+  }
+  onConnect(handler) {
+    this.handlers.onConnect = handler;
+  }
+  onDisconnect(handler) {
+    this.handlers.onDisconnect = handler;
+  }
+  onError(handler) {
+    this.handlers.onError = handler;
+  }
+  onTuned(handler) {
+    this.handlers.onTuned = handler;
+  }
+  onUntuned(handler) {
+    this.handlers.onUntuned = handler;
+  }
+  getState() {
+    return this.state;
+  }
+  getTunedFrequencies() {
+    return new Set(this.tunedFrequencies);
+  }
+  handleMessage(data) {
+    try {
+      const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+      const message = JSON.parse(text);
+      this.log("Received:", message.type);
+      switch (message.type) {
+        case "connected":
+          this.log(`\u2705 ${message.message} (Client ID: ${message.clientId})`);
+          this.log("Available frequencies:", message.availableFrequencies);
+          break;
+        case "tuned":
+          message.frequencies.forEach((freq) => {
+            this.handlers.onTuned?.(freq);
+            this.log(`\u2705 Tuned to ${freq} FM`);
+          });
+          if (message.invalid.length > 0) {
+            this.log(`\u26A0\uFE0F Invalid frequencies: ${message.invalid.join(", ")}`);
+          }
+          break;
+        case "untuned":
+          message.frequencies.forEach((freq) => {
+            this.handlers.onUntuned?.(freq);
+            this.log(`\u2705 Untuned from ${freq} FM`);
+          });
+          break;
+        case "broadcast":
+          this.handlers.onBroadcast?.(message.frequency, message.event);
+          this.log(`\uD83D\uDCFB Broadcast from ${message.frequency} FM`);
+          break;
+        case "pong":
+          this.log("\uD83D\uDC93 Heartbeat");
+          break;
+        case "error":
+          const error = new Error(message.message);
+          this.handlers.onError?.(error);
+          this.log(`\u274C Error: ${message.message}`);
+          break;
+      }
+    } catch (error) {
+      this.log("Failed to parse message:", error);
+    }
+  }
+  handleClose(code, reason) {
+    this.stopHeartbeat();
+    this.state = "DISCONNECTED";
+    this.log(`Connection closed (${code}): ${reason}`);
+    this.handlers.onDisconnect?.(code, reason);
+    if (this.options.reconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+      this.reconnect();
+    }
+  }
+  async reconnect() {
+    this.reconnectAttempts++;
+    this.state = "RECONNECTING";
+    const delay = this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.options.maxReconnectAttempts})...`);
+    await Bun.sleep(delay);
+    try {
+      await this.connect();
+      for (const freq of this.tunedFrequencies) {
+        await this.tune(freq);
+      }
+    } catch (error) {
+      this.log("Reconnection failed:", error);
+    }
+  }
+  send(message) {
+    if (!this.ws || this.state !== "CONNECTED") {
+      throw new Error("Not connected to Radio Protocol server");
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.state === "CONNECTED") {
+        this.send({ action: "ping" });
+      }
+    }, this.options.heartbeatInterval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  validateFrequency(frequency) {
+    const pattern = /^[0-9]{1,3}\.[0-9]$/;
+    if (!pattern.test(frequency)) {
+      throw new Error(`Invalid frequency format: ${frequency}. Expected XX.X (e.g., "91.5")`);
+    }
+    const num = parseFloat(frequency);
+    if (num < 40 || num > 108) {
+      throw new Error(`Frequency out of range: ${frequency}. Must be between 40.0 and 108.0`);
+    }
+  }
+  ensureConnected() {
+    if (this.state !== "CONNECTED") {
+      throw new Error("Not connected. Call connect() first.");
+    }
+  }
+  log(...args) {
+    if (this.options.debug) {
+      console.log("[Radio]", ...args);
+    }
+  }
+}
+export {
+  Radio
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "radio-faf",
+  "version": "0.1.0",
+  "description": "Radio Protocol client for RadioFAF — AI Context Broadcasting via WebSocket. Built for Bun.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "project.faf"
+  ],
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "prepublishOnly": "bun run build",
+    "example": "bun run examples/basic.ts"
+  },
+  "keywords": [
+    "ai-context",
+    "persistent-context",
+    "mcpaas",
+    "websocket",
+    "bun",
+    "claude",
+    "grok",
+    "gemini",
+    "faf"
+  ],
+  "author": "Wolfe James",
+  "license": "MIT",
+  "peerDependencies": {
+    "bun-types": "^1.3.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wolfe-Jam/faf-radio-bun.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wolfe-Jam/faf-radio-bun/issues"
+  },
+  "homepage": "https://radiofaf.com"
+}

package/project.faf

@@ -0,0 +1,116 @@
+faf_version: 2.5.0
+generated: 2026-03-04T01:30:00.000Z
+ai_scoring_system: 2025-09-20
+ai_score: 85%
+ai_confidence: HIGH
+ai_value: 30_seconds_replaces_20_minutes_of_questions
+ai_tldr:
+  project: 'mcpaas - "Persistent AI context SDK — your AI remembers across tools, sessions, and teams"'
+  stack: TypeScript, Bun, WebSocket
+  quality_bar: production_ready
+  current_focus: npm publish as mcpaas@0.1.0
+  your_role: Build features with perfect context
+instant_context:
+  what_building: MCPaaS SDK — persistent AI context via Radio Protocol
+  tech_stack: TypeScript, Bun, WebSocket
+  main_language: TypeScript
+  key_files:
+    - src/radio.ts
+    - src/types.ts
+    - src/index.ts
+    - package.json
+context_quality:
+  slots_filled: 18/21 (86%)
+  ai_confidence: HIGH
+  handoff_ready: true
+  missing_context:
+    - CI/CD pipeline
+    - Database
+    - Authentication
+project:
+  name: mcpaas
+  goal: Persistent AI context SDK that connects to mcpaas.live via Radio Protocol
+  main_language: TypeScript
+  type: sdk
+ai_instructions:
+  priority_order:
+    - 1. Read THIS .faf file first
+    - 2. Check CLAUDE.md for session context
+    - 3. Review package.json for dependencies
+  working_style:
+    code_first: true
+    explanations: minimal
+    quality_bar: zero_errors
+    testing: required
+  warnings:
+    - All TypeScript must pass strict mode
+    - Test coverage required for new features
+    - Package name is mcpaas (not faf-radio-bun)
+stack:
+  package_manager: bun
+  targetUser: developers building AI applications
+  coreProblem: AI forgets context between sessions, tools, and teams
+  missionPurpose: WebSocket SDK for Radio Protocol — broadcast once, every AI receives
+  mainLanguage: TypeScript
+  runtime: Bun
+  frontend: None
+  backend: None
+  database: None
+  build: Bun
+  hosting: npm registry
+  cicd: None
+  testing: Bun Test + WJTTC (19/19 passing)
+  ui_library: None
+preferences:
+  quality_bar: zero_errors
+  commit_style: conventional_emoji
+  response_style: concise_code_first
+  explanation_level: minimal
+  communication: direct
+  testing: required
+  documentation: as_needed
+state:
+  phase: publish
+  version: 0.1.0
+  focus: npm_publish
+  status: green_flag
+  next_milestone: mcpaas@0.1.0 live on npm
+  blockers: null
+scores:
+  faf_score: 85
+  slot_based_percentage: 86
+  total_slots: 21
+tags:
+  auto_generated:
+    - mcpaas
+    - typescript
+    - bun
+    - websocket
+  smart_defaults:
+    - .faf
+    - ai-ready
+    - "2026"
+    - sdk
+    - open-source
+  user_defined: null
+human_context:
+  who: Developers using Claude, Grok, Gemini, Cursor — anyone tired of re-explaining context
+  what: MCPaaS SDK — persistent AI context via Radio Protocol (WebSocket broadcast)
+  why: Your AI forgets you every session. MCPaaS remembers. Broadcast once, every AI receives.
+  where: npm (mcpaas) + GitHub (Wolfe-Jam/faf-radio-bun) + mcpaas.live (hosted service)
+  when: v0.1.0 ready to publish — 19/19 tests passing, 6.6KB tarball
+  how: npm install mcpaas → connect to mcpaas.live → tune to frequency → context persists
+  additional_context: Part of MCPaaS ecosystem. SDK connects to mcpaas.live (Cloudflare Workers, 300+ edge locations). IANA-registered format (application/vnd.faf+yaml).
+  context_score: 100
+  total_prd_score: 100
+  success_rate: 100%
+faf_dna:
+  birth_dna: 43
+  birth_certificate: FAF-2026-FAFRADIO-7PMX
+  birth_date: 2026-02-13T03:38:41.451Z
+  current_score: 85
+stack_signature: typescript-bun-websocket
+detected_frameworks:
+  - Bun
+  - TypeScript
+  - WebSocket

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @faf/radio-bun
+ *
+ * Radio Protocol client for Bun - AI Context Broadcasting
+ * Built for Bun, Claude's Runtime
+ *
+ * @example
+ * ```typescript
+ * import { Radio } from '@faf/radio-bun';
+ *
+ * const radio = new Radio('wss://mcpaas.live/beacon/radio');
+ * await radio.connect();
+ * await radio.tune('91.5');
+ * radio.onBroadcast((freq, msg) => console.log(freq, msg));
+ * ```
+ */
+
+export { Radio } from './radio';
+export type * from './types';

package/src/radio.ts

@@ -0,0 +1,356 @@
+/**
+ * Radio Protocol Client for Bun
+ * Built for Bun - Claude's Runtime
+ *
+ * @example
+ * ```typescript
+ * const radio = new Radio('wss://mcpaas.live/beacon/radio');
+ * await radio.connect();
+ * await radio.tune('91.5');
+ * radio.onBroadcast((freq, msg) => console.log(freq, msg));
+ * await radio.broadcast('91.5', { hello: 'world' });
+ * ```
+ */
+
+import type {
+  Frequency,
+  RadioOptions,
+  RadioEventHandlers,
+  ConnectionState,
+  ServerMessage,
+  ClientMessage,
+  BroadcastReceivedMessage,
+} from './types';
+
+export class Radio {
+  private url: string;
+  private ws: WebSocket | null = null;
+  private state: ConnectionState = 'DISCONNECTED';
+  private options: Required<RadioOptions>;
+  private handlers: RadioEventHandlers = {};
+  private reconnectAttempts = 0;
+  private heartbeatTimer: Timer | null = null;
+  private tunedFrequencies = new Set<Frequency>();
+
+  constructor(url: string, options: RadioOptions = {}) {
+    this.url = url;
+    this.options = {
+      reconnect: options.reconnect ?? true,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 5,
+      reconnectDelay: options.reconnectDelay ?? 1000,
+      heartbeatInterval: options.heartbeatInterval ?? 30000,
+      debug: options.debug ?? false,
+    };
+  }
+
+  /**
+   * Connect to Radio Protocol server
+   */
+  async connect(): Promise<void> {
+    if (this.state === 'CONNECTED' || this.state === 'CONNECTING') {
+      this.log('Already connected or connecting');
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.state = 'CONNECTING';
+      this.log(`Connecting to ${this.url}...`);
+
+      try {
+        this.ws = new WebSocket(this.url);
+
+        this.ws.onopen = () => {
+          this.state = 'CONNECTED';
+          this.reconnectAttempts = 0;
+          this.log('Connected to Radio Protocol');
+          this.startHeartbeat();
+          this.handlers.onConnect?.();
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event.data);
+        };
+
+        this.ws.onerror = (event) => {
+          const error = new Error('WebSocket error');
+          this.log('WebSocket error:', event);
+          this.handlers.onError?.(error);
+          reject(error);
+        };
+
+        this.ws.onclose = (event) => {
+          this.handleClose(event.code, event.reason);
+        };
+      } catch (error) {
+        this.state = 'DISCONNECTED';
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Tune to a frequency (subscribe)
+   */
+  async tune(frequency: Frequency): Promise<void> {
+    this.validateFrequency(frequency);
+    this.ensureConnected();
+
+    const message: ClientMessage = {
+      action: 'tune',
+      frequencies: [frequency],
+    };
+
+    this.send(message);
+    this.tunedFrequencies.add(frequency);
+    this.log(`Tuning to ${frequency} FM...`);
+  }
+
+  /**
+   * Untune from a frequency (unsubscribe)
+   */
+  async untune(frequency: Frequency): Promise<void> {
+    this.validateFrequency(frequency);
+    this.ensureConnected();
+
+    const message: ClientMessage = {
+      action: 'untune',
+      frequencies: [frequency],
+    };
+
+    this.send(message);
+    this.tunedFrequencies.delete(frequency);
+    this.log(`Untuning from ${frequency} FM...`);
+  }
+
+  /**
+   * Disconnect from server
+   */
+  disconnect(): void {
+    this.stopHeartbeat();
+    if (this.ws) {
+      this.state = 'CLOSED';
+      this.ws.close();
+      this.ws = null;
+    }
+    this.tunedFrequencies.clear();
+    this.log('Disconnected');
+  }
+
+  /**
+   * Event: On broadcast received
+   */
+  onBroadcast(handler: (frequency: Frequency, message: any) => void): void {
+    this.handlers.onBroadcast = handler;
+  }
+
+  /**
+   * Event: On connection established
+   */
+  onConnect(handler: () => void): void {
+    this.handlers.onConnect = handler;
+  }
+
+  /**
+   * Event: On disconnection
+   */
+  onDisconnect(handler: (code?: number, reason?: string) => void): void {
+    this.handlers.onDisconnect = handler;
+  }
+
+  /**
+   * Event: On error
+   */
+  onError(handler: (error: Error) => void): void {
+    this.handlers.onError = handler;
+  }
+
+  /**
+   * Event: On tuned confirmation
+   */
+  onTuned(handler: (frequency: Frequency) => void): void {
+    this.handlers.onTuned = handler;
+  }
+
+  /**
+   * Event: On untuned confirmation
+   */
+  onUntuned(handler: (frequency: Frequency) => void): void {
+    this.handlers.onUntuned = handler;
+  }
+
+  /**
+   * Get current connection state
+   */
+  getState(): ConnectionState {
+    return this.state;
+  }
+
+  /**
+   * Get list of tuned frequencies
+   */
+  getTunedFrequencies(): Set<Frequency> {
+    return new Set(this.tunedFrequencies);
+  }
+
+  /**
+   * Handle incoming server message
+   */
+  private handleMessage(data: string | Blob | ArrayBuffer): void {
+    try {
+      const text = typeof data === 'string' ? data : new TextDecoder().decode(data as ArrayBuffer);
+      const message: ServerMessage = JSON.parse(text);
+
+      this.log('Received:', message.type);
+
+      switch (message.type) {
+        case 'connected':
+          this.log(`✅ ${message.message} (Client ID: ${message.clientId})`);
+          this.log('Available frequencies:', message.availableFrequencies);
+          break;
+
+        case 'tuned':
+          // Call handler for each tuned frequency
+          message.frequencies.forEach(freq => {
+            this.handlers.onTuned?.(freq);
+            this.log(`✅ Tuned to ${freq} FM`);
+          });
+          if (message.invalid.length > 0) {
+            this.log(`⚠️ Invalid frequencies: ${message.invalid.join(', ')}`);
+          }
+          break;
+
+        case 'untuned':
+          // Call handler for each untuned frequency
+          message.frequencies.forEach(freq => {
+            this.handlers.onUntuned?.(freq);
+            this.log(`✅ Untuned from ${freq} FM`);
+          });
+          break;
+
+        case 'broadcast':
+          this.handlers.onBroadcast?.(message.frequency, message.event);
+          this.log(`📻 Broadcast from ${message.frequency} FM`);
+          break;
+
+        case 'pong':
+          this.log('💓 Heartbeat');
+          break;
+
+        case 'error':
+          const error = new Error(message.message);
+          this.handlers.onError?.(error);
+          this.log(`❌ Error: ${message.message}`);
+          break;
+      }
+    } catch (error) {
+      this.log('Failed to parse message:', error);
+    }
+  }
+
+  /**
+   * Handle connection close
+   */
+  private handleClose(code?: number, reason?: string): void {
+    this.stopHeartbeat();
+    this.state = 'DISCONNECTED';
+    this.log(`Connection closed (${code}): ${reason}`);
+    this.handlers.onDisconnect?.(code, reason);
+
+    // Auto-reconnect if enabled
+    if (this.options.reconnect && this.reconnectAttempts < this.options.maxReconnectAttempts) {
+      this.reconnect();
+    }
+  }
+
+  /**
+   * Reconnect with exponential backoff
+   */
+  private async reconnect(): Promise<void> {
+    this.reconnectAttempts++;
+    this.state = 'RECONNECTING';
+
+    const delay = this.options.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+    this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.options.maxReconnectAttempts})...`);
+
+    await Bun.sleep(delay);
+
+    try {
+      await this.connect();
+
+      // Re-tune to all previously tuned frequencies
+      for (const freq of this.tunedFrequencies) {
+        await this.tune(freq);
+      }
+    } catch (error) {
+      this.log('Reconnection failed:', error);
+    }
+  }
+
+  /**
+   * Send message to server
+   */
+  private send(message: ClientMessage): void {
+    if (!this.ws || this.state !== 'CONNECTED') {
+      throw new Error('Not connected to Radio Protocol server');
+    }
+
+    this.ws.send(JSON.stringify(message));
+  }
+
+  /**
+   * Start heartbeat timer
+   */
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+
+    this.heartbeatTimer = setInterval(() => {
+      if (this.state === 'CONNECTED') {
+        this.send({ action: 'ping' });
+      }
+    }, this.options.heartbeatInterval);
+  }
+
+  /**
+   * Stop heartbeat timer
+   */
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Validate frequency format
+   */
+  private validateFrequency(frequency: Frequency): void {
+    const pattern = /^[0-9]{1,3}\.[0-9]$/;
+    if (!pattern.test(frequency)) {
+      throw new Error(`Invalid frequency format: ${frequency}. Expected XX.X (e.g., "91.5")`);
+    }
+
+    const num = parseFloat(frequency);
+    if (num < 40.0 || num > 108.0) {
+      throw new Error(`Frequency out of range: ${frequency}. Must be between 40.0 and 108.0`);
+    }
+  }
+
+  /**
+   * Ensure client is connected
+   */
+  private ensureConnected(): void {
+    if (this.state !== 'CONNECTED') {
+      throw new Error('Not connected. Call connect() first.');
+    }
+  }
+
+  /**
+   * Debug logging
+   */
+  private log(...args: any[]): void {
+    if (this.options.debug) {
+      console.log('[Radio]', ...args);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Radio Protocol Types for Bun
+ * Built for Bun - Claude's Runtime
+ */
+
+/**
+ * Radio Protocol message types (from protocol spec)
+ */
+export type MessageType =
+  | 'TUNE'      // Subscribe to frequency
+  | 'UNTUNE'    // Unsubscribe from frequency
+  | 'BROADCAST' // Send message to frequency
+  | 'PING'      // Heartbeat
+  | 'TUNED'     // Confirmation of tune
+  | 'UNTUNED'   // Confirmation of untune
+  | 'PONG'      // Heartbeat response
+  | 'ERROR';    // Error response
+
+/**
+ * Frequency format: XX.X (e.g., "91.5")
+ * Range: 40.0 - 108.0 FM
+ */
+export type Frequency = string;
+
+/**
+ * Client → Server messages
+ * Note: Server expects "action" field (not "type") and "frequencies" array
+ */
+export interface TuneMessage {
+  action: 'tune';
+  frequencies: Frequency[];
+}
+
+export interface UntuneMessage {
+  action: 'untune';
+  frequencies: Frequency[];
+}
+
+export interface PingMessage {
+  action: 'ping';
+}
+
+export type ClientMessage =
+  | TuneMessage
+  | UntuneMessage
+  | PingMessage;
+
+/**
+ * Server → Client messages
+ * Note: Server sends lowercase "type" values
+ */
+export interface ConnectedMessage {
+  type: 'connected';
+  clientId: string;
+  message: string;
+  availableFrequencies: Record<string, string>;
+}
+
+export interface TunedMessage {
+  type: 'tuned';
+  frequencies: Frequency[];
+  invalid: Frequency[];
+  souls: Array<{ frequency: Frequency; soul: string }>;
+}
+
+export interface UntunedMessage {
+  type: 'untuned';
+  frequencies: Frequency[];
+}
+
+export interface BroadcastReceivedMessage {
+  type: 'broadcast';
+  frequency: Frequency;
+  event: any;
+  timestamp?: number;
+}
+
+export interface PongMessage {
+  type: 'pong';
+  timestamp: number;
+}
+
+export interface ErrorMessage {
+  type: 'error';
+  message: string;
+}
+
+export type ServerMessage =
+  | ConnectedMessage
+  | TunedMessage
+  | UntunedMessage
+  | BroadcastReceivedMessage
+  | PongMessage
+  | ErrorMessage;
+
+/**
+ * Radio client options
+ */
+export interface RadioOptions {
+  /** Enable automatic reconnection (default: true) */
+  reconnect?: boolean;
+
+  /** Max reconnection attempts (default: 5) */
+  maxReconnectAttempts?: number;
+
+  /** Reconnection delay in ms (default: 1000) */
+  reconnectDelay?: number;
+
+  /** Heartbeat interval in ms (default: 30000) */
+  heartbeatInterval?: number;
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * Radio connection state
+ */
+export type ConnectionState =
+  | 'DISCONNECTED'
+  | 'CONNECTING'
+  | 'CONNECTED'
+  | 'RECONNECTING'
+  | 'CLOSED';
+
+/**
+ * Event handlers
+ */
+export interface RadioEventHandlers {
+  onConnect?: () => void;
+  onDisconnect?: (code?: number, reason?: string) => void;
+  onError?: (error: Error) => void;
+  onBroadcast?: (frequency: Frequency, message: any) => void;
+  onTuned?: (frequency: Frequency) => void;
+  onUntuned?: (frequency: Frequency) => void;
+}