webview.io 1.0.5 → 1.1.0

package/README.md

@@ -106,9 +106,11 @@ function MapComponent() {
 
 ```javascript
 // In your HTML/JS loaded in the WebView
+// The bridge is automatically available as window._wio after injection
 
-// The bridge is automatically available as window._wio
+// IMPORTANT: You must manually call listen() to start the connection
 const wio = window._wio
+wio.listen() // Required to initiate connection handshake
 
 // Handle connection
 wio.on('connect', () => {
@@ -140,7 +142,9 @@ const wio = new WIO({
   maxMessageSize: 1024 * 1024,       // Max message size in bytes (1MB)
   maxMessagesPerSecond: 100,         // Rate limit (100 messages/second)
   autoReconnect: true,               // Enable automatic reconnection
-  messageQueueSize: 50               // Max queued messages when disconnected
+  messageQueueSize: 50,              // Max queued messages when disconnected
+  allowedIncomingEvents: ['hello', 'response'], // Optional incoming event allowlist (non-reserved events)
+  validateIncoming: (event, payload) => true    // Optional custom incoming validator
 })
 ```
 
@@ -180,12 +184,28 @@ This prevents:
 - Fires `connect_timeout` event if all attempts fail
 
 **EMBEDDED Side:**
-- Automatically announces `__embedded_ready` when loaded
+- Bridge is available as `window._wio` after injection
+- **Must manually call `window._wio.listen()` to start connection**
+- Automatically announces `__embedded_ready` when `listen()` is called
 - Retries announcement every 2 seconds until connected
 - Handles race condition if loaded before React Native
 - Responds to `ping` with `pong` containing same token
 - Confirms connection upon receiving `__connection_ack`
 
+## Reserved Events
+
+The library uses several internal events for connection management. These events are handled automatically and **bypass normal message queuing** to ensure reliable connection establishment:
+
+- **`ping`** - Initial connection request from WEBVIEW
+- **`pong`** - Connection response from EMBEDDED
+- **`__heartbeat`** - Periodic health check request
+- **`__heartbeat_response`** - Health check response
+- **`__embedded_ready`** - EMBEDDED announces it's ready to connect
+- **`__connection_ack`** - Final handshake acknowledgment from WEBVIEW
+- **`__webview_ready`** - Signal that WEBVIEW peer is ready (currently logged but not actively used)
+
+**Important:** These events are sent immediately even when disconnected, unlike regular events which are queued. Do not use these event names for your application logic.
+
 ## Async/Await Support
 
 ### Send Messages with Acknowledgments
@@ -231,7 +251,7 @@ console.log('User data received:', userData)
 ### Connection Timeout Handling
 
 ```javascript
-// Handle connection timeout (new event)
+// Handle connection timeout
 wio.on('connect_timeout', ({ attempts }) => {
   console.log(`Failed to connect after ${attempts} attempts`)
   // Optionally retry manually or show error to user
@@ -267,13 +287,13 @@ const stats = wio.getStats()
 console.log(stats)
 // {
 //   connected: true,
-//   embeddedReady: true,              // NEW: EMBEDDED peer readiness state
+//   embeddedReady: true,              // EMBEDDED peer readiness state
 //   peerType: 'WEBVIEW',
 //   origin: 'https://example.com',
 //   lastHeartbeat: 1609459200000,
 //   queuedMessages: 0,
 //   reconnectAttempts: 0,
-//   connectionAttempts: 0,            // NEW: Current connection attempts
+//   connectionAttempts: 0,            // Current connection attempts
 //   activeListeners: 5,
 //   messageRate: 2
 // }
@@ -288,7 +308,7 @@ Each connection uses a unique token for validation:
 ```javascript
 // Automatically generated and validated during handshake
 // Prevents accepting messages from previous connections
-// Tokens are only used for connection-related events
+// Tokens are only used for reserved connection events
 ```
 
 ### Origin Validation
@@ -312,6 +332,29 @@ wio.emit('data', {
 })
 ```
 
+### Incoming Event Allowlist & Validation
+
+For defense-in-depth, you can restrict which **application-level** events are accepted and/or validate incoming payloads. Reserved internal events (handshake/heartbeat/readiness) are always allowed.
+
+```javascript
+const wio = new WIO({
+  type: 'WEBVIEW',
+  debug: true,
+  allowedIncomingEvents: ['get:location', 'location:picked'],
+  validateIncoming: (event, payload) => {
+    // Example: simple checks
+    if (event === 'location:picked') return payload && typeof payload.lat === 'number'
+    return true
+  }
+})
+
+wio.on('error', (error) => {
+  if (error.type === 'DISALLOWED_EVENT' || error.type === 'INVALID_MESSAGE') {
+    console.warn('Dropped incoming message:', error)
+  }
+})
+```
+
 ### Rate Limiting
 
 ```javascript
@@ -356,6 +399,7 @@ wio.on('error', (error) => {
 
 ```javascript
 // Messages are automatically queued when disconnected
+// Reserved events bypass the queue for reliable connection handling
 wio.emit('important-data', { data: 'This will be queued if disconnected' })
 
 // Clear queue manually if needed
@@ -382,7 +426,7 @@ console.log(`${stats.queuedMessages} messages queued`)
 
 #### Connection Methods
 - **`initiate(webViewRef, origin)`** - Establish connection with retry logic (WEBVIEW peer only)
-- **`listen(hostOrigin?)`** - Listen for connection with readiness announcement (EMBEDDED peer only)
+- **`listen(hostOrigin?)`** - Start listening for connection (EMBEDDED peer only). The `hostOrigin` parameter is informational only and used for logging - no validation is performed.
 - **`handleMessage(event)`** - Handle incoming message from WebView
 - **`disconnect(callback?)`** - Disconnect and cleanup all resources
 - **`isConnected()`** - Check connection status
@@ -399,15 +443,19 @@ console.log(`${stats.queuedMessages} messages queued`)
 #### Connection Events
 - **`connect`** - Connection established (after 3-way handshake)
 - **`disconnect`** - Connection lost with reason
-- **`connect_timeout`** - Initial connection failed after all attempts (NEW)
+- **`connect_timeout`** - Initial connection failed after all attempts
 - **`reconnecting`** - Reconnection attempt started
 - **`reconnection_failed`** - All reconnection attempts failed
 
-#### Internal Events (handled automatically)
+#### Reserved Internal Events
+These events are handled automatically by the library. Do not use these names for your application events:
+- **`ping`** - Connection initiation from WEBVIEW
+- **`pong`** - Connection response from EMBEDDED
 - **`__embedded_ready`** - EMBEDDED peer announces readiness
 - **`__connection_ack`** - Final acknowledgment in 3-way handshake
-- **`__heartbeat`** - Connection health check
+- **`__heartbeat`** - Connection health check request
 - **`__heartbeat_response`** - Heartbeat response
+- **`__webview_ready`** - WEBVIEW ready signal (informational)
 
 #### Error Events
 - **`error`** - Various error conditions with detailed error objects
@@ -575,6 +623,8 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 | `MESSAGE_HANDLING_ERROR` | Error processing incoming message |
 | `EMIT_ERROR` | Error sending message |
 | `LISTENER_ERROR` | Error in event listener |
+| `DISALLOWED_EVENT` | Incoming event rejected by `allowedIncomingEvents` |
+| `INVALID_MESSAGE` | Incoming message rejected by `validateIncoming` |
 | `RATE_LIMIT_EXCEEDED` | Too many messages sent |
 | `NO_CONNECTION` | Attempted to send without connection |
 
@@ -600,12 +650,13 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 **Symptoms:** `connect_timeout` event fires, connection never succeeds
 
 **Solutions:**
-1. Check that `injectedJavaScript` is properly set on WebView
-2. Verify `javaScriptEnabled={true}` is set
-3. Check browser console for JavaScript errors in WebView
-4. Ensure origin matches exactly (including protocol)
-5. Increase `connectionTimeout` for slow networks
-6. Check that WebView content loads successfully
+1. **Verify `listen()` is called** - The EMBEDDED side must manually call `window._wio.listen()` to start the connection
+2. Check that `injectedJavaScript` is properly set on WebView
+3. Verify `javaScriptEnabled={true}` is set
+4. Check browser console for JavaScript errors in WebView
+5. Ensure origin matches exactly (including protocol)
+6. Increase `connectionTimeout` for slow networks
+7. Check that WebView content loads successfully
 
 ### Messages Not Received
 
@@ -617,6 +668,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 3. Look for errors in `error` event listener
 4. Check if rate limiting is being exceeded
 5. Verify message size is under `maxMessageSize`
+6. Ensure you're not using reserved event names
 
 ### Frequent Disconnections
 
@@ -637,7 +689,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - Already handled! The three-way handshake with readiness announcements prevents this
 - EMBEDDED announces readiness periodically until connected
 - WEBVIEW retries connection attempts automatically
-- No action needed from your side
+- Just ensure `window._wio.listen()` is called in your WebView code
 
 ## Differences from iframe.io
 
@@ -647,6 +699,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - **Initialization**: Uses `RefObject<WebView>` instead of `Window` object
 - **Message Handling**: Requires explicit `handleMessage()` call in `onMessage` prop
 - **Injected Script**: Uses `getInjectedJavaScript()` to setup bridge in WebView
+- **Manual Connection**: EMBEDDED side must call `listen()` to start connection
 - **No DOM Dependencies**: Works in React Native environment without DOM APIs
 - **Enhanced Handshake**: Three-way handshake with token validation for mobile reliability
 - **Connection Retry**: Built-in retry logic for spotty mobile connections

package/dist/index.d.ts

@@ -14,6 +14,16 @@ export type Options = {
     messageQueueSize?: number;
     connectionPingInterval?: number;
     maxConnectionAttempts?: number;
+    /**
+     * Optional allowlist of incoming application-level events.
+     * Reserved internal events (ping/pong/heartbeat/handshake) are always allowed.
+     */
+    allowedIncomingEvents?: string[];
+    /**
+     * Optional custom validator for incoming messages.
+     * Return false to drop a message; an 'error' event will be emitted.
+     */
+    validateIncoming?: (event: string, payload: any) => boolean;
 };
 export interface RegisteredEvents {
     [index: string]: Listener[];
@@ -78,6 +88,9 @@ export default class WIO {
     initiate(webViewRef: RefObject<WebView>, origin: string): this;
     /**
      * Listening to connection from the WebView host
+     *
+     * NOTE: This is called manually from page code,
+     * not auto-initialized
      */
     listen(hostOrigin?: string): this;
     /**
@@ -115,6 +128,7 @@ export default class WIO {
     /**
      * Get injected JavaScript for WebView
      * Sets up the EMBEDDED side of the bridge
+     * NOTE: Does not auto-initialize - page must call window._wio.listen()
      */
     getInjectedJavaScript(): string;
 }

package/dist/index.js

@@ -45,6 +45,22 @@ var ackId = function () {
     return "".concat(timestamp, "_").concat(random);
 };
 var generateToken = function () {
+    // Prefer cryptographically strong randomness when available
+    try {
+        var globalCrypto = (typeof crypto !== 'undefined'
+            ? crypto
+            : (typeof window !== 'undefined' && window.crypto)
+                || (typeof globalThis !== 'undefined' && globalThis.crypto));
+        if (globalCrypto && typeof globalCrypto.getRandomValues === 'function') {
+            var buffer = new Uint32Array(4);
+            globalCrypto.getRandomValues(buffer);
+            var randomPart = Array.from(buffer).map(function (n) { return n.toString(16); }).join('');
+            return "".concat(Date.now(), "_").concat(randomPart);
+        }
+    }
+    catch (_a) {
+        // Fall back to Math.random-based implementation below
+    }
     return "".concat(Date.now(), "_").concat(Math.random().toString(36).substring(2, 15));
 };
 var RESERVED_EVENTS = [
@@ -143,13 +159,9 @@ var WIO = /** @class */ (function () {
             _this.connectionAttempts = 0;
             _this.connectionToken = generateToken();
             // Re-initiate connection for WEBVIEW type
-            if (_this.peer.type === 'WEBVIEW') {
-                _this.startConnectionAttempt();
-            }
+            _this.peer.type === 'WEBVIEW' && _this.startConnectionAttempt();
             // For EMBEDDED type, announce readiness
-            if (_this.peer.type === 'EMBEDDED') {
-                _this.announceEmbeddedReady();
-            }
+            _this.peer.type === 'EMBEDDED' && _this.announceEmbeddedReady();
             // Set timeout for this reconnection attempt
             setTimeout(function () {
                 if (_this.peer.connected)
@@ -181,9 +193,8 @@ var WIO = /** @class */ (function () {
                 _this.debug("[".concat(_this.peer.type, "] Connection attempt ").concat(_this.connectionAttempts, "/").concat(_this.options.maxConnectionAttempts));
                 _this.emit('ping', { token: _this.connectionToken });
             }
-            else {
+            else
                 _this.stopConnectionAttempt();
-            }
         }, this.options.connectionPingInterval);
         // Set overall timeout
         this.connectionAttemptTimer = setTimeout(function () {
@@ -225,16 +236,15 @@ var WIO = /** @class */ (function () {
                 _this.debug("[".concat(_this.peer.type, "] Ready announcement attempt ").concat(attempts, "/").concat(maxAttempts));
                 _this.emit('__embedded_ready');
             }
-            else {
+            else
                 _this.stopEmbeddedReadyAnnouncement();
-            }
         }, this.options.connectionPingInterval);
     };
     WIO.prototype.stopEmbeddedReadyAnnouncement = function () {
-        if (this.embeddedReadyCheckInterval) {
-            clearInterval(this.embeddedReadyCheckInterval);
-            this.embeddedReadyCheckInterval = undefined;
-        }
+        if (!this.embeddedReadyCheckInterval)
+            return;
+        clearInterval(this.embeddedReadyCheckInterval);
+        this.embeddedReadyCheckInterval = undefined;
     };
     // Message rate limiting
     WIO.prototype.checkRateLimit = function () {
@@ -257,8 +267,8 @@ var WIO = /** @class */ (function () {
     };
     // Queue messages when not connected
     WIO.prototype.queueMessage = function (_event, payload, fn) {
+        // Remove oldest message
         if (this.messageQueue.length >= this.options.messageQueueSize) {
-            // Remove oldest message
             var removed = this.messageQueue.shift();
             this.debug("[".concat(this.peer.type, "] Message queue full, removed oldest message:"), removed === null || removed === void 0 ? void 0 : removed._event);
         }
@@ -311,6 +321,9 @@ var WIO = /** @class */ (function () {
     };
     /**
      * Listening to connection from the WebView host
+     *
+     * NOTE: This is called manually from page code,
+     * not auto-initialized
      */
     WIO.prototype.listen = function (hostOrigin) {
         var _this = this;
@@ -320,9 +333,7 @@ var WIO = /** @class */ (function () {
         this.reconnectAttempts = 0;
         this.debug("[".concat(this.peer.type, "] Listening to connect").concat(hostOrigin ? ": Host <".concat(hostOrigin, ">") : ''));
         // Start announcing readiness
-        setTimeout(function () {
-            _this.announceEmbeddedReady();
-        }, 100);
+        setTimeout(function () { return _this.announceEmbeddedReady(); }, 100);
         return this;
     };
     /**
@@ -359,9 +370,9 @@ var WIO = /** @class */ (function () {
                 this.peer.embeddedReady = true;
                 this.debug("[".concat(this.peer.type, "] Embedded peer ready"));
                 // If we're WEBVIEW and not connected, send ping
-                if (this.peer.type === 'WEBVIEW' && !this.peer.connected) {
-                    this.emit('ping', { token: this.connectionToken });
-                }
+                this.peer.type === 'WEBVIEW'
+                    && !this.peer.connected
+                    && this.emit('ping', { token: this.connectionToken });
                 return;
             }
             // Handle webview ready signal
@@ -424,6 +435,27 @@ var WIO = /** @class */ (function () {
                 }
                 return;
             }
+            // Optional application-level incoming validation (non-reserved events only)
+            if (!RESERVED_EVENTS.includes(_event)) {
+                if (this.options.allowedIncomingEvents
+                    && !this.options.allowedIncomingEvents.includes(_event)) {
+                    this.fire('error', {
+                        type: 'DISALLOWED_EVENT',
+                        direction: 'incoming',
+                        event: _event
+                    });
+                    return;
+                }
+                if (this.options.validateIncoming
+                    && !this.options.validateIncoming(_event, payload)) {
+                    this.fire('error', {
+                        type: 'INVALID_MESSAGE',
+                        direction: 'incoming',
+                        event: _event
+                    });
+                    return;
+                }
+            }
             // Fire available event listeners
             this.fire(_event, payload, cid);
         }
@@ -583,9 +615,7 @@ var WIO = /** @class */ (function () {
         var _this = this;
         if (timeout === void 0) { timeout = 5000; }
         return new Promise(function (resolve, reject) {
-            var timeoutId = setTimeout(function () {
-                reject(new Error("Event '".concat(_event, "' acknowledgment timeout after ").concat(timeout, "ms")));
-            }, timeout);
+            var timeoutId = setTimeout(function () { return reject(new Error("Event '".concat(_event, "' acknowledgment timeout after ").concat(timeout, "ms"))); }, timeout);
             try {
                 _this.emit(_event, payload, function (error) {
                     var args = [];
@@ -677,9 +707,10 @@ var WIO = /** @class */ (function () {
     /**
      * Get injected JavaScript for WebView
      * Sets up the EMBEDDED side of the bridge
+     * NOTE: Does not auto-initialize - page must call window._wio.listen()
      */
     WIO.prototype.getInjectedJavaScript = function () {
-        return "\n      (function() {\n        try {\n          console.log('[EMBEDDED] Initializing WIO bridge...')\n          \n          const RESERVED_EVENTS = [\n            'ping',\n            'pong',\n            '__heartbeat',\n            '__heartbeat_response',\n            '__embedded_ready',\n            '__connection_ack',\n            '__webview_ready'\n          ]\n          \n          // Use closure variable to avoid 'this' binding issues\n          window._wio = {\n            type: 'EMBEDDED',\n            connected: false,\n            Events: {},\n            messageQueue: [],\n            connectionToken: null,\n            setupComplete: false,\n\n            listen: function(){\n              console.log('[EMBEDDED] Setting up message listeners...')\n\n              // Listen to messages from React Native\n              window.addEventListener('message', function( event ){\n                try {\n                  const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                  window._wio.handleMessage( message )  // Use window._wio instead of this\n                }\n                catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n              })\n              \n              // Android support\n              if( typeof document !== 'undefined' ){\n                document.addEventListener('message', function( event ){\n                  try {\n                    const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                    window._wio.handleMessage( message )  // Use window._wio instead of this\n                  }\n                  catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n                })\n              }\n\n              window._wio.setupComplete = true  // Use window._wio instead of this\n              console.log('[EMBEDDED] Setup complete')\n\n              return window._wio\n            },\n            \n            ackId: function(){\n              const\n              rmin = 100000,\n              rmax = 999999,\n              timestamp = Date.now(),\n              random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )\n\n              return timestamp + '_' + random\n            },\n            \n            fire: function( _event, payload, cid ){\n              if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){\n                console.log('[EMBEDDED] No listener for:', _event)\n                return\n              }\n              \n              const ackFn = cid\n                ? ( error, ...args ) => window._wio.emit( _event + '--' + cid + '--@ack', { error: error || false, args } )\n                : undefined\n              \n              let listeners = []\n              if( window._wio.Events[_event + '--@once'] ){\n                _event += '--@once'\n                listeners = window._wio.Events[_event]\n\n                delete window._wio.Events[_event]\n              }\n              else listeners = window._wio.Events[_event] || []\n              \n              listeners.forEach( fn => {\n                try { payload !== undefined ? fn( payload, ackFn ) : fn( ackFn ) }\n                catch( error ){ console.error('[EMBEDDED] Listener error:', error ) }\n              })\n            },\n            \n            emit: function( _event, payload, fn ){\n              if( typeof payload === 'function' ){\n                fn = payload\n                payload = undefined\n              }\n              \n              if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){\n                window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })\n                console.log('[EMBEDDED] Queued message:', _event)\n                return\n              }\n              \n              try {\n                let cid\n                if( typeof fn === 'function' ){\n                  cid = window._wio.ackId()\n                  window._wio.once( _event + '--' + cid + '--@ack', ({ error, args }) => fn( error, ...args ) )\n                }\n                \n                const messageData = {\n                  _event,\n                  payload,\n                  cid,\n                  timestamp: Date.now(),\n                  token: RESERVED_EVENTS.includes(_event) ? window._wio.connectionToken : undefined\n                }\n                \n                if( typeof window.ReactNativeWebView !== 'undefined' )\n                  window.ReactNativeWebView.postMessage( JSON.stringify( messageData ) )\n                else console.error('[EMBEDDED] ReactNativeWebView not available')\n              }\n              catch( error ){\n                console.error('[EMBEDDED] Emit error:', error )\n                typeof fn === 'function' && fn( String(error) )\n              }\n            },\n            \n            on: function( _event, fn ){\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            once: function( _event, fn ){\n              _event += '--@once'\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            off: function( _event, fn ){\n              if( fn && window._wio.Events[_event] ){\n                const index = window._wio.Events[_event].indexOf( fn )\n                if( index > -1 ){\n                  window._wio.Events[_event].splice( index, 1 )\n                  if( window._wio.Events[_event].length === 0 ) delete window._wio.Events[_event]\n                }\n              }\n              else delete window._wio.Events[_event]\n\n              return window._wio\n            },\n            \n            processMessageQueue: function(){\n              if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return\n              \n              console.log('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')\n              const queue = [ ...window._wio.messageQueue ]\n              window._wio.messageQueue = []\n              \n              queue.forEach( msg => {\n                try { window._wio.emit( msg._event, msg.payload, msg.fn ) }\n                catch( error ){ console.error('[EMBEDDED] Queue process error:', error ) }\n              })\n            },\n            \n            handleMessage: function( data ){\n              if( !data || !data._event ) return\n              \n              const { _event, payload, cid, token } = data\n              \n              console.log('[EMBEDDED] Received:', _event )\n              \n              // Handle heartbeat response\n              if( _event === '__heartbeat_response' )\n                return\n              \n              // Handle heartbeat request\n              if( _event === '__heartbeat' ){\n                window._wio.emit('__heartbeat_response', { timestamp: Date.now() })\n                return\n              }\n              \n              // Handle webview ready signal\n              if( _event === '__webview_ready' ){\n                console.log('[EMBEDDED] WebView ready signal received')\n                return\n              }\n              \n              // Handle ping from WEBVIEW\n              if( _event === 'ping' ){\n                console.log('[EMBEDDED] Received ping, sending pong')\n                window._wio.connectionToken = token\n\n                window._wio.emit('pong', { token: window._wio.connectionToken })\n                return\n              }\n              \n              // Handle connection acknowledgment\n              if( _event === '__connection_ack' ){\n                if( token && token !== window._wio.connectionToken ){\n                  console.error('[EMBEDDED] Invalid connection token in ack')\n                  return\n                }\n                \n                console.log('[EMBEDDED] Connection established (received ack)')\n\n                window._wio.connected = true\n                window._wio.processMessageQueue()\n                window._wio.fire('connect')\n\n                return\n              }\n              \n              // Fire event listeners\n              window._wio.fire( _event, payload, cid )\n            },\n            \n            announceReady: function(){\n              let attempts = 0\n              const maxAttempts = 5\n              const interval = 2000\n              \n              console.log('[EMBEDDED] Starting ready announcements')\n              \n              const announce = () => {\n                if( window._wio.connected ){\n                  console.log('[EMBEDDED] Connected, stopping announcements')\n                  return\n                }\n                \n                attempts++\n                if( attempts > maxAttempts ){\n                  console.log('[EMBEDDED] Max announcement attempts reached')\n                  return\n                }\n                \n                console.log('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')\n                window._wio.emit('__embedded_ready')\n                \n                setTimeout( announce, interval )\n              }\n              \n              announce()\n            }\n          }\n\n          // Initialize\n          window._wio.listen()\n          // Start announcing readiness after a short delay\n          setTimeout(() => window._wio.announceReady(), 100)\n          \n          console.log('[EMBEDDED] WIO bridge initialized successfully')\n        }\n        catch( error ){\n          console.error('[EMBEDDED] Setup failed:', error )\n          \n          // Create minimal fallback\n          window._wio = {\n            error: error.toString(),\n            emit: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            on: function(){},\n            once: function(){},\n            off: function(){}\n          }\n        }\n\n        true\n      })()\n    ";
+        return "\n      (function() {\n        try {\n          console.debug('[EMBEDDED] Initializing WIO bridge...')\n          \n          const RESERVED_EVENTS = [\n            'ping',\n            'pong',\n            '__heartbeat',\n            '__heartbeat_response',\n            '__embedded_ready',\n            '__connection_ack',\n            '__webview_ready'\n          ]\n          \n          // Use closure variable to avoid 'this' binding issues\n          window._wio = {\n            type: 'EMBEDDED',\n            connected: false,\n            Events: {},\n            messageQueue: [],\n            connectionToken: null,\n            setupComplete: false,\n\n            listen: function(){\n              if( this.setupComplete ){\n                console.warn('[EMBEDDED] Already listening')\n                return this\n              }\n\n              console.debug('[EMBEDDED] Setting up message listeners...')\n\n              // Listen to messages from React Native\n              window.addEventListener('message', function( event ){\n                try {\n                  const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                  window._wio.handleMessage( message )\n                }\n                catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n              })\n              \n              // Android support\n              if( typeof document !== 'undefined' ){\n                document.addEventListener('message', function( event ){\n                  try {\n                    const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                    window._wio.handleMessage( message )\n                  }\n                  catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n                })\n              }\n\n              this.setupComplete = true\n              console.debug('[EMBEDDED] Setup complete, starting ready announcements')\n\n              // Start announcing readiness\n              this.announceReady()\n\n              return this\n            },\n            \n            ackId: function(){\n              const\n              rmin = 100000,\n              rmax = 999999,\n              timestamp = Date.now(),\n              random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )\n\n              return timestamp + '_' + random\n            },\n            \n            fire: function( _event, payload, cid ){\n              if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){\n                console.debug('[EMBEDDED] No listener for:', _event)\n                return\n              }\n              \n              const ackFn = cid\n                ? ( error, ...args ) => window._wio.emit( _event + '--' + cid + '--@ack', { error: error || false, args } )\n                : undefined\n              \n              let listeners = []\n              if( window._wio.Events[_event + '--@once'] ){\n                _event += '--@once'\n                listeners = window._wio.Events[_event]\n\n                delete window._wio.Events[_event]\n              }\n              else listeners = window._wio.Events[_event] || []\n              \n              listeners.forEach( fn => {\n                try { payload !== undefined ? fn( payload, ackFn ) : fn( ackFn ) }\n                catch( error ){ console.error('[EMBEDDED] Listener error:', error ) }\n              })\n            },\n            \n            emit: function( _event, payload, fn ){\n              if( typeof payload === 'function' ){\n                fn = payload\n                payload = undefined\n              }\n              \n              if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){\n                window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })\n                console.debug('[EMBEDDED] Queued message:', _event)\n                return\n              }\n              \n              try {\n                let cid\n                if( typeof fn === 'function' ){\n                  cid = window._wio.ackId()\n                  window._wio.once( _event + '--' + cid + '--@ack', ({ error, args }) => fn( error, ...args ) )\n                }\n                \n                const messageData = {\n                  _event,\n                  payload,\n                  cid,\n                  timestamp: Date.now(),\n                  token: RESERVED_EVENTS.includes(_event) ? window._wio.connectionToken : undefined\n                }\n                \n                if( typeof window.ReactNativeWebView !== 'undefined' )\n                  window.ReactNativeWebView.postMessage( JSON.stringify( messageData ) )\n                else console.error('[EMBEDDED] ReactNativeWebView not available')\n              }\n              catch( error ){\n                console.error('[EMBEDDED] Emit error:', error )\n                typeof fn === 'function' && fn( String(error) )\n              }\n            },\n            \n            on: function( _event, fn ){\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            once: function( _event, fn ){\n              _event += '--@once'\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            off: function( _event, fn ){\n              if( fn && window._wio.Events[_event] ){\n                const index = window._wio.Events[_event].indexOf( fn )\n                if( index > -1 ){\n                  window._wio.Events[_event].splice( index, 1 )\n                  if( window._wio.Events[_event].length === 0 ) delete window._wio.Events[_event]\n                }\n              }\n              else delete window._wio.Events[_event]\n\n              return window._wio\n            },\n            \n            processMessageQueue: function(){\n              if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return\n              \n              console.debug('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')\n              const queue = [ ...window._wio.messageQueue ]\n              window._wio.messageQueue = []\n              \n              queue.forEach( msg => {\n                try { window._wio.emit( msg._event, msg.payload, msg.fn ) }\n                catch( error ){ console.error('[EMBEDDED] Queue process error:', error ) }\n              })\n            },\n            \n            handleMessage: function( data ){\n              if( !data || !data._event ) return\n              \n              const { _event, payload, cid, token } = data\n              \n              console.debug('[EMBEDDED] Received:', _event )\n              \n              // Handle heartbeat response\n              if( _event === '__heartbeat_response' )\n                return\n              \n              // Handle heartbeat request\n              if( _event === '__heartbeat' ){\n                window._wio.emit('__heartbeat_response', { timestamp: Date.now() })\n                return\n              }\n              \n              // Handle webview ready signal\n              if( _event === '__webview_ready' ){\n                console.debug('[EMBEDDED] WebView ready signal received')\n                return\n              }\n              \n              // Handle ping from WEBVIEW\n              if( _event === 'ping' ){\n                console.debug('[EMBEDDED] Received ping, sending pong')\n                window._wio.connectionToken = token\n\n                window._wio.emit('pong', { token: window._wio.connectionToken })\n                return\n              }\n              \n              // Handle connection acknowledgment\n              if( _event === '__connection_ack' ){\n                if( token && token !== window._wio.connectionToken ){\n                  console.error('[EMBEDDED] Invalid connection token in ack')\n                  return\n                }\n                \n                console.debug('[EMBEDDED] Connection established (received ack)')\n\n                window._wio.connected = true\n                window._wio.processMessageQueue()\n                window._wio.fire('connect')\n\n                return\n              }\n              \n              // Fire event listeners\n              window._wio.fire( _event, payload, cid )\n            },\n            \n            announceReady: function(){\n              let attempts = 0\n              const maxAttempts = 10\n              const interval = 1000\n              \n              console.debug('[EMBEDDED] Starting ready announcements')\n              \n              const announce = () => {\n                if( window._wio.connected ){\n                  console.debug('[EMBEDDED] Connected, stopping announcements')\n                  return\n                }\n                \n                attempts++\n                if( attempts > maxAttempts ){\n                  console.debug('[EMBEDDED] Max announcement attempts reached')\n                  return\n                }\n                \n                console.debug('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')\n                window._wio.emit('__embedded_ready')\n                \n                setTimeout( announce, interval )\n              }\n              \n              announce()\n            }\n          }\n\n          console.debug('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')\n        }\n        catch( error ){\n          console.error('[EMBEDDED] Setup failed:', error )\n          \n          // Create minimal fallback\n          window._wio = {\n            error: error.toString(),\n            listen: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            emit: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            on: function(){},\n            once: function(){},\n            off: function(){}\n          }\n        }\n\n        true\n      })()\n    ";
     };
     return WIO;
 }());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webview.io",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Easy and friendly API to connect and interact between React Native and WebView with enhanced security, reliability, and modern async/await support.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -17,6 +17,16 @@ export type Options = {
   messageQueueSize?: number
   connectionPingInterval?: number
   maxConnectionAttempts?: number
+  /**
+   * Optional allowlist of incoming application-level events.
+   * Reserved internal events (ping/pong/heartbeat/handshake) are always allowed.
+   */
+  allowedIncomingEvents?: string[]
+  /**
+   * Optional custom validator for incoming messages.
+   * Return false to drop a message; an 'error' event will be emitted.
+   */
+  validateIncoming?: ( event: string, payload: any ) => boolean
 }
 
 export interface RegisteredEvents {
@@ -83,7 +93,26 @@ const ackId = () => {
 }
 
 const generateToken = () => {
-  return `${Date.now()}_${Math.random().toString(36).substring(2, 15)}`
+  // Prefer cryptographically strong randomness when available
+  try {
+    const globalCrypto = (typeof crypto !== 'undefined'
+      ? crypto
+      : (typeof window !== 'undefined' && (window as any).crypto)
+        || (typeof globalThis !== 'undefined' && (globalThis as any).crypto))
+
+    if( globalCrypto && typeof globalCrypto.getRandomValues === 'function' ){
+      const buffer = new Uint32Array(4)
+      globalCrypto.getRandomValues( buffer )
+
+      const randomPart = Array.from( buffer ).map( n => n.toString( 16 ) ).join('')
+      return `${Date.now()}_${randomPart}`
+    }
+  }
+  catch{
+    // Fall back to Math.random-based implementation below
+  }
+
+  return `${Date.now()}_${Math.random().toString( 36 ).substring( 2, 15 )}`
 }
 
 const RESERVED_EVENTS = [
@@ -131,8 +160,7 @@ export default class WIO {
     this.Events = {}
     this.peer = { type: 'WEBVIEW', connected: false, embeddedReady: false }
 
-    if( options.type )
-      this.peer.type = options.type
+    if( options.type ) this.peer.type = options.type
   }
 
   debug( ...args: any[] ){
@@ -211,24 +239,19 @@ export default class WIO {
       this.connectionToken = generateToken()
 
       // Re-initiate connection for WEBVIEW type
-      if( this.peer.type === 'WEBVIEW' ){
-        this.startConnectionAttempt()
-      }
-
+      this.peer.type === 'WEBVIEW' && this.startConnectionAttempt()
       // For EMBEDDED type, announce readiness
-      if( this.peer.type === 'EMBEDDED' ){
-        this.announceEmbeddedReady()
-      }
+      this.peer.type === 'EMBEDDED' && this.announceEmbeddedReady()
 
       // Set timeout for this reconnection attempt
-      setTimeout(() => {
+      setTimeout( () => {
         if( this.peer.connected ) return
 
         this.reconnectAttempts < this.maxReconnectAttempts
             ? this.attemptReconnection()
             : this.fire('reconnection_failed', { attempts: this.reconnectAttempts })
-      }, this.options.connectionTimeout!)
-    }, delay)
+      }, this.options.connectionTimeout! )
+    }, delay )
   }
 
   // Start connection attempt with timeout and retries
@@ -257,10 +280,8 @@ export default class WIO {
         this.debug(`[${this.peer.type}] Connection attempt ${this.connectionAttempts}/${this.options.maxConnectionAttempts}`)
         this.emit('ping', { token: this.connectionToken })
       }
-      else {
-        this.stopConnectionAttempt()
-      }
-    }, this.options.connectionPingInterval!)
+      else this.stopConnectionAttempt()
+    }, this.options.connectionPingInterval! )
 
     // Set overall timeout
     this.connectionAttemptTimer = setTimeout(() => {
@@ -310,17 +331,15 @@ export default class WIO {
         this.debug(`[${this.peer.type}] Ready announcement attempt ${attempts}/${maxAttempts}`)
         this.emit('__embedded_ready')
       }
-      else {
-        this.stopEmbeddedReadyAnnouncement()
-      }
+      else this.stopEmbeddedReadyAnnouncement()
     }, this.options.connectionPingInterval!)
   }
 
   private stopEmbeddedReadyAnnouncement(){
-    if( this.embeddedReadyCheckInterval ){
-      clearInterval( this.embeddedReadyCheckInterval )
-      this.embeddedReadyCheckInterval = undefined
-    }
+    if( !this.embeddedReadyCheckInterval ) return
+
+    clearInterval( this.embeddedReadyCheckInterval )
+    this.embeddedReadyCheckInterval = undefined
   }
 
   // Message rate limiting
@@ -351,8 +370,8 @@ export default class WIO {
 
   // Queue messages when not connected
   private queueMessage( _event: string, payload?: any, fn?: AckFunction ){
+    // Remove oldest message
     if( this.messageQueue.length >= this.options.messageQueueSize! ){
-      // Remove oldest message
       const removed = this.messageQueue.shift()
       this.debug(`[${this.peer.type}] Message queue full, removed oldest message:`, removed?._event)
     }
@@ -413,6 +432,9 @@ export default class WIO {
 
   /**
    * Listening to connection from the WebView host
+   * 
+   * NOTE: This is called manually from page code, 
+   * not auto-initialized
    */
   listen( hostOrigin?: string ){
     this.peer.type = 'EMBEDDED'
@@ -423,9 +445,7 @@ export default class WIO {
     this.debug(`[${this.peer.type}] Listening to connect${hostOrigin ? `: Host <${hostOrigin}>` : ''}`)
 
     // Start announcing readiness
-    setTimeout(() => {
-      this.announceEmbeddedReady()
-    }, 100)
+    setTimeout( () => this.announceEmbeddedReady(), 100 )
 
     return this
   }
@@ -436,9 +456,9 @@ export default class WIO {
   handleMessage( event: { nativeEvent: { data: string } } ){
     try {
       const data = JSON.parse( event.nativeEvent.data )
-
       // Enhanced security: check valid message structure
-      if( typeof data !== 'object' || !data.hasOwnProperty('_event') ) return
+      if( typeof data !== 'object' || !data.hasOwnProperty('_event') )
+        return
 
       const { _event, payload, cid, timestamp, token } = data as MessageData
 
@@ -470,9 +490,10 @@ export default class WIO {
         this.debug(`[${this.peer.type}] Embedded peer ready`)
         
         // If we're WEBVIEW and not connected, send ping
-        if( this.peer.type === 'WEBVIEW' && !this.peer.connected ){
-          this.emit('ping', { token: this.connectionToken })
-        }
+        this.peer.type === 'WEBVIEW'
+        && !this.peer.connected
+        && this.emit('ping', { token: this.connectionToken })
+        
         return
       }
 
@@ -494,6 +515,7 @@ export default class WIO {
           // Don't set fully connected yet - wait for ack
           this.debug(`[${this.peer.type}] Received ping, sent pong`)
         }
+
         return
       }
 
@@ -522,6 +544,7 @@ export default class WIO {
           
           this.debug(`[${this.peer.type}] Connected (3-way handshake complete)`)
         }
+
         return
       }
 
@@ -546,9 +569,33 @@ export default class WIO {
           
           this.debug(`[${this.peer.type}] Connected (received ack)`)
         }
+
         return
       }
 
+      // Optional application-level incoming validation (non-reserved events only)
+      if( !RESERVED_EVENTS.includes( _event ) ){
+        if( this.options.allowedIncomingEvents
+            && !this.options.allowedIncomingEvents.includes( _event ) ){
+          this.fire('error', {
+            type: 'DISALLOWED_EVENT',
+            direction: 'incoming',
+            event: _event
+          })
+          return
+        }
+
+        if( this.options.validateIncoming
+            && !this.options.validateIncoming( _event, payload ) ){
+          this.fire('error', {
+            type: 'INVALID_MESSAGE',
+            direction: 'incoming',
+            event: _event
+          })
+          return
+        }
+      }
+
       // Fire available event listeners
       this.fire( _event, payload, cid )
     }
@@ -569,11 +616,11 @@ export default class WIO {
     }
 
     const ackFn = cid
-      ? ( error: boolean | string, ...args: any[] ): void => {
-          this.emit(`${_event}--${cid}--@ack`, { error: error || false, args })
-          return
-        }
-      : undefined
+                ? ( error: boolean | string, ...args: any[] ): void => {
+                    this.emit(`${_event}--${cid}--@ack`, { error: error || false, args })
+                    return
+                  }
+                : undefined
     let listeners: Listener[] = []
 
     if( this.Events[_event + '--@once'] ){
@@ -717,9 +764,7 @@ export default class WIO {
 
   emitAsync<T = any, R = any>( _event: string, payload?: T, timeout: number = 5000 ): Promise<R> {
     return new Promise(( resolve, reject ) => {
-      const timeoutId = setTimeout(() => {
-        reject( new Error(`Event '${_event}' acknowledgment timeout after ${timeout}ms`) )
-      }, timeout )
+      const timeoutId = setTimeout(() => reject( new Error(`Event '${_event}' acknowledgment timeout after ${timeout}ms`) ), timeout )
 
       try {
         this.emit( _event, payload, ( error, ...args ) => {
@@ -745,17 +790,17 @@ export default class WIO {
     return new Promise(( resolve, reject ) => {
       if( this.isConnected() ) return resolve()
 
-      const timeoutId = setTimeout(() => {
-        this.off('connect', connectHandler)
+      const timeoutId = setTimeout( () => {
+        this.off('connect', connectHandler )
         reject( new Error('Connection timeout') )
-      }, timeout || this.options.connectionTimeout)
+      }, timeout || this.options.connectionTimeout )
 
       const connectHandler = () => {
         clearTimeout( timeoutId )
         resolve()
       }
 
-      this.once('connect', connectHandler)
+      this.once('connect', connectHandler )
     })
   }
 
@@ -822,12 +867,13 @@ export default class WIO {
   /**
    * Get injected JavaScript for WebView
    * Sets up the EMBEDDED side of the bridge
+   * NOTE: Does not auto-initialize - page must call window._wio.listen()
    */
   getInjectedJavaScript(): string {
     return `
       (function() {
         try {
-          console.log('[EMBEDDED] Initializing WIO bridge...')
+          console.debug('[EMBEDDED] Initializing WIO bridge...')
           
           const RESERVED_EVENTS = [
             'ping',
@@ -849,13 +895,18 @@ export default class WIO {
             setupComplete: false,
 
             listen: function(){
-              console.log('[EMBEDDED] Setting up message listeners...')
+              if( this.setupComplete ){
+                console.warn('[EMBEDDED] Already listening')
+                return this
+              }
+
+              console.debug('[EMBEDDED] Setting up message listeners...')
 
               // Listen to messages from React Native
               window.addEventListener('message', function( event ){
                 try {
                   const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data
-                  window._wio.handleMessage( message )  // Use window._wio instead of this
+                  window._wio.handleMessage( message )
                 }
                 catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }
               })
@@ -865,16 +916,19 @@ export default class WIO {
                 document.addEventListener('message', function( event ){
                   try {
                     const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data
-                    window._wio.handleMessage( message )  // Use window._wio instead of this
+                    window._wio.handleMessage( message )
                   }
                   catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }
                 })
               }
 
-              window._wio.setupComplete = true  // Use window._wio instead of this
-              console.log('[EMBEDDED] Setup complete')
+              this.setupComplete = true
+              console.debug('[EMBEDDED] Setup complete, starting ready announcements')
 
-              return window._wio
+              // Start announcing readiness
+              this.announceReady()
+
+              return this
             },
             
             ackId: function(){
@@ -889,7 +943,7 @@ export default class WIO {
             
             fire: function( _event, payload, cid ){
               if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){
-                console.log('[EMBEDDED] No listener for:', _event)
+                console.debug('[EMBEDDED] No listener for:', _event)
                 return
               }
               
@@ -920,7 +974,7 @@ export default class WIO {
               
               if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){
                 window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })
-                console.log('[EMBEDDED] Queued message:', _event)
+                console.debug('[EMBEDDED] Queued message:', _event)
                 return
               }
               
@@ -981,7 +1035,7 @@ export default class WIO {
             processMessageQueue: function(){
               if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return
               
-              console.log('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')
+              console.debug('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')
               const queue = [ ...window._wio.messageQueue ]
               window._wio.messageQueue = []
               
@@ -996,7 +1050,7 @@ export default class WIO {
               
               const { _event, payload, cid, token } = data
               
-              console.log('[EMBEDDED] Received:', _event )
+              console.debug('[EMBEDDED] Received:', _event )
               
               // Handle heartbeat response
               if( _event === '__heartbeat_response' )
@@ -1010,13 +1064,13 @@ export default class WIO {
               
               // Handle webview ready signal
               if( _event === '__webview_ready' ){
-                console.log('[EMBEDDED] WebView ready signal received')
+                console.debug('[EMBEDDED] WebView ready signal received')
                 return
               }
               
               // Handle ping from WEBVIEW
               if( _event === 'ping' ){
-                console.log('[EMBEDDED] Received ping, sending pong')
+                console.debug('[EMBEDDED] Received ping, sending pong')
                 window._wio.connectionToken = token
 
                 window._wio.emit('pong', { token: window._wio.connectionToken })
@@ -1030,7 +1084,7 @@ export default class WIO {
                   return
                 }
                 
-                console.log('[EMBEDDED] Connection established (received ack)')
+                console.debug('[EMBEDDED] Connection established (received ack)')
 
                 window._wio.connected = true
                 window._wio.processMessageQueue()
@@ -1045,24 +1099,24 @@ export default class WIO {
             
             announceReady: function(){
               let attempts = 0
-              const maxAttempts = 5
-              const interval = 2000
+              const maxAttempts = 10
+              const interval = 1000
               
-              console.log('[EMBEDDED] Starting ready announcements')
+              console.debug('[EMBEDDED] Starting ready announcements')
               
               const announce = () => {
                 if( window._wio.connected ){
-                  console.log('[EMBEDDED] Connected, stopping announcements')
+                  console.debug('[EMBEDDED] Connected, stopping announcements')
                   return
                 }
                 
                 attempts++
                 if( attempts > maxAttempts ){
-                  console.log('[EMBEDDED] Max announcement attempts reached')
+                  console.debug('[EMBEDDED] Max announcement attempts reached')
                   return
                 }
                 
-                console.log('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')
+                console.debug('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')
                 window._wio.emit('__embedded_ready')
                 
                 setTimeout( announce, interval )
@@ -1072,12 +1126,7 @@ export default class WIO {
             }
           }
 
-          // Initialize
-          window._wio.listen()
-          // Start announcing readiness after a short delay
-          setTimeout(() => window._wio.announceReady(), 100)
-          
-          console.log('[EMBEDDED] WIO bridge initialized successfully')
+          console.debug('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')
         }
         catch( error ){
           console.error('[EMBEDDED] Setup failed:', error )
@@ -1085,6 +1134,7 @@ export default class WIO {
           // Create minimal fallback
           window._wio = {
             error: error.toString(),
+            listen: function(){ console.error('[EMBEDDED] WIO failed to initialize') },
             emit: function(){ console.error('[EMBEDDED] WIO failed to initialize') },
             on: function(){},
             once: function(){},