@mindexec/cli 0.2.113 → 0.2.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindexec/cli",
-  "version": "0.2.113",
+  "version": "0.2.115",
   "description": "MindExec local runtime and bridge CLI",
   "main": "server.js",
   "type": "module",
@@ -20,7 +20,7 @@
   "scripts": {
     "start": "node launch-bridge.cjs",
     "dev": "node launch-bridge.cjs --watch",
-    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs",
+    "test:syntax": "node --check server.js && node --check remote-hub.js && node --check codex-runtime.js && node --check launch-bridge.cjs && node --check port-guard.cjs && node --check scripts/setup-tree-sitter-grammars.mjs && node --check scripts/auth-session-smoke.mjs && node --check scripts/remote-hub-smoke.mjs && node --check scripts/remote-hub-scale-smoke.mjs && node --check scripts/remote-fleet-render-smoke.mjs && node --check scripts/remote-http-smoke.mjs && node --check scripts/remote-frame-ws-smoke.mjs",
     "test:auth": "node scripts/auth-session-smoke.mjs",
     "test:remote": "node scripts/remote-hub-smoke.mjs",
     "test:remote:scale": "node scripts/remote-hub-scale-smoke.mjs",

package/remote-hub.js

@@ -601,6 +601,7 @@ export function createRemoteHub(options = {}) {
     const logEvent = options.logEvent || (() => {});
     const logWarn = options.logWarn || (() => {});
     const emitEvent = options.emitEvent || (() => {});
+    const emitFrame = typeof options.emitFrame === 'function' ? options.emitFrame : (() => {});
 
     const enabled = isEnabledValue(env.MINDEXEC_REMOTE_HUB ?? env.REMOTE_HUB_ENABLED, true)
         && !isDisabledValue(env.REMOTE_HUB_DISABLED);
@@ -985,6 +986,14 @@ export function createRemoteHub(options = {}) {
         });
         device.latestLiveFrame = frame;
         rememberRecentFramePayload(device, 'live', frame);
+        emitFrame({
+            kind: 'live',
+            deviceId: device.deviceId,
+            frame: serializeRemoteFrame(frame, device.deviceId, 'live', { includeDataUrl: false }),
+            payload: frame.payload,
+            mimeType: frame.mimeType,
+            byteLength: frame.byteLength
+        });
         device.activeLiveStream.lastFrameAt = frame.receivedAt;
         device.activeLiveStream.lastFrameSeq = frame.frameSeq;
         device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;
@@ -1780,6 +1789,14 @@ export function createRemoteHub(options = {}) {
             accessToken: createFrameAccessToken()
         };
         rememberRecentFramePayload(device, 'live', device.latestLiveFrame);
+        emitFrame({
+            kind: 'live',
+            deviceId: device.deviceId,
+            frame: serializeRemoteFrame(device.latestLiveFrame, device.deviceId, 'live', { includeDataUrl: false }),
+            payload: device.latestLiveFrame.payload,
+            mimeType: device.latestLiveFrame.mimeType,
+            byteLength: device.latestLiveFrame.byteLength
+        });
         device.activeLiveStream.lastFrameAt = device.lastSeenAt;
         device.activeLiveStream.lastFrameSeq = frameSeq;
         device.activeLiveStream.framesReceived = (device.activeLiveStream.framesReceived || 0) + 1;

package/scripts/remote-frame-ws-smoke.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WebSocket } from 'ws';
+
+const BRIDGE_TOKEN = 'remote-frame-ws-smoke-token';
+const PAIR_TOKEN = 'remote-frame-ws-pair-token';
+
+function wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function findFreePort() {
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+
+async function fetchJson(url, options = {}) {
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            ...(options.body ? { 'Content-Type': 'application/json' } : {}),
+            'X-Bridge-Token': BRIDGE_TOKEN,
+            ...(options.headers || {})
+        }
+    });
+    const payload = await response.json().catch(() => null);
+    return { ok: response.ok, status: response.status, payload };
+}
+
+async function waitForBridge(baseUrl, details) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < 30000) {
+        try {
+            const result = await fetchJson(`${baseUrl}/api/remote/status`);
+            if (result.ok && result.payload?.started === true) {
+                return result.payload;
+            }
+        } catch {
+            // Server is still starting.
+        }
+        await wait(100);
+    }
+
+    throw new Error(`Timed out waiting for LocalBridge.\n${details()}`);
+}
+
+function spawnBridge({ bridgePort, remoteHubPort }) {
+    const bridgeRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const env = {
+        ...process.env,
+        BRIDGE_PORT: String(bridgePort),
+        BRIDGE_TOKEN,
+        BRIDGE_REQUIRE_TOKEN: '1',
+        MINDEXEC_REMOTE_HUB: '1',
+        MINDEXEC_REMOTE_SYNTHETIC_FLEET: '1',
+        REMOTE_HUB_HOST: '127.0.0.1',
+        REMOTE_HUB_PORT: String(remoteHubPort),
+        REMOTE_HUB_PAIR_TOKEN: PAIR_TOKEN,
+        NO_COLOR: '1'
+    };
+
+    const child = spawn(process.execPath, ['server.js'], {
+        cwd: bridgeRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        env
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => {
+        stdout += chunk.toString();
+    });
+    child.stderr.on('data', chunk => {
+        stderr += chunk.toString();
+    });
+
+    const exitPromise = new Promise(resolve => child.once('exit', resolve));
+    const stop = async () => {
+        if (child.exitCode === null && !child.killed) {
+            child.kill('SIGTERM');
+            await Promise.race([exitPromise, wait(5000)]);
+            if (child.exitCode === null && !child.killed) {
+                child.kill('SIGKILL');
+            }
+        }
+    };
+
+    return {
+        baseUrl: `http://127.0.0.1:${bridgePort}`,
+        details: () => `stdout=${stdout}\nstderr=${stderr}`,
+        stop
+    };
+}
+
+function parseFramePacket(data) {
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    assert.ok(buffer.length > 8, 'binary frame packet should include header, metadata, and payload');
+    const metaLength = buffer.readUInt32BE(0);
+    assert.ok(metaLength > 0 && metaLength < 64 * 1024, 'metadata length should be bounded');
+    assert.ok(4 + metaLength < buffer.length, 'packet should include binary payload after metadata');
+    const metadata = JSON.parse(buffer.subarray(4, 4 + metaLength).toString('utf8'));
+    const payload = buffer.subarray(4 + metaLength);
+    return { metadata, payload };
+}
+
+async function waitForBinaryFrame(ws) {
+    return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('timed out waiting for binary frame')), 10000);
+        ws.on('message', data => {
+            if (typeof data === 'string') {
+                return;
+            }
+            const raw = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            if (raw[0] === 0x7b || raw[0] === 0x5b) {
+                return;
+            }
+            clearTimeout(timeout);
+            try {
+                resolve(parseFramePacket(raw));
+            } catch (error) {
+                reject(error);
+            }
+        });
+        ws.on('error', reject);
+        ws.on('close', () => reject(new Error('websocket closed before binary frame')));
+    });
+}
+
+async function main() {
+    const bridgePort = await findFreePort();
+    const remoteHubPort = await findFreePort();
+    const bridge = spawnBridge({ bridgePort, remoteHubPort });
+
+    try {
+        const status = await waitForBridge(bridge.baseUrl, bridge.details);
+        assert.equal(status.started, true);
+
+        const seed = await fetchJson(`${bridge.baseUrl}/api/remote/synthetic/seed`, {
+            method: 'POST',
+            body: JSON.stringify({ count: 4, connectedRatio: 1, liveRatio: 1 })
+        });
+        assert.equal(seed.ok, true);
+
+        const devicesResult = await fetchJson(`${bridge.baseUrl}/api/remote/devices`);
+        assert.equal(devicesResult.ok, true);
+        const device = devicesResult.payload?.devices?.find(item => item.connected === true);
+        assert.ok(device?.deviceId, 'expected connected synthetic device');
+
+        const ws = new WebSocket(`${bridge.baseUrl.replace(/^http:/, 'ws:')}/api/remote/frames/ws?token=${encodeURIComponent(BRIDGE_TOKEN)}`);
+        await new Promise((resolve, reject) => {
+            ws.once('open', resolve);
+            ws.once('error', reject);
+        });
+        ws.send(JSON.stringify({ type: 'subscribe', deviceIds: [device.deviceId] }));
+
+        const framePromise = waitForBinaryFrame(ws);
+        const live = await fetchJson(`${bridge.baseUrl}/api/remote/devices/${encodeURIComponent(device.deviceId)}/live/start`, {
+            method: 'POST',
+            body: JSON.stringify({ fps: 10 })
+        });
+        assert.equal(live.ok, true);
+
+        const frame = await framePromise;
+        assert.equal(frame.metadata.type, 'remote.frame.binary');
+        assert.equal(frame.metadata.kind, 'live');
+        assert.equal(frame.metadata.deviceId, device.deviceId);
+        assert.ok(frame.metadata.frameSeq > 0, 'frameSeq should be positive');
+        assert.equal(frame.metadata.mimeType, 'image/png');
+        assert.ok(frame.payload.length > 0, 'payload should be non-empty');
+        ws.close();
+
+        console.log('Remote frame WebSocket smoke OK');
+    } finally {
+        await bridge.stop();
+    }
+}
+
+main().catch(error => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/server.js

@@ -2120,28 +2120,41 @@ app.get('/api/local-files/:id', async (req, res) => {
 
 const httpServer = createServer(app);
 const wss = new WebSocketServer({ noServer: true });
+const remoteFrameWss = new WebSocketServer({ noServer: true });
 const wsClients = new Set();
-const shellJobs = new Map();
-
-httpServer.on('upgrade', (req, socket, head) => {
-    try {
-        const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
-        const token = parsed.searchParams.get('token') || '';
-
-        if (parsed.pathname !== '/events' || token !== wsToken) {
-            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
-            socket.destroy();
-            return;
-        }
-
-        wss.handleUpgrade(req, socket, head, (ws) => {
-            wss.emit('connection', ws, req);
-        });
-    } catch {
-        socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
-        socket.destroy();
-    }
-});
+const remoteFrameClients = new Set();
+const shellJobs = new Map();
+
+httpServer.on('upgrade', (req, socket, head) => {
+    try {
+        const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+        const token = parsed.searchParams.get('token') || '';
+
+        if (parsed.pathname === '/events' && token === wsToken) {
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                wss.emit('connection', ws, req);
+            });
+            return;
+        }
+
+        if (parsed.pathname === '/api/remote/frames/ws'
+            && (!bridgeAuthRequired || token === bridgeToken)) {
+            remoteFrameWss.handleUpgrade(req, socket, head, (ws) => {
+                remoteFrameWss.emit('connection', ws, req);
+            });
+            return;
+        }
+
+        {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+    } catch {
+        socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+        socket.destroy();
+    }
+});
 
 wss.on('connection', (ws) => {
     wsClients.add(ws);
@@ -2154,11 +2167,168 @@ wss.on('connection', (ws) => {
             projectRoot: projectSession.rootPath,
             fileCount: projectSession.symbolsByFile.size
         }
-    }));
-});
-
-// Helper: Validate path is within workspace
-function validatePath(requestedPath) {
+    }));
+});
+
+function normalizeRemoteFrameWsDeviceIds(value) {
+    const raw = [];
+    if (Array.isArray(value)) {
+        raw.push(...value);
+    } else if (typeof value === 'string') {
+        raw.push(...value.split(','));
+    }
+
+    const ids = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const id = String(entry || '').trim();
+        if (!id || seen.has(id)) {
+            continue;
+        }
+
+        seen.add(id);
+        ids.push(id);
+        if (ids.length >= 240) {
+            break;
+        }
+    }
+
+    return ids;
+}
+
+function sendRemoteFrameClientJson(ws, payload) {
+    if (!ws || ws.readyState !== 1) {
+        return false;
+    }
+
+    try {
+        ws.send(JSON.stringify(payload));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function updateRemoteFrameClientSubscription(ws, payload = {}) {
+    const deviceIds = normalizeRemoteFrameWsDeviceIds(payload.deviceIds ?? payload.devices ?? payload.deviceId);
+    ws.remoteFrameDeviceIds = new Set(deviceIds);
+    ws.remoteFrameSubscriptionUpdatedAt = new Date().toISOString();
+    sendRemoteFrameClientJson(ws, {
+        type: 'RemoteFrameSubscription',
+        timestamp: ws.remoteFrameSubscriptionUpdatedAt,
+        deviceIds,
+        mode: deviceIds.length > 0 ? 'selected-devices' : 'all-devices'
+    });
+}
+
+function buildRemoteFrameBinaryPacket(frameEvent) {
+    const payload = frameEvent?.payload;
+    if (!Buffer.isBuffer(payload) || payload.length === 0) {
+        return null;
+    }
+
+    const frame = frameEvent.frame || {};
+    const metadata = {
+        type: 'remote.frame.binary',
+        kind: frameEvent.kind || 'live',
+        deviceId: frameEvent.deviceId || frame.deviceId || '',
+        frameSeq: Number(frame.frameSeq || 0) || 0,
+        streamId: frame.streamId || '',
+        width: Number(frame.width || 0) || 0,
+        height: Number(frame.height || 0) || 0,
+        mimeType: frameEvent.mimeType || frame.mimeType || frame.format || 'image/jpeg',
+        mode: frame.mode || '',
+        fps: Number(frame.fps || 0) || 0,
+        capturedAt: frame.capturedAt || '',
+        receivedAt: frame.receivedAt || '',
+        byteLength: Number(frameEvent.byteLength || payload.length) || payload.length,
+        transport: frame.transport || '',
+        contentHash: frame.contentHash || '',
+        captureMs: Number(frame.captureMs || 0) || 0,
+        sameContentStreak: Number(frame.sameContentStreak || 0) || 0
+    };
+    const metaBuffer = Buffer.from(JSON.stringify(metadata), 'utf8');
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32BE(metaBuffer.length, 0);
+    return Buffer.concat([header, metaBuffer, payload], header.length + metaBuffer.length + payload.length);
+}
+
+function broadcastRemoteBinaryFrame(frameEvent) {
+    if (remoteFrameClients.size === 0) {
+        return;
+    }
+
+    const deviceId = String(frameEvent?.deviceId || frameEvent?.frame?.deviceId || '').trim();
+    if (!deviceId) {
+        return;
+    }
+
+    const packet = buildRemoteFrameBinaryPacket(frameEvent);
+    if (!packet) {
+        return;
+    }
+
+    for (const client of remoteFrameClients) {
+        if (client.readyState !== 1) {
+            continue;
+        }
+
+        const ids = client.remoteFrameDeviceIds;
+        if (ids instanceof Set && ids.size > 0 && !ids.has(deviceId)) {
+            continue;
+        }
+
+        if (client.bufferedAmount > 8 * 1024 * 1024) {
+            client.remoteFrameDroppedCount = (client.remoteFrameDroppedCount || 0) + 1;
+            continue;
+        }
+
+        try {
+            client.send(packet, { binary: true });
+            client.remoteFrameSentCount = (client.remoteFrameSentCount || 0) + 1;
+        } catch {
+            client.remoteFrameDroppedCount = (client.remoteFrameDroppedCount || 0) + 1;
+        }
+    }
+}
+
+remoteFrameWss.on('connection', (ws, req) => {
+    remoteFrameClients.add(ws);
+    ws.binaryType = 'arraybuffer';
+    try {
+        const parsed = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+        updateRemoteFrameClientSubscription(ws, {
+            deviceIds: parsed.searchParams.get('devices') || ''
+        });
+    } catch {
+        updateRemoteFrameClientSubscription(ws, {});
+    }
+
+    ws.on('message', data => {
+        try {
+            const text = Buffer.isBuffer(data) ? data.toString('utf8') : String(data || '');
+            const payload = JSON.parse(text);
+            if (payload?.type === 'subscribe') {
+                updateRemoteFrameClientSubscription(ws, payload);
+            }
+        } catch {
+            sendRemoteFrameClientJson(ws, {
+                type: 'RemoteFrameSubscriptionError',
+                error: 'invalid-message'
+            });
+        }
+    });
+    ws.on('close', () => remoteFrameClients.delete(ws));
+    ws.on('error', () => remoteFrameClients.delete(ws));
+    sendRemoteFrameClientJson(ws, {
+        type: 'RemoteFrameSocketReady',
+        timestamp: new Date().toISOString(),
+        protocol: 'mindexec.remote.frames.binary.v1'
+    });
+});
+
+// Helper: Validate path is within workspace
+function validatePath(requestedPath) {
     const fullPath = resolveWorkspaceBoundPath(requestedPath);
     if (!isPathWithin(workspacePath, fullPath)) {
         throw new Error('Path must be within workspace');
@@ -2726,6 +2896,7 @@ const remoteHub = createRemoteHub({
     logWarn,
     logError,
     emitEvent: emitBridgeEvent,
+    emitFrame: broadcastRemoteBinaryFrame,
     managerPackage: BRIDGE_PACKAGE_NAME,
     managerVersion: BRIDGE_VERSION,
     hostInstanceId: BRIDGE_INSTANCE_ID
@@ -3136,7 +3307,6 @@ async function startRemoteAgentConnection(options = {}) {
 
     const activeConnectionKeys = new Set(managers.map(manager => createRemoteAgentConnectionKey(manager, leaseId)));
     if (isRemoteAgentProcessRunning()
-        && remoteAgentState.ready === true
         && activeConnectionKeys.has(remoteAgentState.connectionKey)) {
         return { ok: true, alreadyRunning: true, agent: serializeRemoteAgentState() };
     }
@@ -7773,8 +7943,9 @@ app.get('/api/status', async (req, res) => {
         status: 'ok',
         version: BRIDGE_VERSION,
         workspace: workspacePath,
-        wsToken,
-        wsPath: '/events',
+        wsToken,
+        wsPath: '/events',
+        remoteFrameWsPath: '/api/remote/frames/ws',
         bridgeToken,
         bridgeTokenHeader,
         bridgeAuthRequired,

package/wwwroot/_content/MindExecution.Shared/js/mind-map-core.js

@@ -5,7 +5,7 @@
     const DEBUG = false;
     const FPS_DEBUG = false;
     const FRAME_PERF_DEBUG = false;
-const MINDMAP_CORE_BUILD_ID = '20260616-remote-agent-sticky-overlay-frames-v571';
+const MINDMAP_CORE_BUILD_ID = '20260616-remote-ws-binary-frames-v572';
     const CanvasPhase = Object.freeze({
         Booting: 'booting',
         BoardFileLoading: 'board-file-loading',

package/wwwroot/_content/MindExecution.Shared/js/mind-map-css3d-manager.js

@@ -13351,13 +13351,17 @@
     const REMOTE_FLEET_FRAME_BLOB_CACHE_LIMIT = 96;
     const REMOTE_FLEET_LIVE_FRAME_DECODE_TIMEOUT_MS = 180;
     const REMOTE_FLEET_THUMBNAIL_FRAME_DECODE_TIMEOUT_MS = 1200;
+    const REMOTE_FLEET_BINARY_FRAME_WS_RECONNECT_MS = 1500;
+    const REMOTE_FLEET_BINARY_FRAME_SUBSCRIBE_MS = 1000;
     const REMOTE_FLEET_TASK_FOLLOW_INITIAL_MS = 250;
     const REMOTE_FLEET_TASK_FOLLOW_REFRESH_MS = 2000;
     const REMOTE_FLEET_TASK_FOLLOW_MAX_TICKS = 60;
     const REMOTE_FLEET_HOST_LEASE_REFRESH_MS = 10000;
     const remoteFleetHostLeaseTimers = new Map();
     const remoteFleetLocalHostTargets = new Map();
+    const remoteFleetBinaryFrameSessions = new Map();
     const remoteFleetFrameBlobCache = new Map();
+    let remoteFleetBridgeStatusPromise = null;
     let activeRemoteFleetControlPopup = null;
 
     function findRemoteFleetBodyByNodeId(nodeId) {
@@ -13495,6 +13499,7 @@
 
     function clearRemoteFleetTimers(bodyView) {
         if (!bodyView) return;
+        releaseRemoteFleetBinaryFrameSocket(bodyView);
         if (bodyView._remoteFleetLiveRefreshTimer) {
             clearInterval(bodyView._remoteFleetLiveRefreshTimer);
             bodyView._remoteFleetLiveRefreshTimer = null;
@@ -13519,6 +13524,323 @@
         }
     }
 
+    function getRemoteFleetBridgeBaseUrlCandidates() {
+        const candidates = [];
+        const push = value => {
+            const text = String(value || '').trim().replace(/\/+$/, '');
+            if (text && !candidates.includes(text)) {
+                candidates.push(text);
+            }
+        };
+
+        push(window.MindExecLocalBridge?.activeBridgeUrl);
+        push(window.location?.origin);
+        return candidates;
+    }
+
+    async function getRemoteFleetBridgeStatusForFrames() {
+        if (remoteFleetBridgeStatusPromise) {
+            return remoteFleetBridgeStatusPromise;
+        }
+
+        remoteFleetBridgeStatusPromise = (async () => {
+            const nonce = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+            let lastError = null;
+            for (const baseUrl of getRemoteFleetBridgeBaseUrlCandidates()) {
+                try {
+                    const response = await fetch(`${baseUrl}/api/status?remoteFrames=ws&cb=${encodeURIComponent(nonce)}`, {
+                        cache: 'no-store',
+                        credentials: 'omit'
+                    });
+                    if (!response.ok) {
+                        lastError = new Error(`status:${response.status}`);
+                        continue;
+                    }
+
+                    const status = await response.json();
+                    status.__remoteFleetBridgeBaseUrl = baseUrl;
+                    return status;
+                } catch (error) {
+                    lastError = error;
+                }
+            }
+
+            throw lastError || new Error('bridge-status-unavailable');
+        })();
+
+        try {
+            return await remoteFleetBridgeStatusPromise;
+        } catch (error) {
+            remoteFleetBridgeStatusPromise = null;
+            throw error;
+        }
+    }
+
+    function buildRemoteFleetBinaryFrameWsUrl(status) {
+        const baseUrl = String(status?.__remoteFleetBridgeBaseUrl || window.location?.origin || '').trim();
+        const path = String(status?.remoteFrameWsPath || '/api/remote/frames/ws').trim() || '/api/remote/frames/ws';
+        if (!baseUrl) {
+            return '';
+        }
+
+        const url = new URL(path, baseUrl);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        const bridgeToken = String(status?.bridgeToken || '').trim();
+        if (bridgeToken) {
+            url.searchParams.set('token', bridgeToken);
+        }
+        return url.toString();
+    }
+
+    async function parseRemoteFleetBinaryFrameMessage(data) {
+        let buffer = null;
+        if (data instanceof ArrayBuffer) {
+            buffer = data;
+        } else if (data?.arrayBuffer && typeof data.arrayBuffer === 'function') {
+            buffer = await data.arrayBuffer();
+        }
+
+        if (!buffer || buffer.byteLength < 5) {
+            return null;
+        }
+
+        const view = new DataView(buffer);
+        const metaLength = view.getUint32(0);
+        if (!Number.isFinite(metaLength)
+            || metaLength <= 0
+            || metaLength > 64 * 1024
+            || 4 + metaLength >= buffer.byteLength) {
+            return null;
+        }
+
+        const metadataBytes = new Uint8Array(buffer, 4, metaLength);
+        const metadataText = new TextDecoder().decode(metadataBytes);
+        const metadata = JSON.parse(metadataText);
+        if (String(metadata?.type || '').toLowerCase() !== 'remote.frame.binary') {
+            return null;
+        }
+
+        const payload = buffer.slice(4 + metaLength);
+        const mimeType = String(metadata.mimeType || metadata.format || 'image/jpeg').trim() || 'image/jpeg';
+        const objectUrl = URL.createObjectURL(new Blob([payload], { type: mimeType }));
+        return {
+            ...metadata,
+            kind: String(metadata.kind || 'live').toLowerCase() === 'thumbnail' ? 'thumbnail' : 'live',
+            mimeType,
+            frameUrl: objectUrl,
+            framePath: objectUrl,
+            dataUrl: '',
+            _remoteFleetObjectUrl: objectUrl,
+            _remoteFleetBinaryFrame: true
+        };
+    }
+
+    function releaseRemoteFleetFrameObjectUrl(preview, nextObjectUrl = '') {
+        const previous = preview?._remoteFleetObjectUrl || '';
+        if (previous && previous !== nextObjectUrl && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+            try {
+                URL.revokeObjectURL(previous);
+            } catch {
+                // Best-effort browser memory cleanup.
+            }
+        }
+
+        if (preview) {
+            preview._remoteFleetObjectUrl = nextObjectUrl || '';
+        }
+    }
+
+    function getRemoteFleetBinaryFrameDeviceIds(getDeviceIds) {
+        const ids = typeof getDeviceIds === 'function'
+            ? getDeviceIds()
+            : [];
+        return Array.from(new Set((Array.isArray(ids) ? ids : [])
+            .map(value => String(value || '').trim())
+            .filter(Boolean)))
+            .slice(0, 240);
+    }
+
+    function refreshRemoteFleetBinaryFrameSubscription(session, force = false) {
+        if (!session?.ws || session.ws.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+
+        const deviceIds = getRemoteFleetBinaryFrameDeviceIds(session.getDeviceIds);
+        const key = deviceIds.join('\n');
+        if (!force && session.subscriptionKey === key) {
+            return true;
+        }
+
+        session.subscriptionKey = key;
+        session.ws.send(JSON.stringify({
+            type: 'subscribe',
+            nodeId: session.nodeId,
+            deviceIds
+        }));
+        return true;
+    }
+
+    function scheduleRemoteFleetBinaryFrameReconnect(session) {
+        if (!session || session.reconnectTimer || session.bodies.size === 0) {
+            return;
+        }
+
+        session.reconnectTimer = setTimeout(() => {
+            session.reconnectTimer = null;
+            openRemoteFleetBinaryFrameSocket(session);
+        }, REMOTE_FLEET_BINARY_FRAME_WS_RECONNECT_MS);
+    }
+
+    async function openRemoteFleetBinaryFrameSocket(session) {
+        if (!session || session.bodies.size === 0 || typeof WebSocket !== 'function') {
+            return false;
+        }
+
+        if (session.ws && (session.ws.readyState === WebSocket.OPEN || session.ws.readyState === WebSocket.CONNECTING)) {
+            refreshRemoteFleetBinaryFrameSubscription(session);
+            return true;
+        }
+
+        try {
+            const status = await getRemoteFleetBridgeStatusForFrames();
+            const wsUrl = buildRemoteFleetBinaryFrameWsUrl(status);
+            if (!wsUrl) {
+                throw new Error('remote-frame-ws-url-unavailable');
+            }
+
+            const ws = new WebSocket(wsUrl);
+            session.ws = ws;
+            session.subscriptionKey = '';
+            ws.binaryType = 'arraybuffer';
+            ws.onopen = () => {
+                window.RuntimeTrace?.emit?.('remote.frame.wsOpen', { nodeId: session.nodeId });
+                refreshRemoteFleetBinaryFrameSubscription(session, true);
+                if (!session.subscriptionTimer) {
+                    session.subscriptionTimer = setInterval(
+                        () => refreshRemoteFleetBinaryFrameSubscription(session),
+                        REMOTE_FLEET_BINARY_FRAME_SUBSCRIBE_MS
+                    );
+                }
+            };
+            ws.onmessage = event => {
+                if (typeof event.data === 'string') {
+                    window.RuntimeTrace?.emit?.('remote.frame.wsMeta', {
+                        nodeId: session.nodeId,
+                        message: event.data.slice(0, 120)
+                    });
+                    return;
+                }
+
+                parseRemoteFleetBinaryFrameMessage(event.data)
+                    .then(frame => {
+                        if (!frame || session.bodies.size === 0) {
+                            if (frame?._remoteFleetObjectUrl && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+                                URL.revokeObjectURL(frame._remoteFleetObjectUrl);
+                            }
+                            return;
+                        }
+
+                        let applied = 0;
+                        session.bodies.forEach(body => {
+                            if (document.body.contains(body)) {
+                                applied += applyRemoteFleetFramePatches(body, [frame]);
+                            }
+                        });
+
+                        if (applied <= 0 && frame._remoteFleetObjectUrl && typeof URL !== 'undefined' && typeof URL.revokeObjectURL === 'function') {
+                            URL.revokeObjectURL(frame._remoteFleetObjectUrl);
+                        }
+                    })
+                    .catch(error => {
+                        window.RuntimeTrace?.emit?.('remote.frame.wsParseFailed', {
+                            nodeId: session.nodeId,
+                            error: error?.message || String(error || '')
+                        });
+                    });
+            };
+            ws.onclose = () => {
+                if (session.ws === ws) {
+                    session.ws = null;
+                }
+                window.RuntimeTrace?.emit?.('remote.frame.wsClosed', { nodeId: session.nodeId });
+                scheduleRemoteFleetBinaryFrameReconnect(session);
+            };
+            ws.onerror = () => {
+                try {
+                    ws.close();
+                } catch {
+                    // Ignore WebSocket close failures.
+                }
+            };
+            return true;
+        } catch (error) {
+            window.RuntimeTrace?.emit?.('remote.frame.wsOpenFailed', {
+                nodeId: session.nodeId,
+                error: error?.message || String(error || '')
+            });
+            scheduleRemoteFleetBinaryFrameReconnect(session);
+            return false;
+        }
+    }
+
+    function startRemoteFleetBinaryFrameSocket(bodyView, getDeviceIds) {
+        const nodeId = String(bodyView?.dataset?.nodeId || '').trim();
+        if (!nodeId || typeof WebSocket !== 'function') {
+            return false;
+        }
+
+        let session = remoteFleetBinaryFrameSessions.get(nodeId);
+        if (!session) {
+            session = {
+                nodeId,
+                bodies: new Set(),
+                ws: null,
+                reconnectTimer: null,
+                subscriptionTimer: null,
+                subscriptionKey: '',
+                getDeviceIds: null
+            };
+            remoteFleetBinaryFrameSessions.set(nodeId, session);
+        }
+
+        session.bodies.add(bodyView);
+        session.getDeviceIds = getDeviceIds;
+        bodyView._remoteFleetBinaryFrameSession = session;
+        openRemoteFleetBinaryFrameSocket(session).catch(() => undefined);
+        return true;
+    }
+
+    function releaseRemoteFleetBinaryFrameSocket(bodyView) {
+        const session = bodyView?._remoteFleetBinaryFrameSession;
+        if (!session) {
+            return;
+        }
+
+        delete bodyView._remoteFleetBinaryFrameSession;
+        session.bodies.delete(bodyView);
+        if (session.bodies.size > 0) {
+            return;
+        }
+
+        if (session.reconnectTimer) {
+            clearTimeout(session.reconnectTimer);
+            session.reconnectTimer = null;
+        }
+        if (session.subscriptionTimer) {
+            clearInterval(session.subscriptionTimer);
+            session.subscriptionTimer = null;
+        }
+        if (session.ws) {
+            try {
+                session.ws.close();
+            } catch {
+                // Ignore WebSocket close failures.
+            }
+            session.ws = null;
+        }
+        remoteFleetBinaryFrameSessions.delete(session.nodeId);
+    }
+
     function requestRemoteFleetFrameLoopFrame(callback) {
         if (typeof requestAnimationFrame === 'function') {
             return {
@@ -14021,6 +14343,7 @@
         }
 
         const nextSeq = Number(frame.frameSeq || 0);
+        releaseRemoteFleetFrameObjectUrl(preview, frame._remoteFleetObjectUrl || '');
         preview.dataset.remoteFleetFrameKind = frame.kind;
         preview.dataset.remoteFleetFrameSeq = String(nextSeq || 0);
         preview.dataset.remoteFleetFrameUrl = frame.frameUrl;
@@ -17086,7 +17409,13 @@
                     error: error?.message || String(error || '')
                 });
             });
-            startRemoteFleetFrameLoop(bodyView, REMOTE_FLEET_LIVE_FRAME_REFRESH_MS, () => refreshRemoteFleetVisibleLiveFrames());
+            const binaryFrameSocketStarted = startRemoteFleetBinaryFrameSocket(bodyView, () => {
+                const liveIds = getVisibleLiveFrameDeviceIds();
+                return liveIds.length > 0 ? liveIds : getVisibleFrameDeviceIds();
+            });
+            if (!binaryFrameSocketStarted) {
+                startRemoteFleetFrameLoop(bodyView, REMOTE_FLEET_LIVE_FRAME_REFRESH_MS, () => refreshRemoteFleetVisibleLiveFrames());
+            }
             bodyView._remoteFleetLiveRefreshTimer = setInterval(async () => {
                 if (!document.body.contains(bodyView)) {
                     clearRemoteFleetTimers(bodyView);

package/wwwroot/index.html

@@ -7,8 +7,8 @@
     <title>MindExec | Run your ideas as AI task graphs</title>
     <meta name="description" content="MindExec is an AI execution canvas for solo builders, researchers, developers, and creators. Start with free browser tools, then move serious work into saved MindCanvas projects." />
     <base href="/" />
-    <link rel="stylesheet" href="_content/MindExecution.Shared/css/app.css?v=20260616-remote-agent-sticky-overlay-frames-v571" />
-    <link rel="stylesheet" href="_content/MindExecution.Shared/css/mind-map-overrides.css?v=20260616-remote-agent-sticky-overlay-frames-v571" />
+    <link rel="stylesheet" href="_content/MindExecution.Shared/css/app.css?v=20260616-remote-ws-binary-frames-v572" />
+    <link rel="stylesheet" href="_content/MindExecution.Shared/css/mind-map-overrides.css?v=20260616-remote-ws-binary-frames-v572" />
     <!-- ?쇄뼹??Font Awesome (local) ?쇄뼹??-->
     <link rel="stylesheet" href="_content/MindExecution.Shared/lib/font-awesome/css/all.min.css" />
     <!-- ?꿎뼯??-->
@@ -579,7 +579,7 @@
             }
 
             const base = '_content/MindExecution.Shared/js/';
-        const scriptVersion = '20260616-remote-agent-sticky-overlay-frames-v571';
+        const scriptVersion = '20260616-remote-ws-binary-frames-v572';
             const scriptUrl = (script) => `${base}${script}?v=${scriptVersion}`;
             console.log(`[Script Loader] Shared JS version: ${scriptVersion}`);
             const criticalScripts = [

package/wwwroot/service-worker-assets.js

@@ -1,5 +1,5 @@
 self.assetsManifest = {
-    "version":  "WOO5ml3v",
+    "version":  "DOWuXy9Z",
     "assets":  [
                    {
                        "hash":  "sha256-+CSYMcqLNTsq3VnH11jgYyOCCdxvHzL74CBmo4sCmMU=",
@@ -78,7 +78,7 @@
                        "url":  "_content/MindExecution.Shared/js/marked.min.js"
                    },
                    {
-                       "hash":  "sha256-UtXpHLTnYeP2BPz7IAicclCMMdLjzYd29I+u5rMi270=",
+                       "hash":  "sha256-HZDEcs9fkSz0iNXD6WOKZwOj8VrjJD+r4oRH9XBQhjA=",
                        "url":  "_content/MindExecution.Shared/js/mind-map-core.js"
                    },
                    {
@@ -86,7 +86,7 @@
                        "url":  "_content/MindExecution.Shared/js/mind-map-core.js.backup"
                    },
                    {
-                       "hash":  "sha256-itUEN+HfFS2lC/aHq02RNF70gDWhggsJok0F3uOLHT0=",
+                       "hash":  "sha256-KgIwiH8bPKxBAXnomKCDPKRgD/hL6CSeV2nM5EpyMdQ=",
                        "url":  "_content/MindExecution.Shared/js/mind-map-css3d-manager.js"
                    },
                    {
@@ -834,7 +834,7 @@
                        "url":  "image-manifest.json"
                    },
                    {
-                       "hash":  "sha256-fojDZj+Dr+k8SI1esa0xdrCRBfXVHxr+cLNb3bvD7t8=",
+                       "hash":  "sha256-ANyJXyCBiGthYmrg5ygLEqNR6Vuu+eXOi+fQ/da00pM=",
                        "url":  "index.html"
                    },
                    {

package/wwwroot/service-worker.js

@@ -1,4 +1,4 @@
-/* Manifest version: WOO5ml3v */
+/* Manifest version: DOWuXy9Z */
 // Hosted deployments should prefer the network over stale offline caches.
 // This service worker immediately clears old Blazor offline caches and unregisters itself.