@naylence/runtime 0.3.5-test.941 → 0.3.5-test.943

package/dist/esm/naylence/fame/connector/broadcast-channel-connector.browser.js

@@ -3,6 +3,7 @@ import { FameTransportClose } from '../errors/errors.js';
 import { getLogger } from '../util/logging.js';
 import { BoundedAsyncQueue, QueueFullError, } from '../util/bounded-async-queue.js';
 import { ConnectorState } from '@naylence/core';
+import { wrapTransportFrame, unwrapTransportFrame, serializeTransportFrame, } from './transport-frame.js';
 const logger = getLogger('naylence.fame.connector.broadcast_channel_connector');
 export const BROADCAST_CHANNEL_CONNECTOR_TYPE = 'broadcast-channel-connector';
 const DEFAULT_CHANNEL = 'naylence-fabric';
@@ -68,9 +69,20 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
         this.inbox = new BoundedAsyncQueue(preferredCapacity);
         this.connectorId = BroadcastChannelConnector.generateConnectorId();
         this.channel = new BroadcastChannel(this.channelName);
+        // Set local and remote node IDs (defaults to connector ID for backwards compatibility)
+        this.localNodeId =
+            typeof config.localNodeId === 'string' && config.localNodeId.trim().length > 0
+                ? config.localNodeId.trim()
+                : this.connectorId;
+        this.remoteNodeId =
+            typeof config.remoteNodeId === 'string' && config.remoteNodeId.trim().length > 0
+                ? config.remoteNodeId.trim()
+                : '*'; // Accept from any remote if not specified
         logger.debug('broadcast_channel_connector_created', {
             channel: this.channelName,
             connector_id: this.connectorId,
+            local_node_id: this.localNodeId,
+            remote_node_id: this.remoteNodeId,
             inbox_capacity: preferredCapacity,
             timestamp: new Date().toISOString(),
         });
@@ -103,6 +115,46 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
             if (busMessage.senderId === this.connectorId) {
                 return;
             }
+            // Try to unwrap as transport frame
+            const unwrapped = unwrapTransportFrame(busMessage.payload, this.localNodeId, this.remoteNodeId === '*' ? busMessage.senderId : this.remoteNodeId);
+            if (unwrapped) {
+                // Successfully unwrapped transport frame
+                logger.debug('broadcast_channel_transport_frame_received', {
+                    channel: this.channelName,
+                    sender_id: busMessage.senderId,
+                    connector_id: this.connectorId,
+                    local_node_id: this.localNodeId,
+                    remote_node_id: this.remoteNodeId,
+                    payload_length: unwrapped.byteLength,
+                });
+                if (this._shouldSkipDuplicateAck(busMessage.senderId, unwrapped)) {
+                    return;
+                }
+                try {
+                    if (typeof this.inbox.tryEnqueue === 'function') {
+                        const accepted = this.inbox.tryEnqueue(unwrapped);
+                        if (accepted) {
+                            return;
+                        }
+                    }
+                    this.inbox.enqueue(unwrapped);
+                }
+                catch (error) {
+                    if (error instanceof QueueFullError) {
+                        logger.warning('broadcast_channel_receive_queue_full', {
+                            channel: this.channelName,
+                        });
+                    }
+                    else {
+                        logger.error('broadcast_channel_receive_error', {
+                            channel: this.channelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                return;
+            }
+            // Fall back to legacy format (no transport frame)
             const payload = BroadcastChannelConnector.coercePayload(busMessage.payload);
             if (!payload) {
                 logger.debug('broadcast_channel_payload_rejected', {
@@ -241,10 +293,26 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
         logger.debug('broadcast_channel_message_sending', {
             channel: this.channelName,
             sender_id: this.connectorId,
+            local_node_id: this.localNodeId,
+            remote_node_id: this.remoteNodeId,
         });
+        // Only use transport framing if both localNodeId and remoteNodeId are explicitly set
+        // (not using default values). This ensures backwards compatibility.
+        const useTransportFrame = this.localNodeId !== this.connectorId ||
+            this.remoteNodeId !== '*';
+        let payload;
+        if (useTransportFrame) {
+            // Wrap payload in transport frame
+            const frame = wrapTransportFrame(data, this.localNodeId, this.remoteNodeId);
+            payload = serializeTransportFrame(frame);
+        }
+        else {
+            // Legacy format: send raw payload
+            payload = data;
+        }
         this.channel.postMessage({
             senderId: this.connectorId,
-            payload: data,
+            payload,
         });
     }
     async _transportReceive() {

package/dist/esm/naylence/fame/connector/inpage-connector-factory.js

@@ -81,6 +81,8 @@ export class InPageConnectorFactory extends ConnectorFactory {
             type: INPAGE_CONNECTOR_TYPE,
             channelName,
             inboxCapacity,
+            localNodeId: normalized.localNodeId,
+            remoteNodeId: normalized.remoteNodeId,
         };
         const connector = new InPageConnector(connectorConfig, baseConfig);
         if (options.authorization) {
@@ -149,6 +151,16 @@ export class InPageConnectorFactory extends ConnectorFactory {
         if (candidate.authorizationContext !== undefined) {
             normalized.authorizationContext = candidate.authorizationContext;
         }
+        // Handle localNodeId
+        const localNodeId = candidate.localNodeId ?? candidate['local_node_id'];
+        if (typeof localNodeId === 'string' && localNodeId.trim().length > 0) {
+            normalized.localNodeId = localNodeId.trim();
+        }
+        // Handle remoteNodeId
+        const remoteNodeId = candidate.remoteNodeId ?? candidate['remote_node_id'];
+        if (typeof remoteNodeId === 'string' && remoteNodeId.trim().length > 0) {
+            normalized.remoteNodeId = remoteNodeId.trim();
+        }
         normalized.channelName = normalized.channelName ?? DEFAULT_CHANNEL;
         normalized.inboxCapacity =
             normalized.inboxCapacity ?? DEFAULT_INBOX_CAPACITY;

package/dist/esm/naylence/fame/connector/inpage-connector.js

@@ -6,6 +6,8 @@ import { BaseAsyncConnector, } from './base-async-connector.js';
 import { FameTransportClose } from '../errors/errors.js';
 import { getLogger } from '../util/logging.js';
 import { BoundedAsyncQueue, QueueFullError, } from '../util/bounded-async-queue.js';
+import { ConnectorState } from '@naylence/core';
+import { wrapTransportFrame, unwrapTransportFrame, serializeTransportFrame, } from './transport-frame.js';
 const logger = getLogger('naylence.fame.connector.inpage_connector');
 export const INPAGE_CONNECTOR_TYPE = 'inpage-connector';
 const DEFAULT_CHANNEL = 'naylence-fabric';
@@ -64,6 +66,7 @@ export class InPageConnector extends BaseAsyncConnector {
         ensureBrowserEnvironment();
         super(baseConfig);
         this.listenerRegistered = false;
+        this.visibilityChangeListenerRegistered = false;
         this.channelName =
             typeof config.channelName === 'string' && config.channelName.trim().length > 0
                 ? config.channelName.trim()
@@ -75,9 +78,20 @@ export class InPageConnector extends BaseAsyncConnector {
             : DEFAULT_INBOX_CAPACITY;
         this.inbox = new BoundedAsyncQueue(preferredCapacity);
         this.connectorId = InPageConnector.generateConnectorId();
+        // Set local and remote node IDs (defaults to connector ID for backwards compatibility)
+        this.localNodeId =
+            typeof config.localNodeId === 'string' && config.localNodeId.trim().length > 0
+                ? config.localNodeId.trim()
+                : this.connectorId;
+        this.remoteNodeId =
+            typeof config.remoteNodeId === 'string' && config.remoteNodeId.trim().length > 0
+                ? config.remoteNodeId.trim()
+                : '*'; // Accept from any remote if not specified
         logger.debug('inpage_connector_initialized', {
             channel: this.channelName,
             connector_id: this.connectorId,
+            local_node_id: this.localNodeId,
+            remote_node_id: this.remoteNodeId,
         });
         this.onMsg = (event) => {
             const messageEvent = event;
@@ -111,6 +125,43 @@ export class InPageConnector extends BaseAsyncConnector {
             if (busMessage.senderId === this.connectorId) {
                 return;
             }
+            // Try to unwrap as transport frame
+            const unwrapped = unwrapTransportFrame(busMessage.payload, this.localNodeId, this.remoteNodeId === '*' ? busMessage.senderId : this.remoteNodeId);
+            if (unwrapped) {
+                // Successfully unwrapped transport frame
+                logger.debug('inpage_transport_frame_received', {
+                    channel: this.channelName,
+                    sender_id: busMessage.senderId,
+                    connector_id: this.connectorId,
+                    local_node_id: this.localNodeId,
+                    remote_node_id: this.remoteNodeId,
+                    payload_length: unwrapped.byteLength,
+                });
+                try {
+                    if (typeof this.inbox.tryEnqueue === 'function') {
+                        const accepted = this.inbox.tryEnqueue(unwrapped);
+                        if (accepted) {
+                            return;
+                        }
+                    }
+                    this.inbox.enqueue(unwrapped);
+                }
+                catch (error) {
+                    if (error instanceof QueueFullError) {
+                        logger.warning('inpage_receive_queue_full', {
+                            channel: this.channelName,
+                        });
+                    }
+                    else {
+                        logger.error('inpage_receive_error', {
+                            channel: this.channelName,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                return;
+            }
+            // Fall back to legacy format (no transport frame)
             const payload = InPageConnector.coercePayload(busMessage.payload);
             if (!payload) {
                 logger.debug('inpage_payload_rejected', {
@@ -151,6 +202,92 @@ export class InPageConnector extends BaseAsyncConnector {
         };
         getSharedBus().addEventListener(this.channelName, this.onMsg);
         this.listenerRegistered = true;
+        // Setup visibility change monitoring
+        this.visibilityChangeHandler = () => {
+            const isHidden = document.hidden;
+            logger.debug('inpage_visibility_changed', {
+                channel: this.channelName,
+                connector_id: this.connectorId,
+                visibility: isHidden ? 'hidden' : 'visible',
+                timestamp: new Date().toISOString(),
+            });
+            // Pause/resume connector based on visibility
+            if (isHidden && this.state === ConnectorState.STARTED) {
+                this.pause().catch((err) => {
+                    logger.warning('inpage_pause_failed', {
+                        channel: this.channelName,
+                        connector_id: this.connectorId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+            else if (!isHidden && this.state === ConnectorState.PAUSED) {
+                this.resume().catch((err) => {
+                    logger.warning('inpage_resume_failed', {
+                        channel: this.channelName,
+                        connector_id: this.connectorId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+        };
+        if (typeof document !== 'undefined') {
+            document.addEventListener('visibilitychange', this.visibilityChangeHandler);
+            this.visibilityChangeListenerRegistered = true;
+            // Track page lifecycle events to detect browser unload/discard
+            if (typeof window !== 'undefined') {
+                const lifecycleLogger = (event) => {
+                    logger.info('inpage_page_lifecycle', {
+                        channel: this.channelName,
+                        connector_id: this.connectorId,
+                        event_type: event.type,
+                        visibility_state: document.visibilityState,
+                        timestamp: new Date().toISOString(),
+                    });
+                };
+                window.addEventListener('beforeunload', lifecycleLogger);
+                window.addEventListener('unload', lifecycleLogger);
+                window.addEventListener('pagehide', lifecycleLogger);
+                window.addEventListener('pageshow', lifecycleLogger);
+                document.addEventListener('freeze', lifecycleLogger);
+                document.addEventListener('resume', lifecycleLogger);
+            }
+            // Log initial state with detailed visibility info
+            logger.debug('inpage_initial_visibility', {
+                channel: this.channelName,
+                connector_id: this.connectorId,
+                visibility: document.hidden ? 'hidden' : 'visible',
+                document_hidden: document.hidden,
+                visibility_state: document.visibilityState,
+                has_focus: document.hasFocus(),
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    /**
+     * Override start() to check initial visibility state
+     */
+    async start(inboundHandler) {
+        await super.start(inboundHandler);
+        // After transitioning to STARTED, check if tab is already hidden
+        if (typeof document !== 'undefined' && document.hidden) {
+            logger.debug('inpage_start_in_hidden_tab', {
+                channel: this.channelName,
+                connector_id: this.connectorId,
+                document_hidden: document.hidden,
+                visibility_state: document.visibilityState,
+                has_focus: document.hasFocus(),
+                timestamp: new Date().toISOString(),
+            });
+            // Immediately pause if tab is hidden at start time
+            await this.pause().catch((err) => {
+                logger.warning('inpage_initial_pause_failed', {
+                    channel: this.channelName,
+                    connector_id: this.connectorId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
     }
     // Allow listeners to feed envelopes directly into the in-page receive queue.
     async pushToReceive(rawOrEnvelope) {
@@ -183,11 +320,27 @@ export class InPageConnector extends BaseAsyncConnector {
         logger.debug('inpage_message_sending', {
             channel: this.channelName,
             sender_id: this.connectorId,
+            local_node_id: this.localNodeId,
+            remote_node_id: this.remoteNodeId,
         });
+        // Only use transport framing if both localNodeId and remoteNodeId are explicitly set
+        // (not using default values). This ensures backwards compatibility.
+        const useTransportFrame = this.localNodeId !== this.connectorId ||
+            this.remoteNodeId !== '*';
+        let payload;
+        if (useTransportFrame) {
+            // Wrap payload in transport frame
+            const frame = wrapTransportFrame(data, this.localNodeId, this.remoteNodeId);
+            payload = serializeTransportFrame(frame);
+        }
+        else {
+            // Legacy format: send raw payload
+            payload = data;
+        }
         const event = new MessageEvent(this.channelName, {
             data: {
                 senderId: this.connectorId,
-                payload: data,
+                payload,
             },
         });
         getSharedBus().dispatchEvent(event);
@@ -200,6 +353,11 @@ export class InPageConnector extends BaseAsyncConnector {
             getSharedBus().removeEventListener(this.channelName, this.onMsg);
             this.listenerRegistered = false;
         }
+        if (this.visibilityChangeListenerRegistered && this.visibilityChangeHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.visibilityChangeHandler);
+            this.visibilityChangeListenerRegistered = false;
+            this.visibilityChangeHandler = undefined;
+        }
         const closeCode = typeof code === 'number' ? code : 1000;
         const closeReason = typeof reason === 'string' && reason.length > 0 ? reason : 'closed';
         const shutdownError = new FameTransportClose(closeReason, closeCode);

package/dist/esm/naylence/fame/connector/transport-frame.js

@@ -0,0 +1,94 @@
+/**
+ * Transport frame layer for multiplexing logical links on physical channels.
+ *
+ * This lightweight framing layer wraps raw FAME payloads to enable multiple
+ * logical connections over a single physical channel (BroadcastChannel or InPage bus).
+ *
+ * The transport frame does NOT modify FAME envelopes - it only wraps the raw
+ * Uint8Array payload at the connector level.
+ */
+/**
+ * Transport frame version for future compatibility
+ */
+export const TRANSPORT_FRAME_VERSION = 1;
+/**
+ * Wrap a raw payload in a transport frame
+ *
+ * @param payload - Raw FAME envelope bytes
+ * @param srcNodeId - Local node ID (this connector)
+ * @param dstNodeId - Remote node ID (target connector)
+ * @returns Transport frame ready for transmission
+ */
+export function wrapTransportFrame(payload, srcNodeId, dstNodeId) {
+    return {
+        v: TRANSPORT_FRAME_VERSION,
+        src: srcNodeId,
+        dst: dstNodeId,
+        payload,
+    };
+}
+/**
+ * Serialize a transport frame for transmission over the bus
+ *
+ * @param frame - Transport frame to serialize
+ * @returns Serialized frame data ready for postMessage/dispatchEvent
+ */
+export function serializeTransportFrame(frame) {
+    // Convert Uint8Array to regular array for JSON serialization
+    const serializable = {
+        v: frame.v,
+        src: frame.src,
+        dst: frame.dst,
+        payload: Array.from(frame.payload),
+    };
+    return serializable;
+}
+/**
+ * Unwrap a transport frame, validating source and destination
+ *
+ * @param raw - Raw data from the bus
+ * @param localNodeId - This connector's node ID
+ * @param remoteNodeId - Expected remote node ID
+ * @returns Unwrapped payload if frame is valid and addressed to us, null otherwise
+ */
+export function unwrapTransportFrame(raw, localNodeId, remoteNodeId) {
+    // Validate basic structure
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const frame = raw;
+    // Check version
+    if (frame.v !== TRANSPORT_FRAME_VERSION) {
+        return null;
+    }
+    // Check src and dst
+    if (typeof frame.src !== 'string' || typeof frame.dst !== 'string') {
+        return null;
+    }
+    // Only accept frames addressed to us from the expected remote
+    if (frame.dst !== localNodeId || frame.src !== remoteNodeId) {
+        return null;
+    }
+    // Extract payload
+    if (!frame.payload || !Array.isArray(frame.payload)) {
+        return null;
+    }
+    // Convert array back to Uint8Array
+    return Uint8Array.from(frame.payload);
+}
+/**
+ * Check if raw data looks like a transport frame
+ *
+ * @param raw - Raw data from the bus
+ * @returns True if this appears to be a transport frame
+ */
+export function isTransportFrame(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return false;
+    }
+    const frame = raw;
+    return (typeof frame.v === 'number' &&
+        typeof frame.src === 'string' &&
+        typeof frame.dst === 'string' &&
+        Array.isArray(frame.payload));
+}

package/dist/esm/naylence/fame/grants/broadcast-channel-connection-grant.js

@@ -19,6 +19,14 @@ export function isBroadcastChannelConnectionGrant(candidate) {
             record.inboxCapacity <= 0)) {
         return false;
     }
+    if (record.localNodeId !== undefined &&
+        (typeof record.localNodeId !== 'string' || record.localNodeId.length === 0)) {
+        return false;
+    }
+    if (record.remoteNodeId !== undefined &&
+        (typeof record.remoteNodeId !== 'string' || record.remoteNodeId.length === 0)) {
+        return false;
+    }
     return true;
 }
 export function normalizeBroadcastChannelConnectionGrant(candidate) {
@@ -52,6 +60,20 @@ export function normalizeBroadcastChannelConnectionGrant(candidate) {
         }
         result.inboxCapacity = Math.floor(inboxValue);
     }
+    const localNodeIdValue = candidate.localNodeId ?? candidate['local_node_id'];
+    if (localNodeIdValue !== undefined) {
+        if (typeof localNodeIdValue !== 'string' || localNodeIdValue.trim().length === 0) {
+            throw new TypeError('BroadcastChannelConnectionGrant "localNodeId" must be a non-empty string when provided');
+        }
+        result.localNodeId = localNodeIdValue.trim();
+    }
+    const remoteNodeIdValue = candidate.remoteNodeId ?? candidate['remote_node_id'];
+    if (remoteNodeIdValue !== undefined) {
+        if (typeof remoteNodeIdValue !== 'string' || remoteNodeIdValue.trim().length === 0) {
+            throw new TypeError('BroadcastChannelConnectionGrant "remoteNodeId" must be a non-empty string when provided');
+        }
+        result.remoteNodeId = remoteNodeIdValue.trim();
+    }
     return result;
 }
 export function broadcastChannelGrantToConnectorConfig(grant) {
@@ -65,5 +87,11 @@ export function broadcastChannelGrantToConnectorConfig(grant) {
     if (normalized.inboxCapacity !== undefined) {
         config.inboxCapacity = normalized.inboxCapacity;
     }
+    if (normalized.localNodeId) {
+        config.localNodeId = normalized.localNodeId;
+    }
+    if (normalized.remoteNodeId) {
+        config.remoteNodeId = normalized.remoteNodeId;
+    }
     return config;
 }

package/dist/esm/naylence/fame/grants/inpage-connection-grant.js

@@ -19,6 +19,14 @@ export function isInPageConnectionGrant(candidate) {
             record.inboxCapacity <= 0)) {
         return false;
     }
+    if (record.localNodeId !== undefined &&
+        (typeof record.localNodeId !== 'string' || record.localNodeId.length === 0)) {
+        return false;
+    }
+    if (record.remoteNodeId !== undefined &&
+        (typeof record.remoteNodeId !== 'string' || record.remoteNodeId.length === 0)) {
+        return false;
+    }
     return true;
 }
 export function normalizeInPageConnectionGrant(candidate) {
@@ -52,6 +60,20 @@ export function normalizeInPageConnectionGrant(candidate) {
         }
         result.inboxCapacity = Math.floor(inboxValue);
     }
+    const localNodeIdValue = candidate.localNodeId ?? candidate['local_node_id'];
+    if (localNodeIdValue !== undefined) {
+        if (typeof localNodeIdValue !== 'string' || localNodeIdValue.trim().length === 0) {
+            throw new TypeError('InPageConnectionGrant "localNodeId" must be a non-empty string when provided');
+        }
+        result.localNodeId = localNodeIdValue.trim();
+    }
+    const remoteNodeIdValue = candidate.remoteNodeId ?? candidate['remote_node_id'];
+    if (remoteNodeIdValue !== undefined) {
+        if (typeof remoteNodeIdValue !== 'string' || remoteNodeIdValue.trim().length === 0) {
+            throw new TypeError('InPageConnectionGrant "remoteNodeId" must be a non-empty string when provided');
+        }
+        result.remoteNodeId = remoteNodeIdValue.trim();
+    }
     return result;
 }
 export function inPageGrantToConnectorConfig(grant) {
@@ -65,5 +87,11 @@ export function inPageGrantToConnectorConfig(grant) {
     if (normalized.inboxCapacity !== undefined) {
         config.inboxCapacity = normalized.inboxCapacity;
     }
+    if (normalized.localNodeId) {
+        config.localNodeId = normalized.localNodeId;
+    }
+    if (normalized.remoteNodeId) {
+        config.remoteNodeId = normalized.remoteNodeId;
+    }
     return config;
 }

package/dist/esm/naylence/fame/node/upstream-session-manager.js

@@ -385,7 +385,7 @@ export class UpstreamSessionManager extends TaskSpawner {
             this.currentStopSubtasks = null;
             await Promise.allSettled(tasks.map((task) => task.promise));
             if (this.connector) {
-                logger.info('upstream_stopping_old_connector', {
+                logger.debug('upstream_stopping_old_connector', {
                     connect_epoch: this.connectEpoch,
                     target_system_id: this.targetSystemId,
                     timestamp: new Date().toISOString(),
@@ -396,7 +396,7 @@ export class UpstreamSessionManager extends TaskSpawner {
                         error: err instanceof Error ? err.message : String(err),
                     });
                 });
-                logger.info('upstream_old_connector_stopped', {
+                logger.debug('upstream_old_connector_stopped', {
                     connect_epoch: this.connectEpoch,
                     target_system_id: this.targetSystemId,
                     timestamp: new Date().toISOString(),

package/dist/esm/version.js

@@ -1,7 +1,7 @@
 // This file is auto-generated during build - do not edit manually
-// Generated from package.json version: 0.3.5-test.941
+// Generated from package.json version: 0.3.5-test.943
 /**
  * The package version, injected at build time.
  * @internal
  */
-export const VERSION = '0.3.5-test.941';
+export const VERSION = '0.3.5-test.943';