@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/server/web-socket-protocol.test.ts

@@ -1,241 +1,740 @@
 import { describe, it, expect } from 'vitest';
-import { encodeMessage, decodePluginMessage } from './web-socket-protocol.js';
+import {
+  encodeMessage,
+  decodePluginMessage,
+  decodeServerMessage,
+  type PluginMessage,
+  type ServerMessage,
+} from './web-socket-protocol.js';
 
-describe('encodeMessage', () => {
-  it('encodes a welcome message', () => {
-    const json = encodeMessage({
-      type: 'welcome',
-      sessionId: 'abc-123',
-      payload: { sessionId: 'abc-123' },
+/** Encode a plugin message, decode it, and return the result. */
+function roundTripPlugin(msg: Record<string, unknown>): PluginMessage | null {
+  return decodePluginMessage(JSON.stringify(msg));
+}
+
+/** Encode a server message via encodeMessage, decode it, and return the result. */
+function roundTripServer(msg: ServerMessage): ServerMessage | null {
+  return decodeServerMessage(encodeMessage(msg));
+}
+
+describe('decodePluginMessage', () => {
+  describe('scriptComplete', () => {
+    it('decodes scriptComplete with requestId', () => {
+      const msg = roundTripPlugin({
+        type: 'scriptComplete',
+        sessionId: 'sess-1',
+        requestId: 'req-42',
+        payload: { success: true },
+      });
+      expect(msg).toEqual({
+        type: 'scriptComplete',
+        sessionId: 'sess-1',
+        requestId: 'req-42',
+        payload: { success: true, error: undefined },
+      });
     });
-    const parsed = JSON.parse(json);
-    expect(parsed).toEqual({
-      type: 'welcome',
-      sessionId: 'abc-123',
-      payload: { sessionId: 'abc-123' },
+
+    it('decodes scriptComplete without requestId (v1 compat)', () => {
+      const msg = roundTripPlugin({
+        type: 'scriptComplete',
+        sessionId: 'sess-1',
+        payload: { success: false, error: 'oops' },
+      });
+      expect(msg).toEqual({
+        type: 'scriptComplete',
+        sessionId: 'sess-1',
+        payload: { success: false, error: 'oops' },
+      });
+      expect(msg).not.toHaveProperty('requestId');
     });
   });
 
-  it('encodes a shutdown message', () => {
-    const json = encodeMessage({ type: 'shutdown', sessionId: 'abc-123', payload: {} });
-    const parsed = JSON.parse(json);
-    expect(parsed).toEqual({ type: 'shutdown', sessionId: 'abc-123', payload: {} });
-  });
+  describe('register', () => {
+    const validRegister = {
+      type: 'register',
+      sessionId: 'sess-1',
+      payload: {
+        pluginVersion: '2.0.0',
+        instanceId: 'inst-abc',
+        placeName: 'TestPlace',
+        state: 'Edit',
+        capabilities: ['execute', 'queryState'],
+      },
+    };
 
-  it('encodes an execute message', () => {
-    const json = encodeMessage({
-      type: 'execute',
-      sessionId: 'abc-123',
-      payload: { script: 'print("hi")' },
+    it('decodes a valid register message', () => {
+      const msg = roundTripPlugin(validRegister);
+      expect(msg).toEqual({
+        type: 'register',
+        sessionId: 'sess-1',
+        payload: {
+          pluginVersion: '2.0.0',
+          instanceId: 'inst-abc',
+          placeName: 'TestPlace',
+          placeFile: undefined,
+          state: 'Edit',
+          pid: undefined,
+          capabilities: ['execute', 'queryState'],
+        },
+      });
     });
-    const parsed = JSON.parse(json);
-    expect(parsed).toEqual({
-      type: 'execute',
-      sessionId: 'abc-123',
-      payload: { script: 'print("hi")' },
+
+    it('decodes register with optional fields', () => {
+      const msg = roundTripPlugin({
+        ...validRegister,
+        payload: {
+          ...validRegister.payload,
+          placeFile: 'TestPlace.rbxl',
+          pid: 12345,
+        },
+      });
+      expect(msg).not.toBeNull();
+      expect((msg as any).payload.placeFile).toBe('TestPlace.rbxl');
+      expect((msg as any).payload.pid).toBe(12345);
+    });
+
+    it('returns null when required payload field is missing', () => {
+      const broken = {
+        ...validRegister,
+        payload: { pluginVersion: '2.0.0' },
+      };
+      expect(roundTripPlugin(broken)).toBeNull();
     });
   });
-});
 
-describe('decodePluginMessage', () => {
-  describe('hello', () => {
-    it('decodes a valid hello message', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'hello',
-          sessionId: 'test-session',
-          payload: { sessionId: 'test-session' },
-        })
-      );
+  describe('stateResult', () => {
+    it('decodes a valid stateResult', () => {
+      const msg = roundTripPlugin({
+        type: 'stateResult',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: {
+          state: 'Play',
+          placeId: 123,
+          placeName: 'MyPlace',
+          gameId: 456,
+        },
+      });
       expect(msg).toEqual({
-        type: 'hello',
-        sessionId: 'test-session',
-        payload: { sessionId: 'test-session' },
+        type: 'stateResult',
+        sessionId: 'sess-1',
+        requestId: 'req-1',
+        payload: {
+          state: 'Play',
+          placeId: 123,
+          placeName: 'MyPlace',
+          gameId: 456,
+        },
       });
     });
 
-    it('returns null for hello without sessionId in payload', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'hello',
-          sessionId: 'test-session',
-          payload: {},
+    it('returns null without requestId', () => {
+      expect(
+        roundTripPlugin({
+          type: 'stateResult',
+          sessionId: 'sess-1',
+          payload: {
+            state: 'Play',
+            placeId: 123,
+            placeName: 'MyPlace',
+            gameId: 456,
+          },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
 
-    it('returns null for hello without top-level sessionId', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'hello',
-          payload: { sessionId: 'test-session' },
+    it('returns null with missing payload fields', () => {
+      expect(
+        roundTripPlugin({
+          type: 'stateResult',
+          sessionId: 'sess-1',
+          requestId: 'req-1',
+          payload: { state: 'Play' },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
   });
 
-  describe('output', () => {
-    it('decodes a valid output message with multiple entries', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'output',
-          sessionId: 'test-session',
-          payload: {
-            messages: [
-              { level: 'Print', body: 'Hello world' },
-              { level: 'Warning', body: 'Watch out' },
-            ],
-          },
-        })
-      );
+  describe('screenshotResult', () => {
+    it('decodes a valid screenshotResult', () => {
+      const msg = roundTripPlugin({
+        type: 'screenshotResult',
+        sessionId: 'sess-1',
+        requestId: 'req-2',
+        payload: {
+          data: 'base64data',
+          format: 'png',
+          width: 1920,
+          height: 1080,
+        },
+      });
       expect(msg).toEqual({
-        type: 'output',
-        sessionId: 'test-session',
+        type: 'screenshotResult',
+        sessionId: 'sess-1',
+        requestId: 'req-2',
         payload: {
-          messages: [
-            { level: 'Print', body: 'Hello world' },
-            { level: 'Warning', body: 'Watch out' },
-          ],
+          data: 'base64data',
+          format: 'png',
+          width: 1920,
+          height: 1080,
         },
       });
     });
 
-    it('filters out invalid entries in messages array', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'output',
-          sessionId: 'test-session',
+    it('returns null without requestId', () => {
+      expect(
+        roundTripPlugin({
+          type: 'screenshotResult',
+          sessionId: 'sess-1',
+          payload: {
+            data: 'base64data',
+            format: 'png',
+            width: 1920,
+            height: 1080,
+          },
+        })
+      ).toBeNull();
+    });
+
+    it('returns null with wrong format', () => {
+      expect(
+        roundTripPlugin({
+          type: 'screenshotResult',
+          sessionId: 'sess-1',
+          requestId: 'req-2',
           payload: {
-            messages: [
-              { level: 'Print', body: 'valid' },
-              { level: 123, body: 'bad level' },
-              'not an object',
-              null,
-            ],
+            data: 'base64data',
+            format: 'jpeg',
+            width: 1920,
+            height: 1080,
           },
         })
-      );
+      ).toBeNull();
+    });
+  });
+
+  describe('dataModelResult', () => {
+    const instance = {
+      name: 'Workspace',
+      className: 'Workspace',
+      path: 'game.Workspace',
+      properties: {},
+      attributes: {},
+      childCount: 3,
+      children: [],
+    };
+
+    it('decodes a valid dataModelResult', () => {
+      const msg = roundTripPlugin({
+        type: 'dataModelResult',
+        sessionId: 'sess-1',
+        requestId: 'req-3',
+        payload: { instance },
+      });
       expect(msg).toEqual({
-        type: 'output',
-        sessionId: 'test-session',
+        type: 'dataModelResult',
+        sessionId: 'sess-1',
+        requestId: 'req-3',
+        payload: { instance },
+      });
+    });
+
+    it('returns null without requestId', () => {
+      expect(
+        roundTripPlugin({
+          type: 'dataModelResult',
+          sessionId: 'sess-1',
+          payload: { instance },
+        })
+      ).toBeNull();
+    });
+
+    it('returns null when instance is not an object', () => {
+      expect(
+        roundTripPlugin({
+          type: 'dataModelResult',
+          sessionId: 'sess-1',
+          requestId: 'req-3',
+          payload: { instance: 'not-an-object' },
+        })
+      ).toBeNull();
+    });
+  });
+
+  describe('logsResult', () => {
+    it('decodes a valid logsResult', () => {
+      const msg = roundTripPlugin({
+        type: 'logsResult',
+        sessionId: 'sess-1',
+        requestId: 'req-4',
+        payload: {
+          entries: [{ level: 'Print', body: 'Hello', timestamp: 1000 }],
+          total: 1,
+          bufferCapacity: 1000,
+        },
+      });
+      expect(msg).toEqual({
+        type: 'logsResult',
+        sessionId: 'sess-1',
+        requestId: 'req-4',
         payload: {
-          messages: [{ level: 'Print', body: 'valid' }],
+          entries: [{ level: 'Print', body: 'Hello', timestamp: 1000 }],
+          total: 1,
+          bufferCapacity: 1000,
         },
       });
     });
 
-    it('returns null for output without messages array', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'output',
-          sessionId: 'test-session',
-          payload: { messages: 'not-an-array' },
+    it('returns null without requestId', () => {
+      expect(
+        roundTripPlugin({
+          type: 'logsResult',
+          sessionId: 'sess-1',
+          payload: { entries: [], total: 0, bufferCapacity: 1000 },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
 
-    it('returns null for output without top-level sessionId', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'output',
-          payload: { messages: [{ level: 'Print', body: 'test' }] },
+    it('returns null with missing total', () => {
+      expect(
+        roundTripPlugin({
+          type: 'logsResult',
+          sessionId: 'sess-1',
+          requestId: 'req-4',
+          payload: { entries: [], bufferCapacity: 1000 },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
   });
 
-  describe('scriptComplete', () => {
-    it('decodes a successful scriptComplete', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'scriptComplete',
-          sessionId: 'test-session',
-          payload: { success: true },
-        })
-      );
+  describe('stateChange', () => {
+    it('decodes a valid stateChange', () => {
+      const msg = roundTripPlugin({
+        type: 'stateChange',
+        sessionId: 'sess-1',
+        payload: { previousState: 'Edit', newState: 'Play', timestamp: 12345 },
+      });
       expect(msg).toEqual({
-        type: 'scriptComplete',
-        sessionId: 'test-session',
-        payload: { success: true, error: undefined },
+        type: 'stateChange',
+        sessionId: 'sess-1',
+        payload: { previousState: 'Edit', newState: 'Play', timestamp: 12345 },
       });
     });
 
-    it('decodes a failed scriptComplete with error', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'scriptComplete',
-          sessionId: 'test-session',
-          payload: { success: false, error: 'Script errored' },
+    it('returns null with missing timestamp', () => {
+      expect(
+        roundTripPlugin({
+          type: 'stateChange',
+          sessionId: 'sess-1',
+          payload: { previousState: 'Edit', newState: 'Play' },
         })
-      );
+      ).toBeNull();
+    });
+  });
+
+  describe('heartbeat', () => {
+    it('decodes a valid heartbeat', () => {
+      const msg = roundTripPlugin({
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: { uptimeMs: 60000, state: 'Edit', pendingRequests: 0 },
+      });
       expect(msg).toEqual({
-        type: 'scriptComplete',
-        sessionId: 'test-session',
-        payload: { success: false, error: 'Script errored' },
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: { uptimeMs: 60000, state: 'Edit', pendingRequests: 0 },
+      });
+    });
+
+    it('accepts heartbeat with missing fields using defaults', () => {
+      const msg = roundTripPlugin({
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: { uptimeMs: 60000, state: 'Edit' },
+      });
+      expect(msg).toEqual({
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: { uptimeMs: 60000, state: 'Edit', pendingRequests: 0 },
+      });
+    });
+
+    it('accepts empty payload with all defaults', () => {
+      const msg = roundTripPlugin({
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: {},
+      });
+      expect(msg).toEqual({
+        type: 'heartbeat',
+        sessionId: 'sess-1',
+        payload: { uptimeMs: 0, state: 'Edit', pendingRequests: 0 },
+      });
+    });
+  });
+
+  describe('error (plugin)', () => {
+    it('decodes error with requestId', () => {
+      const msg = roundTripPlugin({
+        type: 'error',
+        sessionId: 'sess-1',
+        requestId: 'req-7',
+        payload: { code: 'TIMEOUT', message: 'Request timed out' },
+      });
+      expect(msg).toEqual({
+        type: 'error',
+        sessionId: 'sess-1',
+        requestId: 'req-7',
+        payload: {
+          code: 'TIMEOUT',
+          message: 'Request timed out',
+          details: undefined,
+        },
+      });
+    });
+
+    it('decodes error without requestId', () => {
+      const msg = roundTripPlugin({
+        type: 'error',
+        sessionId: 'sess-1',
+        payload: { code: 'INTERNAL_ERROR', message: 'Something failed' },
+      });
+      expect(msg).toEqual({
+        type: 'error',
+        sessionId: 'sess-1',
+        payload: {
+          code: 'INTERNAL_ERROR',
+          message: 'Something failed',
+          details: undefined,
+        },
       });
+      expect(msg).not.toHaveProperty('requestId');
     });
 
-    it('returns null if success is not boolean', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'scriptComplete',
-          sessionId: 'test-session',
-          payload: { success: 'yes' },
+    it('decodes error with details', () => {
+      const msg = roundTripPlugin({
+        type: 'error',
+        sessionId: 'sess-1',
+        requestId: 'req-8',
+        payload: {
+          code: 'INVALID_PAYLOAD',
+          message: 'Bad data',
+          details: { field: 'path' },
+        },
+      });
+      expect(msg).not.toBeNull();
+      expect((msg as any).payload.details).toEqual({ field: 'path' });
+    });
+
+    it('returns null without code', () => {
+      expect(
+        roundTripPlugin({
+          type: 'error',
+          sessionId: 'sess-1',
+          payload: { message: 'No code' },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
 
-    it('returns null for scriptComplete without top-level sessionId', () => {
-      const msg = decodePluginMessage(
-        JSON.stringify({
-          type: 'scriptComplete',
-          payload: { success: true },
+    it('returns null without message', () => {
+      expect(
+        roundTripPlugin({
+          type: 'error',
+          sessionId: 'sess-1',
+          payload: { code: 'TIMEOUT' },
         })
-      );
-      expect(msg).toBeNull();
+      ).toBeNull();
     });
   });
+});
 
-  describe('malformed messages', () => {
-    it('returns null for invalid JSON', () => {
-      expect(decodePluginMessage('not json')).toBeNull();
+describe('encodeMessage / decodeServerMessage', () => {
+  describe('basic messages', () => {
+    it('round-trips execute without requestId', () => {
+      const msg: ServerMessage = {
+        type: 'execute',
+        sessionId: 'sess-1',
+        payload: { script: 'print("hi")' },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
     });
 
-    it('returns null for non-object JSON', () => {
-      expect(decodePluginMessage('"just a string"')).toBeNull();
+    it('round-trips execute with requestId', () => {
+      const msg: ServerMessage = {
+        type: 'execute',
+        sessionId: 'sess-1',
+        requestId: 'req-99',
+        payload: { script: 'print("hi")' },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+
+    it('round-trips shutdown', () => {
+      const msg: ServerMessage = {
+        type: 'shutdown',
+        sessionId: 'sess-1',
+        payload: {} as Record<string, never>,
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+  });
+
+  describe('queryState', () => {
+    it('round-trips queryState', () => {
+      const msg: ServerMessage = {
+        type: 'queryState',
+        sessionId: 'sess-1',
+        requestId: 'req-10',
+        payload: {} as Record<string, never>,
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+
+    it('returns null without requestId', () => {
+      expect(
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'queryState',
+            sessionId: 'sess-1',
+            payload: {},
+          })
+        )
+      ).toBeNull();
+    });
+  });
+
+  describe('captureScreenshot', () => {
+    it('round-trips captureScreenshot with format', () => {
+      const msg: ServerMessage = {
+        type: 'captureScreenshot',
+        sessionId: 'sess-1',
+        requestId: 'req-11',
+        payload: { format: 'png' },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+
+    it('round-trips captureScreenshot without format', () => {
+      const msg: ServerMessage = {
+        type: 'captureScreenshot',
+        sessionId: 'sess-1',
+        requestId: 'req-11',
+        payload: {},
+      };
+      const decoded = roundTripServer(msg);
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('captureScreenshot');
+      expect((decoded as any).payload.format).toBeUndefined();
+    });
+
+    it('returns null without requestId', () => {
+      expect(
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'captureScreenshot',
+            sessionId: 'sess-1',
+            payload: {},
+          })
+        )
+      ).toBeNull();
+    });
+  });
+
+  describe('queryDataModel', () => {
+    it('round-trips queryDataModel with all options', () => {
+      const msg: ServerMessage = {
+        type: 'queryDataModel',
+        sessionId: 'sess-1',
+        requestId: 'req-12',
+        payload: {
+          path: 'game.Workspace',
+          depth: 2,
+          properties: ['Name', 'Position'],
+          includeAttributes: true,
+          find: { name: 'Part', recursive: true },
+          listServices: false,
+        },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
     });
 
-    it('returns null for missing type', () => {
-      expect(decodePluginMessage(JSON.stringify({ sessionId: 's', payload: {} }))).toBeNull();
+    it('round-trips queryDataModel with minimal options', () => {
+      const msg: ServerMessage = {
+        type: 'queryDataModel',
+        sessionId: 'sess-1',
+        requestId: 'req-12',
+        payload: { path: 'game.Workspace' },
+      };
+      const decoded = roundTripServer(msg);
+      expect(decoded).not.toBeNull();
+      expect((decoded as any).payload.path).toBe('game.Workspace');
     });
 
-    it('returns null for missing payload', () => {
-      expect(decodePluginMessage(JSON.stringify({ type: 'hello', sessionId: 's' }))).toBeNull();
+    it('returns null without path', () => {
+      expect(
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'queryDataModel',
+            sessionId: 'sess-1',
+            requestId: 'req-12',
+            payload: { depth: 1 },
+          })
+        )
+      ).toBeNull();
     });
 
-    it('returns null for missing sessionId', () => {
+    it('returns null without requestId', () => {
       expect(
-        decodePluginMessage(
-          JSON.stringify({ type: 'hello', payload: { sessionId: 's' } })
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'queryDataModel',
+            sessionId: 'sess-1',
+            payload: { path: 'game.Workspace' },
+          })
         )
       ).toBeNull();
     });
+  });
+
+  describe('queryLogs', () => {
+    it('round-trips queryLogs with all options', () => {
+      const msg: ServerMessage = {
+        type: 'queryLogs',
+        sessionId: 'sess-1',
+        requestId: 'req-13',
+        payload: {
+          count: 50,
+          direction: 'tail',
+          levels: ['Error', 'Warning'],
+          includeInternal: true,
+        },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
 
-    it('returns null for unknown message type', () => {
+    it('round-trips queryLogs with empty payload', () => {
+      const msg: ServerMessage = {
+        type: 'queryLogs',
+        sessionId: 'sess-1',
+        requestId: 'req-13',
+        payload: {},
+      };
+      const decoded = roundTripServer(msg);
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('queryLogs');
+    });
+
+    it('returns null without requestId', () => {
       expect(
-        decodePluginMessage(
+        decodeServerMessage(
           JSON.stringify({
-            type: 'unknown',
-            sessionId: 'test',
+            type: 'queryLogs',
+            sessionId: 'sess-1',
             payload: {},
           })
         )
       ).toBeNull();
     });
   });
+
+  describe('error (server)', () => {
+    it('round-trips error with requestId', () => {
+      const msg: ServerMessage = {
+        type: 'error',
+        sessionId: 'sess-1',
+        requestId: 'req-16',
+        payload: { code: 'CAPABILITY_NOT_SUPPORTED', message: 'Not available' },
+      };
+      expect(roundTripServer(msg)).toEqual({
+        ...msg,
+        payload: { ...msg.payload, details: undefined },
+      });
+    });
+
+    it('round-trips error without requestId', () => {
+      const msg: ServerMessage = {
+        type: 'error',
+        sessionId: 'sess-1',
+        payload: { code: 'BUSY', message: 'Server busy' },
+      };
+      const decoded = roundTripServer(msg);
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('error');
+      expect(decoded).not.toHaveProperty('requestId');
+    });
+
+    it('round-trips error with details', () => {
+      const msg: ServerMessage = {
+        type: 'error',
+        sessionId: 'sess-1',
+        requestId: 'req-17',
+        payload: {
+          code: 'INVALID_PAYLOAD',
+          message: 'Bad request',
+          details: { hint: 'missing path' },
+        },
+      };
+      expect(roundTripServer(msg)).toEqual(msg);
+    });
+
+    it('returns null without code', () => {
+      expect(
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'error',
+            sessionId: 'sess-1',
+            payload: { message: 'No code' },
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null without message', () => {
+      expect(
+        decodeServerMessage(
+          JSON.stringify({
+            type: 'error',
+            sessionId: 'sess-1',
+            payload: { code: 'TIMEOUT' },
+          })
+        )
+      ).toBeNull();
+    });
+  });
+});
+
+describe('decodeServerMessage (malformed)', () => {
+  it('returns null for invalid JSON', () => {
+    expect(decodeServerMessage('not json')).toBeNull();
+  });
+
+  it('returns null for non-object JSON', () => {
+    expect(decodeServerMessage('"just a string"')).toBeNull();
+  });
+
+  it('returns null for missing type', () => {
+    expect(
+      decodeServerMessage(JSON.stringify({ sessionId: 's', payload: {} }))
+    ).toBeNull();
+  });
+
+  it('returns null for missing payload', () => {
+    expect(
+      decodeServerMessage(JSON.stringify({ type: 'shutdown', sessionId: 's' }))
+    ).toBeNull();
+  });
+
+  it('returns null for missing sessionId', () => {
+    expect(
+      decodeServerMessage(JSON.stringify({ type: 'shutdown', payload: {} }))
+    ).toBeNull();
+  });
+
+  it('returns null for unknown message type', () => {
+    expect(
+      decodeServerMessage(
+        JSON.stringify({ type: 'unknown', sessionId: 's', payload: {} })
+      )
+    ).toBeNull();
+  });
 });